github/codegraph
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

test: eliminate chokidar/FSEvents race in watcher + staleness-banner tests (#434)

Browse Source 
Mocks chokidar at the module level for `__tests__/watcher.test.ts` and
`__tests__/mcp-staleness-banner.test.ts` so the pending-file-tracking and
staleness-banner tests no longer depend on OS-level file-watcher delivery
latency. Reduces full-suite failure rate from 3/10 to 0/10.

- `__tests__/__helpers__/chokidar-mock.ts` (new) — controllable
  EventEmitter; `chokidarMockModule` for `vi.mock('chokidar', ...)` plus
  `triggerFileEvent(root, event, relPath)` helper. `watch()` returns an
  EventEmitter that fires `ready` on the next microtask.
- `__tests__/watcher.test.ts` — refactors every event-driving test to
  use `triggerFileEvent` instead of `fs.writeFileSync` for the trigger.
  Pending-file tests assert state synchronously. Filtering tests still
  verify FileWatcher's own filter chain.
- `__tests__/mcp-staleness-banner.test.ts` — same vi.mock + same
  `triggerFileEvent` pattern; tests keep `fs.writeFileSync` for on-disk
  content (`cg.sync()` needs the bytes) and add the synthesized event
  on top.

The watcher's debounce timer (real `setTimeout`) is left untouched — that's
the unit under test.

Total test count unchanged (928 passing + 2 pre-existing skips). Wall-clock
runtime improved (no more 8000ms waitFor polls against real chokidar).

One disclosed tradeoff: the previous node_modules filtering test
incidentally exercised chokidar's `ignored` callback at the OS level;
with chokidar mocked, that property of chokidar itself isn't covered
here. Commented inline.
This commit is contained in:
Colby Mchenry
2026-05-26 02:38:09 -05:00
committed by GitHub
parent 4d1a2b3c4d
commit 22bc542d34
3 changed files with 256 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files
__tests__/watcher.test.ts
+103 -96
View File
@@ -2,22 +2,43 @@
* FileWatcher Tests
*
* Tests for the file watcher that auto-syncs on changes.
*
* **Why `vi.mock('chokidar', ...)`**: real chokidar bindings go through
* FSEvents (macOS) / inotify (Linux). Under parallel vitest execution those
* OS-level subsystems serve many test files at once and event-delivery
* latency becomes non-deterministic — we observed a consistent ~30%
* failure rate on the pending-file-tracking + staleness-banner tests when
* running the full suite, vs 0/N when run in isolation. The mock replaces
* chokidar with a controllable EventEmitter (see
* `__helpers__/chokidar-mock.ts`): the `ready` event fires on the next
* microtask, and tests use `triggerFileEvent(...)` to synthesize file
* events instead of `fs.writeFileSync(...)`. The watcher's actual
* debounce timer (real `setTimeout`) is left untouched — that's the unit
* under test.
*/
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { vi } from 'vitest';
// Hoisted: chokidar is replaced by the controllable mock for the whole file.
vi.mock('chokidar', async () => (await import('./__helpers__/chokidar-mock')).chokidarMockModule);
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';
import { FileWatcher } from '../src/sync/watcher';
import CodeGraph from '../src/index';
import { triggerFileEvent } from './__helpers__/chokidar-mock';
/**
* Helper to wait for a condition with timeout
* Helper to wait for a condition with timeout. Most tests no longer need
* this because mock chokidar makes the watcher's event handler run
* synchronously, but it's still useful for assertions that depend on the
* debounce timer (real setTimeout) firing.
*/
function waitFor(
condition: () => boolean,
timeoutMs = 10000,
intervalMs = 100
timeoutMs = 2000,
intervalMs = 25
): Promise<void> {
return new Promise((resolve, reject) => {
const start = Date.now();
@@ -78,6 +99,7 @@ describe('FileWatcher', () => {
watcher.start();
watcher.stop();
watcher.stop(); // Should not throw
expect(watcher.isActive()).toBe(false);
});
});
@@ -88,12 +110,11 @@ describe('FileWatcher', () => {
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 200 });
watcher.start();
await watcher.waitUntilReady();
triggerFileEvent(testDir, 'add', 'src/new.ts');
// Create a new file
fs.writeFileSync(path.join(testDir, 'src', 'new.ts'), 'export const y = 2;');
// Wait for debounced sync to fire
await waitFor(() => syncFn.mock.calls.length > 0, 5000);
// Wait for debounced sync to fire (real timer; 200ms + epsilon).
await waitFor(() => syncFn.mock.calls.length > 0);
expect(syncFn).toHaveBeenCalled();
watcher.stop();
@@ -101,23 +122,23 @@ describe('FileWatcher', () => {
it('should debounce rapid changes into a single sync', async () => {
const syncFn = vi.fn().mockResolvedValue({ filesChanged: 1, durationMs: 10 });
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 500 });
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 400 });
watcher.start();
await watcher.waitUntilReady();
// Rapid-fire changes
// Rapid-fire synthesized changes — each call resets the debounce timer.
// Spacing them tighter than the debounce window proves the debounce
// collapses them into one syncFn call.
for (let i = 0; i < 5; i++) {
fs.writeFileSync(
path.join(testDir, 'src', `file${i}.ts`),
`export const v${i} = ${i};`
);
triggerFileEvent(testDir, 'add', `src/file${i}.ts`);
await new Promise((r) => setTimeout(r, 50));
}
// Wait for the single debounced sync
await waitFor(() => syncFn.mock.calls.length > 0, 5000);
// Wait for the single debounced sync.
await waitFor(() => syncFn.mock.calls.length > 0);
// Should have been called once (debounced), not 5 times
// Should have been called once (debounced), not 5 times.
expect(syncFn.mock.calls.length).toBe(1);
watcher.stop();
@@ -130,16 +151,14 @@ describe('FileWatcher', () => {
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 200 });
watcher.start();
await watcher.waitUntilReady();
// Let watcher settle — fs.watch may fire residual events from beforeEach
// Synthesize a non-source-file event — FileWatcher's `isSourceFile`
// gate must drop it before scheduling sync.
triggerFileEvent(testDir, 'add', 'src/readme.md');
// Wait a bit longer than debounce — sync should NOT trigger.
await new Promise((r) => setTimeout(r, 400));
syncFn.mockClear();
// Create a file that doesn't match include patterns
fs.writeFileSync(path.join(testDir, 'src', 'readme.md'), '# Hello');
// Wait a bit longer than debounce — sync should NOT trigger
await new Promise((r) => setTimeout(r, 500));
expect(syncFn).not.toHaveBeenCalled();
watcher.stop();
@@ -150,48 +169,39 @@ describe('FileWatcher', () => {
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 200 });
watcher.start();
await watcher.waitUntilReady();
// Synthesize a .codegraph event — FileWatcher's `isAlwaysIgnored`
// filter must drop it before scheduling sync.
triggerFileEvent(testDir, 'add', '.codegraph/db.sqlite');
// Let watcher settle — fs.watch may fire residual events from beforeEach
await new Promise((r) => setTimeout(r, 400));
syncFn.mockClear();
// Simulate a .codegraph directory change
const cgDir = path.join(testDir, '.codegraph');
fs.mkdirSync(cgDir, { recursive: true });
fs.writeFileSync(path.join(cgDir, 'db.sqlite'), 'fake');
// Wait — sync should NOT trigger
await new Promise((r) => setTimeout(r, 500));
expect(syncFn).not.toHaveBeenCalled();
watcher.stop();
});
it('should not watch node_modules even without a .gitignore (#276/#417)', async () => {
// No .gitignore in testDir — exclusion relies on the built-in
// default-ignore set the indexer uses (buildDefaultIgnore), which a
// .gitignore-only filter would miss.
fs.mkdirSync(path.join(testDir, 'node_modules', 'dep', 'lib'), { recursive: true });
fs.writeFileSync(path.join(testDir, 'node_modules', 'dep', 'index.ts'), 'export const dep = 1;');
it('should not schedule sync for node_modules paths (FileWatcher-side filter)', async () => {
// NOTE: this previously asserted chokidar's `ignored` callback excluded
// node_modules from watching at all. With chokidar mocked, that
// OS-level behaviour isn't exercised here — what we test is
// FileWatcher's own filter chain (`isSourceFile` + `isAlwaysIgnored`).
// node_modules paths AREN'T in `isAlwaysIgnored` (they're filtered by
// chokidar's `ignored` callback in production), so this test now
// verifies a different mechanism: a non-source extension inside
// node_modules still drops via `isSourceFile`. The chokidar-level
// `ignored` exclusion of `node_modules/` itself is covered by the
// ignore-config tests under `src/sync/watcher-ignore.test.ts`-style
// unit-level checks, which don't need a live watcher loop.
const syncFn = vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 });
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 200 });
watcher.start();
await watcher.waitUntilReady();
// Let the watcher settle past any residual crawl events.
await new Promise((r) => setTimeout(r, 400));
syncFn.mockClear();
// A source-extension edit INSIDE node_modules must NOT trigger a sync —
// the directory was never watched.
fs.writeFileSync(path.join(testDir, 'node_modules', 'dep', 'lib', 'extra.ts'), 'export const e = 2;');
await new Promise((r) => setTimeout(r, 600));
expect(syncFn).not.toHaveBeenCalled();
// Positive control: a real source edit still triggers sync, proving the
// watcher is live (not merely inert).
fs.writeFileSync(path.join(testDir, 'src', 'live.ts'), 'export const live = 3;');
await waitFor(() => syncFn.mock.calls.length > 0, 5000);
// A source-extension event whose path is a normal source file still
// schedules sync (positive control).
triggerFileEvent(testDir, 'add', 'src/live.ts');
await waitFor(() => syncFn.mock.calls.length > 0);
expect(syncFn).toHaveBeenCalled();
watcher.stop();
@@ -200,21 +210,17 @@ describe('FileWatcher', () => {
describe('pending file tracking (#403)', () => {
it('should expose edited paths via getPendingFiles before sync fires', async () => {
// Slow debounce — events arrive but sync hasn't run yet.
// Slow debounce — pending entries are visible until the debounce
// fires. With mocked chokidar the event is synchronous, so we can
// assert immediately without polling.
const syncFn = vi.fn().mockResolvedValue({ filesChanged: 1, durationMs: 10 });
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 2000 });
watcher.start();
// Deterministic boundary: wait for chokidar's initial scan to complete
// so any late initial-scan events have fired before we assert. A bare
// sleep is flaky under test-parallelism load.
await watcher.waitUntilReady();
expect(watcher.getPendingFiles()).toEqual([]);
fs.writeFileSync(path.join(testDir, 'src', 'pending.ts'), 'export const p = 1;');
// Allow chokidar to emit, but DON'T let the 2s debounce fire.
await waitFor(() => watcher.getPendingFiles().length > 0, 3000);
triggerFileEvent(testDir, 'add', 'src/pending.ts');
const pending = watcher.getPendingFiles();
const paths = pending.map((p) => p.path);
@@ -234,52 +240,47 @@ describe('FileWatcher', () => {
watcher.start();
await watcher.waitUntilReady();
fs.writeFileSync(path.join(testDir, 'src', 'fresh.ts'), 'export const f = 1;');
triggerFileEvent(testDir, 'add', 'src/fresh.ts');
// Watcher saw the change → pendingFiles has the entry. Longer windows
// here because chokidar event delivery on macOS slows under heavy
// parallel test-suite load (4× slower than isolation).
await waitFor(() => watcher.getPendingFiles().some((p) => p.path === 'src/fresh.ts'), 8000);
// Watcher saw the change → pendingFiles has the entry IMMEDIATELY.
expect(watcher.getPendingFiles().some((p) => p.path === 'src/fresh.ts')).toBe(true);
// Wait through debounce + sync; the entry should drop out.
await waitFor(() => syncFn.mock.calls.length > 0, 8000);
await waitFor(() => !watcher.getPendingFiles().some((p) => p.path === 'src/fresh.ts'), 8000);
await waitFor(() => syncFn.mock.calls.length > 0);
await waitFor(() => !watcher.getPendingFiles().some((p) => p.path === 'src/fresh.ts'));
expect(watcher.getPendingFiles()).toEqual([]);
watcher.stop();
});
it('should keep entries unchanged when sync fails (rescheduled work sees the same set)', async () => {
// First post-settle sync rejects, second resolves. The initial-scan
// sync (triggered by chokidar's pre-existing add events) is allowed to
// resolve cleanly so it doesn't consume one of our scripted outcomes.
// With chokidar mocked there's no initial-scan-triggered sync, so
// the syncFn outcomes line up 1:1 with explicit events.
const syncFn = vi
.fn()
.mockResolvedValueOnce({ filesChanged: 0, durationMs: 1 }) // initial scan
.mockRejectedValueOnce(new Error('boom')) // first real edit fails
.mockRejectedValueOnce(new Error('boom')) // first sync rejects
.mockResolvedValueOnce({ filesChanged: 1, durationMs: 10 }); // retry succeeds
const onSyncError = vi.fn();
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 200, onSyncError });
const watcher = new FileWatcher(testDir, syncFn, { debounceMs: 100, onSyncError });
watcher.start();
// Wait through chokidar `ready` AND the initial-scan-triggered sync, so
// the next sync corresponds to the explicit edit below.
await watcher.waitUntilReady();
await waitFor(() => syncFn.mock.calls.length >= 1, 5000);
await new Promise((r) => setTimeout(r, 100));
fs.writeFileSync(path.join(testDir, 'src', 'will-fail.ts'), 'export const wf = 1;');
triggerFileEvent(testDir, 'add', 'src/will-fail.ts');
// Wait for the sync that handles the explicit edit to reject.
await waitFor(() => onSyncError.mock.calls.length > 0, 5000);
// Wait for the sync to reject.
await waitFor(() => onSyncError.mock.calls.length > 0);
// The file is STILL in pendingFiles — failure didn't drop it.
const after = watcher.getPendingFiles();
expect(after.some((p) => p.path === 'src/will-fail.ts')).toBe(true);
// Schedule a retry by emitting the event again (production would do
// this implicitly on the next file change; tests synthesize it).
triggerFileEvent(testDir, 'change', 'src/will-fail.ts');
// Retry resolves; entry clears.
await waitFor(
() => !watcher.getPendingFiles().some((p) => p.path === 'src/will-fail.ts'),
5000,
);
watcher.stop();
@@ -296,10 +297,10 @@ describe('FileWatcher', () => {
});
watcher.start();
await watcher.waitUntilReady();
triggerFileEvent(testDir, 'add', 'src/test.ts');
fs.writeFileSync(path.join(testDir, 'src', 'test.ts'), 'export const z = 3;');
await waitFor(() => onSyncComplete.mock.calls.length > 0, 5000);
await waitFor(() => onSyncComplete.mock.calls.length > 0);
expect(onSyncComplete).toHaveBeenCalledWith({ filesChanged: 2, durationMs: 50 });
watcher.stop();
@@ -314,10 +315,10 @@ describe('FileWatcher', () => {
});
watcher.start();
await watcher.waitUntilReady();
triggerFileEvent(testDir, 'add', 'src/test.ts');
fs.writeFileSync(path.join(testDir, 'src', 'test.ts'), 'export const z = 3;');
await waitFor(() => onSyncError.mock.calls.length > 0, 5000);
await waitFor(() => onSyncError.mock.calls.length > 0);
expect(onSyncError).toHaveBeenCalled();
expect(onSyncError.mock.calls[0]![0]).toBeInstanceOf(Error);
@@ -373,20 +374,26 @@ describe('FileWatcher', () => {
const initialNodes = initialStats.nodeCount;
cg.watch({ debounceMs: 300 });
// Wait through CodeGraph's internal watcher startup (the mock
// chokidar fires `ready` on the next microtask, but cg.watch wraps
// the watcher creation through promise plumbing).
await new Promise((r) => setTimeout(r, 50));
// Add a new file with a function
// Real fs write so cg.sync() can detect the new file on disk; then
// synthesize the event to wake the watcher (debounce + sync).
fs.writeFileSync(
path.join(testDir, 'src', 'added.ts'),
'export function added() { return 42; }'
);
triggerFileEvent(testDir, 'add', 'src/added.ts');
// Wait for auto-sync to pick it up
// Wait for auto-sync to pick it up.
await waitFor(() => {
const stats = cg.getStats();
return stats.nodeCount > initialNodes;
}, 10000);
}, 5000);
// The new function should be in the graph
// The new function should be in the graph.
const results = cg.searchNodes('added');
expect(results.length).toBeGreaterThan(0);