Testing Infrastructure

show.fm uses a comprehensive testing stack optimized for Svelte 5 Runes and Cloudflare Workers compatibility.

Documentation Overview

Document	Purpose
Testing Strategy	Philosophy, conventions, and the "why" of testing
Domain Map	Business logic coverage tracking (the "what")
Mock Factories	Complete mock library reference
Testing Patterns	Svelte 5, API, and Worker testing patterns

Two Sources of Truth

• Code coverage (pnpm test:coverage) tracks vertical coverage (lines, branches)
• Domain Map tracks horizontal coverage (business flows across services)

Stack Overview

Tool	Version	Purpose
Vitest	4.x	Unit & integration test runner
@testing-library/svelte	5.x	Svelte component testing
jest-axe	10.x	Accessibility (WCAG) compliance
Playwright	-	End-to-end browser testing

Directory Structure

src/test/
├── setup.ts        # Global config (jest-dom, jest-axe, browser mocks)
├── utils.ts        # Mock factories for external services
├── index.ts        # Re-exports for clean imports
└── fixtures/       # Test fixture components
    └── TestButton.svelte

src/lib/__tests__/  # Infrastructure verification tests
src/lib/[module]/__tests__/  # Module-specific tests
tests/              # Playwright E2E tests
docs/testing/flows/ # Complex flow specifications

Quick Start

Essential Commands

# Run all unit tests
pnpm test

# Watch mode (live reload)
pnpm test:watch

# Run specific test file
pnpm test src/lib/module/__tests__/file.test.ts

# Coverage report
pnpm test -- --coverage

# E2E tests (Playwright)
pnpm test:e2e

# Rate-limiting regression tests
pnpm test src/api/middleware/__tests__/rate-limit.test.ts
pnpm test src/api/routes/guests/__tests__/index.test.ts
pnpm test src/api/middleware/__tests__/rate-limit.test.ts src/api/routes/guests/__tests__/index.test.ts

Rate Limiting Coverage (Phase 4)

Test File	Scope
src/api/middleware/__tests__/rate-limit.test.ts	Middleware behavior (allow, block/429, fail-open, identity)
src/api/routes/guests/__tests__/index.test.ts	Route wiring for POST /api/guests/send-verification

Import Pattern

Use the $test alias for clean imports:

import { createMockSupabaseClient, testData } from '$test';
import { createMockR2Bucket, createMockQueue } from '$test/utils';

Configuration

Vitest (vitest.config.ts)

Setting	Value	Purpose
environment	jsdom	Default browser-like environment
globals	true	Auto-imports describe, it, expect
setupFiles	./src/test/setup.ts	Runs before all tests
coverage.provider	v8	Coverage reporting

Worker Tests

Add // @vitest-environment node at the top of worker test files to use Node.js environment instead of jsdom.

Path Aliases

Alias	Path
$lib	/src/lib
$api	/src/api
$components	/src/lib/components
$test	/src/test

Global Test Setup

The setup.ts file configures:

DOM Matchers (jest-dom)

// Available matchers
expect(element).toBeInTheDocument();
expect(element).toBeDisabled();
expect(element).toHaveAttribute('aria-busy', 'true');
expect(element).toHaveTextContent('Hello');

Accessibility Testing (jest-axe)

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

it('should have no accessibility violations', async () => {
	const { container } = render(Component);
	expect(await axe(container)).toHaveNoViolations();
});

Browser API Mocks

These are globally mocked in setup.ts:

API	Purpose
window.matchMedia	Media query testing
ResizeObserver	Component resize detection
IntersectionObserver	Lazy loading / visibility
window.scrollTo	Navigation scroll behavior

Test File Naming

Source Location	Test Location	Pattern
src/lib/module/file.ts	src/lib/module/__tests__/file.test.ts	{name}.test.ts
src/api/routes/resource.ts	src/api/routes/__tests__/resource.test.ts	{name}.test.ts
src/lib/components/Feature.svelte	src/lib/components/__tests__/Feature.test.ts	{name}.test.ts
workers/worker-name/src/index.ts	workers/worker-name/__tests__/index.test.ts	{name}.test.ts
User flows (E2E)	tests/{feature}.spec.ts	{feature}.spec.ts
Integration tests	__tests__/{feature}-integration.test.ts	{feature}-integration.test.ts

Current Test Statistics

See the Domain Map for detailed coverage by business domain.

Quick Stats

Metric	Value
Total Test Files	33
Total Test Cases	895
Flows Covered	19
Partial Coverage	8
Missing Coverage	5

Coverage by Domain

Domain	Files	Cases
Guest Booking	4	162
Automation Engine	6	168
Payments & Billing	4	65
Media & Storage	2	105
Calendar Integration	3	111
Email & Notifications	7	256
Search & Discovery	1	65
Core Infrastructure	6	68

Quality Gates

Before marking tests complete:

• [ ] All tests pass (pnpm test)
• [ ] No TypeScript errors (pnpm check)
• [ ] Security tests for API/DB code
• [ ] Accessibility tests for UI components
• [ ] Edge cases covered (null, empty, invalid inputs)
• [ ] External services mocked
• [ ] Domain Map updated if new flows added

Claude Code Workflows

Standard Test Generation

For single-module tests or when you know the exact files:

/generate-tests [feature-name] path/to/file.ts

Full Test Workflow (4 Stages)

For business flows, follow the complete pipeline:

Stage	Command	Purpose
1. Scout	/scout-test-flow [flow-name]	Analyze complexity, create spec if needed
2. Generate	/generate-tests ...	Create test files
3. Sync	/sync-domain-map --auto	Update Domain Map coverage tracking
4. Document	/write-internal-docs testing	Update related docs

Stage 1 (Scout) determines complexity:

• Simple flows (score 0-1): Outputs a direct /generate-tests command
• Complex flows (score 2+): Creates a spec file

Stage 2 (Generate) runs in a fresh conversation:

• Simple: Run the command scout provided
• Complex: /generate-tests --spec=docs/testing/flows/[flow]-spec.md

Stage 3 (Sync) keeps the Domain Map accurate:

• Detects new/modified test files
• Updates flow statuses and test counts

Stage 4 (Document) updates feature documentation if needed.

See Complex Flow Testing for detailed workflow documentation.

Next Steps

• Testing Strategy - Philosophy and conventions
• Domain Map - Track what's tested
• Mock Factories Reference - Complete mock library documentation
• Testing Patterns - Svelte 5, API, and Worker testing patterns