vitest-auto-spy: Instructions file for Codex

vitest-auto-spy — instructions for AI coding agents

Reference for an agent writing tests with vitest-auto-spy in someone else's project: typed test spies generated from a class, a type, or nothing at all, on Vitest, bun:test, node:test and Rstest. It ships in the npm package, so it works offline: node_modules/vitest-auto-spy/AGENTS.md. Working on the library's own source? Read CONTRIBUTING.md in the repository instead.

The spec you will write most often, an Angular service with a spied store and HTTP (the full recipe is §3):

import { TestBed } from '@angular/core/testing';
import { type Spy, injectSpy, provideAutoSpy } from 'vitest-auto-spy/angular';
import { expectRequest, provideHttpTesting } from 'vitest-auto-spy/angular-http';

let store: Spy<CartStore>;

beforeEach(() => {
  TestBed.configureTestingModule({ providers: [...provideHttpTesting(), provideAutoSpy(CartStore)] });
  store = injectSpy(CartStore);
});

it('posts the order', async () => {
  const order = TestBed.inject(OrderService).checkout(); // Promise<Order>, sent through HttpClient

  await expectRequest('/api/orders', { method: 'POST' }).flush({ id: 1 });
  await expect(order).resolves.toEqual({ id: 1 });
  expect(store.clear).toHaveBeenCalled();
});

To point a team's agents at this file, run npx vitest-auto-spy init: it adds a pointer to AGENTS.md, CLAUDE.md, GEMINI.md and the rule files of tools already set up, all or nothing. --check is the CI form and fails on a stale hand-made skill copy (delete it, re-run init) or an edited managed block. --only CLAUDE.md,.claude limits it to untracked files. Full table: https://asdalexey.github.io/vitest-auto-spy/utilities/cli.

Read dist/*.d.ts before inventing a call. Every export is typed and documented there, and the type is the authority when this file and the code disagree.