cursorrules

Testing Rules & Best Practices

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

Core Testing Principles

1. Testing Coverage Strategy

• Aim for 100% test coverage using the "Foundation First" approach
• Start with complete test structure - write all describe blocks and test stubs first
• Use .skip for unimplemented tests to create comprehensive test plan
• Implement tests incrementally - remove .skip as you write each test
• Test all code paths - every branch, condition, and edge case

2. Test File Organization

• Component Tests: *.svelte.test.ts - Real browser testing with vitest-browser-svelte
• SSR Tests: *.ssr.test.ts - Server-side rendering validation
• Server Tests: *.test.ts - API routes, utilities, business logic
• Colocate tests next to the files they test

vitest-browser-svelte Patterns

Essential Imports & Setup

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';

CRITICAL: Always Use Locators, Never Containers

// ❌ NEVER use containers - no auto-retry, manual DOM queries
const { container } = render(MyComponent);
const button = container.querySelector('[data-testid="submit"]');

// ✅ ALWAYS use locators - auto-retry, semantic queries
render(MyComponent);
const button = page.getByTestId('submit');
await button.click(); // Automatic waiting and retrying

Locator Patterns (Auto-retry Built-in)

// ✅ Semantic queries (preferred - test accessibility)
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)
page.getByTestId('submit-button');

// ✅ Assertions with locators (always await)
await expect.element(page.getByText('Success')).toBeInTheDocument();
await expect.element(page.getByRole('button')).toBeDisabled();