ORBCART DOCUMENTATION
Test a purchase
A Vitest test that buys a backpack against your real Worker, pays with a card through a fake Stripe, reads the Order back and proves a double click buys once.
You write the one test every shop should have: it buys something. It runs your real Worker, your
real offers and the real SDKs, fakes only Stripe, and ends with an Order your backend can read. A
second click on the order button must not buy twice, so the test proves that too.
You need a commerce Worker that maps card to stripe, and the vitest.config.ts from
Testing, which runs the Worker and its Durable Objects locally.
The test
import { env, exports } from "cloudflare:workers";
import { createAdmin } from "@orbcart/admin";
import { createCommerce } from "@orbcart/client";
import { fakeStripe, issueKey, publishStandardRates } from "@orbcart/runtime/testing";
import { afterEach, beforeEach, expect, it, vi } from "vitest";
const url = "https://commerce.test";
const worker = (request: Request) => exports.default.fetch(request);
const shipTo = {
name: "Anna Berg",
line1: "Bergstraße 12",
postalCode: "10115",
city: "Berlin",
country: "DE",
};
// What Stripe's card field hands over; the fake takes any token.
const byCard = { payment: "card", instrument: { confirmationToken: "ctoken_test" } };
beforeEach(async () => {
vi.stubGlobal("fetch", fakeStripe({ created: { status: "requires_capture" } }).fetch);
// An `eu-standard` Channel quotes with the day's EU rates, published here without the network.
const today = new Date().toISOString().slice(0, 10);
await publishStandardRates(env, { on: today, rates: { DE: "19" } });
});
afterEach(() => {
vi.unstubAllGlobals();
});
it("buys a backpack with a card, once, and hands the Order to the backend", 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" } });
const result = await quote.accept(byCard);
if (result.status !== "ordered") throw new Error(`Expected an Order, got ${result.status}.`);
expect(result.order.quote.totals.total).toEqual(quote.totals.total);
// A double click is the same purchase: the same Payment, the same Order.
expect(await quote.accept(byCard)).toMatchObject({
status: "ordered",
order: { id: result.order.id },
});
const admin = createAdmin({ url, key: await issueKey(env, { kind: "secret" }), fetch: worker });
const order = await admin.orders.get(result.order.id);
expect(order.payment).toMatchObject({ method: "card", provider: "stripe" });
});Run it with pnpm exec vitest run test/purchase.test.ts.
What each part does
| Part | Why |
|---|---|
exports.default.fetch | Your Worker as the SDKs reach it, without a network. |
issueKey | A publishable key for the storefront, a secret key for the backend, straight from the Worker. |
fakeStripe | Answers like Stripe and keeps the first answer per idempotency key, as Stripe does. |
requires_capture | The card is authorized at once. Leave it out and the fake asks for 3-D Secure. |
quote.accept() | pay() without a buyer: it takes the field's token as instrument and runs no dialog. |
When your systems use fetch too
fakeStripe answers every request as Stripe would. If your offers or ERP calls go out over
fetch, send Stripe's to the fake and the rest to a fake of your own:
import { vi } from "vitest";
import { fakeStripe } from "@orbcart/runtime/testing";
const stripe = fakeStripe({ created: { status: "requires_capture" } });
vi.stubGlobal("fetch", (input: RequestInfo | URL, init?: RequestInit) =>
new URL(input instanceof Request ? input.url : input).host === "api.stripe.com"
? stripe.fetch(input, init)
: fakeErp(input, init),
);fakeErp is yours: answer the articles your test buys. Never mock OrbCart itself; fake only what you
do not own.
Next
- Testing: 3-D Secure with signed webhooks, EU rates and component tests without a Worker.
- Free shipping and a welcome code: the same setup proves a promotion.
- Nordgrat's
examples/nordgrat/test/scenarios.test.ts: a sale ending mid-checkout, the ERP away for an hour, one part of a bundle refunded.
A gift message, end to end
Declare a gift message once, let the buyer write it in the bag, and print it on the packing slip. Checked on the server, kept in the Quote and frozen in the Order.
Extend OrbCart
Every place your code plugs into OrbCart, from one line of configuration to a package of your own, and what cannot be extended yet.