Testing and reliability

Testing Discipline

Find the existing setup

• Locate the test runner, its config and existing tests before writing any (package.json scripts, phpunit.xml, pytest.ini, Makefile, CI workflow).
• Use the repo's framework, file layout, naming and helpers. Do not introduce a second test framework.
• Learn the exact command CI runs and use it.

Write or update tests

• Every behavior change gets a test: new behavior is covered, changed behavior has its tests updated to the new expectation.
• Test observable behavior through public interfaces, not private internals.
• Cover the edge cases the change touches: empty, null, boundaries, error paths, permissions.
• One behavior per test, with a name that says what it proves.
• A pure refactor keeps existing tests green without editing their assertions. If an assertion must change, the behavior changed: say so.

Bugs: reproduce first

• Write a test that fails for the reported bug before fixing it. Run it and confirm it fails for the right reason.
• Fix the code, then see the same test pass.
• If the bug cannot be reproduced in a test, say so and explain how you verified the fix instead.

Keep tests deterministic

• No dependence on wall clock, timezone, locale, randomness, network, test order or shared global state. Freeze or inject time, seed randomness, stub external services.
• No arbitrary sleeps; wait for a condition or use fake timers.
• Each test creates and cleans up its own data (temp dirs, transactions, fresh databases).
• A flaky test is a bug: fix the cause, do not retry until green.

Never fake green

• Do not skip, delete, comment out, mark as expected-failure or loosen a test to make the suite pass.
• Do not weaken assertions (truthy instead of an exact value) or update snapshots blindly. Review every snapshot diff.
• Do not mock the unit under test.
• If a test fails for reasons unrelated to your task, leave it as is and report it with the error.

Run and report

• Run the tests you wrote, then the relevant wider suite; run the full suite when it is reasonably fast.
• Report the real result: the command, pass/fail counts and failures verbatim. Never claim tests pass without running them in this session.
• If tests cannot run (missing service, credentials, tooling), say exactly that and what remains unverified.

Before you finish

• Every behavior change has a new or updated test.
• Bug fixes have a test that failed before the fix and passes after it.
• Tests ran in this session with the repo's own command; results reported as observed.
• No skipped, deleted or weakened tests.
• New tests are deterministic and independent of each other.