Scaffold Tests

Scaffold Advanced Testing Infrastructure

You are setting up advanced testing infrastructure for a mission-critical TypeScript project. This skill goes beyond the basic unit/integration tests set up by /project-init and /scaffold-module, adding specialized testing techniques that validate test quality, service integration, performance, and resilience.

Available Test Types

Instructions

1. Determine test types

If $ARGUMENTS is provided, parse it as a comma-separated list of keys. Otherwise, ask the user which test types to set up using a multi-select question.

2. Load context

• Read package.json for test runner (Vitest expected per coding standard), dependencies, and scripts
• Read tsconfig.json for TypeScript configuration
• Scan src/ for existing modules (to scope mutation testing)
• Read .claude/docs/TypeScript Coding Standard for Mission-Critical Systems.md if present

Type: mutation — Mutation Testing (Stryker)

Mutation testing evaluates test suite quality by making small changes to source code ("mutants") and checking if tests detect them. The coding standard requires >= 95% branch coverage (Rule 9.1) — mutation testing validates that this coverage is meaningful.

1. Generate stryker.config.mjs:

   /** @type {import('@stryker-mutator/api/core').PartialStrykerOptions} */
   export default {
     packageManager: 'npm',
     reporters: ['html', 'clear-text', 'progress'],
     testRunner: 'vitest',
     checkers: ['typescript'],
     tsconfigFile: 'tsconfig.json',
     vitest: {
       configFile: 'vitest.config.ts',
     },
     coverageAnalysis: 'perTest',
     incremental: true,
     incrementalFile: '.stryker-tmp/incremental.json',
     thresholds: {
       high: 90,
       low: 80,
       break: 75,
     },
     mutate: ['src/**/*.ts', '!src/**/*.test.ts', '!src/**/*.spec.ts', '!src/**/index.ts'],
     tempDirName: '.stryker-tmp',
   };
   

2. Add to .gitignore: .stryker-tmp/, reports/mutation/

3. Add npm scripts:

   {
     "mutation-test": "stryker run",
     "mutation-test:incremental": "stryker run --incremental"
   }
   

4. List install commands:

   npm install --save-exact -D @stryker-mutator/core @stryker-mutator/vitest-runner @stryker-mutator/typescript-checker
   

5. Usage guidance: Explain that mutation testing is computationally expensive. Recommend:

   • Run incrementally during development (npm run mutation-test:incremental)
   • Run full mutation analysis in CI on a nightly schedule
   • Start with core business logic modules, not the entire codebase
   • A surviving mutant means: "if this code changed, no test would fail"

6. If CI pipeline exists (.github/workflows/), suggest adding a nightly mutation testing job.

Type: contract — Contract Testing (Pact)

Contract testing validates API compatibility between services without requiring all services to run simultaneously. Consumer-Driven Contracts (CDC) let the consumer define expectations and the provider verify them.

1. Ask the user:

   • Is this service a consumer, provider, or both?
   • What API endpoints/operations need contracts?
   • Is there a Pact Broker URL (or use local file-based contracts)?

2. Generate directory structure: tests/contract/

3. For consumers, generate tests/contract/consumer.test.ts:

   import { describe, it, expect } from 'vitest';
   import { PactV3, MatchersV3 } from '@pact-foundation/pact';
   
   const provider = new PactV3({
     consumer: '<consumer-name>',
     provider: '<provider-name>',
     dir: './pacts',
   });
   
   describe('<Provider> API Contract', () => {
     it('should return a valid response for GET /endpoint', async () => {
       await provider
         .given('a specific state')
         .uponReceiving('a request for data')
         .withRequest({
           method: 'GET',
           path: '/endpoint',
         })
         .willRespondWith({
           status: 200,
           headers: { 'Content-Type': 'application/json' },
           body: MatchersV3.like({
             // Match the expected shape using the module's Zod schema
           }),
         })
         .executeTest(async (mockServer) => {
           // Call your client code against mockServer.url
           // Assert on the result
         });
     });
   });
   

4. For providers, generate tests/contract/provider.test.ts:

   import { Verifier } from '@pact-foundation/pact';
   
   describe('Provider Verification', () => {
     it('should fulfill all consumer contracts', async () => {
       const verifier = new Verifier({
         providerBaseUrl: 'http://localhost:3000',
         pactUrls: ['./pacts/consumer-provider.json'],
         // Or: pactBrokerUrl: process.env.PACT_BROKER_URL,
         stateHandlers: {
           'a specific state': async () => {
             // Set up the provider state
           },
         },
       });
       await verifier.verifyProvider();
     });
   });
   

5. Generate pacts/.gitkeep and tests/contract/README.md explaining the workflow.

6. Add npm scripts:

   {
     "test:contract:consumer": "vitest run tests/contract/consumer",
     "test:contract:provider": "vitest run tests/contract/provider"
   }
   

7. List install commands:

   npm install --save-exact -D @pact-foundation/pact
   

Type: load — Load Testing (k6)

Load testing validates performance under expected and peak traffic conditions. k6 provides high-performance execution with built-in thresholds.

1. Ask the user:

   • Target service URL/endpoint (default: http://localhost:3000)
   • Expected requests per second at steady state
   • Acceptable latency thresholds (p95, p99)
   • Acceptable error rate threshold
   • Test duration

2. Generate tests/load/ directory with:

   tests/load/config.ts: Typed configuration constants

   export const LOAD_TEST_CONFIG = {
     baseUrl: process.env.LOAD_TEST_URL ?? 'http://localhost:3000',
     thresholds: {
       http_req_duration_p95_ms: 200,
       http_req_duration_p99_ms: 500,
       http_req_failed_rate: 0.01, // 1% error rate
     },
     scenarios: {
       warmUp: { duration: '30s', vus: 5 },
       rampUp: { duration: '1m', target: 50 },
       sustained: { duration: '3m', vus: 50 },
       spike: { duration: '30s', target: 100 },
       coolDown: { duration: '30s', target: 0 },
     },
   } as const;
   

   tests/load/main.ts: k6 test script with scenarios, thresholds, and checks.

   tests/load/README.md: How to run tests, interpret results, and adjust scenarios.

3. Add npm scripts:

   {
     "test:load": "k6 run tests/load/main.ts"
   }
   

4. Note: k6 must be installed separately (it's a Go binary, not an npm package). Provide installation instructions for the user's platform.

Type: chaos — Chaos Testing (node-chaos-monkey)

Chaos testing validates system resilience by injecting controlled failures. This directly tests the coding standard's requirements around timeouts (Rule 4.2), error handling (Rule 6.2), and bounded operations (Rule 8.1).

1. Generate tests/chaos/ directory with:

   tests/chaos/config.ts: Chaos scenario configuration

   export const CHAOS_SCENARIOS = {
     dependencyTimeout: {
       description: 'Simulates slow downstream service',
       validates: 'AbortController + Promise.race (Rule 4.2)',
     },
     memoryPressure: {
       description: 'Validates memory limits and OOM handling',
       validates: 'Resource disposal (Rule 5.1)',
     },
     processCrash: {
       description: 'Validates restart and data consistency',
       validates: 'Graceful shutdown (Rule 12.2)',
     },
     random500: {
       description: 'Injects random 500 errors on routes',
       validates: 'Error handling (Rule 6.2)',
     },
     eventLoopBlock: {
       description: 'Blocks event loop to test health check responsiveness',
       validates: 'Timeout handling (Rule 4.2)',
     },
   } as const;
   

   tests/chaos/runner.ts: Test harness that:

   • Checks CHAOS_ENABLED=true environment variable (safety guard — never set in production)
   • Starts the application with chaos middleware injected
   • Runs a workload against the application
   • Validates that health checks still respond correctly
   • Validates that error counts are within acceptable bounds

   tests/chaos/README.md: Explains chaos testing, safety guardrails, and how to run scenarios.

2. Add npm scripts:

   {
     "test:chaos": "CHAOS_ENABLED=true vitest run tests/chaos"
   }
   

3. List install commands:

   npm install --save-exact -D node-chaos-monkey
   

4. Safety guardrails: Emphasize that chaos testing must NEVER run in production. The CHAOS_ENABLED env var must not be set in any production environment. Add a comment in .env.example documenting this.

Summary

After setting up all selected test types:

1. List all created files and directories
2. List all install commands the user needs to run
3. Explain how each test type integrates with CI:
   • mutation: Nightly scheduled job
   • contract: On every PR (consumer tests) and on release (provider verification)
   • load: Weekly scheduled job or before each release candidate
   • chaos: Periodic game day exercises, not on every PR
4. Note that all generated test code follows the coding standard (no any, Result patterns where applicable, TSDoc)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.