Svelte Testing Patterns

Svelte Testing Patterns

Test Svelte 5 components with Vitest and @testing-library/svelte — render, user events, store mocking, and async tick flushing

When to Use

• You are writing unit tests for Svelte components
• You need to test reactive behavior triggered by user interactions (clicks, input, form submission)
• You need to mock Svelte stores or module imports in tests
• You are testing async behavior and need to flush the update queue with tick()

Instructions

Setup:

1. Install dependencies and configure Vitest with the Svelte plugin:

npm install -D vitest @testing-library/svelte @testing-library/jest-dom jsdom

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [svelte({ hot: !process.env.VITEST })],
  test: {
    environment: 'jsdom',
    setupFiles: ['./src/tests/setup.ts'],
    globals: true,
  },
});

// src/tests/setup.ts
import '@testing-library/jest-dom';

Rendering components:

2. Use render from @testing-library/svelte to mount components. Query the DOM with Testing Library queries:

import { render, screen } from '@testing-library/svelte';
import MyButton from '$lib/components/MyButton.svelte';

test('renders with label', () => {
  render(MyButton, { props: { label: 'Click me' } });
  expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
});

3. Pass props using the props option:

render(UserCard, {
  props: {
    user: { id: 1, name: 'Alice', email: 'alice@example.com' },
  },
});

Firing events:

4. Use fireEvent or the userEvent library for simulating interactions:

import { render, screen, fireEvent } from '@testing-library/svelte';
import Counter from '$lib/components/Counter.svelte';

test('increments on click', async () => {
  render(Counter);
  const button = screen.getByRole('button', { name: '+' });

  await fireEvent.click(button);
  await fireEvent.click(button);

  expect(screen.getByText('2')).toBeInTheDocument();
});

5. Use @testing-library/user-event for more realistic interactions (typing, tabbing):

import userEvent from '@testing-library/user-event';

test('types in search input', async () => {
  const user = userEvent.setup();
  render(SearchBar);

  await user.type(screen.getByRole('searchbox'), 'svelte');
  expect(screen.getByDisplayValue('svelte')).toBeInTheDocument();
});

Async updates with tick:

6. After triggering reactive updates, await tick() from svelte to flush Svelte's update queue:

import { tick } from 'svelte';

test('shows error after failed submit', async () => {
  render(LoginForm);

  await fireEvent.submit(screen.getByRole('form'));
  await tick();

  expect(screen.getByText('Email is required')).toBeInTheDocument();
});

Testing stores:

7. Mock writable stores by importing and setting them directly:

import { count } from '$lib/stores/counter';
import CounterDisplay from '$lib/components/CounterDisplay.svelte';

test('displays current count', () => {
  count.set(42);
  render(CounterDisplay);
  expect(screen.getByText('42')).toBeInTheDocument();
});

Mocking modules:

8. Use vi.mock to mock module imports in tests:

vi.mock('$lib/services/api', () => ({
  fetchUsers: vi.fn().mockResolvedValue([
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' },
  ]),
}));

test('renders fetched users', async () => {
  render(UserList);
  await tick();

  expect(screen.getByText('Alice')).toBeInTheDocument();
  expect(screen.getByText('Bob')).toBeInTheDocument();
});

Testing with context:

9. Wrap components in a context provider using a wrapper component, or use the context option:

render(MyComponent, {
  context: new Map([['theme', { primary: '#3b82f6' }]]),
});

Details

Svelte 5 vs. Svelte 4 testing differences:

Svelte 5 with @testing-library/svelte v5+ uses the new component API internally. The test API (render, screen, fireEvent) is unchanged from the user's perspective. Ensure @testing-library/svelte v5 or later for Svelte 5 components.

The Testing Library philosophy:

Prefer queries that reflect how users perceive the UI:

1. getByRole — most semantic (button, heading, checkbox, etc.)
2. getByLabelText — for form fields
3. getByPlaceholderText — fallback for inputs
4. getByText — visible text content
5. getByTestId — last resort (add data-testid to elements)

Avoid testing implementation details (component state, store values) — test observable behavior.

act in Svelte:

Unlike React Testing Library, Svelte Testing Library uses tick() for flushing updates rather than act(). Most interactions already resolve automatically with await; tick() is needed when updates are triggered by direct reactive changes rather than DOM events.

Testing SvelteKit load functions:

Load functions are plain async functions — test them directly without mounting a component:

import { load } from './+page.server';

test('returns user data', async () => {
  const result = await load({
    params: { id: '1' },
    locals: { user: mockUser },
    fetch: global.fetch,
  } as any);

  expect(result.user.id).toBe(1);
});

Snapshot testing:

test('matches snapshot', () => {
  const { container } = render(MyComponent);
  expect(container).toMatchSnapshot();
});

Use sparingly — prefer behavior assertions over structural snapshots.

Source

https://kit.svelte.dev/docs/testing

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.