plan-forge testing.instructions.md

Testing Instructions

When this loads: every time you edit, write, debug, or report on a test file. Sister script: scripts/audit/test-smells.mjs — mechanical scan for the patterns this file rules against.

---

The 6 Rules

1. Time-sensitive tests must declare tolerance OR use fake timers

The single biggest source of CI flake. Phase 41 Slice 5 reference incident: timeline-core cache-invalidation test used a +5ms tolerance — too tight for the Windows scheduler. Fix: bumped to +50ms (commit 0630fb5). Same class of bug has shipped at least three times in different files.

Two acceptable patterns. Anything else is a flake waiting to land on the worst possible PR.

Pattern A — fake timers (preferred when the test is about timing)

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';

describe('cache TTL', () => {
  beforeEach(() => vi.useFakeTimers());
  afterEach(() => vi.useRealTimers());

  it('expires after 5 minutes', () => {
    const cache = makeCache({ ttlMs: 5 * 60 * 1000 });
    cache.set('k', 'v');
    vi.advanceTimersByTime(5 * 60 * 1000 + 1);
    expect(cache.get('k')).toBeUndefined();
  });
});

Pattern B — explicit tolerance (only when you must measure real wall-clock)

const start = Date.now();
await operationUnderTest();
const elapsed = Date.now() - start;
// Comment required — names the tolerance + the reason for it.
// +50ms accommodates the Windows scheduler; Phase 41 S5 used +5ms and flaked.
expect(elapsed).toBeGreaterThanOrEqual(target);
expect(elapsed).toBeLessThan(target + 50);

Banned patterns (caught by test-smells.mjs as TIME-FLAKE):

• setTimeout(fn, N) in a test body without vi.useFakeTimers()
• Math.random() anywhere in a test — use a seeded RNG or fixture
• Date.now() / new Date() without vi.setSystemTime() or an explicit tolerance comment
• performance.now() without a tolerance comment

2. Never commit .only or focused tests