Describe the failure before changing code
A useful bug report states the input, the expected result, and the observed result separately. Add the environment and the steps required to reproduce the behavior. This distinguishes an implementation defect from a mistaken expectation. For intermittent failures, record timing and shared state where possible. A change that happened to make one execution succeed is weaker evidence than a hypothesis that explains both successful and failing cases.
Reduce the example to a boundary
Suppose a function selects people aged eighteen or older but excludes an eighteen-year-old. Reduce the input to ages seventeen, eighteen, and nineteen. Removing unrelated database access and sorting makes a strict greater-than comparison a testable hypothesis. The expected result contains the second and third people, not merely two arbitrary records. Check the actual identities or values so the test captures the contract instead of an incidental count.
def adults(ages):
return [age for age in ages if age >= 18]
assert adults([17, 18, 19]) == [18, 19]Preserve the explanation as a regression test
After confirming the cause, retain a small automated test that failed before the fix and passes afterward. Prefer observable behavior over a test that repeats the implementation line by line. Add empty inputs, invalid values, or upper boundaries when they correspond to meaningful requirements. Each case should have a reason to exist. A suite of many near-identical examples can still miss the single transition where the decision changes.
Choose the right verification boundary
Unit tests isolate a function, but they cannot establish that database permissions, network responses, and user input formats agree. Use an integration test when the suspected defect lies at such a boundary. Conversely, investigating every arithmetic error through a browser makes diagnosis unnecessarily slow. Start with the smallest informative check, then verify the relevant end-to-end behavior. If a fix changes the specification rather than the implementation, update the contract explicitly instead of silently teaching tests to accept the new result.
Check that the test distinguishes the defect
Temporarily restoring the original comparison should make the regression test fail. That observation checks that the test actually distinguishes the identified defect instead of passing for an unrelated reason. Review the code difference afterward and ask whether the new rule consistently explains all three ages. Avoid a special case that merely recognizes the reported person. The intended contract should continue to apply to another user with the same relevant input.