# Testing

Test real purchases against your own Worker, in Vitest, without a network.

The best OrbCart test buys something. It runs your real Worker, your real
`offers` function and the real SDK, and fakes only what lies outside: the payment
provider and your ERP.

## Test your Worker

Use Cloudflare's Vitest integration. It runs your Worker and its Durable Objects
locally:

```ts title="vitest.config.ts"
import { cloudflareTest } from "@cloudflare/vitest-plugin";
import { defineProject } from "vitest/config";

export default defineProject({
  plugins: [
    cloudflareTest({
      wrangler: { configPath: "./wrangler.jsonc" },
      miniflare: {
        // Test values only. None of them is a usable credential.
        bindings: {
          JURISDICTION: "none",
          ROOT_SECRET: "b3JiY2FydC10ZXN0LXJvb3Qtc2VjcmV0LTMyYnl0ZXM",
          STRIPE_SECRET_KEY: "stripe-secret-for-tests",
          STRIPE_PUBLISHABLE_KEY: "stripe-publishable-for-tests",
          STRIPE_WEBHOOK_SECRET: "stripe-webhook-for-tests",
        },
      },
    }),
  ],
});
```

`JURISDICTION: "none"` is needed because the local runtime has no data jurisdictions.

## Buy something in a test

`@orbcart/runtime/testing` issues keys straight from the environment. Point the
SDK at your Worker with `fetch`:

```ts title="test/purchase.test.ts"
import { env, exports } from "cloudflare:workers";
import { createCommerce } from "@orbcart/client";
import { issueKey } from "@orbcart/runtime/testing";
import { expect, it } from "vitest";

const worker = (request: Request) => exports.default.fetch(request);
const url = "https://commerce.test";
const shipTo = {
  name: "Anna Berg",
  line1: "Bergstraße 12",
  postalCode: "10115",
  city: "Berlin",
  country: "DE",
};

it("quotes a backpack with shipping", async () => {
  const key = await issueKey(env, { kind: "publishable", channel: "de" });
  const commerce = createCommerce({ url, key, fetch: worker });

  const cart = await commerce.cart();
  await cart.add("BACKPACK-30-GREEN");
  const quote = await cart.quote({ shipTo, contact: { email: "anna@example.com" } });

  expect(quote.totals.total).toEqual({ amount: 9485, currency: "EUR" });
});
```

To pay as well, with a fake Stripe, and prove a double click buys once, see the recipe
[Test a purchase](/docs/shop/test-a-purchase).

For backend tests, issue a secret key and use the Admin SDK the same way:

```ts
const admin = createAdmin({ url, key: await issueKey(env, { kind: "secret" }), fetch: worker });
```

## EU VAT without the network

An `eu-standard` Channel needs the day's rates. Publish them in your test setup:

```ts
import { publishDailyRates } from "@orbcart/runtime/testing";

const today = new Date().toISOString().slice(0, 10);
await publishDailyRates(env, {
  on: today,
  rates: {
    DE: { standard: "19", reduced: ["7"] },
    AT: { standard: "20", reduced: ["4.9", "10", "13"] },
  },
});
```

## Fake the payment provider

Replace `fetch` at the boundary and answer like the provider would:

```ts
import { vi } from "vitest";

vi.stubGlobal("fetch", async (request: Request) => {
  if (request.url.includes("adyen.com"))
    return Response.json({ resultCode: "Authorised", pspReference: "PSP123" });
  throw new Error(`Unexpected request to ${request.url}`);
});
```

For Stripe there is a complete fake. It refuses what Stripe refuses, replays
idempotent requests and signs webhooks the way Stripe does:

```ts
import { vi } from "vitest";
import { fakeStripe } from "@orbcart/runtime/testing";

const stripe = fakeStripe({ created: { status: "requires_capture" } });
vi.stubGlobal("fetch", stripe.fetch);
```

`signedStripeEvent(env, stripe.authenticate(paymentId), webhookUrl)` builds the
signed webhook request for a 3-D Secure payment.
Never mock OrbCart itself. Fake only what you don't own.

## Test storefront code without a Worker

`@orbcart/client/testing` gives you a fake runtime with ready-made answers.
It's ideal for component tests:

```ts browser
import { fakeRuntime, cartPath, cart } from "@orbcart/client/testing";

const { commerce, requests } = fakeRuntime({
  [`GET ${cartPath}`]: cart,
});

// render your component with commerce.openCart(token) ...
expect(requests.map((r) => r.route)).toEqual([`GET ${cartPath}`]);
```

## Test scenarios worth having

Nordgrat's `test/scenarios.test.ts` shows how to write them:

- **A sale ends during checkout.** The buyer sees `quote_changed`, not the old price.
- **A double click on the order button.** One payment, one Order.
- **The ERP is down for an hour.** The Order arrives once it's back.
- **One part of a bundle is refunded.** The amount comes from the frozen Order.
- **A product can't go by express.** The method disappears with a reason.

## Commands

```sh
pnpm test                                                # everything
pnpm test:watch                                          # watch mode
pnpm --filter @orbcart/example-nordgrat exec vitest run  # one package
pnpm exec vitest run test/purchase.test.ts               # one file
```

[See every SDK and tool →](/docs/cart/sdks)