Mock the wire, not the SDK

The last lesson left you a habit: stub the boundary your code actually calls, auth.api.getSession, not the library internals underneath it. This lesson pushes that boundary one step further out, to where your code stops talking to a library and starts talking to someone else’s server.

That boundary hides the most expensive bug in this chapter: not a test that fails, but one that passes while production is broken. The fix is to move the mock to the one line where the test can’t lie.

The test that passes while production breaks

Here is a Server Action that puts a customer on a paid plan. It’s the subscription sibling of the createInvoice you’ve carried through this chapter: same wrapper and shape, except it reaches out to Stripe to start a checkout instead of writing a row.

export const createSubscription = authedAction(
  'member',
  createSubscriptionSchema,
  async (input, { user, orgId }) => {
    const session = await stripeClient.checkout.sessions.create({
      mode: 'subscription',
      line_items: [{ price: input.priceId, quantity: 1 }],
      metadata: { userId: user.id, orgId },
    });
    return ok({ checkoutUrl: session.url });
  },
);

To test it, you reach for the tool you know, SDK mocking from the unit-testing lessons, and write the obvious thing:

src/server/actions/createSubscription.int.test.ts

vi.mock('stripe');

it('starts a subscription checkout', async () => {
  await signedInAs({ plan: 'free' }, tx);

  await createSubscription({ priceId: 'price_pro_monthly' });

  expect(stripeClient.checkout.sessions.create).toHaveBeenCalledWith({
    mode: 'subscription',
    line_items: [{ price: 'price_pro_monthly', quantity: 1 }],
    metadata: expect.any(Object),
  });
});

It passes, it’s fast, you ship it. Three weeks later production starts throwing 400s on checkout. Maybe Stripe bumped a required header on your pinned API version, maybe the SDK renamed a field, maybe that metadata shape was one Stripe rejects. Real Stripe said no, and your test stayed green through every commit.

Your assertion checked that a function was called with certain arguments; it never checked the bytes that reached Stripe. Those bytes, the method, URL, headers, and body that go on the wire , are the only contract Stripe enforces. Stripe never saw your create call; it saw a request, and you shipped that request untested.

A mock contains your guess about the third party, not the third party, so it can only confirm your own assumptions back to you. If the guess is wrong, the test is wrong the same way and stays green.

Caution

A passing test that can’t fail when production fails is worse than no test: it costs the same to write and maintain, and “we have a test for that” becomes the reason nobody looks closer. The goal isn’t a green check, it’s a test that goes red exactly when the thing it covers breaks.

So if mocking the SDK can’t catch the bug, where does the mock go instead? First you have to see what the SDK actually is.

An SDK is a tower on top of one network call

It’s tempting to picture stripeClient as a magic object whose methods “talk to Stripe.” Drop that picture. An SDK is a stack of plain code, and every method you call runs down that stack to a single rung at the bottom: one outbound network call. Everything above that rung is ordinary JavaScript running in your process.

Here’s the tower for one checkout.sessions.create call.

stripeClient.checkout.sessions.create({ … }) your call — typed, ergonomic, the only line you wrote

Serialize turns the JS object into a URL-encoded form body (application/x-www-form-urlencoded — not JSON)

Sign & set headers adds Authorization: Bearer, Idempotency-Key, Stripe-Version

Retry on 429 / 5xx, retries with backoff

HTTP request to api.stripe.com the real process boundary

this is the only thing Stripe sees

Parse decodes the response body, maps error JSON to a thrown StripeError

runs for real — but only if you mock at the network

thrown away if you mock the function or the class

Every checkout.sessions.create call is a trip down this tower. The only line you wrote is the top one; the SDK generates everything below it.

Each rung does work a function-mock silently throws away:

• Serialize. Stripe’s v1 API doesn’t take JSON; it takes application/x-www-form-urlencoded . So line_items: [{ price: 'price_x', quantity: 1 }] goes out as line_items[0][price]=price_x&line_items[0][quantity]=1.
• Sign and set headers. The SDK attaches Authorization: Bearer sk_..., a Stripe-Version, and an Idempotency-Key that stops a retry from double-charging a customer.
• Retry. On a 429 or 5xx, the SDK backs off and tries again.
• The network call. The one rung that leaves your process, and the only thing Stripe observes.
• Parse. The SDK decodes the response bytes and maps an error into a typed StripeError you can catch.

So “the wire” isn’t an abstraction. It’s a specific string of bytes the SDK builds for you, the request you’d read in a network tab.

POST /v1/checkout/sessions HTTP/1.1
Host: api.stripe.com
Authorization: Bearer sk_live_***
Stripe-Version: 2025-04-30
Idempotency-Key: 6f1c... (auto-generated)
Content-Type: application/x-www-form-urlencoded

mode=subscription&line_items[0][price]=price_pro_monthly&line_items[0][quantity]=1&metadata[userId]=usr_123&metadata[orgId]=org_42

Method, path, and host. Your call site named none of these; sessions.create resolved to POST /v1/checkout/sessions on api.stripe.com. A function-mock checks your arguments, never that the request reached the right place.

POST /v1/checkout/sessions HTTP/1.1
Host: api.stripe.com
Authorization: Bearer sk_live_***
Stripe-Version: 2025-04-30
Idempotency-Key: 6f1c... (auto-generated)
Content-Type: application/x-www-form-urlencoded

mode=subscription&line_items[0][price]=price_pro_monthly&line_items[0][quantity]=1&metadata[userId]=usr_123&metadata[orgId]=org_42

Three headers the SDK added, not you. The Idempotency-Key matters most: it stops a retried checkout from charging twice. No mock of your code can verify a header your code never wrote.

POST /v1/checkout/sessions HTTP/1.1
Host: api.stripe.com
Authorization: Bearer sk_live_***
Stripe-Version: 2025-04-30
Idempotency-Key: 6f1c... (auto-generated)
Content-Type: application/x-www-form-urlencoded

mode=subscription&line_items[0][price]=price_pro_monthly&line_items[0][quantity]=1&metadata[userId]=usr_123&metadata[orgId]=org_42

The body, form-encoded rather than JSON. Your { price, quantity } object became line_items[0][price]=.... Real Stripe parses this exact string; a mock of create() receives your object and never runs the serializer that produces it.

← Previous 1 / 1 Next →

The payoff is bigger than Stripe. Every outbound HTTP client is this same tower over one network call: the Resend SDK, an AI provider’s SDK, an internal RPC client. They differ in what they serialize and which host they hit, but they all bottom out at the same rung, because the network is the one exit they all share. That shared exit is why a single tool can mock all of them: MSW (Mock Service Worker) intercepts at the network rung, so it doesn’t care which SDK built the request. The mechanics are the next lesson.

Two ways to mock too high

The naive test mocked too high up the tower. “Too high” comes in two flavors, one rung apart. Here are all three options, the two mistakes and the fix, with what each actually tests.

Mock the function

const createSession = vi.spyOn(
  stripeClient.checkout.sessions,
  'create',
);

await createSubscription({ priceId: 'price_pro_monthly' });

expect(createSession).toHaveBeenCalledWith(
  expect.objectContaining({ mode: 'subscription' }),
);

Asserts your inputs, nothing else. The serializer, signer, retry, and parser never run, so you’ve tested only the object you handed create. When Stripe bumps the Stripe-Version header your client sends and the new version rejects a field you pass, real requests start 400ing. Your spy saw your arguments, never the header.

Mock the SDK class

vi.mock('stripe', () => ({
  default: class FakeStripe {
    checkout = {
      sessions: { create: vi.fn().mockResolvedValue({ url: 'https://x' }) },
    };
  },
}));

The same trap, one rung deeper. Request building, idempotency-key generation, and error mapping are all hand-written stand-ins, so your test runs against a Stripe that doesn’t exist. Break the SDK’s key generation in a refactor and retried checkouts ship without a key; a customer who double-clicks “Subscribe” is charged twice. No test built on FakeStripe catches it, because the fake never generated a key.

Mock the wire

server.use(
  http.post('https://api.stripe.com/v1/checkout/sessions', () =>
    HttpResponse.json({ id: 'cs_test_123', url: 'https://checkout.stripe.com/c/x' }),
  ),
);

await createSubscription({ priceId: 'price_pro_monthly' });
// the real SDK ran: it serialized, signed, and sent a real request.
// we assert on that request — the bytes Stripe would have seen.

The real SDK runs; only the network is frozen. The serializer, signer, and retry build an actual request, and MSW catches it at the boundary and returns a canned response. Everything above the network line is production code; only the bytes below it are fake. Real tower, frozen ground.

You’ve seen this shape before. Last lesson, mocking the JWT verifier instead of auth.api.getSession was too deep: you reached past the boundary your code calls, into the library’s internals. Mocking create here is too shallow: you stopped short of the boundary that matters, the network. Too deep and too shallow are the same error, the wrong boundary, the same skill pointed at a different seam.

So one diagnostic, for any test that touches a third party:

Tip

If my assertion is about which SDK method ran with what arguments, I’m mocking too high. If it’s about what request crossed the wire, I’m at the boundary.

Watch video

Artem Zakharchenko, MSW’s creator, opens with this section’s failure mode: drawing the test boundary too high and throwing away the code you most need to test.

Mock what you don’t own, roll back what you do

This lesson and the chapter’s first are two halves of one idea. There you tested against a real Postgres and contained it with transaction rollback; here you mock Stripe and never let a real request leave the machine. Run the real thing in one place, fake it in the other: the contradiction dissolves once you ask the only question that matters, do you own this boundary?

Tip

Mock the boundary you don’t own: Stripe, Resend, AI providers, any third-party HTTP. Roll back the boundary you do own: your Postgres.

You don’t own Stripe, so freeze the wire and assert on the request your code produced, the half of the contract you’re responsible for, rather than risk flaky networks, rate limits, and charges to real cards in CI.

You own your Postgres, so run it for real and roll it back: a stub only encodes your assumptions about the schema, and the schema is the thing most likely to have drifted.

createSubscription your Server Action

you own it

Postgres your schema

you don't own it

Stripe api.stripe.com

One action, two boundaries, opposite rules — keyed on which one you own.

Now check that the rule transferred. The trap is sliding “your Postgres” into the mock column, so watch for it as you sort.

Each of these is something an integration test has to deal with. Decide whether to mock it at the network boundary, or run it for real and roll it back. Drag each item into the bucket it belongs to, then press Check.

Mock the wire (MSW) You don't own it — freeze the request

Run it, roll back (tx) You own it — run the real thing

stripeClient.checkout.sessions.create

An insert into your own invoices table

A resend.emails.send call

A Drizzle query against your own schema

An OpenAI completion call

Reading your own session row

Check Reset

If every database item landed in “run it, roll back,” the rule transferred: one question, not two techniques.

Assert on the request, not the call

You know where to mock. What’s left is what to assert: the request your code sent. State the contract plainly: “when a member subscribes, the action must POST to Stripe with metadata.userId, metadata.orgId, and an Idempotency-Key header.” The arrange-act-assert shape is the one you know; only the assert line changes, from the SDK call to the intercepted request MSW caught.

// ❌ asserts the call you made — blind to everything the SDK did with it
expect(stripeClient.checkout.sessions.create).toHaveBeenCalledWith(/* ... */);

// ✓ asserts the request Stripe would have received
expect(capturedRequest.headers.get('Idempotency-Key')).toBeTruthy();
expect(decodedBody).toMatchObject({ metadata: { userId: 'usr_123' } });

How you capture capturedRequest and decodedBody is the next lesson. Two policies make this assertion trustworthy. First, an unhandled request must fail loud: set onUnhandledRequest: 'error' so a call you forgot to handle throws instead of returning a silent 200 that fakes success. Second, no hand-rolled fetch outside your client layer: route third-party HTTP through a typed client like stripeClient, so every call has one seam to intercept. A raw fetch in a handler is a refactor target first, a test target second.

Boundary mocks are assumptions; contract tests catch drift

A boundary mock encodes what you assume the third party does, and that assumption can drift: Stripe ships changes on its own schedule, and your frozen handler won’t hear about them. The catch is a different test, named here only so you know it exists: a contract test runs against Stripe’s live sandbox on a schedule, nightly rather than per commit, to notice when reality has drifted from your assumption. Too slow and flaky for the inner loop, it lives outside it.

Note

Building contract tests is out of scope for this chapter. You have the name and the shape, enough to reach for them when a provider’s drift starts biting.

One habit follows: hand-write your fixtures, don’t record them. A recorded Stripe response arrives bloated with dozens of fields you never assert on, and when one of those drifts, nothing tells you. Five explicit lines naming only the fields your test reads, HttpResponse.json({ id: 'cs_test_123', url: '...' }), keep your assumption about Stripe’s response visible in the test.

A test does vi.mock('stripe') and asserts checkout.sessions.create ran with the expected line_items. It’s green. Which production failures is this test structurally unable to catch? Select all that apply.

You passed the wrong priceId into line_items from the action.

A regression drops the auto-generated Idempotency-Key, so a double-clicked subscribe charges twice.

Stripe starts 400ing because the SDK negotiates a Stripe-Version the account no longer accepts.

The action calls create even though the member is on a plan that shouldn’t reach checkout.

Your action writes an audit-log row to your own Postgres and fires an HTTP call to your internal notifications microservice — a separate service your team also runs. In one integration test, how should each collaborator be handled?

Mock both: each is a collaborator the action depends on, and mocking keeps the test fast and isolated.

Let the audit-log insert hit the database inside tx and roll it back; intercept the notifications request at the network and assert on it.

Run both against the real services — only an end-to-end path proves the action actually works.

Stub the audit-log write, but let the notifications call go through for real, since it’s the side effect that matters most here.

External resources

MSW — Philosophy: intercept at the network boundary

mswjs.io

The tool author's case for the exact thesis of this lesson: mock at the network level, not the call site.

Kent C. Dodds — Stop mocking fetch

kentcdodds.com

Why mocking the client or fetch gives false confidence, and what to assert at the network instead.

Stripe — Designing robust APIs with idempotency

stripe.com

A deep dive on the Idempotency-Key header this lesson highlights, and the safe-retry behavior the SDK gives you.