Testing Guidelines

Follow these principles when writing tests for this codebase.

Core Principles

1. Mock External Services, Use Real Fixtures

ALWAYS mock third-party network services. ALWAYS use fixtures based on real-world data.

Fixtures must be scrubbed of PII (use dummy data like foo@example.com, user-123)
Capture real API responses, then sanitize them
Never make actual network calls in tests

2. Prefer Integration Tests Over Unit Tests

Focus on end-to-end style tests that validate inputs and outputs, not implementation details.

Test the public interface, not internal methods
Unit tests are valuable for edge cases in pure functions, but integration tests are the priority
If refactoring breaks tests but behavior is unchanged, the tests were too coupled to implementation

3. Minimize Edge Case Testing

Don't test every variant of a problem.

Cover the common path thoroughly
Skip exhaustive input permutations
Skip unlikely edge cases that add maintenance burden without value
One representative test per category of input is usually sufficient

4. Always Add Regression Tests for Bugs

When a bug is identified, ALWAYS add a test that would have caught it.

The test should fail before the fix and pass after
Name it descriptively to document the bug
This prevents the same bug from recurring

Note: Regression tests are for unintentional broken behavior (bugs), not intentional changes. Intentional feature removals, deprecations, or breaking changes do NOT need regression tests—these are design decisions, not defects.

5. Cover Every User Entry Point

ALWAYS have at least one basic test for each customer/user entry point.

CLI commands, API endpoints, public/exported functions
Test the common/happy path first
This proves the entry point works at all

Note: "Entry point" means the public interface—exported functions, CLI commands, API routes. Internal/private functions are NOT entry points, even if they handle user-facing flags or options. Test entry points; internal functions get coverage through those tests.

6. Tests Validate Before Manual QA

Tests are how we validate ANY functionality works before manual testing.

Write tests first or alongside code, not as an afterthought
If you can't test it, reconsider the design
Passing tests should give confidence to ship

Technical Guidelines

File Organization

Test files use *.test.ts extension
Co-locate tests with source: foo.ts → foo.test.ts

Test Isolation

Every test must:

Run independently without affecting other tests
Use temporary directories for file operations
Clean up resources in afterEach hooks

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

describe('my feature', () => {
  let tempDir: string;

  beforeEach(() => {
    tempDir = join(tmpdir(), `warden-test-${Date.now()}`);
    mkdirSync(tempDir, { recursive: true });
  });

  afterEach(() => {
    rmSync(tempDir, { recursive: true, force: true });
  });

  it('does something with files', () => {
    writeFileSync(join(tempDir, 'test.ts'), 'content');
    // ... test code
  });
});

Pure Function Tests

For pure functions without side effects, no special setup is needed:

import { describe, it, expect } from 'vitest';
import { matchGlob } from './matcher.js';

describe('matchGlob', () => {
  it('matches exact paths', () => {
    expect(matchGlob('src/index.ts', 'src/index.ts')).toBe(true);
  });
});

Running Tests

pnpm test              # Run all tests in watch mode
pnpm test:run          # Run all tests once

Checklist Before Submitting

New entry points have at least one happy-path test
Bug fixes (not intentional changes) include a regression test
External services are mocked with sanitized fixtures
Tests validate behavior, not implementation
No shared state between tests

testing-guidelines