Checkout stability playbook

This playbook is the minimum required test matrix before any change to cart, shipping, payment, or order modules merges to main. It pairs backend orchestration, the payment gateway, the checkout UI, and the storefront — a missed regression in any of these costs real orders.

Cadence

Per PR touching cart, order, payments, or any PSP module: run the smoke sequence
Weekly against production: full matrix (smoke + cross-PSP + idempotency)
Pre-release for every backend tag: full matrix + chaos drills

1. Test fixtures

A reliable stability program needs known-good and known-broken fixtures so every regression test has predictable inputs.

Never point smoke tests at real merchant shops. Use the fixture shops below.

Fixture shops

Slug	Purpose	Shipping profile	Payment methods
`qa-physical-easypost`	Real EasyPost rates, physical goods, US→US	EasyPost	Stripe (test), PayMob (sandbox), Bonum (sandbox)
`qa-physical-printful`	POD goods via Printful	Printful	Stripe (test)
`qa-physical-uae`	UAE→MENA, exercises Telr + PayMob	Custom flat-rate by country	Telr (sandbox), PayMob (sandbox), Stripe (test)
`qa-digital-only`	Pure digital items, no shipping	none	Stripe (test), Bonum (sandbox)
`qa-mixed`	Physical + digital, split shipping	EasyPost (physical only)	Stripe (test)
`qa-crypto`	Web3 product, on-chain settlement	none / digital	x402 / Coinbase Commerce / SOL Pay

Fixture customer accounts

Test-mode-only — never real cards.

Email	Card	Address country	Why
`qa+stripe-pass@...`	`4242 4242 4242 4242`	US	Happy path
`qa+stripe-3ds@...`	`4000 0025 0000 3155`	US	Forces 3DS challenge
`qa+stripe-decline@...`	`4000 0000 0000 0002`	US	Generic decline
`qa+stripe-insufficient@...`	`4000 0000 0000 9995`	US	Insufficient funds
`qa+stripe-disputed@...`	`4000 0000 0000 0259`	US	Triggers dispute post-charge
`qa+stripe-mena@...`	`4242 4242 4242 4242`	AE / SA / EG	AVS variations, currency conversion

Fixture environments

Stage (apiv3stage + checkoutstage) — primary smoke target. Hits Stripe test mode, EasyPost test API, PayMob sandbox, Telr sandbox.
Production (apiv3prod + checkout.droplinked.io) — full live target. Run from a UAE-IP runner for IP-allowlist coverage.
Local docker compose — backend-only assertions; can’t exercise full Stripe Elements.

Fixture freshness

Schedule a weekly clean of qa-* shop carts older than 7 days, void all qa+* test charges, and archive completed test orders. Stops fixture rot from masking regressions.

2. Per-PR smoke sequence

Twelve assertions. Should complete in under 10 minutes against stage.

#	Scenario	Fixture	Expected
S1	Add 1 physical item → checkout init	`qa-physical-easypost`	200, cart ID returned, totals match items + 0 shipping
S2	Enter US shipping address → `availableShipping` populated	+ US addr	≥1 shipping group, ≥1 rate per group with `rateId` + price + carrier
S3	Select shipping rate → totals update	continued	`totals.shipping` reflects rate; `totals.total = items + shipping + tax`
S4	Create Stripe PaymentIntent → `client_secret`	continued	`clientSecret` + `paymentIntentId` present, no shipping mismatch
S5	Pay with `4242…` → order moves to `PAID`	continued	Order flips `PENDING`→`PAID` within 30s of webhook
S6	Stripe charge has populated branding fields	Stripe dashboard test mode	`statement_descriptor_suffix`, `receipt_email`, `shipping` block populated
S7	Digital-only cart skips shipping entirely	`qa-digital-only`	Frontend hides shipping section; checkout completes with billing only
S8	Mixed cart splits shipping correctly	`qa-mixed`	Only physical item in `availableShipping`; digital is unshippable but non-blocking
S9	EasyPost-tagged product gets real carrier rates	`qa-physical-easypost`, US→US	USPS / UPS / FedEx appear; no silent fallthrough to custom strategy
S10	Printful-tagged product gets Printful rates	`qa-physical-printful`	Printful strategy fires; no EasyPost call
S11	3DS challenge card completes payment	`qa+stripe-3ds@…`	Redirects to 3DS challenge, returns, charge completes
S12	Decline card lands clean error	`qa+stripe-decline@…`	Generic “card declined” surfaced, cart preserved, no order created

A PR that breaks any of S1–S12 against stage must not merge.

S1–S6 + S7 + S9 should run automatically in CI. S5, S11, S12 require Stripe sandbox client interaction (Playwright against test mode).

3. Cross-PSP matrix (weekly)

Run the same 12 scenarios across each enabled PSP for the relevant currency.

PSP	Currency	Origin	Dest
Stripe	USD	US	US
Stripe	AED	AE	AE
Stripe	AED	AE	SA
PayMob	EGP	EG	EG
PayMob	AED	AE	AE
Telr	AED	AE	AE
Bonum	MNT	MN	MN
Coinbase Commerce	USDC	global	digital (digital-only carts)
x402 / SOL Pay	USDC	global	digital (digital-only carts)
PayPal	USD	US	US

For each row, capture:

Time-to-complete checkout (p50, p95)
Webhook latency (PSP → integration service → backend)
Order status transition path
Cart-preserved-on-failure behavior

4. Idempotency + replay matrix

Every PR that touches webhook handlers or cart-status transitions must pass:

#	Scenario	Expected
I1	Same webhook delivered twice (Stripe replay)	Second is no-op; no double-paid; no duplicate emails
I2	Webhook arrives before payment-intent succeeded callback	Backend resolves to correct final state regardless of arrival order
I3	Webhook arrives 24h late (Stripe retries)	Still processed correctly; idempotency key honored
I4	Two concurrent “Pay Now” clicks	One PaymentIntent created; second click 4xxs cleanly (no double-charge)
I5	User abandons checkout, returns next day	Cart preserved if not expired; expired carts show empty-state, not 500
I6	Selected shipping rate expires (EasyPost ~15min TTL)	Backend revalidates; customer asked to reselect; no silent total drift
I7	Network failure mid-payment (Stripe `requires_action` → connection drop)	Order reconciles via webhook within 5 minutes

5. Chaos drills (pre-release / monthly)

Test failure modes that only happen in production.

#	Drill	How to simulate	Pass criteria
C1	EasyPost insufficient funds	Drain EasyPost wallet in sandbox	Backend alerts ops; existing checkouts fall back to flat-rate; new checkouts surface a graceful banner
C2	Stripe 5xx	Toxiproxy outage simulation	Backend retries once, then fails gracefully; cart preserved
C3	Mongo Atlas connection drop	Block Atlas IP in test env	Backend serves cached cart; surfaces error on writes; no 500s to reads
C4	Integration service down	Stop the 3rdp container	Backend opens circuit breaker after 3 failures; surfaces “Payment provider unavailable” within 2s
C5	Webhook signature failure (rotated key)	Send webhook with stale HMAC	401, log, alert; do NOT process the event
C6	Restricted Stripe key from unauthorized IP	Spin up runner without IP allowlist	Stripe returns 403; backend should not retry-loop
C7	UAE→US Stripe currency conversion	AED-priced order, US card	Conversion happens once; receipt + dashboard agree on FX rate
C8	Mixed cart with one out-of-stock item	Stock one item to 0 mid-checkout	Item removed with clear message; cart total recomputes; selected shipping rate revalidates

6. Known regression — EasyPost silently uses custom strategy

A product configured with shippingProfileId = 'easypost' can silently fall through to the custom shipping strategy if the strategy factory only registers Printful + Custom. The custom strategy’s canHandle returns true for any non-Printful profile, so EasyPost-tagged products get routed to a strategy expecting merchant flat-rate config. Result: empty availableShipping, checkout dead-ends at “Shipping these items is not available to this address.”

Fix path:

Implement an EasyPost shipping strategy

Wrap the easy-post module’s rate-fetch in a ShippingRateStrategy adapter.

Add it to the strategy factory’s default-initialization list before the custom strategy.

Tighten canHandle

Update the custom strategy to only return true for explicit 'custom' / 'flat-rate' identifiers — never as a catch-all.

Guard the regression

S9 in the per-PR smoke matrix is the standing regression guard once the strategy ships.

7. Tooling roadmap

What we have:

A narrowly-Bonum stress-test script — pattern-extend for other PSPs
Some payment-gateway specs needing repo-level jest cleanup
A backend CI workflow with lint+test as a soft-fail

What we need:

Playwright suite for S1–S12

Drive Stripe Elements test-mode card entry; assert on backend cart state via direct API checks between UI steps.

GitHub Actions workflow

checkout-smoke.yml runs the Playwright suite on every PR labelled area:checkout or touching cart/order/payments modules.

Tagged Stripe test-mode dashboard

Isolate regressions from real-money flow with a dedicated dashboard tag.

Weekly UAE-egress cron

Run sections 2 + 3 + 4 against production weekly from a UAE-IP runner; post to a #stability channel.

Chaos toolkit

Toxiproxy (or similar) for section 5 drills.

Appendix — “Shipping these items is not available” fault tree

"Shipping these items is not available to this address"
└── frontend: MethodsLoader status === 'failed'
    └── ShippingMethodsSection: noShippingAvailable === true
        └── cart.availableShipping has length 0
            ├── FetchShippingRateUseCase returned hasErrors: true
            │   ├── No strategy matched profileId
            │   ├── Strategy threw (EasyPost outage, Printful 5xx)
            │   └── Address mapping failed (country not in DB)
            └── FetchShippingRateUseCase returned empty responses
                ├── Custom strategy: shop has no flat-rate config for destination
                ├── Printful strategy: API returned no shippable carriers
                └── EasyPost insufficient funds (manifests as no rates)

Walk this tree from leaf upward to pin which node fired. Update the tree when a new node is discovered.

Get Started

Core Concepts

Deploy & Operate

Trust Fabric Guides

Order Lifecycle

Payment Integrations

Fulfillment Integrations

Library

Platform & Architecture

Cadence

1. Test fixtures

Fixture shops

Fixture customer accounts

Fixture environments

Fixture freshness

2. Per-PR smoke sequence

3. Cross-PSP matrix (weekly)

4. Idempotency + replay matrix

5. Chaos drills (pre-release / monthly)

6. Known regression — EasyPost silently uses custom strategy

7. Tooling roadmap

Appendix — “Shipping these items is not available” fault tree

​Cadence

​1. Test fixtures

​Fixture shops

​Fixture customer accounts

​Fixture environments

​Fixture freshness

​2. Per-PR smoke sequence

​3. Cross-PSP matrix (weekly)

​4. Idempotency + replay matrix

​5. Chaos drills (pre-release / monthly)

​6. Known regression — EasyPost silently uses custom strategy

​7. Tooling roadmap

​Appendix — “Shipping these items is not available” fault tree

​Related

Cadence

1. Test fixtures

Fixture shops

Fixture customer accounts

Fixture environments

Fixture freshness

2. Per-PR smoke sequence

3. Cross-PSP matrix (weekly)

4. Idempotency + replay matrix

5. Chaos drills (pre-release / monthly)

6. Known regression — EasyPost silently uses custom strategy

7. Tooling roadmap

Appendix — “Shipping these items is not available” fault tree

Related