Regression Tests for Bug Fixes

Scenario

Your application has a mature test suite, but bug fixes occasionally reappear months later.

The team wants reproducible bugs to become permanent test cases whenever practical.

The expected workflow is:

Reproduce bug
      ↓
Write failing test
      ↓
Fix behavior
      ↓
Verify test passes
      ↓
Run related tests

You want coding agents to follow this workflow instead of only patching the immediate symptom.

Repository Structure

commerce/
├── src/
│   ├── checkout/
│   │   ├── calculate-total.ts
│   │   └── apply-coupon.ts
│   └── payments/
├── tests/
│   ├── checkout/
│   │   └── calculate-total.test.ts
│   └── payments/
└── AGENTS.md

AGENTS.md

# Project Instructions

## Bug Fixes

When fixing a reproducible bug:

1. Identify the behavior that is incorrect.
2. Add or update a test that reproduces the bug when practical.
3. Confirm the test fails for the expected reason.
4. Implement the smallest appropriate fix.
5. Confirm the regression test passes.
6. Run related tests.

## Regression Tests

- Test the user-visible or externally observable failure.
- Prefer reproducing the original conditions over testing implementation details.
- Keep the regression test after the bug is fixed.
- Use a descriptive test name that explains the previously broken behavior.

## Scope

- Do not refactor unrelated code solely because it was discovered while fixing the bug.
- Broaden the change only when necessary to fix the underlying cause safely.

## Validation

Before completing the fix:

- run the regression test;
- run related tests;
- run `pnpm lint`;
- run `pnpm typecheck`.

What This Does

This turns a bug report into a reusable test case.

Suppose checkout incorrectly applies a coupon to an already discounted item.

A regression test might describe the actual behavior:

it("does not apply a coupon to an already discounted item", () => {
  const total = calculateTotal({
    price: 100,
    discountedPrice: 80,
    couponPercent: 10,
  });

  expect(total).toBe(80);
});

Before the fix, the test should reproduce the failure.

After the fix, it becomes protection against recurrence.

What This Does NOT Do

The instructions do not require forcing every bug into a unit test.

Some bugs may involve:

• race conditions;
• third-party services;
• browser-specific behavior;
• infrastructure;
• production-only data conditions.

The appropriate regression protection might instead be an:

integration test
E2E test
contract test
monitoring check

The important idea is to preserve evidence of the failure at the most useful testing level.

The instructions also do not require a large refactor every time a bug exposes imperfect code.

Why These Instructions Matter

Without a regression test, the repository may contain only the fix.

Future developers see:

if (item.discountedPrice) {
  return item.discountedPrice;
}

but may not know why the condition matters.

A regression test documents the expected behavior:

An existing discount must prevent a coupon from being applied again.

That behavior remains visible even if the implementation changes later.

Regression tests also help verify that the fix addresses the actual problem rather than merely changing nearby code.

Key Decisions

Reproduce first when practical

A failing test provides evidence that:

the bug exists

and later:

the fix works

Test the failure, not the patch

Avoid tests that simply mirror the implementation added during the fix.

Test the behavior that users or callers care about.

Keep the test

The regression test is not temporary debugging code.

Its purpose is to prevent recurrence.

Control scope

Bug fixes often reveal unrelated cleanup opportunities.

Do not automatically combine:

bug fix
+
architecture refactor
+
dependency upgrade
+
formatting cleanup

into one change.

Smaller changes are easier to reason about and validate.

When to Use This Pattern

Use this pattern when:

• a bug can be reproduced reliably;
• the failure represents important behavior;
• recurrence would be costly;
• the existing test suite has an appropriate level for the scenario.

A good regression test turns a production mistake into permanent repository knowledge.