5.1 KiB
Adding or changing harness helpers
A permanent helper needs discoverable documentation without making every product task read its implementation history. Apply this format when adding a helper or changing its public contract. Existing reference prose was moved from the old README; improve the affected section when needed, without rewriting unrelated references.
Where each kind of information belongs
| Location | Contents |
|---|---|
test/README.md |
Short mandatory rules and links chosen by task need; keep under 8 KiB. |
test/docs/helpers/README.md |
One row per module: link, kind and one-line purpose. |
test/docs/helpers/test_<name>.md |
The module's usage, requirements, observations, refusals, cleanup and verification. |
test/docs/<topic>.md |
A cross-module procedure such as account setup, scenario teardown or launch behavior. |
test_<name>.h |
Signatures and concise caller contracts: units, ownership, lifetime and return/refusal semantics. Link the reference for examples and longer explanations. |
| Task evidence/history | Full discovery chronology, repeated run logs and implementation deliberations. |
Use the existing module reference when extending a helper; do not add another README paragraph for each new function. A separate module gets its own page. Group related operations with headings. Link a shared procedure instead of copying it into every helper page. Keep a brief historical example only when it explains a non-obvious constraint; move the full chronology to task evidence.
Keep the mandatory README small by replacing detail with a precise routing link, not by making an essential prerequisite optional. Its topic links tell a reader when account, media, input, capture or teardown guidance is required. Do not add a rule requiring all helper pages or the diagnostic history to be read. A helper-specific platform caveat belongs with that helper.
Module reference template
Use the module stem for the filename so a source/header search finds its page. Fill the relevant sections concretely; omit a section only when it is truly inapplicable, and say when an operation has no cleanup or platform restriction. Keep the opening purpose and selection guidance short enough to choose a helper before reading its complete contract.
# test_<name>
[Harness guide](../../README.md) · [Helper index](README.md)
Type: Reusable API / Harness self-test / Internal dependency.
Source contract: [test_<name>.h](../../test_<name>.h).
## Use when
What observable need this answers; when a nearby existing helper is preferable.
For an internal dependency, name its real callers instead of suggesting overlay use.
## Preconditions and limits
Required process/session/widget state, platform support, coordinate/time units,
identity or generation requirements, and what this helper does not establish.
## Minimal use
One small example against the real API. Include its readiness gate, assertion
and required cleanup; keep fixture values synthetic and secrets out of text.
## Readings and refusals
Return values and log markers; what an accepted reading proves; named refusals
and which ones make a measurement undecidable. Never equate a refusal with PASS.
## Lifetime and cleanup
What is owned or retained, cancellation, restoration, and onFinish obligations.
Name any lasting side effect, including clipboard changes or account writes.
## Verification
The self-test entry or focused command, required environment, a negative control
or deliberate mutation it catches, and known platform/evidence limitations.
Distinguish an executed check from a proposed check.
## Related guidance
Links to prerequisite topic guides and related helpers, without copying them.
A pure self-test page must name the production harness behavior it protects, its fixture, expected verdict and teardown. It is not a general-purpose helper and need not be used by product overlays. An internal dependency page names its actual callers; an absence of direct overlay includes is not non-use.
Before finishing the change
- Update the module page and its one-line index entry in the same change as the API. Update callers' topic links when a prerequisite or contract moves.
- Read the header and the example together: signatures, units, ownership and refusal behavior must agree. Do not invent an example API or promise a negative control that was never run.
- Link to the reference from the header when detailed guidance exists. Keep comments about the callable contract; do not paste the reference into the header or the mandatory README.
- Preserve useful constraints when moving old prose. Search existing references and diagnostic rows before creating a duplicate explanation.
- Check relative links and heading anchors, the index's coverage of public helper modules, and the mandatory README's byte size. Keep source citations symbolic rather than line-number based.
Documentation reorganization alone needs link/content checks, not a Telegram build. Changes to helper behavior still need their normal focused evidence and review; this format does not replace that workflow.