Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

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:

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:

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.

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

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:

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:

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:

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:

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

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 →

On this page