writing-tests

Writes tests following project conventions. Handles test file organization, runtime vs type tests, table-driven tests with Test module, and type assertions with Assert API.

⭐4stars🔀0forks📁View on GitHub🕐Updated Dec 22, 2025

When & Why to Use This Skill

This Claude skill automates the generation of standardized unit and type tests, ensuring code reliability through project-specific conventions. It excels at creating table-driven tests, managing runtime and type-level assertions, and organizing test files for optimal maintainability in TypeScript projects using specialized Test and Assert APIs.

Use Cases

  • Automating the creation of table-driven unit tests for complex functions to ensure comprehensive edge-case coverage and input/output validation.
  • Developing TypeScript type-level tests (.test-d.ts) to validate type safety, generic constraints, and API contracts using the Assert API.
  • Standardizing test file organization by automatically colocating test files with modules and following naming conventions like _.test.ts for better project structure.
  • Implementing robust error reporting in test suites by utilizing value-level assertions that report all failures simultaneously rather than short-circuiting.
  • Refactoring sprawling test code into concise, high-performance test suites that follow best practices like avoiding redundant describe blocks.
namewriting-tests
descriptionWrites tests following project conventions. Handles test file organization, runtime vs type tests, table-driven tests with Test module, and type assertions with Assert API.

Writing Tests

Steps

  1. Create test file colocated with module: _.test.ts for module tests, <file>.test.ts for complex parts
  2. Import the namespace: import { ModuleName } from './_.js'
  3. Write tests using appropriate patterns below

Reference

Test Categories

Category File Purpose
Runtime .test.ts Test runtime behavior
Type .test-d.ts Validate TypeScript types via tsc

Table-Driven Tests (Preferred)

Use Kit's Test module for table-driven tests:

import { Test } from '@kitz/test'

// Function mode - types inferred from function
Test.on(add)
  .cases(
    [[2, 3], 5],
    [[-1, 1], 0]
  )
  .test()

// Describe mode - with custom types
Test.describe('Transform')
  .inputType<string>()
  .outputType<string>()
  .cases(['hello', 'HELLO'])
  .test(({ input, output }) => {
    expect(input.toUpperCase()).toBe(output)
  })

Type Assertions

Use value-level Assert API (reports ALL errors, not just first):

import { Assert } from '@kitz/assert'

// Preferred - value-level
Assert.exact.ofAs<string>().on(value)

// In .test-d.ts - flat type aliases (no test blocks)
type _pass1 = Assert.exact.of<string, string>

// @ts-expect-error - testing that types fail
type _fail1 = Assert.exact.of<string, number>

File Organization

src/foo/
├── _.test.ts              # Module tests (simple interface)
└── complex-part.test.ts   # Dedicated tests for complex parts

Notes

  • Don't use top-level describe blocks repeating module name - file path provides context
  • Don't wrap Test.on() inside Vitest describe - Test module creates its own
  • Don't use Assert.Cases<> - it short-circuits on first error
  • Prefer fast-check for property-based testing when applicable
  • Be concise - don't write sprawling test code