How-to › Test and mock integrations

How to inject latency and failures into SDK tests#

Make a generated SDK fail on purpose with 429 responses, connection errors, and latency, then test a sixty-second backoff in milliseconds.

Audience
Library maintainer
Level
intermediate
Topic
Mock an API
Languages
TypeScript, Go and Python
Verified

Your SDK’s retry policy has never met a real 429. The one test that tries waits out a sixty-second Retry-After, so CI skips it, and the timeout path has never fired at all. When the API throttles a customer, the client waits two seconds instead of sixty and earns another 429.

What you get

You will end up with tests that make a generated SDK see 429 responses, connection errors, an outage, and latency, on an injected clock, in all three of its languages. This is for you if you ship an sdkgen SDK and its retry code has only ever met a healthy server.

Short answer

Switch on sdkgen’s netsim feature in the client constructor, beside retry and timeout, and give retry an injected sleep. netsim answers with a 429, a connection error, an outage, or latency before a request leaves the client, so a test of a sixty-second Retry-After finishes in milliseconds. Build its options in one function that refuses any NODE_ENV but test, because a simulated 503 in production looks like a real one.

You will need

Node 22.18 or later, and an SDK generated by sdkgen that you can rebuild. Python 3 and Go 1.24 or later run the cross-language check. Verified 2026-11-21 against Node 22.23.5, Python 3.13.18, Go 1.24.7, @voxgig/sdkgen 4.44.3, NSwag 14.8.0, and oapi-codegen v2.8.2. The document, api.json, describes a rates API whose two operations both declare 429 and 503 responses. server.ts stands in for the API on 127.0.0.1 and logs each request it receives.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
NSwagA .NET shop generating C# and TypeScript clients from one documentNo fault option and no retry, so you write a faulty fetch or DelegatingHandler and the retry it testsYou want generated retry behavior to test rather than your own
oapi-codegenGo clients that take any HttpRequestDoer you hand themNo retry or fault code generated, so both doers are yours to write and keepYou want faults switched on by an option instead of a type
sdkgen netsim featureYour SDK is generated by sdkgen and you test its own retry and timeoutProves only the client’s layers, since no byte crosses a socket, and it ships in the SDKYou need to see a half-read body or a reset socket
ToxiproxyAny client, any TCP dependency, faults set per test over its HTTP APIA Go server to run beside the tests, and a proxy address the client must useYour CI cannot start a server process
WireMockHTTP stubs with fixed delays, resets, and garbage responsesA JVM or container per suite, and faults in fixed shapes per stubYou want the fault inside the client, with no network

Voxgig maintains sdkgen. This page is about its netsim feature, and the table’s sdkgen row says where a proxy or a stub server proves more.

Toxiproxy and WireMock sit on the wire, so they also prove what the socket does, at the price of a process beside the tests. netsim needs no process and sees no socket. NSwag and oapi-codegen generate neither faults nor retry, so their tests exercise code you wrote around the client.

Switch netsim on beside retry and timeout

generate.sh scaffolded the project with -t ts -t py -t go -f netsim -f retry -f timeout. All three features wrap the transport, and in a map the default order puts timeout outermost, then retry, then netsim, so a retried call meets the fault again.1 One module makes every faulty client:

// The only place netsim options are made. Outside NODE_ENV=test it throws,
// because a simulated 503 in production reads as a real outage.
export function netsimFor(env: Env, faults: Record<string, unknown>) {
  if (env.NODE_ENV !== 'test') {
    throw new Error(`netsim refused: NODE_ENV is ${env.NODE_ENV ?? 'unset'}, not test`)
  }
  return { active: true, ...faults }
}

export type FaultyOptions = {
  faults: Record<string, unknown>
  sleep: (ms: number) => void
  timeoutMs?: number
  env?: Env
}

// A client whose transport is wrapped, from the outside in, by timeout,
// retry and netsim: the default order for these three features.
export function faultyClient(base: string, options: FaultyOptions) {
  const feature: Record<string, unknown> = {
    netsim: netsimFor(options.env ?? process.env, options.faults),
    retry: { active: true, retries: 2, minDelay: 100, maxDelay: 120_000, jitter: false, sleep: options.sleep },
  }
  if (options.timeoutMs !== undefined) feature.timeout = { active: true, ms: options.timeoutMs }
  return new RatecardSDK({ base, feature })
}

The faults are netsim options: rateLimitTimes with retryAfter for 429 responses, errorTimes for connection errors, offline for an outage, and latency in milliseconds. maxDelay is raised to two minutes because retry caps every wait at it, a Retry-After included. sleep is the injected clock: virtualClock() in the same file records each wait and returns at once.

Wait out a sixty-second Retry-After in milliseconds

demo.ts runs four faults against the stand-in. NODE_ENV=test is what lets netsimFor build them.

NODE_ENV=test node demo.ts
429, then Retry-After: 60
  loaded r1; attempts: 2; waits on the injected clock: [60000] ms
  requests that reached the API: 1, wall clock under 1 s: true
connection error twice
  loaded r1; attempts: 3; waits on the injected clock: [100, 200] ms
  requests that reached the API: 1, wall clock under 1 s: true
outage
  failed: netsim_offline; attempts: 3; waits on the injected clock: [100, 200] ms
  requests that reached the API: 0, wall clock under 1 s: true
300 ms of latency against a 50 ms timeout
  failed: timeout; attempts: 1; waits on the injected clock: [] ms
  requests that reached the API: 0, wall clock under 1 s: true

The minute passed on the injected clock and not on the wall. Every fault was answered inside the client: the 429 attempt and the two failed connections never reached server.ts, which is the limit of this approach. The timeout case uses real time, 50 ms of it, because the deadline is a real timer.

Check the same faults in the Python and Go SDKs

same.ts runs three faults on the TypeScript SDK and starts same.py and the Go program in gocheck/sdkgen, which run them on the other two targets. All three use the test feature, so nothing leaves the process.

node same.ts
scenario                   typescript                        python                            go
429, then Retry-After: 60  loaded r1 [60000]                 loaded r1 [60000]                 loaded r1 [60000]
connection error twice     loaded r1 [100, 200]              loaded r1 [100, 200]              loaded r1 [100, 200]
outage                     failed: netsim_offline [100, 200] failed: netsim_offline [100, 200] failed: netsim_offline [100, 200]
identical in all three: true

The options are the same keys in all three languages. The injected sleep differs only in type: a function of ms in TypeScript, list.append in Python, and a func(int) in Go.

Inject the same faults under NSwag and oapi-codegen clients

NSwag’s TypeScript client takes http?: { fetch(url, init) } in its constructor, and its C# client takes an HttpClient, so a DelegatingHandler is the .NET seam. Neither generated client retries, so the fault needs a retry layer to test.

// Answers the first statuses.length requests itself, then passes on.
export function faultyFetch(statuses: number[], retryAfter: string, next: Fetch): Fetch {
  const script = [...statuses]
  return async (url, init) => {
    const status = script.shift()
    if (status === undefined) return next(url, init)
    return new Response('', { status, headers: { 'retry-after': retryAfter } })
  }
}
node nswag.ts
429, then Retry-After: 60, under a retrying fetch
  rate r1; waits on the injected clock: [60000] ms
  requests that reached the API: 1, wall clock under 1 s: true
the same fault with no retrying fetch
  ApiException 429, retry-after header: 60

oapi-codegen’s client takes any HttpRequestDoer through WithHTTPClient, and its README mentions no retry. gocheck/oapi puts a scripted faultyDoer under a retryDoer with an injected sleep, and calls the generated GetRateWithResponse.

go -C gocheck run ./oapi
429, then Retry-After: 60, under a retrying doer
  status 200, rate r1; waits on the injected clock: [1m0s]
  requests that reached the API: 1, wall clock under 1 s: true
the same fault with no retrying doer
  status 429, JSON200 is nil: true

Check it worked

The test that carries the page asserts the minute, the wall clock, and the API’s request log:

test('a sixty second Retry-After is honoured on the injected clock in milliseconds', async (t) => {
  const api = await serve(t)
  const clock = virtualClock()
  const client = faultyClient(api.base, { faults: { rateLimitTimes: 1, retryAfter: 60 }, sleep: clock.sleep, env: TEST_ENV })
  const started = Date.now()
  const rate = await client.Rate().load({ id: 'r1' })
  assert.equal(rate.data().id, 'r1')
  assert.deepEqual(clock.slept, [60_000])
  assert.ok(Date.now() - started < 1000, 'no real minute went by')
  assert.equal(client._netsim.calls, 2)
  assert.deepEqual(api.requests, ['GET /v1/rates/r1'], 'the simulated 429 never reached the API')
})
node --test faults.test.ts
# tests 12
# suites 0
# pass 12
# fail 0
# cancelled 0
# skipped 0
# todo 0

The other eleven cover the remaining faults, the guard, all three languages agreeing, both substitutes, and a Retry-After given as a date, which the hand-written retry layers decline to guess at.

When it goes wrong

The sixty-second test passes with [2000]. retry caps a Retry-After at maxDelay, whose default is 2000 ms, so the client comes back 58 seconds early.2 Raise maxDelay to the longest wait your API states, and keep the test that fails on [2000].

Your SDK reports a 503 on every third call while the API’s status page shows no incident. netsim was left active in options a production client shares with the tests.

node pitfall.ts
netsim left on in shared options, failEvery: 3, six loads
  ok ok 503 ok ok 503
  requests that reached the API: 4 of 6
  the error the caller logs: RatecardSDK: load: request: 503: Simulated Failure
the same faults through netsimFor, NODE_ENV=production
  netsim refused: NODE_ENV is production, not test

The API never saw the failing calls, so its own logs show nothing wrong. Only the message says Simulated Failure, and a dashboard that counts statuses never reads it. Build netsim options in netsimFor alone, and let it throw outside tests.

When not to do this

Do not rely on netsim to prove socket behavior. A response that stops halfway, a connection that resets after the headers, and a slow TLS handshake never happen inside the client. Put Toxiproxy or WireMock in front of a real endpoint for those.3

Do not add sdkgen to get fault injection for a client you did not generate with it. NSwag is the better choice for a .NET team that already owns its HTTP handlers, since the faults go in a handler beside the retry it tests. oapi-codegen is the better choice when the Go service already wraps its HttpRequestDoer, because two small doers cost less than a second generator.

Do not ship a build where netsim can be switched on by configuration alone. The guard costs one function, and the incident it prevents looks real.

Last verified

Verified 2026-11-21 against Node 22.23.5, Python 3.13.18 (and 3.12.3 for same.py), Go 1.24.7, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, NSwag 14.8.0 on the ASP.NET Core runtime 10.0.15, oapi-codegen v2.8.2, and github.com/oapi-codegen/runtime v1.8.0. Every output block is what the command preceding it printed. The generators ran once, in generate.sh, and their output is committed under generated/ and gocheck/ratecard/. NSwag ran once: its TypeScript client is committed and runs under Node in nswag.ts. Its C# client was generated and committed to read its HttpClient constructor, and was neither compiled nor run. No DelegatingHandler was written or run. @voxgig/sdkgen 4.45.0 wrote identical ts, py, and go trees from the same project.

Footnotes

  1. The sdkgen feature reference explains the order: in a map, test initializes first and the remaining features follow in alphabetical order, and the one initialized last wraps the rest. So timeout ends up outside retry because t follows r in the alphabet, and one deadline covers the whole retry sequence. An array instead of a map sets the order by position. ↩︎ Back to text

  2. The example in RFC 6585, which defined 429 in April 2012, sends Retry-After: 3600 with a page explaining that the site allows 50 requests per hour per logged-in user. Against the default cap that client would return 3,598 seconds early, and the RFC itself observes that a server under attack need not send a 429 at all. ↩︎ Back to text

  3. Toxiproxy’s README describes it as made specifically for testing, CI, and development environments, and says Shopify has run it in all of its development and test environments since October 2014. The same paragraph says, in bold, that it is the tool you need to prove with tests that a system has no single points of failure. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.