# ihumane · QA and testing · v0.1 You are an agent about to test work before it reaches people: your own change, a feature someone else built, or a product before it ships. This module is written for you, not for a human reader. It turns what a careful QA person (someone whose job is finding problems before users do) does by habit into rules you can follow and checks you can run. Read this file fully. Read the other files when the step below tells you to. --- ## Why this exists A QA person tests with the person in mind: what they asked for, what they'll type, where they'll get stuck, what they'll do when the page is slow. You test with the code in mind, because you just wrote it. That gives three failures people keep finding after you've said "done": 1. **Only the happy path was tried.** One test, written with the tidy example you built against, so it can only agree with you. The first real person with a long name, a slow train connection or a habit of pressing back finds the bug. 2. **"Tests pass" was reported as "it works".** The tests ran, so the report says it works. Nobody opened the page, the tests mocked the part that broke, and half of what was asked has no test at all. 3. **What was built got tested, not what was asked.** You test the feature you made against your own idea of it. The part of the brief you missed is missing from the tests too, so nothing tells you. The person reads your test report to decide whether to ship. Every rule here is about whether that decision is a safe one. This module covers testing the work. Verifying your own code change (run it, read your diff, never weaken a test) is in Code craft `4-verify.md`; where the two meet, this module points there instead of repeating it. --- ## Size the job first A full test pass suits a feature or a release. A one-line fix doesn't need all of it, and a heavy process on a small job annoys the person. | Size | Looks like | Do | |---|---|---| | **Small** | A bug fix, a copy change, a small change to one screen or one function | Write what "working" means in one line (T1). Try the fix the way the person would hit it, then two or three nearby cases (E1, E3). Check one neighbour that shares the code (T4). Report what you tried and what you didn't (H2). Skip the written plan, the bug report format and the review lenses unless you found something. | | **Large** | A new feature or flow, a release, a change to something many screens share, "test this before we launch" | The full workflow below, every step. Write the plan (T6) before you start, and fill it in as you go. | If unsure, treat it as small. The honest report is never skipped: it's what the person uses to decide whether to ship. --- ## The workflow | Step | What you do | File | |------|-------------|------| | 1. Plan | Work out what "working" means to the person, what was asked against what was built, where it would hurt most, and what else the change could break. | `1-plan.md` | | 2. Explore | Use it as a person would: real data, wrong input, boundaries, back and refresh, a slow network, a phone, the keyboard. Then retest the neighbours. | `2-explore.md` | | 3. Automate | Write or fix the tests that keep it working: from the plan, at the right level, with fakes that behave like the real thing, and none that pass or fail at random. | `3-automate.md` | | 4. Bugs | Write up what you found so someone else can reproduce it, rate it by what it does to a person, and fix only what's yours. | `4-bugs.md` | | 5. Report | Review through five lenses, then report what you tested, what you didn't and what you couldn't. | `5-report.md` | --- ## The format of every rule Rules in this module use the same fields: - **Rule:** what to do, as specifically as possible. - **Why:** what happens to a real person if you don't: the person who asked, the person using it, or the developer who picks up the bug. - **Agent trap:** the specific way agents like you get this wrong. - **Check:** how to verify it, ideally something you can run or count. - **Limit:** where the rule stops, when it could be taken too far. Runnable checks live in `checks/`. Run them; don't trust your memory of what the tests do. | Check | Finds | |---|---| | `checks/trust.js` | Tests you can't trust: no assertion, only checks that a fake was called, checks that pass for almost anything, snapshot-only tests, fixed waits, retries that hide flaky tests, end-to-end tests that find elements by CSS class, and the real clock or random numbers used inside a check. Node, no dependencies. `--diff` checks only the test files you changed. | Code craft's `checks/tidy.js` finds `.only` and `.skip` left in tests. Run it too. --- ## Five rules that matter most If you remember nothing else: 1. **Write down what "working" means to them first.** In their words, from the brief, before you look at the code. (`1-plan.md` T1) 2. **Test what was asked, not what was built.** Go through the ask line by line; the part you missed has no test. (`1-plan.md` T2) 3. **Use it the way a person would.** Long names, wrong input, back, refresh, slow network, phone width. (`2-explore.md` E1, E4) 4. **"Tests pass" is not "it works".** Say which one you saw, and how. (`5-report.md` H1) 5. **Say what you didn't test.** What you skipped and what you couldn't reach go in the report, in plain words. (`5-report.md` H2) --- ## Precedence The person's instructions and the project's own testing setup come before this module. Use the project's test framework, its folders, its naming and its commands (Code craft B4). If the project does something these rules advise against (a suite full of retries, tests that mock everything), follow it in what you add, and mention the conflict once in your report instead of rewriting their tests. One exception: never test against live data that belongs to real people, or send real emails, payments or messages, to make a test work (T5). Use a test account or a test mode, or say you couldn't test that part.