The agent writes a Bookshelf client, runs its tests, and the tests call api.example.com with the
key from your shell. A create test leaves a record in production. When you cut the network, every
test fails on a connection error, because nothing local answers the calls the agent wrote.
What you get
You will end up with an agent whose commands cannot leave the machine and tests that start their own mock. A guard fails any test that opens a connection to a real host. This is for you if you let an agent run tests against code that talks to a paid or shared API.
Short answer
Run the agent inside a boundary with no outbound network: a Docker container on the none
network, Codex CLI with --sandbox workspace-write, or Claude Code’s /sandbox with an empty
domain list. Give its tests a mock the test process starts: Prism on 127.0.0.1, or sdkgen’s
test mode in process. Import a guard that refuses non-loopback connections, so an escaped
call fails a test.
You will need
Node 22 or later, an OpenAPI 3 document with response examples, and a coding agent that can run
shell commands. Verified 2026-11-20 against Node 22.23.5. The sample’s api.json has three
operations, an example on each success, and a declared 404.
Pick the boundary before the mock. The Docker none network driver
gives a container a loopback device and nothing else.1 Codex documents that its default
workspace-write mode
keeps network access off until
network_access = true appears under [sandbox_workspace_write]. Claude Code’s
Bash sandbox routes commands through a proxy that
checks network.allowedDomains, which starts empty.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| NSwag client with an in-memory fetch | The client is NSwag’s Fetch template, and tests can pass the constructor an object with fetch | A fake transport you write and keep matching the document, because NSwag generates no mock | You want the mock to follow the document without code |
| Prism mock | Any client in any language, and the document carries good examples | One fixed example per response, so pages and missing ids all look alike | The tests must reach pagination or error branches unprompted |
| sdkgen test feature | The client is an sdkgen SDK, and tests should run with no server or port | Only exists inside a generated SDK, so the SDK must exist before the agent’s tests | The agent is writing the client itself |
| Swagger Codegen WireMock tests | A Java client, and you want a test class that starts WireMock already written | Stubs that answer 200 with no body, in a class marked @Ignore | The client is TypeScript, or the stubs need real bodies |
| WireMock stubs and faults | You need scripted answers per request, delays, and connection resets | A JVM or container in the test setup, and every stub authored by hand | The document’s examples already say what the tests need |
Voxgig maintains sdkgen. It is one of five options here, not the recommendation.
Prism costs nothing to author and returns the same example for every call, which hides branches. WireMock reaches every branch, at the price of writing each stub. sdkgen’s test mode needs no process at all, but only an sdkgen SDK has one. NSwag and Swagger Codegen leave the mock to you. NSwag takes it as a constructor argument; Swagger Codegen writes a Java test to fill in.
Generate an sdkgen client that answers from a seed
An sdkgen SDK needs no mock server, because its test feature is an in-memory transport. Add
the feature when you scaffold, then generate and compile. generate.sh ran these commands once,
outside the gate, and kept the compiled .js files in generated/:
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts --feature test
(cd bookshelf-sdk/.sdk && npm run generate)
(cd bookshelf-sdk/ts && npm install --no-audit --no-fund && npm run build)
(cd bookshelf-sdk/ts/dist && find . -name '*.js' -exec install -D {} ../../../generated/{} \;)
echo '{ "type": "commonjs" }' > generated/package.json
The scaffold writes .sdk/model/feature/test.aontu, whose options: active: false keeps a
client built with new BookshelfSDK(options) live. Write the records the tests need as a seed,
keyed by entity and then by id:
export const seed = {
entity: {
book: {
b1: { id: 'b1', title: 'Dune', author: 'Frank Herbert' },
b2: { id: 'b2', title: 'Emma', author: 'Jane Austen' },
},
},
}
Construct the client with BookshelfSDK.test(seed). It sets feature.test.active and hands the
seed to the feature, and every entity call is answered from the seed in process:
// sdkgen: the test feature answers from the seed, in process.
const sdk = BookshelfSDK.test(seed)
console.log('sdkgen client mode'.padEnd(34), sdk._mode)
await show('sdkgen list', async () => (await sdk.Book().list()).map((b) => b.data().title))
await show('sdkgen load b2', async () => (await sdk.Book().load({ id: 'b2' })).data().title)
await show('sdkgen load nope', async () => (await sdk.Book().load({ id: 'nope' })).data())
Give the tests a mock they start themselves
A mock running in another terminal is the first thing a sandbox breaks. On Linux, Claude Code’s
documentation says, the localhost of a command inside the sandbox is private to that command.
It reaches the servers it started itself and not the ones on the host. Start the mock from the
test process.
An NSwag client takes an object with a fetch method as its second constructor argument, so its
tests pass an in-memory one, which answers only the two GET routes the document declares.
offline.mjs runs the sdkgen client and the NSwag client, then makes the mistake the guard exists
for, a client constructed with no base URL.
node --experimental-strip-types offline.mjs
sdkgen client mode test
sdkgen list ["Dune","Emma"]
sdkgen load b2 "Emma"
sdkgen load nope error: BookshelfSDK: load: request: 404: Not found
nswag listBooks ["Dune","Emma"]
nswag getBook nope error: ErrorDto {"error":"not found"}
sdkgen live client, list error: BookshelfSDK: list: fetch failed
connections refused ["api.example.com:443"]
The seeded client reaches the 404 branch on an id nobody seeded. The NSwag client throws the
parsed 404 body, an ErrorDto, rather than an Error, which an agent’s catch may not expect.
The last client fell back to the document’s server URL, and the guard refused it.
Make an escaped connection fail the test
The sandbox stops the packet, but the agent only sees a connection error it may retry or skip.
A guard inside the test process turns the attempt into a named failure. Node’s fetch and its
https module open their sockets through one method, which the test checks for both:
const connect = net.Socket.prototype.connect
net.Socket.prototype.connect = function (...args) {
const t = target(args)
if (t.path || LOOPBACK.has(t.host)) return connect.apply(this, args)
refused.push(`${t.host}:${t.port}`)
const err = new Error(`no-network: refused a connection to ${t.host}:${t.port}`)
err.code = 'ENETUNREACH'
process.nextTick(() => this.destroy(err))
return this
}
Import it on the first line of each test file, and assert that refused did not grow. Loopback
stays open, so Prism or a node:http stand-in on 127.0.0.1 still answers. Put the rule in the
agent’s instructions too: every test imports no-network.mjs and sets a loopback base URL.
Mock the same API with NSwag and Swagger Codegen
NSwag 14.8.0 writes no mock and no test. Its TypeScript client’s constructor is
constructor(baseUrl?: string, http?: { fetch(url, init): Promise<Response> }), the signature
the NSwag wiki shows for the
Fetch template. Pass the in-memory fetch from fixtures.mjs, as offline.mjs does. NSwag beats
sdkgen when the client should be an Angular service or use jQuery for HTTP. The wiki lists a
template for each, and sdkgen’s 23 targets are languages, not frameworks.
Swagger Codegen 3.0.85 has a mock option for its Java client. config-help -l java lists
wiremock, “Use wiremock to generate endpoint calls to mock on generated tests”, as does the
hosted generator’s
Java option list, and
--additional-properties wiremock=true writes a test that starts WireMock on a dynamic port.
node swagger-stubs.mjs
class is @Ignore: true
stubs with a body: 0
tests that assert: 0 of 3
stub answers document declares
POST /books 200 201
GET /books/{bookId} 200 200, 404
GET /books 200 200
The class runs nothing until someone removes @Ignore, and then every stub answers 200 with an
empty body.2 Treat it as scaffolding for stubs you write. It beats sdkgen for a Java team that
wants WireMock’s fault injection in the same harness.
Check it worked
Run the suite with the guard imported. Eight tests cover the guard both ways, both offline clients, the routes the in-memory fetch refuses, the Prism behavior below, and the Swagger Codegen stubs.
node --experimental-strip-types --test sandbox.test.mjs
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
Run the same command inside the agent’s sandbox before you hand the task over.
When it goes wrong
The agent’s tests pass against fixed data and never reach a page two or a missing record. Prism in its default static mode answers with the document’s example, whatever the page or the id:
node pitfall.mjs
GET /books?page=1 200 [{"id":"b1","title":"Dune","author":"Frank Herbert","published":1965}]
GET /books?page=2 200 [{"id":"b1","title":"Dune","author":"Frank Herbert","published":1965}]
GET /books/no-such-book 200 {"id":"b1","title":"Dune","author":"Frank Herbert","published":1965}
same, Prefer: code=404 404 {"error":"not found"}
A paging loop that stops on an empty page never stops, and a 404 handler never runs. Ask for the
branch with the
Prefer header
in a test of its own, or seed a stateful mock that holds real pages.
The mock starts but the tests cannot reach it under the sandbox. It was started outside the
command the sandbox wraps. Start it from the test, as prism.mjs does on a free port.
The guard reports nothing and calls still leave. Something connects outside Node’s net
module: a native module, or a child process. The OS boundary still stops those, which is
why the guard sits inside a sandbox rather than replacing one.
When not to do this
Do not treat a passing suite against Prism as evidence that error handling works. A static mock answers the happy path for every request, so the agent’s retry and 404 code may never run.
Do not reach for sdkgen’s test feature when the agent is writing the client by hand. It exists only inside an SDK sdkgen generated, so adopting it means generating that SDK first. Prism, or WireMock when you need faults, fits a hand-written client with no generator in the loop.
Do not open the sandbox’s domain list to the real API so the tests pass. That is the call the sandbox exists to stop, with the agent holding your credentials.
Do not use NSwag’s in-memory fetch as your only mock if the TypeScript client is all you ship from NSwag. A Prism run catches a fake that has drifted from the document, which the fake cannot.
Related how-tos
Last verified
Verified 2026-11-20 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@stoplight/prism-cli 5.16.0, NSwag 14.8.0 and Swagger Codegen 3.0.85. Every output block is what
the command preceding it printed. NSwag and Swagger Codegen were run once and their output is
committed. Codex CLI, Claude Code’s sandbox and Docker were not run; their behavior comes from
their documentation. WireMock was not run.
Footnotes
-
Docker lists
noneamong its network drivers, besidebridgeandhost, and documents that with it only the loopback device is created. A driver whose job is to provide no network is filed as a network driver all the same, and chosen with the same--networkflag as the others. ↩︎ Back to text -
The
pom.xmlSwagger Codegen writes beside that test asks forcom.github.tomakehurst:wiremock2.27.2. Maven Central’s index fororg.wiremock:wiremock-standalonestarts at 3.0.0-beta-11 and lists 4.0.0-beta.44 as its latest release, under a group id the generated build does not mention. ↩︎ Back to text