testing-standards

name	testing-standards
description	Apply when writing, reviewing, or planning tests — covers BDD style, happy-path AND sad-path coverage, deriving tests from user stories, and using bun:test. Load whenever creating *.test.ts files, adding coverage, or turning a requirement into a spec.

🧪 Testing Standards

🛠️ Tooling

Use bun:test whenever possible — import { describe, it, expect, beforeEach } from "bun:test". No Jest, no Vitest unless a real constraint forces it.

📖 BDD, driven by user stories

Start from the story, not the implementation:

As a customer, I want to add an item to my cart so that I can buy it later.

Each story becomes a describe block. Each acceptance condition becomes an it that reads as a sentence:

describe("Cart — adding items", () => {
  it("adds a new line when the item is not already in the cart", () => { /* ... */ });
  it("increments quantity when the item is already in the cart", () => { /* ... */ });
});

it/describe text should read like spoken English. If the test name needs "and" twice, it's testing too much — split it.

✅ Happy path AND 😱 sad path — both, always

Every behavior gets both. A feature isn't tested until its failure modes are:

• Happy: valid input, expected outcome.
• Sad: invalid input, boundary, empty/zero/negative, missing record, permission denied, downstream failure.

describe("OrderService.place", () => {
  it("places an order when the cart has items and payment succeeds", async () => { /* happy */ });

  it("rejects an empty cart", async () => { /* sad */ });
  it("does not charge twice when called concurrently", async () => { /* sad */ });
  it("surfaces a clear error when payment is declined", async () => { /* sad */ });
});

If you only wrote happy-path tests, you're not done — state that and add the sad paths.

🧭 Structure

• Arrange → Act → Assert, with blank lines separating the three.
• One logical assertion per it where practical.
• Use beforeEach for setup; keep tests independent and order-agnostic.
• Tests live in /tests, mirroring the domain or behavior: tests/orders/orders.test.ts (see code-architecture).
• Prefer SQLite in-memory for data-touching tests (see data-access).

🏁 Done means green

Per CLAUDE.md: never report something works without running it. Run bun test and show the result before claiming a fix.