Testing Strategy & Frameworks
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for this monorepo is designed to ensure code quality across diverse environments, including UI components, CLI tools, and web applications. The project utilizes a multi-layered approach involving unit testing, end-to-end (E2E) testing, and specialized documentation testing to maintain high reliability and technical accuracy.
Testing tasks are orchestrated through Turborepo, allowing for cached and parallel execution across the workspace. The primary tools used include Vitest for unit/integration tests in React environments, Bun's built-in test runner for high-performance JavaScript/TypeScript testing, and Playwright for browser-based E2E scenarios.
Sources: AGENTS.md:65-71, package.json:16-18, turbo.json:17-27
Testing Layers and Frameworks
The project categorizes tests by the nature of the code being verified. Each package or app follows a specific framework pattern based on its technology stack.
Framework Allocation
| Test Category | Framework / Tool | Scope |
|---|---|---|
| UI Components | Vitest + React Testing Library | Component logic and rendering in @siluat/ui-craft. |
| E2E Tests | Playwright | User-facing applications like dotori-note. |
| CLI / Library | Bun Test | Computation logic and CLI behavior in color-contrast. |
| Rust Code | Cargo Test | Data extraction logic in noumenon-gleaner. |
| Doctests | Custom Bun Test | Synchronizing MDX documentation with API behavior. |
Sources: AGENTS.md:37-41, AGENTS.md:65-70, packages/color-contrast/src/doctest.test.ts:18-28
Test Co-location
Test files are generally co-located with their respective source files (e.g., foo.test.ts resides next to foo.ts) rather than being isolated in a separate __tests__/ directory. This promotes better visibility and maintenance of test coverage as features evolve.
Sources: AGENTS.md:71-72
Orchestration and Execution
Testing is integrated into the Turborepo pipeline. The following diagram illustrates the relationship between build tasks and testing execution.
The diagram shows that test tasks depend on the completion of build tasks to ensure artifacts are ready for verification.
Sources: turbo.json:17-27, package.json:17-18
Development Commands
Developers can execute tests at different scopes using the following commands:
turbo run test: Runs tests across all packages.turbo run test:coverage: Executes tests and generates coverage reports in thecoverage/directory.bun test: Local execution for specific packages using the Bun runner.
Sources: AGENTS.md:12-14, package.json:18, turbo.json:22-24
Specialized Testing Strategies
1. Documentation Testing (Doctest)
In the @siluat/color-contrast package, a specialized "Doctest" system ensures that documentation examples remain accurate as the API changes. It reads MDX files as a single source of truth, extracts TypeScript code blocks, and evaluates them against the actual library exports.
The system identifies assertions via // expected comments and compares the actual return values (serialized) against the documented expectations.
// Example of a testable block in library-api.mdx
const ratio = contrastRatio('#000', '#fff');
// 21
Sources: packages/color-contrast/src/doctest.test.ts:1-16, packages/color-contrast/src/doctest.test.ts:133-145
2. End-to-End (E2E) Testing
For user-facing applications like dotori-note, Playwright is used to simulate user interactions. This includes:
- Theme Switching: Verifying that clicking theme options correctly updates the
htmlclass andlocalStorage. - Heading Autolinks: Testing that MDX-generated headings have correct IDs, show link icons on hover, and support keyboard navigation.
- Visual Regression: Capturing screenshots on test failure for easier debugging.
Sources: apps/dotori-note/tests/header-switch-theme.spec.ts:127-160, apps/dotori-note/tests/heading-autolink.spec.ts:84-100
3. Visual Verification
For algorithmic changes (like color suggestions), the project uses visual check scripts that generate HTML comparison pages. This allows developers to verify that hue and saturation are preserved during contrast adjustments by rendering samples side-by-side.
Sources: packages/color-contrast-cli/scripts/visual-check.ts:1-12, packages/color-contrast-cli/scripts/README.md:1-15
Code Quality Standards
Testing is part of a broader "Static Check" strategy that combines type checking, linting, and formatting.
| Check Type | Tool | Command |
|---|---|---|
| Lint/Format | Biome | biome check . |
| Type Check | TypeScript | turbo run check-types |
| Git Hook | Lefthook | Pre-commit Biome checks |
Sources: AGENTS.md:19-25, package.json:21-23
Summary
The testing strategy focuses on maintaining a tight loop between implementation, documentation, and user experience. By utilizing Turborepo for orchestration and specialized tools like Playwright and custom Doctests, the project ensures that both internal logic and external documentation remain synchronized and functional.