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:
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:
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