Skip to content

Test Documentation Templates

mavrovde edited this page Nov 1, 2026 · 1 revision

Test Documentation Templates

The templates for test case specifications and test completion reports, after ISO/IEC/IEEE 29119-3, in ISTQB terms. Part of the Testing Strategy. The defect report template is on Defect Management.

1. Test case specification

Most test cases live as code; the template below is what the code, its name and its metadata must express. A test case that cannot be read this way is incomplete. Written specifications in this form are used for review of high-risk areas (licence gate, authentication, admission) and for manual tests.

Fields

Field Content
Identifier the requirement ID plus a short slug, for example SEC-033 partial-permitted-families; the ID is carried in the test name or metadata (TEST-001)
Requirement IDs every requirement the case verifies
Level Static, Component, Component integration, Integration, Contract, System, Non-functional system, Acceptance ([[Testing Strategy
Type Functional, Contract, Parity, Security, Licence, Configuration, Performance, Resilience, Observability, Documentation, Accessibility, i18n
Priority from the component's risk class (High, Medium, Low)
Preconditions and test data the fixture profile and seed, or the inline values; the configuration overrides; the key's plan and scopes
Given the state before the action
When the single action under test
Then the expected observable result: status, headers, and either the expected envelope (members and values of data, meta, links) or the expected problem (type, status, errors[])
And further expectations: log fields, metrics, storage state, timing
Mutant proof the planted fault or unfixed commit under which this case was shown to fail (TST-013)
Automation the test file and name; or "manual" with the reason

Example: envelope expected

Field Value
Identifier LIC-001 attribution-on-empty-result
Requirement IDs LIC-001, ENV-003
Level / Type Component integration / Licence
Priority High
Test data tiny profile, seed printed; key with a plan permitting family-alpha and family-beta
Given an area with no charging station
When the client asks for charging options near the area
Then 200; data is an empty list; meta.attribution lists both families consulted; meta.freshness has one entry per family; the response validates against the document
And the access log line has the operation id and status, and no key material
Mutant proof removing the attribution for empty results turns the case red
Automation handler test tagged LIC-001

Example: problem expected

Field Value
Identifier SEC-002 key-in-query-refused
Requirement IDs SEC-002, ERR-001
Level / Type Component integration / Security
Priority High
Test data generated vf_test_ key
Given a valid key
When the client sends it as a query parameter
Then 400; application/problem+json; type ends in key-in-query; the key is not checked
And the key id is flagged for the operator; the full key appears in no log sink
Mutant proof accepting the query parameter as a credential turns the case red
Automation handler test tagged SEC-002

Gherkin form

Where a team prefers it, the same case can be written in Given / When / Then text, with the requirement ID as a tag:

@SEC-033 @licence @component-integration
Scenario: Only permitted families are returned when some are forbidden
  Given a key whose plan permits family-alpha and not family-gamma
  And the tiny fixture set with items of both families near point P
  When the client asks for points of interest near P
  Then the status is 200
  And every item in data has sourceFamily family-alpha
  And meta.warnings contains partial

2. Test completion report

One report per release, and one per milestone at its close. It is drafted by CI (issue #14) and completed by the maintainers. It is the test evidence referenced by the release acceptance (TEST-011).

# Test completion report: <version>

## 1. Summary
- Release / milestone: <version> / <milestone>
- Specification revision: <wiki commit>
- Image digest: <digest>
- Verdict: <ready | ready with deviations | not ready>

## 2. Scope
- In-scope requirements: <count>, list attached
- Out of scope, with reason: <list>

## 3. Results by level
| Level | Executed | Passed | Failed | Skipped | Quarantined |

## 4. Requirement report
- Automated MUST rows in scope with a passing test: <n> of <n>
- Rows without a passing test, with reason: <list>

## 5. Quality measures against targets
| Measure | Target | Result |
| Line coverage, overall / critical | 85 % / 95 % | |
| Mutation score, changed / overall | 80 % / 70 % | |
| Parity fact equality | 100 % | |
| Latency per endpoint class against budget | ≤ 1.0 | |
| Flake rate | < 0.5 % | |

## 6. Non-functional results
- Load, stress, spike, soak: <result files>
- Chaos scenarios: <list with results>
- Security scans and DAST: <findings by severity>
- Accessibility: <automated result, manual pass reviewer>

## 7. Deviations
- SHOULD rows not met, with reason
- Open defects by severity, with issue links
- Gates changed since the last report, with the decision reference

## 8. Escaped defects since the last report
| Defect | Found in | Level that should have caught it | Regression test |

## 9. Lessons and actions
<what changes in tests, gates or data because of this release>

## 10. Approval
- Maintainer: <name>, <date>
- Owner: <name>, <date>

All figures in a report are results of that run. Until an implementation exists, the template carries placeholders only.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally