Unit test coverage for the cart checkout flow, Stripe integration, and fee calculations.

Cart Checkout — Unit Test Coverage

81 tests across 5 suites. Every test exists because a real failure mode was identified during design — there are no "nice to have" tests here.

Checkout Flow Overview

                         ┌──────────────┐
                         │  CartDrawer  │
                         └──────┬───────┘
                                │
                    ┌───────────▼───────────┐
                    │  POST /cart/validate   │  ← 26 tests
                    │  (pre-flight check)    │
                    └───────────┬───────────┘
                                │ per-line status
                    ┌───────────▼───────────┐
                    │  POST /cart/checkout   │  ← 18 tests
                    │  (create PI)           │
                    └───────────┬───────────┘
                                │ clientSecret
                    ┌───────────▼───────────┐
                    │  stripe.confirmPayment │  (frontend, not tested here)
                    │  (on-session, 3DS)     │
                    └───────────┬───────────┘
                                │ PI succeeds
                    ┌───────────▼───────────┐
                    │  POST /cart/confirm    │  ← 14 tests
                    │  (transfers + txns)    │
                    └───────────┘

    ┌──────────────────────┐         ┌──────────────────────┐
    │  POST /stripe/       │         │  stripeClient.js     │
    │  setup-card          │ ← 8     │  (fee utils)         │ ← 15 tests
    └──────────────────────┘         └──────────────────────┘

1. validate-cart — 26 tests

Pre-flight validation that determines which cart lines can proceed to checkout. This is the last safety net before money moves.

Auth & Input Validation (5 tests)

#	Test	Why it exists
1	401 if not authenticated	Cart validation must never leak data for unauthenticated users. Without this, an attacker could probe session availability for any cart ID.
2	400 if cartId missing	Missing field should fail fast rather than throwing a Supabase query error downstream.
3	404 if cart not found	Could be wrong user, wrong cart ID, or cart already checked out (status != active). Must not reveal why it wasn't found.
4	400 if cart is empty (no lines)	A cart with zero lines should never reach the session query layer — it's a client bug or stale cart.
5	400 if cart lines are null	Supabase can return `null` instead of `[]` for some error conditions. Prevents `lines.map is not a function` crash.

Line Status: `available` (3 tests)

#	Test	Why it exists
6	Marks available when published + has seats	Happy path baseline — confirms the normal case works and `available` count increments.
7	Counts `price_changed` toward canCheckout	Price changes are informational, not blocking. Parent should see the new price and still be able to proceed. If we blocked on price changes, stale carts would be permanently stuck.
8	Allows checkout when `registration_opens_at` is null	Null means "always open". Must not accidentally treat null as a falsy date and block.

Line Status: `price_changed` (1 test)

#	Test	Why it exists
9	Detects price changes, reports both prices	Vendor can change session price after parent adds to cart. Frontend needs `currentPrice` and `cartPrice` to show "was $50, now $60".

Line Status: `session_not_found` (1 test)

#	Test	Why it exists
10	Marks `session_not_found` when session deleted	Vendor can delete a session while it's in someone's cart. Must gracefully degrade, not crash with "Cannot read property 'status' of undefined".

Line Status: `not_open` (3 tests)

#	Test	Why it exists
11	Marks `not_open` when `registration_opens_at` is future	Core gate for the "drop time" feature. Sessions with future registration dates must not be purchasable early.
12	Allows checkout when `registration_opens_at` is past	Confirms the date comparison works in the right direction — past dates must not block.
13	Allows checkout when `registration_opens_at` is null	Null = always open (re-tested in this context to ensure null doesn't accidentally trip the date comparison).

Line Status: `session_not_available` (2 tests)

#	Test	Why it exists
14	Draft session → `session_not_available`	Vendor may unpublish a session mid-booking. Must block checkout, not allow booking against a draft.
15	Cancelled session → `session_not_available`	Different status, same behaviour — cancelled sessions are dead.

Line Status: `sold_out` (2 tests)

#	Test	Why it exists
16	`seats_remaining` is 0 → sold out	Obvious case, but must be explicitly tested because `0` is falsy in JS.
17	`null` seats_remaining → treated as 0	New sessions or misconfigured data may have null. The `??` operator must default to 0, not pass `null` to arithmetic.

Multi-Line Seat Allocation (5 tests)

These test the fairness algorithm when a parent books multiple children into the same session.

Session S-1: seats_remaining = 1

Cart:
  line-1 → S-1 (child Alice)    ← gets the seat
  line-2 → S-1 (child Bob)      ← sold_out

Order matters: lines are processed in created_at order.

#	Test	Why it exists
18	2 children, 1 seat → first gets seat, second sold out	Fairness: first-come-first-served within a single cart. Without per-session tracking, both lines would see `seats_remaining: 1` and both would be marked available.
19	3 children, 3 seats → all available	Boundary: exact match should work. Off-by-one errors here would block legitimate bookings.
20	2 children, exactly 2 seats → both available	Boundary test at the exact limit.
21	Mixed statuses across different sessions	Integration test: one session available, one deleted, one full, one not open, one price changed. Validates all 5 status paths simultaneously.
22	All lines unavailable → `canCheckout: false`	Edge: if nothing can be booked, the checkout button must be disabled.

Independent Seat Pools (1 test)

#	Test	Why it exists
23	Seat allocation is independent per session	Without this, a bug in the `seatsAllocated` map could mix up sessions — booking a seat in S-1 could accidentally decrement S-2's count.

Error Handling (2 tests)

#	Test	Why it exists
24	cart_lines query throws → 500	Supabase downtime must return a clean 500, not an unhandled promise rejection that kills the process.
25	sessions query throws → 500	Same rationale — both dependent queries must be caught.

Status Priority (2 tests)

#	Test	Why it exists
26	`session_not_found` > all other statuses	If session doesn't exist, we should never check its fields (would crash). Confirms the `continue` short-circuit works.
25	`not_open` > `session_not_available`	A session that is both draft AND has a future registration date: we want the user to see "not open yet", not "unavailable" — it implies the session will become available.

2. checkout — 18 tests

Creates the PaymentIntent. This is where money gets committed — every edge case here is a potential incorrect charge or lost payment.

Auth & Input Validation (6 tests)

#	Test	Why it exists
1	401 if not authenticated	Must never create a PaymentIntent for an unknown user.
2	400 if cartId missing	Fail fast before querying Supabase.
3	404 if cart not found	Wrong user, wrong ID, or already checked out.
4	400 if cart is empty	Zero lines = no amount to charge.
5	400 if total amount is 0	All lines have `price_sub_units: 0`. Stripe rejects PI with `amount: 0`, so we catch it first with a clear message.
6	null `price_sub_units` treated as 0	Database can have nulls. `null + 5000 = NaN` in JS — the `

Happy Path (4 tests)

#	Test	Why it exists
7	Creates PI and returns clientSecret on success	Golden path: verifies the full chain (Supabase queries → Stripe customer → checkout group → PI → response).
8	Sums total correctly across multiple lines	Arithmetic: 1500 + 2500 + 7000 = 11000. Catches off-by-one or double-counting bugs.
9	`transfer_group` format is correct	The transfer_group links the PI to later Transfers. Format must match `activityfox-checkout-{checkoutId}` exactly — a mismatch means transfers don't reconcile in Stripe Dashboard.
10	PI metadata includes all required fields	Stripe metadata is how we reconcile disputes, refunds, and customer support lookups. Missing metadata = manual investigation.

Stripe Customer Resolution (2 tests)

  User checkout
      │
      ▼
  ┌──────────────────────────────┐
  │ stripe_customers lookup      │
  │   EXISTS? ──yes──▶ use it    │
  │   NULL?   ──no───▶ create    │
  │              ├─▶ stripe.customers.create()
  │              └─▶ INSERT stripe_customers
  └──────────────────────────────┘

#	Test	Why it exists
11	Uses existing customer when found	Must NOT create duplicate Stripe customers. Duplicates cause payment method confusion and reconciliation hell.
12	Creates new customer + stores in DB when none exists	First-time buyer flow. Verifies email/name are passed, metadata is set, and the customer ID is persisted for next time.

Currency Handling (2 tests)

#	Test	Why it exists
13	Uses cart currency when set	Multi-currency support: USD carts should charge USD, not AUD.
14	Defaults to AUD when currency is null	Australian marketplace — AUD is the safe default. `null` currency must not crash Stripe.

Error Handling (4 tests)

#	Test	Why it exists
15	Stripe PI creation fails → 500	Rate limits, network errors, invalid API key. Must not leave orphaned checkout_groups.
16	checkout_groups insert fails → 500	Unique constraint violation (race condition: double-click) or DB downtime.
17	cart_lines query errors → 500	Supabase timeout during line fetch.
18	Preserves Stripe error status code	Stripe errors carry their own HTTP status (e.g., 402 for card_declined). We forward it instead of masking as 500.

3. confirm-checkout — 14 tests

The most critical endpoint: verifies payment, distributes money to vendors, and creates bookings. Partial failures here mean money moved but bookings didn't happen — every guard matters.

Auth & Input Validation (3 tests)

#	Test	Why it exists
1	401 if not authenticated	Must never distribute money for unauthenticated requests.
2	400 if checkoutId missing	Fail fast.
3	404 if checkout not found	Wrong user, wrong ID.

Idempotency Guards (2 tests)

  confirm-checkout called
        │
        ▼
  ┌──────────────────────┐
  │  checkout.status?    │
  │                      │
  │  "completed"  ──────▶ 409 "already completed"
  │  "pending"    ──────▶ 409 "invalid status"
  │  "awaiting_payment" ─▶ proceed ✓
  └──────────────────────┘

#	Test	Why it exists
4	409 if already completed	Double-charge prevention. If frontend retries after a network timeout, we must not create duplicate transfers. This is the most important guard in the entire checkout system.
5	409 if status is not `awaiting_payment`	A checkout stuck in `pending` means the PI was never created — confirming it would crash on null `stripe_payment_intent_id`.

PaymentIntent Verification (2 tests)

#	Test	Why it exists
6	402 if PI `requires_payment_method`	Payment failed or was abandoned. Must not create transfers against an unpaid PI.
7	402 if PI `requires_action` (3DS)	User didn't complete 3DS authentication. Frontend should redirect back to Stripe, not call confirm.

Happy Path (1 test)

#	Test	Why it exists
8	Creates transfers + Sharetribe transactions for each line	Full integration: verifies transfer amounts (85% to vendor), transfer_group linkage, Sharetribe `transactions.initiate()` with correct process alias, listing ID, booking dates, and protectedData.

Vendor Stripe Account Edge Cases (3 tests)

#	Test	Why it exists
9	Skips transfer when vendor has no Stripe account	New vendors may not have onboarded to Stripe yet. Booking should still be created — vendor gets paid later via manual payout.
10	Skips transfer when vendorPayout is 0	Free sessions (community events). Transfer of $0 would error on Stripe.
11	protectedData fallback for Stripe account ID	Sharetribe stores vendor Stripe ID in either `privateData` or `protectedData` depending on configuration. Must check both.

Partial Failure Handling (1 test)

  Line 1: Transfer ✓  Sharetribe TX ✗ (listing not found)  → failed[]
  Line 2: Transfer ✓  Sharetribe TX ✓                      → transactions[]
                                                               │
  checkout_groups.status = "completed"  ◀──────────────────────┘
  (even with partial failure — money has moved)

#	Test	Why it exists
12	Continues processing after one line fails	Non-atomic by design. If line 1 fails (listing deleted between validate and confirm), line 2 must still process. Failed lines are returned in the `failed[]` array for the frontend to display. The alternative — rolling back all transfers — is worse because it introduces refund complexity.

Vendor Lookup Failure (1 test)

#	Test	Why it exists
13	Vendor API lookup failure doesn't crash checkout	Sharetribe Integration API might be down. The vendor just doesn't get a transfer, but the booking still happens.

Finalization (1 test)

#	Test	Why it exists
14	Marks checkout_groups completed + cart checked_out	Both status updates must happen. Without them: duplicate checkouts (checkout_groups) or stale carts showing in the UI (carts).

4. setup-card — 8 tests

Saves a card for future use. Simpler flow, but Stripe Customer creation has the same duplicate-prevention concerns as checkout.

Auth (1 test)

#	Test	Why it exists
1	401 if not authenticated	Must never create a Stripe Customer for unknown users.

Customer Resolution (3 tests)

#	Test	Why it exists
2	SetupIntent with existing customer	Must attach the card to the existing customer, not create a duplicate.
3	Creates new customer when none exists	First-time card save. Verifies email, name, and metadata.
4	Stores new customer in stripe_customers table	The insert must happen so checkout later finds this customer. Without it, every checkout would create yet another Stripe Customer.

SetupIntent Configuration (1 test)

#	Test	Why it exists
5	Metadata includes platform + user ID	Reconciliation in Stripe Dashboard.

Error Handling (3 tests)

#	Test	Why it exists
6	Stripe customer creation fails → 500	Network error or Stripe outage.
7	SetupIntent creation fails → 500	Stripe rejects (rate limit, invalid params).
8	Preserves error status code	503 from Stripe should propagate as 503, not 500.

5. stripeClient (fee utilities) — 15 tests

Money math. Rounding errors here mean the platform either loses money or overcharges vendors on every single transaction.

calculatePlatformFee (7 tests)

#	Test	Why it exists
1	15% of $100.00 = $15.00	Baseline correctness.
2	Rounds to nearest integer	`333 × 0.15 = 49.95` → `50`. Stripe deals in integers (cents). Rounding must be deterministic.
3	0 amount → 0 fee	Free sessions must not produce phantom fees.
4	1 sub-unit → 0 fee	`1 × 0.15 = 0.15` rounds to 0. Ensures the platform doesn't claim 1 cent on a 1-cent charge (which would leave 0 for the vendor).
5	$99,999.99 (large amount)	No integer overflow at realistic maximums. `9,999,999 × 0.15 = 1,499,999.85` must round correctly.
6	$1,000,000.00 (very large)	Stress test for larger amounts (events, corporate bookings).
7	Rounding always produces integer	Property test across 10 odd values. Catches any case where `Math.round` might return a float.

calculateVendorPayout (6 tests)

#	Test	Why it exists
8	$100.00 → $85.00 payout	Baseline.
9	fee + payout = original (single value)	The money invariant: no money created or destroyed.
10	0 amount → 0 payout	Symmetry with fee.
11	fee + payout = amount across 12 values	The critical money-leak test. Tests amounts from 1 cent to $99,999.99. If `Math.round` in fee and `amount - fee` in payout ever disagree, money vanishes. This would compound across thousands of transactions.
12	1 sub-unit: payout=1, fee=0	Minimum non-zero: vendor gets the penny, platform gets nothing.
13	7 sub-units: fee=1, payout=6	`7 × 0.15 = 1.05` → fee rounds to 1. Verifies small-amount rounding.

PLATFORM_COMMISSION_PCT (2 tests)

#	Test	Why it exists
14	Defaults to 15	Must not silently change. A misconfigured env var could set it to 0 or 100.
15	Is an integer	`parseInt` must not produce `NaN` or a float.

What's NOT Tested (and Why)

Gap	Reason
Race condition: two carts checkout same last seat	Sharetribe handles this. `transactions.initiate()` is the atomic gate — if the seat is taken, Sharetribe rejects the transaction. Our validate-cart is advisory only.
Stripe webhook for async PI confirmation	Not implemented yet. Current flow is on-session only — 3DS completes inline. Webhooks will be added for the drop-time deferred checkout feature.
Frontend Stripe Elements integration	Tested via browser integration tests, not unit tests.
Supabase RLS policies	Tested via migration integration tests against a real Supabase instance, not mocked unit tests.
Transaction process state machine	Defined in EDN, tested by Sharetribe's flex-cli tooling.

Running the Tests

# All cart/stripe tests (81 tests, ~1s)
npx jest --testPathPattern='server/api-util/stripeClient|server/api/cart/|server/api/stripe/'

# Individual suites
npx jest server/api/cart/validate-cart.test.js    # 26 tests
npx jest server/api/cart/checkout.test.js          # 18 tests
npx jest server/api/cart/confirm-checkout.test.js  # 14 tests
npx jest server/api/stripe/setup-card.test.js      #  8 tests
npx jest server/api-util/stripeClient.test.js      # 15 tests

Test Coverage

On this page