testing

Testing Rules & Best Practices

You are an expert in Svelte 5, SvelteKit, TypeScript, and modern testing with vitest-browser-svelte.

Core Testing Principles

Foundation First Approach

• Aim for 100% test coverage using complete test structure planning
• Start with all describe blocks and test stubs using .skip
• Implement tests incrementally - remove .skip as you write each test
• Test all code paths - every branch, condition, and edge case

Test File Organization

• Component Tests: *.svelte.test.ts - Real browser testing
• SSR Tests: *.ssr.test.ts - Server-side rendering validation
• Server Tests: *.test.ts - API routes, utilities, business logic

CRITICAL: vitest-browser-svelte Patterns

Always Use Locators, Never Containers

// ❌ NEVER use containers
const { container } = render(MyComponent);

// ✅ ALWAYS use locators with auto-retry
render(MyComponent);
const button = page.getByTestId('submit');
await button.click();

Handle Strict Mode Violations

// ❌ FAILS: Multiple elements match
page.getByRole('link', { name: 'Home' });

// ✅ CORRECT: Use .first(), .nth(), .last()
page.getByRole('link', { name: 'Home' }).first();

Svelte 5 Runes Testing

// ✅ Always use untrack() for $derived
expect(untrack(() => derived_value)).toBe(expected);

// ✅ For getters: get function first, then untrack
const derived_fn = state_object.derived_value;
expect(untrack(() => derived_fn())).toBe(expected);

Form Validation Lifecycle

// ✅ Test the full lifecycle: valid → validate → invalid → fix
const form = create_form_state({
	email: { value: '', validation_rules: { required: true } },
});
expect(untrack(() => form.is_form_valid())).toBe(true); // Initially valid
form.validate_all_fields();
expect(untrack(() => form.is_form_valid())).toBe(false); // Now invalid

Client-Server Alignment Strategy

The Problem

Server unit tests with heavy mocking can pass while production breaks due to client-server mismatches.