The tests subject contains utilities, helpers, and infrastructure to support automated testing across docs.github.com. This includes test helpers, mock servers, schema validation, and shared testing patterns.

This subject is responsible for:

• Test utilities and helper functions shared across subjects
• Mock server infrastructure for integration tests
• Schema validation utilities (AJV)
• Test data and fixtures management
• Vitest configuration and setup
• TypeScript declarations for test tooling
• Shared testing patterns and conventions

Tests are written using Vitest for unit and integration tests, and Playwright for end-to-end browser tests.

• lib/validate-json-schema.ts - AJV validator factory for JSON schema validation
• mocks/start-mock-server.ts - Creates mock HTTP server for integration tests
• helpers/e2etest.ts - Utilities for end-to-end testing scenarios
• vitest.setup.ts - Global Vitest configuration and hooks

Test-only dependencies are optional to keep standard installs faster:

npm ci --include=optional

npm test

Continuously re-runs tests on file changes:

npm run test-watch

# By filename or path
npm test -- <TEST_NAME>

# By directory
vitest src/search/tests

# Single test file
vitest src/versions/tests/versions.ts

By default, console.log is suppressed. To see output:

npm test -- <TEST_NAME> --silent=false

Some tests require a production build:

npx next build
npm test

Error: Could not find a production build means you need to run next build.

• Vitest - Test runner and assertion library
• Playwright - Browser automation for E2E tests
• AJV - JSON schema validation
• Mock server libraries for HTTP mocking

• Fixture content in src/fixtures/
• Schema files in helpers/schemas/
• Mock responses in mocks/

Tests that make HTTP requests to localhost:4000:

• Vitest automatically starts/stops server via hooks
• Disable with START_VITEST_SERVER=false for manual server control

Manual server for debugging:

# Terminal 1
NODE_ENV=test PORT=4000 tsx src/frame/server.ts

# Terminal 2
START_VITEST_SERVER=false vitest src/versions/tests

• src/fixtures - Fixture-based testing with minimal content
• All subjects with /tests/ directories - Test consumers
• CI workflows in .github/workflows/ - Automated test execution

• Fixture content - Fixture-based testing patterns
• Playwright E2E tests - Headless browser testing

• Team: Docs Engineering

Unit tests - Test individual functions/modules:

import { describe, test, expect } from 'vitest'

describe('myFunction', () => {
  test('returns expected value', () => {
    expect(myFunction('input')).toBe('output')
  })
})

Integration tests - Test HTTP endpoints:

import { get } from '@/tests/helpers/e2etest'

test('GET /search returns results', async () => {
  const res = await get('/search?query=test')
  expect(res.statusCode).toBe(200)
})

Playwright tests - Browser automation:

test('search works in browser', async ({ page }) => {
  await page.goto('/search')
  await page.fill('input[name="query"]', 'test')
  // ...assertions
})

Middleware errors are suppressed by default in tests. To see full errors:

export DEBUG_MIDDLEWARE_TESTS=true
vitest src/shielding/tests

npm run lint

• Optional dependencies must be installed for local testing
• Some tests require production build (next build)
• Server startup/shutdown adds overhead to test runs
• Fixtures may lag behind actual content structure

Tests should be co-located with their subject:

• ✅ src/search/tests/api-search.ts
• ✅ src/versions/tests/middleware.ts
• ❌ src/tests/search-tests.ts (wrong - not in subject)

Shared utilities belong in src/tests/:

• Helper functions used across subjects
• Mock servers and fixtures
• Schema validation utilities
• Test infrastructure

1. Create a file in src/tests/helpers/
2. Export reusable functions
3. Document usage with JSDoc
4. Add tests for the helper itself
5. Import in test files across subjects

Tests run automatically in GitHub Actions:

• On pull requests
• On pushes to main
• Various test suites in parallel for speed

See .github/workflows/ for CI configuration.

Tests fail with missing build: Run npx next build before tests.

Tests hang or timeout: Check if server started correctly. Use DEBUG_MIDDLEWARE_TESTS=true.

Flaky tests:

• Check for race conditions
• Ensure proper test isolation
• Verify mocks are properly reset

Mock server issues: Check src/tests/mocks/start-mock-server.ts is running and configured correctly.