Sveltest

Comprehensive Svelte 5 testing examples and patterns using Vitest Browser Mode, Playwright, and vitest-browser-svelte

#playwright #svelte #svelte5 #sveltekit #testing #typescript #vitest #vitest-browser-svelte

Sveltest

A comprehensive example project demonstrating vitest-browser-svelte testing patterns for modern Svelte 5 applications. Built over a weekend as a companion piece to my blog post: Migrating from @testing-library/svelte to vitest-browser-svelte.

🎯 What is Sveltest?

Sveltest is both a comprehensive reference project and a CLI tool for vitest-browser-svelte - the modern testing solution for Svelte applications. Use it as:

📚 A reference project showcasing real-world testing patterns
🤖 A CLI tool for AI assistants to quickly access testing examples
📖 A learning resource with comprehensive documentation

This project demonstrates my opinionated approach to testing with:

Client-side component testing with real browser environments
Server-side testing for SvelteKit API routes and hooks
SSR testing for server-side rendering validation
Full-stack integration patterns for modern web applications

🔄 Client-Server Alignment Strategy

The Problem: Server unit tests with heavy mocking can pass while production breaks due to client-server mismatches. Forms send data in one format, servers expect another, and mocked tests miss the disconnect.

My Solution: This project demonstrates a multi-layer testing approach with minimal mocking:

Shared validation logic between client and server prevents contract mismatches
Real FormData/Request objects in server tests (only external services like databases are mocked)
TypeScript contracts ensure data structures align between client and server
E2E tests provide the final safety net to catch any integration gaps

This methodology gives you fast unit test feedback while maintaining confidence that client and server actually work together in production.

🤖 CLI for AI Assistants

Sveltest includes a CLI tool designed specifically for LLMs to access testing patterns and examples. When working with your AI assistant (Claude, ChatGPT, etc.), you can get instant help with testing patterns:

# Your AI assistant can use this to fetch testing patterns
pnpx sveltest list              # List all available patterns
pnpx sveltest get button        # Get button testing examples
pnpx sveltest search form       # Search for form testing patterns

Usage Example: Tell your AI assistant:

"I need to test a login form with validation. Use pnpx sveltest search form to get the testing patterns."

Your AI can then fetch relevant examples and adapt them to your specific needs. The CLI provides access to all the testing patterns in this repository, making it easy to integrate proven testing approaches into your workflow.

🚀 Features Demonstrated

Component Testing (Client-Side)

Button Component: Variants, sizes, loading states, accessibility
Input Component: Validation, error states, form integration
Modal Component: Focus management, keyboard navigation, portal rendering
Card Component: Slot testing, conditional rendering, click handlers
LoginForm Component: Complex form interactions, async operations
TodoManager Component: State management, CRUD operations, list interactions
Calculator Component: Interactive calculations, input validation
Nav Component: Navigation, responsive design, accessibility

Server-Side Testing

API Routes: Authentication, authorization, error handling
Server Hooks: Security headers, middleware, request processing
Form Actions: CRUD operations, validation, user feedback
Utility Functions: Validation logic, data processing

SSR Testing

Component SSR: Server-side rendering validation
Layout SSR: Navigation, responsive design, meta tags
Page SSR: Multi-page server-side rendering
Hydration Testing: Client-server state synchronization

🛠️ Technology Stack

Framework: Svelte 5 with SvelteKit
Testing: vitest-browser-svelte with Playwright
Styling: TailwindCSS + DaisyUI
Language: TypeScript
Package Manager: pnpm

📦 Installation

Option 1: Use the CLI (Recommended for AI Assistants)

# No installation needed - use with npx/pnpx
pnpx sveltest list              # List all patterns
pnpx sveltest get <component>   # Get specific examples
pnpx sveltest search <keyword>  # Search patterns

Perfect for quickly accessing testing patterns while working with AI assistants.

Option 2: Clone the Repository

# Clone the repository
git clone https://github.com/spences10/sveltest.git
cd sveltest

# Install dependencies
pnpm install

# Run the development server
pnpm dev

# Run tests
pnpm test:unit

# Run specific test suites
pnpm test:client    # Component tests in browser
pnpm test:server    # Server-side tests
pnpm test:ssr       # SSR tests

🧪 Testing Patterns

Client-Side Component Testing

import { render } from 'vitest-browser-svelte';
import { page } from 'vitest/browser';
import { expect, test } from 'vitest';
import Button from './button.svelte';

test('button renders with correct variant', async () => {
    render(Button, { variant: 'primary', children: 'Click me' });

    const button = page.getByRole('button', { name: 'Click me' });
    await expect.element(button).toBeInTheDocument();
    await expect.element(button).toHaveClass('btn-primary');
});

Server-Side API Testing

import { describe, it, expect } from 'vitest';
import { GET } from './+server.ts';

describe('API Route', () => {
    it('should authenticate valid requests', async () => {
        const request = new Request('http://localhost/api/secure-data', {
            headers: { Authorization: 'Bearer valid-token' },
        });

        const response = await GET({ request });
        expect(response.status).toBe(200);
    });
});

SSR Testing

import { render } from 'svelte/server';
import { expect, test } from 'vitest';
import Layout from './+layout.svelte';

test('layout renders navigation on server', () => {
    const { html } = render(Layout);

    expect(html).toContain('<nav');
    expect(html).toContain('aria-label="Main navigation"');
});

📁 Project Structure

This is a monorepo project with multiple packages:

sveltest/
├── apps/
│   └── website/              # Main Sveltest website and examples
│       └── src/
│           ├── lib/
│           │   ├── components/     # Reusable components with tests
│           │   │   ├── button.svelte
│           │   │   ├── button.svelte.test.ts
│           │   │   ├── button.ssr.test.ts
│           │   │   ├── input.svelte
│           │   │   ├── modal.svelte
│           │   │   ├── card.svelte
│           │   │   ├── login-form.svelte
│           │   │   ├── todo-manager.svelte
│           │   │   ├── calculator.svelte
│           │   │   └── nav.svelte
│           │   └── utils/          # Utility functions with tests
│           └── routes/
│               ├── api/            # API routes with tests
│               ├── components/     # Component showcase pages
│               ├── docs/           # Documentation pages
│               └── examples/       # Example pages
│
└── packages/
    └── cli/                  # Sveltest CLI for AI Assistants
        ├── src/
        │   ├── index.ts      # CLI entry point
        │   └── commands/     # List, get, search commands
        └── README.md         # CLI documentation

Each component is co-located with its tests (.svelte.test.ts for client tests, .ssr.test.ts for SSR tests).

🤖 AI Assistant Rules for Teams

One of the key outcomes of this project was creating comprehensive AI assistant rules and tools that help teams adopt this testing methodology more easily. I'm onboarding my team to use this approach!

CLI Tool for Any AI Assistant

The pnpx sveltest CLI works with any AI assistant (Claude, ChatGPT, Cursor, Windsurf, etc.):

Universal access - No project setup required
Instant patterns - Get testing examples in seconds
Always up-to-date - Pulls latest patterns from the repository
Context-aware - Search and filter for your specific needs

Cursor Rules (`.cursor/rules/testing.mdc`)

Comprehensive testing patterns for Cursor AI
Complete vitest-browser-svelte best practices
Code style enforcement (snake_case, kebab-case conventions)
Common error solutions and troubleshooting

Windsurf Rules (`.windsurf/rules/testing.md`)

Adapted for Windsurf's modern rule system
Trigger-based activation for test files
Same comprehensive patterns as Cursor rules
Team-ready configuration

These rules files contain:

Foundation First testing approach guidelines
Complete vitest-browser-svelte patterns and anti-patterns
Svelte 5 runes testing strategies
SSR testing methodologies
Form validation lifecycle patterns
Quick reference DO's and DON'Ts

For Teams: Use the CLI for on-demand access, or copy the rule files to your projects to ensure consistent testing patterns across your team. The AI assistants will automatically follow the established patterns when writing or reviewing tests.

🎨 Testing Conventions

My Opinionated Naming Conventions

I use specific naming conventions to help me identify code I've written versus external libraries:

Files: kebab-case (e.g., login-form.svelte.test.ts)
Variables & Functions: snake_case (e.g., submit_button, error_message) - This helps me instantly recognize my own code
Test IDs: kebab-case (e.g., data-testid="submit-button")
Interfaces: TitleCase (following TypeScript conventions)

Test Organization

Descriptive test groups with describe()
Comprehensive edge case coverage
Real-world interaction patterns
Accessibility testing integration

📊 Test Coverage

32 test files across client, server, and SSR
576 passing tests with comprehensive component coverage
Full server-side testing for API routes and hooks
SSR validation for critical rendering paths

🚀 Migration from @testing-library/svelte

This project was inspired by my experience migrating from @testing-library/svelte to vitest-browser-svelte. Read the full story in my blog post: Migrating from @testing-library/svelte to vitest-browser-svelte.

You can also check the comprehensive Migration Guide which documents:

Step-by-step migration process
Before/after code examples
Common patterns and transformations
Performance improvements
Troubleshooting guide

🤝 Contributing

This project serves as a reference implementation of my testing methodology. Feel free to:

Open issues for questions about testing patterns
Submit PRs to improve examples
Share your own testing patterns
Report bugs or suggest improvements

Keep in mind that the conventions used here are opinionated and reflect my personal coding style preferences.

📄 License

MIT License - see LICENSE for details.

Sveltest - My comprehensive vitest-browser-svelte testing patterns for modern Svelte applications.

Top categories

tailwind daisyui admin template popup mdsvex portfolio blog form ecommerce ui carousel auth dark seo image routing

Sveltest

Sveltest

🎯 What is Sveltest?

🔄 Client-Server Alignment Strategy

🤖 CLI for AI Assistants

🚀 Features Demonstrated

Component Testing (Client-Side)

Server-Side Testing

SSR Testing

🛠️ Technology Stack

📦 Installation

Option 1: Use the CLI (Recommended for AI Assistants)

Option 2: Clone the Repository

🧪 Testing Patterns

Client-Side Component Testing

Server-Side API Testing

SSR Testing

📁 Project Structure

🤖 AI Assistant Rules for Teams

CLI Tool for Any AI Assistant

Cursor Rules (.cursor/rules/testing.mdc)

Windsurf Rules (.windsurf/rules/testing.md)

🎨 Testing Conventions

My Opinionated Naming Conventions

Test Organization

📊 Test Coverage

🚀 Migration from @testing-library/svelte

🤝 Contributing

📄 License

🔗 Related Resources

Top categories

Cursor Rules (`.cursor/rules/testing.mdc`)

Windsurf Rules (`.windsurf/rules/testing.md`)