@dudousxd/nestjs-agent-testing

Every SPI the agent depends on, in-memory: AgentStore, AgentGovernanceQueries, MemoryProvider, QuotaStore, TokenStreamSink, a scripted ModelProvider, and offline embedding/reranking fakes. Exercise auto-executing reads, a suspending action tool, and multi-agent delegation with no API key, no database, and no Redis. It also ships framework-agnostic contract suites a store adapter (yours or the library's) can run to prove it behaves like the real thing.

pnpm add -D @dudousxd/nestjs-agent-testing

Minimal exampleCopy Anchor Link

import { AgentModule, HeaderActorResolver } from '@dudousxd/nestjs-agent';
import { FakeModelProvider, InMemoryAgentStore, echoScript } from '@dudousxd/nestjs-agent-testing';

AgentModule.forRoot({
  model: new FakeModelProvider(echoScript('Hello from the fake model.')),
  store: new InMemoryAgentStore(), // pass directly instead of importing a store module
  actorResolver: new HeaderActorResolver(),
});

Script a tool call instead of a plain reply by returning toolCall from a FakeScript — the function receives (args, turnIndex), so the script is a pure function of the turn history:

import { FakeModelProvider, type FakeScript } from '@dudousxd/nestjs-agent-testing';

const script: FakeScript = (args, turnIndex) =>
  turnIndex === 0
    ? { text: '', toolCall: { name: 'getWeather', input: { city: 'Lisbon' } } }
    : { text: "It's partly cloudy in Lisbon." };

const model = new FakeModelProvider(script);

A requested tool call's id is call-<turnIndex>-<name>. When the same provider instance already issued that id (the same turn of another thread, or the same tool twice in one turn) it gets the first free -2, -3… suffix, since a tool call id is the store's primary key across threads — so one provider can serve many threads.

ExportsCopy Anchor Link

import { InMemoryAgentStore, InMemoryGovernanceQueries } from '@dudousxd/nestjs-agent-testing';

const store = new InMemoryAgentStore();
const queries = new InMemoryGovernanceQueries(
  store,
  new Map([['claude-sonnet-4-6', { inputPricePer1m: 3, outputPricePer1m: 15 }]]),
);

InMemoryAgentStore records run start/end and retries the same way a real store does, so queries.runMetrics(range), .recentRuns(limit), and .pendingApprovals(limit) are assertable in a unit test with no database — useful for testing the Reliability/Approvals dashboard sections, or a tool's HITL approval flow, entirely offline.

Contract suitesCopy Anchor Link

Each suite is a readonly array of { name, run } cases; run throws on the first mismatch, so any test runner works:

import { CHAT_QUEUE_STORE_CONTRACT } from '@dudousxd/nestjs-agent-testing';

for (const contractCase of CHAT_QUEUE_STORE_CONTRACT) {
  it(contractCase.name, async () => contractCase.run(await freshSubject()));
}

Each suite also exports its …ContractCase / …ContractSubject types. The Drizzle and MikroORM adapters run these suites against real SQLite, Postgres and MySQL (testcontainers).

Peer dependenciesCopy Anchor Link

@dudousxd/nestjs-agent-core (>=0.27.0 <1.0.0).

The runnable offline demoCopy Anchor Link

The repo's examples/agent-demo is built entirely on these in-memory pieces — a scripted proof of auto-executing reads, a suspending action tool, and multi-agent delegation, with zero infrastructure:

pnpm --filter agent-demo demo   # the offline scripted proof
pnpm --filter agent-demo start  # the full NestJS app + console at /ai-gateway

When to use itCopy Anchor Link

Use this package for unit tests of your tools and app wiring, and for any environment where a real model/database/Redis would be overkill — CI, demos, local development before you've wired persistence. Swap in a real store adapter (store-mikro-orm or store-drizzle) and a real ModelProvider (@dudousxd/nestjs-agent-ai-sdk's aiSdkModel) for production — the agent loop and your tools are unchanged either way.

RelatedCopy Anchor Link

• Persistence — the AgentStore SPI this package's in-memory store implements, and the two real adapters
• Getting Started — the pnpm --filter agent-demo demo walkthrough