Add a contributor guide for a trustworthy regression test
New contributors copy retry-heavy tests and perpetuate the same failure patterns.
- Focused work estimate
- 1h + prerequisites
- Priority in the scenario
- Low
- Engineering practice
- Technical writing · Testing
Estimated field mix
- Quality engineering100%
Field percentages are editorial estimates of the ticket's engineering focus. They total 100%; they are not measured time, proficiency scores, or ownership evidence.
Review it, then add it to your workspace.
The board opens an editable draft; nothing is saved until you confirm it. Sign-in and workspace permissions apply, and Demo boards remain ephemeral.
Project context
A fictional web team reruns red builds until they pass. Shared clocks, leaked state, and unawaited work make failures hard to trust.
Setup prerequisites
- Create a small local application with three deliberately flaky tests using synthetic data and local endpoints.
Preceding work
Complete these dependencies, or supply their agreed outputs before taking this ticket.
- BTEST-101 · Record first-attempt results separately from rerun results
- BTEST-102 · Reproduce order-dependent failures with a saved shuffle seed
- BTEST-103 · Trace leaked database rows between test cases
- BTEST-104 · Replace wall-clock races with explicit clock control
- BTEST-106 · Find async work that escapes test teardown
- BTEST-107 · Separate product defects from environmental test failures
- BTEST-108 · Add expiring quarantine entries with accountable owners
- BTEST-105 · Remove readiness sleeps from browser tests
- BTEST-109 · Evaluate flake repairs with controlled repeated runs
Acceptance criteria
- Show one deterministic fixture, clock, and cleanup example.
- State when a rerun is diagnostic rather than acceptance.
- Document how to submit a reproducible failure.
Implementation constraints
- Use actual repaired examples from this project.
Verification to include
- Follow the guide to add a passing boundary test.
- Check that an intentionally leaked resource fails review checks.
Deliverables
- Contributor testing guide.
Rollout and recovery
Link the guide from quarantine failures and the test command.
Value of the work
For the engineer: Practice controlled diagnosis, isolation, and test reliability measurement.
For the team: Recover useful failure signals and reduce blind reruns without hiding product defects.
Evidence boundaries
Outcome Evidence: Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.
Ownership Evidence: Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence.