TS Testing

This skill guides you to build pragmatic, maintainable test suites for TypeScript code. Focus on behavioral coverage, fast feedback, and alignment with the project's existing tooling.

The user is a TypeScript‑focused developer. They likely care about correctness, refactoring safety, and not drowning in flaky or brittle tests.

When to use this skill

Use this skill when:

• The user is adding or updating unit, integration, or end‑to‑end tests
• The user reports a bug and wants a regression test
• The user is refactoring and wants confidence they didn’t break behavior
• The repo has test tooling configured (or clearly needs one) and you’re asked to “add tests” or “improve tests”

Do not invent a new test stack if the repo already has one. First detect and follow the existing setup.

Library preferences

Always align with the repo first (check package.json, devDependencies, config files):

• If the repo already uses a framework (Jest, Vitest, Playwright, Cypress, etc.), stick with it.
• Only suggest new libraries if there is no obvious testing stack yet.

When you must choose, prefer:

• Unit / integration tests
  • Node / backend / shared libraries:
    • Prefer Vitest (vitest) or Jest (jest)
    • If vitest is present, use it. Else if jest is present, use that.
• React / UI component tests
  • Use Testing Library with the existing runner:
    • @testing-library/react with Vitest or Jest
• End‑to‑end browser tests
  • Prefer Playwright if installed or if starting from scratch
  • Use Cypress if the repo already uses it or the user asks for it explicitly

If the repo uses a less common stack (Mocha, Ava, Node’s built‑in test runner), respect that choice and adapt.

Core testing philosophy

Follow these principles:

• Test behavior, not implementation details
  • For React/UI: test what the user sees and does (DOM, events, ARIA), not internal state or private methods
  • For services: test public APIs, not private helpers
• Keep tests fast and focused
  • Prefer small, deterministic tests that run quickly
  • Avoid unnecessary network, filesystem, or database calls unless you are explicitly writing integration tests
• Make failures obvious
  • Clear naming and assertions that explain why a test failed
  • Use descriptive test names following “given/when/then” style where helpful
• Minimize mocking, but use it where it makes sense
  • Mock external services, network calls, and slow dependencies
  • Avoid mocking your own business logic unless there’s a strong reason

Standard workflow

When asked to add or improve tests, follow this workflow:

1. Detect the existing stack

   • Inspect package.json for jest, vitest, @playwright/test, cypress, @testing-library/*
   • Look for config files: jest.config.*, vitest.config.*, playwright.config.*, cypress.config.*
   • Check test, unit, or e2e scripts in package.json

2. Locate the right place for the test

   • Mirror existing patterns:
     • If tests live in __tests__ directories, follow that
     • If they use *.test.ts or *.spec.ts, do the same
   • For UI: place tests near the component (e.g. Component.test.tsx) if that’s the existing convention

3. Write the test in a TS‑friendly way

   • Use .test.ts / .test.tsx (or .spec) as per repo convention
   • Avoid any in tests when possible; use real types or minimal interfaces to keep tests robust
   • For async code: use await with async test functions, avoid dangling promises

4. Follow library‑specific best practices

   Vitest / Jest

   • Use describe / it or test with clear names
   • Prefer vi.fn() / jest.fn() for spies and mocks
   • For modules: use vi.mock() / jest.mock() and keep mocks at the top of the file
   • For timers: use fake timers only when necessary (vi.useFakeTimers() / jest.useFakeTimers())

   React Testing Library

   • Use render, screen, and user interactions (userEvent)
   • Query by role, label, text as a user would (prefer getByRole, getByLabelText)
   • Avoid querying by test IDs unless there’s no good semantic alternative

   Playwright / Cypress

   • Use existing fixtures and helpers (e.g. authenticated sessions, base URL) instead of re‑inventing them
   • Keep tests independent; don’t rely on order
   • Use data-testid or semantics consistently as locators

5. Add regression tests for reported bugs

   • Reproduce the bug in a failing test first
   • Only then change the implementation to make the test pass
   • Name regression tests clearly (e.g. it("does not crash when X is null (regression #123)"))

6. Running tests

   • Use existing scripts, e.g. npm test, pnpm test, npx vitest, npx jest, npx playwright test
   • If adding a new test command, wire it into package.json scripts following existing style

Patterns to prefer

• One behavior per test: Don’t cram multiple unrelated assertions into a single test unless they’re part of the same scenario.
• Helper factories: Use small factory functions for building test data (makeUser, makeOrder) instead of duplicating setup.
• Explicit async handling: Always await promises; avoid passing async callbacks to APIs that don’t expect them.

Anti‑patterns to avoid

• Overuse of snapshots for complex objects or DOM – use targeted assertions instead
• Testing private methods directly
• Heavy mocking that makes tests mirror implementation wiring
• Flaky tests that depend on real time, network, or global state without control

TypeScript‑specific guidance

• Use the project’s tsconfig for tests when possible (tsconfig.test.json if present)
• Avoid silencing type errors just to “get tests compiling”
• When stubbing data, create minimal typed helpers rather than using as any

If the user asks you to generate tests, prefer fewer, high‑value tests that mirror real usage over large, mechanical test suites.