# Test Framework Plugins

Zero-config integration for vitest and jest. Import `useAimock`, write tests — the server lifecycle, env vars, and cleanup are handled automatically.

## Vitest

test/app.test.ts ts

    import { useAimock } from "@copilotkit/aimock/vitest";

    const mock = useAimock({ fixtures: "./fixtures" });

    it("responds to hello", async () => {
      // OPENAI_BASE_URL is already set
      const res = await myApp.chat("hello");
      expect(res).toBe("Hi there!");
    });

## Jest

test/app.test.ts ts

    import { useAimock } from "@copilotkit/aimock/jest";

    const mock = useAimock({ fixtures: "./fixtures" });

    it("responds to hello", async () => {
      const res = await myApp.chat("hello");
      expect(res).toBe("Hi there!");
    });

## Options

Both plugins accept the same `UseAimockOptions` object:

Option | Type | Default | Description
--- | --- | --- | ---
`fixtures` | `string` | — | Path to fixture file or directory
`patchEnv` | `boolean` | `true` | Auto-set `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL`
`port` | `number` | `0` (random) | Port to listen on
`host` | `string` | `127.0.0.1` | Host to bind to
`logLevel` | `string` | `silent` | Log verbosity

## The Handle

The getter function returned by `useAimock()` returns an `AimockHandle`:

Property | Type | Description
--- | --- | ---
`llm` | `LLMock` | The LLMock instance — add fixtures programmatically
`url` | `string` | The server URL (e.g., `http://127.0.0.1:4010`)

### Programmatic fixture registration

test/custom.test.ts ts

    const mock = useAimock();

    it("custom fixture", async () => {
      mock().llm.onMessage("custom", { content: "Custom response" });
      // ...
    });

## Lifecycle

Both plugins register framework hooks to manage the server automatically:

1. `beforeAll` — starts the server, loads fixtures from the `fixtures` path, and patches `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` environment variables
2. `beforeEach` — resets match counts (sequential fixture counters return to zero, but fixtures themselves are preserved)
3. `afterAll` — stops the server and restores the original environment variables

## Without Plugins (Manual)

For comparison, here is the equivalent manual setup. The plugins above handle all of this for you:

test/manual.test.ts ts

    import { LLMock } from "@copilotkit/aimock";

    let mock: LLMock;

    beforeAll(async () => {
      mock = new LLMock();
      mock.onMessage("hello", { content: "Hi!" });
      await mock.start();
      process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
    });

    afterAll(async () => {
      await mock.stop();
      delete process.env.OPENAI_BASE_URL;
    });