typescript-testing

TypeScript Testing Rules

Prerequisite Detection

Inspect package.json, the lockfile, test configuration, and existing test imports before selecting a framework or command. Apply Vitest-specific rules only when Vitest is configured; otherwise use the repository's configured TypeScript test harness while preserving the behavior, isolation, and evidence rules below. If no runnable harness is identifiable, report the inspected paths and missing command or configuration.

Test Framework

• Vitest: Use when selected by repository configuration or existing tests
• Test imports: import { describe, it, expect, beforeEach, vi } from 'vitest'
• Mock creation: Use vi.mock()

Basic Testing Policy

Quality Requirements

• Regression protection: concentrate tests on critical paths, business logic, and behavior whose regression would matter. Add a test when an unguarded behavior creates a material regression risk
• Independence: Each test can run independently without depending on other tests
• Reproducibility: Control time, randomness, environment values, and external I/O so identical inputs produce the same observable result
• Readability: Each test names one behavior, separates setup/action/assertion, and keeps fixtures limited to values used by that behavior

Test Types and Scope

1. Unit Tests

   • Verify behavior of individual functions or classes
   • Mock all external dependencies

2. Integration Tests

   • Verify coordination between multiple components
   • Use real in-process components that are part of the behavior under test; for external I/O see Mock Scope Decision
   • Verify flows that implement a primary acceptance criterion or cross an in-process component boundary

3. Cross-functional Verification

   • When a new feature reaches a shared integration point, continuity of the existing feature becomes a proof obligation if its failure would break a primary user journey or public contract, or degrade a secondary observable behavior. Prove it at the cheapest boundary that can expose its failure
   • Verification pattern: Existing feature operation -> Enable new feature -> Verify continuity of existing features
   • Success criteria: Preserve the response fields and observable behavior named by the source acceptance criteria; apply a processing-time threshold only when a requirement or project configuration defines its value and measurement method
   • Designed for automatic execution in CI/CD pipelines