Storybook & Component Testing
Relevant source files
The following files were used as context for generating this wiki page:
Storybook and component testing within the dotorixel project serve as the primary environment for UI development, visual verification, and regression defense. The project utilizes Storybook 10 with Svelte CSF v5 to provide an isolated playground for components, ensuring they behave correctly across various themes (Pebble, Pixel) and responsive breakpoints.
The testing strategy transitions from pure logic testing in Vitest to comprehensive component mounting tests and End-to-End (E2E) verification via Playwright. This multi-layered approach ensures that UI components not only render correctly but also handle user interactions and state synchronizations as expected.
Sources: CLAUDE.md:14, tasks/records/001-pre-workflow-migration.md:20
Storybook Architecture
Storybook is integrated into the Vite-based build pipeline, leveraging @storybook/sveltekit for seamless framework integration. The project follows a "co-location" principle where story files reside immediately next to their corresponding components.
Story Formatting and Metadata
Dotorixel adheres to specific standards for story creation:
- Format: Svelte Component Story Format (CSF) v5 using the
<script module>context. - Metadata: Components use
defineMetato establish story settings. - Hierarchy: Automatic sidebar hierarchy is generated from the file path. Manual
titleproperties are only used when the desired organizational structure differs from the physical file location. - Data Provisioning: Stories use pure data factory functions (e.g.,
createCanvas()) to ensure deterministic and side-effect-free test data.
Sources: CLAUDE.md:124-135
Design Token Verification
Storybook is used extensively to document and verify the design system. Special stories, such as DesignTokens.stories.svelte, visualize the application's color pairs, typography samples (Galmuri fonts), spacing scales, and border styles.
The diagram shows how Storybook integrates with the tech stack to provide both visual documentation and interaction testing environments.
Sources: CLAUDE.md:14, tasks/records/046-editor-layout-restructure.md:100
Component Mounting Tests
Dotorixel utilizes Vitest along with @testing-library/svelte for component-level testing. These tests focus on external behavior through props and callback boundaries rather than internal implementation details.
Test Patterns and Standards
- Environment: Tests run in
happy-domwithresolve.conditions: ['browser']configured in Vitest to ensure Svelte 5 client-side resolution. - Interaction Simulation:
@testing-library/svelte'srenderandfireEventare used to simulate user input, which is necessary due to Svelte 5's event delegation. - Mocking: I/O, global state, and randomness are mocked to ensure test stability.
Sources: CLAUDE.md:131-133, issues/011-canvas-size-control.md:120-135
Key Test Case Examples
The project implements specific test cases for complex components like CanvasSizeControl:
| Test Category | Description | Derived Source |
|---|---|---|
| Interaction | Clicking preset buttons calls onResize with specific dimensions. | issues/011-canvas-size-control.md:75 |
| Validation | Typing invalid dimensions shows a ValidationAlert and suppresses the resize callback. | issues/011-canvas-size-control.md:78 |
| Synchronization | External prop changes must reset internal draft state and clear validation alerts. | issues/011-canvas-size-control.md:79 |
| A11y/UI Variants | Verification that touch variants render labels while compact variants do not. | issues/011-canvas-size-control.md:83 |
End-to-End (E2E) Testing
For behaviors that cannot be verified through unit or component tests—such as language navigation and URL-based routing—the project employs Playwright.
Playwright Configuration
Playwright is used to verify the landing page and locale-switching logic. This is critical because SvelteKit's client-side navigation requires verification that URL changes correctly trigger content updates via the Paraglide.js i18n engine.
This sequence diagram illustrates the E2E flow for testing internationalization and routing logic.
Sources: tasks/records/037-landing-page.md:50-58
Summary of Testing Infrastructure
The following table summarizes the tools and their roles in the testing ecosystem:
| Tool | Scope | Key Configuration / Files |
|---|---|---|
| Vitest | Unit & Component Tests | vitest.config.ts, *.test.ts |
| Storybook | Visual & Manual Review | .storybook/preview.ts, *.stories.svelte |
| Playwright | E2E & Routing Tests | playwright.config.ts, e2e/*.test.ts |
| Svelte Testing Library | DOM Interaction | Part of component test suites |
| Paraglide.js | i18n Verification | Integrated into E2E suites |
Sources: CLAUDE.md:14, tasks/records/037-landing-page.md:45, issues/011-canvas-size-control.md:120
Key Principles for Developers
- Tests are Specifications: Tests should describe the behavioral outcome of the module.
- Behavior over Implementation: Assertions should be made on outcomes (e.g., "callback called") rather than internal state changes.
- Regression Defense: Priority is given to edge cases in coordinate math, boundary conditions, and state consistency (undo/redo).
- Guard the Dev/Prod Gap: CI must verify production builds to catch issues like WASM loading failures or CSP enforcement that do not appear in development mode.
Sources: CLAUDE.md:148-160