Fixing Bugs — Strict TDD Red/Green Bug-Fix Cycle

Fixed. totalCents() let a fixed coupon push the total below zero. It now clamps at 0, and a regression test reproduces the exact Sentry error before the fix and passes after it.

I reproduced the two files from the report in a scratch project and ran everything below with Node's built-in test runner (node --test, Node 24). The output shown is real, with timing lines trimmed. Your project's full suite, linter and CI were

not run (see Next steps).

1. UNDERSTAND

GIVEN:    a cart with one item at 500 cents and coupon WELCOME10 (kind "fixed", value 1000)
WHEN:     checkout calls buildPaymentIntent(cart)
THEN:     RangeError "amount must be a non-negative integer (got -500)" → HTTP 500
EXPECTED: payment intent with amount 0 (fixed coupons never go below zero)

Platform dimension: none. This is pure integer arithmetic with no filesystem, encoding, subprocess or time zone involved, so a single-OS run is enough.

2. Root cause analysis

ROOT CAUSE:
  File: src/pricing.js
  Function: totalCents()
  Line: 7
  Issue: the fixed-coupon branch returns subtotal - coupon.value with no lower bound;
         500 - 1000 = -500, which buildPaymentIntent() correctly rejects
  Fix: return Math.max(0, subtotal - coupon.value)

The guard in checkout.js is behaving correctly. The bug is in pricing.js.

3. Characterization tests (pricing.js had no tests)

These capture the current behavior first, so the fix can't silently change the other branches.

// test/pricing.characterization.test.js
import { test } from "node:test";
import assert from "node:assert/strict";
import { totalCents } from "../src/pricing.js";

const items = [{ unitCents: 2500, qty: 2 }]; // $50.00

test("characterize: no coupon returns the subtotal", () => {
  assert.equal(totalCents(items, null), 5000);
});
test("characterize: percent coupon rounds to whole cents", () => {
  assert.equal(totalCents([{ unitCents: 999, qty: 1 }], { kind: "percent", value: 15 }), 849);
});
test("characterize: fixed coupon smaller than subtotal is subtracted", () => {
  assert.equal(totalCents(items, { kind: "fixed", value: 1000 }), 4000);
});

Result on the unmodified code: tests 3, pass 3, fail 0.

4. Failing test (RED)

The test goes through buildPaymentIntent(), the function in the Sentry stack trace, so it exercises the exact error path and not just the helper.

// test/checkout.bug-417.test.js
import { test } from "node:test";
import assert from "node:assert/strict";
import { buildPaymentIntent } from "../src/checkout.js";

test("should_build_zero_amount_intent_when_fixed_coupon_exceeds_subtotal", () => {
  // Arrange: the exact cart from BUG-417, a $5.00 cart with WELCOME10 ($10 off)
  const cart = {
    items: [{ unitCents: 500, qty: 1 }],
    coupon: { code: "WELCOME10", kind: "fixed", value: 1000 },
    currency: "usd",
  };
  // Act
  const intent = buildPaymentIntent(cart);
  // Assert: the expected behavior, not the buggy one
  assert.deepEqual(intent, { amount: 0, currency: "usd" });
});

TEST: should_build_zero_amount_intent_when_fixed_coupon_exceeds_subtotal
STATUS: FAILED
ERROR: RangeError: amount must be a non-negative integer (got -500)
       at buildPaymentIntent (src/checkout.js:6:11)
MATCHES BUG REPORT: Yes. Same exception, message and frame as the Sentry trace.

5. Fix (minimum change)

--- a/src/pricing.js
+++ b/src/pricing.js
@@ -4,5 +4,5 @@ export function totalCents(items, coupon) {
   if (coupon.kind === "percent") {
     return Math.round((subtotal * (100 - coupon.value)) / 100);
   }
-  return subtotal - coupon.value; // kind === "fixed", value in cents
+  return Math.max(0, subtotal - coupon.value); // kind === "fixed", value in cents; never below zero
 }

6. Passing test (GREEN)

TEST: should_build_zero_amount_intent_when_fixed_coupon_exceeds_subtotal
STATUS: PASSED
BEFORE FIX: RangeError: amount must be a non-negative integer (got -500)
AFTER FIX: pass
ROOT CAUSE: fixed-coupon branch had no lower bound

7. Regression check

$ node --test
✔ should_build_zero_amount_intent_when_fixed_coupon_exceeds_subtotal
✔ characterize: no coupon returns the subtotal
✔ characterize: percent coupon rounds to whole cents
✔ characterize: fixed coupon smaller than subtotal is subtracted
ℹ tests 4
ℹ pass 4
ℹ fail 0

• New bug-fix test passes (GREEN)
• Characterization tests still pass
• Your full unit and integration suite: not run. I only had these two files.
• Linter, formatter and type checker: not run
• CI: not run. The bug is not platform-related, so the normal pipeline is enough.

Brief explanation

• totalCents() subtracted a fixed coupon without a lower bound, so coupons larger than the cart produced negative totals.
• I clamped the fixed-coupon branch at 0. The percent branch and the checkout guard are unchanged.
• The bug-fix test stays in the suite as a permanent guard against this regression.

Suggested commit

fix: clamp fixed-coupon totals at zero

Bug: BUG-417
Root Cause: fixed-coupon branch in totalCents() had no lower bound (500 - 1000 = -500)
Fix: return Math.max(0, subtotal - coupon.value)
Test: should_build_zero_amount_intent_when_fixed_coupon_exceeds_subtotal

Next steps

1. Run npm test, the linter and the type checker in the real repo.

Open question, not fixed here: checkout now produces amount: 0. Many payment providers reject zero-amount charges, so confirm whether $0 orders should skip the payment step. That is a product decision and a separate change.
3. Possible follow-up ticket: a percent coupon above 100 would also go negative. The report didn't cover that case, so I left it alone.