Build Simulation

Build-Simulation Skill

Purpose

Guide an AI agent through the full workflow of turning a bare OpenAPI spec into a realistic, stateful API simulation using Counterfact. This skill covers every step: generation, research, context implementation, testing, and scenario setup.

Step 1 — Generate the initial scaffold

Run Counterfact against the spec to produce a working server immediately:

npx counterfact@latest <spec-url-or-path> <output-directory>

Example:

npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api

This creates:

<output-directory>/
├── routes/          # one .ts file per API path — edit these
└── types/           # generated request/response types — never edit these

Every endpoint is live right away. By default each handler returns schema-valid random data (.random()). The simulation work that follows will replace those random responses with realistic, stateful behaviour.

Docs: Getting Started

Step 2 — Research the real API

Because the spec describes a well-known public API, look up official documentation before writing any simulation code. Understanding what the real API actually does is what separates a useful simulation from a pretty type stub.

Do at least the following:

1. Read the official API docs — authentication flows, pagination styles, required vs. optional fields, status codes, error shapes, and any notable business rules (e.g. "a pet cannot be ordered if its status is sold").
2. Check for public examples and SDKs — official SDKs often clarify which fields are commonly populated and how resources relate to each other.
3. Note realistic data shapes — names, IDs, statuses, and dates that appear in the real API's example responses will make the simulation convincing.

Use this research to inform what methods the context classes should expose, what validation the context should perform, and what data the startup scenario should seed.

Step 3 — Implement context classes

Handlers should be thin. All stateful logic — lookups, mutations, derived data, invariants, error conditions — belongs in a _.context.ts file. Handlers read from context and return responses; they contain no business logic of their own.

Single-domain API

Place one _.context.ts at the root of the routes tree:

// api/routes/_.context.ts
import type { Pet } from "../types/components/pet.types.js";

export class Context {
  private pets = new Map<number, Pet>();
  private nextId = 1;

  add(data: Omit<Pet, "id">): Pet {
    const pet = { ...data, id: this.nextId++ };
    this.pets.set(pet.id, pet);
    return pet;
  }

  get(id: number): Pet | undefined {
    return this.pets.get(id);
  }

  list(status?: Pet["status"]): Pet[] {
    const all = [...this.pets.values()];
    return status ? all.filter((p) => p.status === status) : all;
  }

  remove(id: number): boolean {
    return this.pets.delete(id);
  }
}

Then wire the context into each handler:

// api/routes/pet.ts
export const GET: HTTP_GET = ($) =>
  $.response[200].json($.context.list($.query.status));

export const POST: HTTP_POST = ($) =>
  $.response[200].json($.context.add($.body));

// api/routes/pet/{petId}.ts
export const GET: HTTP_GET = ($) => {
  const pet = $.context.get($.path.petId);
  return pet
    ? $.response[200].json(pet)
    : $.response[404].text(`Pet ${$.path.petId} not found`);
};

export const DELETE: HTTP_DELETE = ($) => {
  $.context.remove($.path.petId);
  return $.response[200];
};

Multi-domain API

For APIs with several distinct domains (users, orders, payments, …), give each domain its own _.context.ts at its subtree boundary. Use $.loadContext(path) to reach across boundaries when one domain needs data from another:

// api/routes/payments/{paymentId}.ts
import type { Context as UsersContext } from "../../users/_.context.js";

export const GET: HTTP_GET = ($) => {
  const payment = $.context.getById($.path.paymentId);
  if (!payment) return $.response[404].text("Payment not found");

  const usersCtx = $.loadContext("/users") as UsersContext;
  const user = usersCtx.getById(payment.userId);

  return $.response[200].json({ ...payment, user });
};

Keep each context class focused on a single responsibility. If a class is growing too large, split it along domain lines.

Docs:

• State: Context Objects
• Pattern: Mock APIs with Dummy Data
• Pattern: Federated Context Files

Step 4 — Test the context classes

The context class accumulates real logic; bugs in it break every handler that depends on it. Write unit tests that exercise the class directly, with no server, no $ object, and no HTTP machinery.

// test/context.test.ts
import { Context } from "../api/routes/_.context.js";

describe("Context", () => {
  let context: Context;

  beforeEach(() => {
    context = new Context();
  });

  it("assigns sequential ids", () => {
    const a = context.add({ name: "Fluffy", status: "available", photoUrls: [] });
    const b = context.add({ name: "Rex",    status: "available", photoUrls: [] });
    expect(a.id).toBe(1);
    expect(b.id).toBe(2);
  });

  it("returns undefined for an unknown id", () => {
    expect(context.get(99)).toBeUndefined();
  });

  it("filters by status", () => {
    context.add({ name: "Fluffy", status: "available", photoUrls: [] });
    context.add({ name: "Rex",    status: "sold",      photoUrls: [] });
    expect(context.list("sold")).toHaveLength(1);
  });

  it("removes a pet", () => {
    const pet = context.add({ name: "Fluffy", status: "available", photoUrls: [] });
    context.remove(pet.id);
    expect(context.get(pet.id)).toBeUndefined();
  });
});

Do not test handler files. Handlers are intentionally thin, freely editable, and contain no logic worth automating against. Only the context class needs tests.

Docs: Pattern: Test the Context, Not the Handlers

Step 5 — Set up scenario scripts

Scenario scripts are TypeScript files in the scenarios/ directory. Each file exports named functions that receive a $ argument giving access to live context and a route builder. Run them from the REPL with .scenario, or have one run automatically at startup.