Test Writing Guide

Before Writing ANY Test

Search for duplicate scenarios — grep the test directory for similar setups
Read the rules file .claude/rules/write-tests.mdc — the 20 rules agents ALWAYS get wrong

Minimal Template

import { expect, test } from "bun:test";
import { type ApiCustomerV3 } from "@autumn/shared";
import { expectCustomerFeatureCorrect } from "@tests/integration/billing/utils/expectCustomerFeatureCorrect";
import { expectStripeSubscriptionCorrect } from "@tests/integration/billing/utils/expectStripeSubCorrect";
import { TestFeature } from "@tests/setup/v2Features.js";
import { items } from "@tests/utils/fixtures/items.js";
import { products } from "@tests/utils/fixtures/products.js";
import { initScenario, s } from "@tests/utils/testInitUtils/initScenario.js";
import chalk from "chalk";

test.concurrent(`${chalk.yellowBright("feature: description")}`, async () => {
  const messagesItem = items.monthlyMessages({ includedUsage: 100 });
  const pro = products.pro({ items: [messagesItem] });

  const { customerId, autumnV1, ctx } = await initScenario({
    customerId: "unique-test-id",
    setup: [s.customer({ paymentMethod: "success" }), s.products({ list: [pro] })],
    actions: [s.billing.attach({ productId: pro.id })],
  });

  const customer = await autumnV1.customers.get<ApiCustomerV3>(customerId);
  expectCustomerFeatureCorrect({ customer, featureId: TestFeature.Messages, balance: 100 });
  await expectStripeSubscriptionCorrect({ ctx, customerId });
});

initScenario — The Core System

initScenario creates customers, products, entities, and runs actions sequentially. It returns everything you need.

Returned Values

const {
  customerId,     // Customer ID (auto-prefixed products)
  autumnV1,       // V1.2 API client
  autumnV2,       // V2.0 API client
  ctx,            // { db, stripeCli, org, env, features }
  testClockId,    // Stripe test clock ID
  customer,       // Customer object after creation
  entities,       // [{ id: "ent-1", name: "Entity 1", featureId }]
  advancedTo,     // Current test clock timestamp (ms)
  otherCustomers, // Map<string, OtherCustomerResult>
} = await initScenario({ ... });

Setup Functions

Function	Purpose	Notes
`s.customer({ paymentMethod?, testClock?, data?, withDefault?, skipWebhooks? })`	Configure customer	`testClock` defaults `true`. Use `paymentMethod: "success"` for any paid product
`s.products({ list, customerIdsToDelete? })`	Products to create	Auto-prefixed with `customerId`
`s.entities({ count, featureId })`	Generate entities	Creates “ent-1” through “ent-N”
`s.otherCustomers([{ id, paymentMethod? }])`	Additional customers	Share same test clock as primary
`s.deleteCustomer({ customerId } \| { email })`	Pre-test cleanup	Delete before creating
`s.reward({ reward, productId })`	Standalone reward	ID auto-suffixed
`s.referralProgram({ reward, program })`	Referral program	IDs auto-suffixed

Action Functions — WITH TIMEOUT BEHAVIOR

CRITICAL: Know which actions have built-in timeouts and which don’t.

Function	Built-in Timeout	Notes
`s.billing.attach({ productId, options?, planSchedule?, items?, newBillingSubscription? })`	5-8s	V2 endpoint. Use for new billing tests
`s.attach({ productId, entityIndex?, options?, newBillingSubscription? })`	4-5s	V1 endpoint. Use for legacy/update-subscription setup
`s.billing.multiAttach({ plans, entityIndex?, freeTrial? })`	2-5s	`plans: [{ productId, featureQuantities? }]`
`s.cancel({ productId, entityIndex? })`	None	No timeout
`s.track({ featureId, value, entityIndex?, timeout? })`	None	Must pass `timeout` explicitly if needed
`s.advanceTestClock({ days?, weeks?, hours?, months? })`	Waits for Stripe	Cumulative from `advancedTo`
`s.advanceToNextInvoice({ withPause? })`	30s	Advances 1 month + 96h for invoice finalization
`s.updateSubscription({ productId, entityIndex?, cancelAction?, items? })`	None	cancel_end_of_cycle, cancel_immediately, uncancel
`s.attachPaymentMethod({ type })`	None	”success”, “fail”, “authenticate”
`s.removePaymentMethod()`	None	Remove all PMs
`s.resetFeature({ featureId, productId?, timeout? })`	2s default	For FREE products only. Use `s.advanceToNextInvoice` for paid
`s.referral.createCode()`	None	Create referral code
`s.referral.redeem({ customerId })`	None	Redeem for another customer

`s.billing.attach` vs `s.attach` — They Are DIFFERENT

	`s.attach`	`s.billing.attach`
Endpoint	V1 `/attach`	V2 `/billing.attach`
Extra params	none	`planSchedule`, `items` (custom plan)
Prepaid quantity	Exclusive of `includedUsage`	Inclusive of `includedUsage`
Use when	Legacy tests, update-subscription setup	New billing/attach tests

Product ID Prefixing

initScenario mutates product objects in-place: product.id becomes "${product.id}_${customerId}". So pro.id after initScenario already includes the prefix. Use product.id everywhere — in s.attach(), in direct API calls, and in assertions.

Multiple Customers — NEVER Call initScenario Twice

// Use s.otherCustomers in setup
const { autumnV1, otherCustomers } = await initScenario({
  customerId: "cus-a",
  setup: [
    s.customer({ paymentMethod: "success" }),
    s.products({ list: [pro] }),
    s.otherCustomers([{ id: "cus-b", paymentMethod: "success" }]),
  ],
  actions: [s.billing.attach({ productId: pro.id })],
});

// Or create manually after initScenario
await autumnV1.customers.create("cus-b", { name: "B" });
await autumnV1.billing.attach({ customer_id: "cus-b", product_id: pro.id });

Assertion Utilities — ALWAYS Use These

Product State

import { expectCustomerProducts, expectProductActive, expectProductCanceling,
  expectProductScheduled, expectProductNotPresent } from "@tests/integration/billing/utils/expectCustomerProductCorrect";

// PREFERRED — batch check multiple products in one call
await expectCustomerProducts({
  customer,
  active: [pro.id],
  canceling: [premium.id],    // "canceling" = status:active + canceled_at set
  scheduled: [free.id],
  notPresent: [oldProduct.id],
});

// Single product checks
await expectProductActive({ customer, productId: pro.id });
await expectProductCanceling({ customer, productId: premium.id });
await expectProductScheduled({ customer, productId: free.id });
await expectProductNotPresent({ customer, productId: pro.id });

Features

import { expectCustomerFeatureCorrect } from "@tests/integration/billing/utils/expectCustomerFeatureCorrect";

// IMPORTANT: requires `customer` object, does NOT fetch from API
expectCustomerFeatureCorrect({
  customer,                        // MUST be fetched customer object, not customerId
  featureId: TestFeature.Messages,
  includedUsage: 100,              // optional
  balance: 100,                    // optional
  usage: 0,                        // optional
  resetsAt: advancedTo + ms.days(30), // optional, 10min tolerance
});

Invoices

import { expectCustomerInvoiceCorrect } from "@tests/integration/billing/utils/expectCustomerInvoiceCorrect";

expectCustomerInvoiceCorrect({
  customer,          // ApiCustomerV3
  count: 2,          // Total invoice count
  latestTotal: 30,   // Most recent invoice total ($), +-0.01 tolerance
  latestStatus: "paid",
});

Stripe Subscription (ALWAYS call after billing actions)

import { expectStripeSubscriptionCorrect } from "@tests/integration/billing/utils/expectStripeSubCorrect";

// Basic — verify all subscriptions match expected state
await expectStripeSubscriptionCorrect({ ctx, customerId });

// With options
await expectStripeSubscriptionCorrect({
  ctx, customerId,
  options: { subCount: 1, status: "trialing", debug: true },
});

For free products, use expectNoStripeSubscription instead:

import { expectNoStripeSubscription } from "@tests/integration/billing/utils/expectNoStripeSubscription";
await expectNoStripeSubscription({ db: ctx.db, customerId, org: ctx.org, env: ctx.env });

Trials

import { expectProductTrialing, expectProductNotTrialing } from "@tests/integration/billing/utils/expectCustomerProductTrialing";

const trialEndsAt = await expectProductTrialing({
  customer, productId: pro.id, trialEndsAt: advancedTo + ms.days(7),
});
await expectProductNotTrialing({ customer, productId: pro.id });

Preview Next Cycle

import { expectPreviewNextCycleCorrect } from "@tests/integration/billing/utils/expectPreviewNextCycleCorrect";

expectPreviewNextCycleCorrect({ preview, startsAt: addMonths(advancedTo, 1).getTime(), total: 20 });
// Or when next_cycle should NOT exist:
expectPreviewNextCycleCorrect({ preview, expectDefined: false });

Proration

import { calculateProratedDiff } from "@tests/integration/billing/utils/proration";

const expected = await calculateProratedDiff({
  customerId, advancedTo, oldAmount: 20, newAmount: 50,
});
expect(preview.total).toBeCloseTo(expected, 0);

Invoice Line Items (for tests verifying stored line items)

import { expectInvoiceLineItemsCorrect, expectBasePriceLineItem } from "@tests/integration/billing/utils/expectInvoiceLineItemsCorrect";

// Full check with per-item expectations
await expectInvoiceLineItemsCorrect({
  stripeInvoiceId: invoice.stripe_id,
  expectedTotal: 20,
  expectedCount: 2,
  expectedLineItems: [
    { isBasePrice: true, amount: 20, direction: "charge" },
    { featureId: TestFeature.Messages, totalAmount: 0 },
  ],
});

// Quick base price check
await expectBasePriceLineItem({ stripeInvoiceId, amount: 20 });

Error Testing

import { expectAutumnError } from "@tests/utils/expectUtils/expectErrUtils";

await expectAutumnError({
  errCode: ErrCode.CustomerNotFound,
  func: () => autumnV1.customers.get("invalid-id"),
});

Cache vs DB Verification

import { expectFeatureCachedAndDb } from "@tests/integration/billing/utils/expectFeatureCachedAndDb";

await expectFeatureCachedAndDb({
  autumn: autumnV1, customerId,
  featureId: TestFeature.Messages, balance: 90, usage: 10,
});

Rollovers

import { expectCustomerRolloverCorrect, expectNoRollovers } from "@tests/integration/billing/utils/rollover/expectCustomerRolloverCorrect";

expectCustomerRolloverCorrect({
  customer, featureId: TestFeature.Messages,
  expectedRollovers: [{ balance: 150 }], totalBalance: 550,
});

Item & Product Fixtures — Quick Reference

Items (`@tests/utils/fixtures/items`)

Item	Feature	Default	Notes
`items.dashboard()`	Dashboard	boolean	On/off access
`items.monthlyMessages({ includedUsage? })`	Messages	100	Resets monthly
`items.monthlyWords({ includedUsage? })`	Words	100	Resets monthly
`items.monthlyCredits({ includedUsage? })`	Credits	100	Resets monthly
`items.monthlyUsers({ includedUsage? })`	Users	5	Resets monthly
`items.unlimitedMessages()`	Messages	unlimited	No cap
`items.lifetimeMessages({ includedUsage? })`	Messages	100	Never resets (interval: null)
`items.prepaidMessages({ includedUsage?, billingUnits?, price? })`	Messages	0, 100, $10	Buy upfront in packs
`items.prepaid({ featureId, includedUsage?, billingUnits?, price? })`	any	0, 100, $10	Generic prepaid
`items.prepaidUsers({ includedUsage?, billingUnits? })`	Users	0, 1	Per-seat prepaid
`items.consumableMessages({ includedUsage? })`	Messages	0	$0.10/unit overage
`items.consumableWords({ includedUsage? })`	Words	0	$0.05/unit overage
`items.consumable({ featureId, includedUsage?, price?, billingUnits? })`	any	0, $0.10, 1	Generic consumable
`items.allocatedUsers({ includedUsage? })`	Users	0	$10/seat prorated
`items.allocatedWorkflows({ includedUsage? })`	Workflows	0	$10/workflow prorated
`items.freeAllocatedUsers({ includedUsage? })`	Users	5	Free seats (no price)
`items.oneOffMessages({ includedUsage?, billingUnits?, price? })`	Messages	0, 100, $10	One-time purchase
`items.monthlyPrice({ price? })`	-	$20	Base price item
`items.annualPrice({ price? })`	-	$200	Annual base price
`items.oneOffPrice({ price? })`	-	$50	One-time base price
`items.monthlyMessagesWithRollover({ includedUsage?, rolloverConfig })`	Messages	100	With rollover
`items.tieredPrepaidMessages({ includedUsage?, billingUnits?, tiers? })`	Messages	-	Graduated tier prepaid
`items.tieredConsumableMessages({ includedUsage?, billingUnits?, tiers? })`	Messages	-	Graduated tier consumable

Products (`@tests/utils/fixtures/products`)

Product	Built-in Base Price	Default ID
`products.base({ items, id?, isDefault?, isAddOn? })`	None (free)	“base”
`products.pro({ items, id? })`	$20/mo	”pro”
`products.premium({ items, id? })`	$50/mo	”premium”
`products.growth({ items, id? })`	$100/mo	”growth”
`products.ultra({ items, id? })`	$200/mo	”ultra”
`products.proAnnual({ items, id? })`	$200/yr	”pro-annual”
`products.proWithTrial({ items, id?, trialDays?, cardRequired? })`	$20/mo + trial	”pro-trial”
`products.baseWithTrial({ items, id?, trialDays?, cardRequired? })`	None + trial	”base-trial”
`products.oneOff({ items, id? })`	$10 one-time	”one-off”
`products.recurringAddOn({ items, id? })`	$20/mo add-on	”addon”
`products.oneOffAddOn({ items, id? })`	$10 one-time add-on	”one-off-addon”

NEVER add items.monthlyPrice() to products.pro() — it already has $20/mo built in.

Common Test Patterns

Attach Test (Upgrade)

test.concurrent(`${chalk.yellowBright("upgrade: free to pro")}`, async () => {
  const messagesItem = items.monthlyMessages({ includedUsage: 100 });
  const free = products.base({ id: "free", items: [messagesItem] });
  const pro = products.pro({ items: [messagesItem] });

  const { customerId, autumnV1, ctx } = await initScenario({
    customerId: "upgrade-free-pro",
    setup: [s.customer({ paymentMethod: "success" }), s.products({ list: [free, pro] })],
    actions: [s.billing.attach({ productId: free.id })],
  });

  await autumnV1.billing.attach({
    customer_id: customerId, product_id: pro.id, redirect_mode: "if_required",
  });

  const customer = await autumnV1.customers.get<ApiCustomerV3>(customerId);
  await expectCustomerProducts({ customer, active: [pro.id], notPresent: [free.id] });
  expectCustomerInvoiceCorrect({ customer, count: 1, latestTotal: 20 });
  await expectStripeSubscriptionCorrect({ ctx, customerId });
});

Downgrade Test (Scheduled)

test.concurrent(`${chalk.yellowBright("downgrade: pro to free")}`, async () => {
  const messagesItem = items.monthlyMessages({ includedUsage: 100 });
  const pro = products.pro({ items: [messagesItem] });
  const free = products.base({ id: "free", items: [messagesItem] });

  const { customerId, autumnV1, ctx } = await initScenario({
    customerId: "downgrade-pro-free",
    setup: [s.customer({ paymentMethod: "success" }), s.products({ list: [pro, free] })],
    actions: [s.billing.attach({ productId: pro.id })],
  });

  await autumnV1.billing.attach({
    customer_id: customerId, product_id: free.id, redirect_mode: "if_required",
  });

  const customer = await autumnV1.customers.get<ApiCustomerV3>(customerId);
  await expectCustomerProducts({
    customer,
    canceling: [pro.id],   // NOT active — canceling means active + canceled_at set
    scheduled: [free.id],
  });
  await expectStripeSubscriptionCorrect({ ctx, customerId });
});

Track Test (Decimal.js Required)

import { Decimal } from "decimal.js";

test.concurrent(`${chalk.yellowBright("track: basic deduction")}`, async () => {
  const messagesItem = items.monthlyMessages({ includedUsage: 100 });
  const free = products.base({ items: [messagesItem] });

  const { customerId, autumnV1 } = await initScenario({
    customerId: "track-basic",
    setup: [s.customer({}), s.products({ list: [free] })],
    actions: [s.attach({ productId: free.id })],
  });

  await autumnV1.track({ customer_id: customerId, feature_id: TestFeature.Messages, value: 23.47 });

  const customer = await autumnV1.customers.get<ApiCustomerV3>(customerId);
  expect(customer.features[TestFeature.Messages].balance).toBe(
    new Decimal(100).sub(23.47).toNumber()
  );
});

Prepaid Test

test.concurrent(`${chalk.yellowBright("prepaid: attach with quantity")}`, async () => {
  const prepaidItem = items.prepaidMessages({ includedUsage: 0, billingUnits: 100, price: 10 });
  const pro = products.base({ id: "prepaid-pro", items: [prepaidItem] });

  const { customerId, autumnV1, ctx } = await initScenario({
    customerId: "prepaid-attach",
    setup: [s.customer({ paymentMethod: "success" }), s.products({ list: [pro] })],
    actions: [
      s.billing.attach({
        productId: pro.id,
        options: [{ feature_id: TestFeature.Messages, quantity: 200 }], // inclusive of includedUsage
      }),
    ],
  });

  const customer = await autumnV1.customers.get<ApiCustomerV3>(customerId);
  // quantity 200 → rounded to nearest billingUnit (200), purchased_balance: 200
  expectCustomerFeatureCorrect({ customer, featureId: TestFeature.Messages, balance: 200 });
  await expectStripeSubscriptionCorrect({ ctx, customerId });
});

Test Type Decision Tree

Writing a…	Use in `initScenario` actions	Test body calls
Billing attach test	`s.billing.attach()` for setup	`autumnV1.billing.attach()` for action under test
Multi-attach test	`s.billing.attach()` for setup	`autumnV1.billing.multiAttach()`
Update subscription test	`s.attach()` for initial attach	`autumnV1.subscriptions.update()`
Cancel test	`s.billing.attach()` for setup	`autumnV1.subscriptions.update({ cancel: "end_of_cycle" })`
Track/check test	`s.attach()` for product setup	`autumnV1.track()` / `autumnV1.check()`
Prepaid test	`s.billing.attach({ options })`	`autumnV1.billing.attach()` or `subscriptions.update()`
Entity test	`s.entities()` in setup, `entityIndex` in actions	Entity-specific API calls
Webhook test	`s.customer({ skipWebhooks: true })`	Manual customer create with `skipWebhooks: false`

Balance Calculation Rules

Feature Type	Balance Formula	Use Decimal.js?
Free metered	`includedUsage - usage`	Yes
Prepaid	`includedUsage + purchasedQuantity - usage`	Yes
Consumable + Prepaid same feature	`consumable.includedUsage + prepaid.purchasedQuantity - usage`	Yes
Allocated	`includedUsage + purchasedSeats - currentSeats`	Yes
Credit system	`creditBalance - sum(action * credit_cost)`	Yes, + `getCreditCost()`

Resetting Features: Free vs Paid

Free products (no Stripe sub): Use s.resetFeature({ featureId, productId }) — simulates cron job
Paid products (has Stripe sub): Use s.advanceToNextInvoice() — advances test clock, triggers invoice.paid webhook

Running Tests

CRITICAL: NEVER run tests automatically. Always ask the user for permission before running any test command. The user likely has a dev server running and needs to coordinate test execution.

Commands (run from repo root)

# Run a single test file
bun test server/tests/integration/billing/attach/my-test.test.ts --timeout 60000

# Run a specific test by name pattern within a file
bun test server/tests/integration/billing/attach/my-test.test.ts -t "upgrade: free to pro" --timeout 60000

# Run all tests in a directory
bun test server/tests/integration/billing/attach/ --timeout 60000

# Using the package.json script (loads env via infisical)
bun run --cwd server test:integration server/tests/integration/billing/attach/my-test.test.ts

Key Points

--timeout 60000 (or higher) is essential — billing tests involve Stripe test clocks and can take 30s+
bunfig.toml sets timeout = 0 (infinite) and preloads env + test setup automatically
Run one test file at a time during development to avoid test clock conflicts
All server-side console.log output goes to the server’s logs, not the test output — ask the user to paste server logs if debugging

After Writing Tests

Always run a typecheck:

bun ts

This runs bunx tsgo --build --noEmit in the server directory. Fix all type errors before considering the task done.

References (Load On-Demand for Edge Cases)

references/SCENARIO.md — Full initScenario details, all builder params
references/FIXTURES.md — Complete item/product fixture params
references/ENTITIES.md — Entity-based testing (entity-products vs per-entity features)
references/EXPECTATIONS.md — All expectation utility signatures
references/PRORATION.md — Proration calculation utilities
references/GOTCHAS.md — Expanded wrong/right examples for every common mistake
references/TRACK-CHECK.md — Track/check endpoint testing, credit systems
references/WEBHOOKS.md — Outbound webhook testing with Svix Play
references/STRIPE-BEHAVIORS.md — Stripe webhook behaviors

write-test

快捷安装