typescript-test
Provides Vitest-based TypeScript testing expertise and best practices. Ensures proper test structure, mocking strategies, async handling patterns, and coverage optimization. Specializes in unit testing, integration testing, test organization with describe/it blocks, vi.mock patterns, snapshot testing, and testing library integration for UI components.Use when: writing TypeScript test files (.spec.ts, .test.ts), structuring tests with describe/it/test blocks, implementing mocks with vi.mock/vi.spyOn, testing async code with async/await or promises, creating test fixtures and helpers, implementing snapshot tests, testing React components with Testing Library, measuring and improving code coverage, or configuring Vitest for TypeScript projects.
When & Why to Use This Skill
This Claude skill provides comprehensive expertise in TypeScript testing using the Vitest framework. It streamlines the creation of high-quality test suites by enforcing best practices in test structure, advanced mocking strategies, and asynchronous code handling. By integrating patterns like Given-When-Then and specialized UI testing tools, it helps developers ensure code reliability, optimize coverage, and maintain scalable TypeScript codebases.
Use Cases
- Case 1: Structuring unit tests for complex TypeScript services using standardized naming conventions and hierarchical describe/it blocks.
- Case 2: Implementing sophisticated mocking for external dependencies, APIs, and databases using vi.mock and vi.spyOn to ensure isolated test environments.
- Case 3: Testing asynchronous logic and Promise rejections to validate error handling and edge cases in modern TypeScript applications.
- Case 4: Integrating React Testing Library with Vitest to perform component-level testing and ensure UI reliability.
- Case 5: Optimizing CI/CD pipelines by configuring meaningful code coverage metrics and identifying untested critical business logic.
| name | typescript-test |
|---|---|
| description | | |
| Use when | writing TypeScript test files (.spec.ts, .test.ts), structuring tests with describe/it/test blocks, implementing mocks with vi.mock/vi.spyOn, testing async code with async/await or promises, creating test fixtures and helpers, implementing snapshot tests, testing React components with Testing Library, measuring and improving code coverage, or configuring Vitest for TypeScript projects. |
TypeScript Testing Code Guide
Test File Structure
One-to-one matching with the file under test. Test files should be located in the same directory as the target file.
File Naming
Format: {target-file-name}.spec.ts.
Example: user.service.ts → user.service.spec.ts
Test Framework
Use Vitest. Maintain consistency within the project.
Test Hierarchy
Organize by method (function) unit as major sections, and by test case as minor sections. Complex methods can have intermediate sections by scenario.
Test Coverage Selection
Omit obvious or overly simple logic (simple getters, constant returns). Prioritize testing business logic, conditional branches, and code with external dependencies.
Test Case Composition
At least one basic success case is required. Focus primarily on failure cases, boundary values, edge cases, and exception scenarios.
Test Independence
Each test should be executable independently. No test execution order dependencies. Initialize shared state for each test.
Given-When-Then Pattern
Structure test code in three stages—Given (setup), When (execution), Then (assertion). Separate stages with comments or blank lines for complex tests.
Test Data
Use hardcoded meaningful values. Avoid random data as it causes unreproducible failures. Fix seeds if necessary.
Mocking Principles
Mock external dependencies (API, DB, file system). For modules within the same project, prefer actual usage; mock only when complexity is high.
Test Reusability
Extract repeated mocking setups, fixtures, and helper functions into common utilities. Be careful not to harm test readability through excessive abstraction.
Integration/E2E Testing
Unit tests are the priority. Write integration/E2E tests when complex flows or multi-module interactions are difficult to understand from code alone. Place in separate directories (tests/integration, tests/e2e).
Test Naming
Test names should clearly express "what is being tested". Recommended format: "should do X when Y". Focus on behavior rather than implementation details.
Assertion Count
Multiple related assertions in one test are acceptable, but separate tests when validating different concepts.
Structure
Group methods/functionality with describe, write individual cases with it. Can classify scenarios with nested describe.
Mocking
Utilize Vitest's vi.mock(), vi.spyOn(). Mock external modules at the top level; change behavior per test with mockReturnValue, mockImplementation.
Async Testing
Use async/await. Test Promise rejection with await expect(fn()).rejects.toThrow() form.
Setup/Teardown
Use beforeEach, afterEach for common setup/cleanup. Use beforeAll, afterAll only for heavy initialization (DB connection, etc.).
Type Safety
Type check test code too. Minimize as any or @ts-ignore. Use type guards or type assertions explicitly when needed.
Test Utils Location
For single-file use, place at bottom of same file. For multi-file sharing, use __tests__/utils or test-utils directory.
Coverage
Code coverage is a reference metric. Focus on meaningful test coverage rather than blindly pursuing 100%.