Frontend Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The Frontend Testing Strategy for the tsz project focuses on validating business logic and data integrity while minimizing overhead on UI components. The strategy prioritizes the testing of shared schemas and server-side functions over individual React components. This approach ensures that data validation rules remain consistent between the client and the server, reducing the risk of runtime errors in the TanStack Start frontend.
The strategy is built upon the project's monorepo structure, utilizing bun as the primary task runner and Vitest as the testing framework for the web package. Core validation is driven by Zod schemas, which act as the single source of truth for form inputs and server function parameters.
Core Testing Principles
The frontend testing philosophy is defined by a "logic-first" approach. Developers are explicitly instructed to avoid creating tests for UI components, focusing instead on the underlying schemas and functions that drive application behavior.
Strategic Priorities
- Skip Component Tests: Developers should not create tests for individual UI components.
- Schema Validation: Extensive testing of Zod schemas to ensure data integrity.
- Server Function Integrity: Validation of
createServerFninputs using the same schemas used in the frontend. - Consolidation: Logic is consolidated in the
features/directory to facilitate easier testing and maintainability.
Sources: packages/web/CLAUDE.md:27, packages/web/CLAUDE.md:12-16, CHANGELOG.md:43
Technical Stack and Tools
The testing environment is integrated into the web package's build pipeline and workspace configuration.
| Tool | Purpose | Configuration File |
|---|---|---|
| Vitest | Main test runner for Typescript/React | packages/web/package.json |
| JSDOM | Browser environment simulation | packages/web/package.json |
| Testing Library | DOM and React utilities (available but secondary) | packages/web/package.json |
| Zod | Schema definition and validation logic | packages/web/src/features/ |
| Bun | Workspace management and script execution | package.json |
Sources: packages/web/package.json:34-40, package.json:42
Schema-Driven Validation Testing
The primary focus of frontend testing is the validation of Zod schemas. These schemas are used by @tanstack/react-form for client-side validation and by TanStack Start server functions for input sanitization.
Testing Pattern for Schemas
Tests for schemas (e.g., customers.schemas.spec.ts) typically verify:
- Positive Cases: Valid objects that meet all criteria.
- Required Fields: Rejection of missing or empty required strings (e.g., name, country).
- Format Validation: Correct identification of invalid email formats.
- Edge Cases: Handling of whitespace-only strings or empty optional fields.
A flowchart showing the validation path from schema definition through test cases to UI feedback.
Sources: packages/web/src/features/customers/customers.schemas.spec.ts:1-50, packages/web/CLAUDE.md:8-11
Integration with Server Functions
The testing strategy ensures that server-side functions are protected by the same validation logic as the frontend. Every createServerFn must pass a Zod schema to .inputValidator.
Data Validation Flow
A sequence diagram illustrating how Zod schemas act as a gatekeeper for both the React UI and the server functions.
Sources: packages/web/src/features/users/users.functions.ts:9-15, packages/web/CLAUDE.md:12-16
Execution and Scripts
Tests are executed via the workspace root or within the specific package directory using bun.
- Run Web Tests:
bun run test:web(runsvp testwithin the web package). - Run All Tests:
bun run test:all(executes both web tests and .NET API tests).
Sources: package.json:15-16, packages/web/package.json:11
Quality Control and Maintenance
The project incorporates automated tools to maintain code quality alongside the testing strategy.
- Dead Code Detection: The
fallowtool is used to identify dead code, duplicate code, and overall project health. - Linting and Formatting: Scripts like
check:fixensure that generated code (such as API schemas) and manual implementations adhere to standards.
Sources: packages/web/package.json:12-16, package.json:12
Summary
The frontend testing strategy in tsz is highly pragmatic, shifting focus from visual component testing to robust data validation. By centering the strategy on shared Zod schemas and server function validation, the project ensures that business rules are strictly enforced across the stack with minimal maintenance of brittle UI tests.