← QA Library
Chapter 4 / 9 · 8 min de lectura

Test documentation

Strategy, plan, checklists, test cases, bug reports, acceptance criteria and reports: what each is for and how to write it.

Test documentation exists for two reasons: to make testing repeatable and to make quality visible to people who weren't in the room. The right amount depends on the project. A start-up MVP may need a one-page strategy and checklists; a payment system needs detailed test cases and traceability.

The main artifacts

ArtifactAnswersLevel of detail
Test strategyHow do we approach quality on this product in general?High; changes rarely
Test planWhat, when, where and by whom for this release?Medium; per release or project
ChecklistWhat conditions should we check?Short items, no steps
Test caseExactly how do we check one condition?Steps, data, expected result
Bug reportWhat is wrong and how to reproduce it?Precise and minimal
Test reportWhat is the state of quality now?Summary with risks
Traceability matrixWhich tests cover which requirements?Table

Test plan: what to include

  • Scope: features in and out of scope
  • Approach: types and levels of testing, manual vs automated
  • Environments and test data
  • Entry and exit criteria (when we start and when we're done)
  • Schedule, roles and responsibilities
  • Risks and how we mitigate them
  • Deliverables: reports, bug lists, recommendations

Checklists or test cases?

Checklists are fast to write and leave room for the tester's judgement, which keeps tests varied. Test cases are precise and repeatable, which matters for complex logic, regulated domains, new team members and automation.

Checklist: Login
[ ] Login with valid email and password
[ ] Error for wrong password (no hint which field is wrong)
[ ] Account locked after 5 failed attempts
[ ] “Remember me” keeps the session after browser restart
[ ] Password field hides characters, show/hide toggle works
[ ] Works with keyboard only and with a screen reader

Test case TC-LOGIN-03: Lock after failed attempts
Preconditions: active account [email protected]
Steps:
 1. Open /login
 2. Enter the email and a wrong password, submit — repeat 5 times
 3. Enter the correct password, submit
Expected: after step 2 a lock message is shown;
          step 3 is rejected; an unlock email is sent

Acceptance criteria

Acceptance criteria define when a user story is done. Written before development, they are the cheapest test design there is. A popular format is Given / When / Then:

Scenario: Free shipping threshold
  Given my cart total is $49.99
  When I add an item for $0.01
  Then shipping cost is $0
  And I see the message “You've got free shipping”

Bug reports

A good report has a clear title, environment, minimal steps, expected and actual results, evidence, severity and priority. See Bug reports developers love for a full template and examples.

Traceability and metrics

RequirementTest casesStatus
REQ-12 Free shipping from $50TC-31, TC-32, TC-33Passed
REQ-13 Promo codesTC-40 – TC-471 failed
REQ-14 Gift wrapping—Not covered

A traceability matrix makes gaps obvious (REQ-14 above). Useful metrics are simple: requirements covered, tests passed/failed/blocked, open bugs by severity, and defects found after release. Avoid metrics that reward the wrong behaviour, such as counting bugs per tester.

Document for the reader. If nobody reads a document, make it shorter or stop writing it.