# Sveltest API Reference

> Core testing utilities and functions for Svelte 5 with vitest-browser-svelte

## Essential Imports

```typescript
import { describe, expect, test, vi } from 'vitest';
import { render } from 'vitest-browser-svelte';
import { page } from '@vitest/browser/context';
import { createRawSnippet } from 'svelte';
import { flushSync, untrack } from 'svelte';
```

## Locator Methods

### Semantic Queries (Preferred)

```typescript
page.getByRole('button', { name: 'Submit' });
page.getByRole('textbox', { name: 'Email' });
page.getByLabel('Email address');
page.getByText('Welcome');
```

### Test IDs (When semantic queries aren't possible)

```typescript
page.getByTestId('submit-button');
```

## Assertions

```typescript
// Always await assertions
await expect.element(element).toBeInTheDocument();
await expect.element(element).toBeVisible();
await expect.element(element).toBeDisabled();
await expect.element(element).toHaveClass('btn-primary');
await expect.element(element).toHaveTextContent('Hello');
await expect.element(element).toHaveValue('text');
```

## User Interactions

```typescript
// Click events
await element.click();
await element.click({ force: true }); // For animations

// Form interactions
await element.fill('text');
await element.selectOption('value');
await element.check(); // Checkboxes
await element.uncheck();

// Keyboard events
await element.press('Enter');
await userEvent.keyboard('{Escape}');
```

## Mocking

```typescript
// Mock functions
const mockFn = vi.fn();
mockFn.mockReturnValue('result');

// Mock modules
vi.mock('$lib/utils/module', () => ({
  utilFunction: vi.fn(() => [{ value: 'option1', label: 'Option 1' }]),
  anotherUtil: vi.fn((input) => `processed-${input}`),
}));

// Mock Svelte context
vi.mock('svelte', async (importOriginal) => {
  const actual = (await importOriginal()) as any;
  return {
    ...actual,
    getContext: vi.fn(() => ({
      subscribe: vi.fn(),
      set: vi.fn(),
      update: vi.fn(),
    })),
  };
});
```

## Svelte 5 Runes Testing

```typescript
// Testing reactive state with runes
test('reactive state with runes', () => {
  let count = $state(0);
  let doubled = $derived(count * 2);

  expect(untrack(() => doubled)).toBe(0);

  count = 5;
  flushSync(); // Still needed for derived state evaluation

  expect(untrack(() => doubled)).toBe(10);
});
```

## SSR Testing

```typescript
import { render } from 'svelte/server';

test('should render without errors', () => {
  expect(() => {
    render(ComponentName);
  }).not.toThrow();
});

test('should render essential content for SEO', () => {
  const { body } = render(ComponentName);

  expect(body).toContain('Primary heading');
  expect(body).toContain('href="/important-link"');
});
```