Task: 2026/10/29/document-the-macos-notification-evidence-recipe-in-the-test-harness
153 lines
8 KiB
Markdown
153 lines
8 KiB
Markdown
# Telegram Desktop task-test harness
|
|
|
|
Read this short guide before designing, authoring or recovering a Telegram
|
|
`-testagent` overlay. Then read only the references needed by the task and
|
|
those helpers' headers. The [helper index](docs/helpers/README.md) is a lookup
|
|
tool; neither it nor the detailed references are a required reading bundle.
|
|
|
|
The permanent harness provides the runner, fixtures, inputs and evidence
|
|
instruments. The disposable overlay supplies task-specific setup, production
|
|
entry points and checks. Search the index before recreating a shared facility.
|
|
Keep the repository's `test_scenario.cpp` a no-op outside the saved overlay.
|
|
|
|
## The stage contract
|
|
|
|
- `run` acts once on prerequisites already established by an earlier stage.
|
|
- `until` observes readiness repeatedly; expected product outcomes belong in
|
|
`then` or `captureAndInspect`. Do not turn a mismatch into a timeout.
|
|
- `then` asserts or acts on the exact object accepted by readiness. Prefer
|
|
`actOnWidget` and lifetime guards over resolving another instance.
|
|
- `skipReason` names an inapplicable prerequisite, never a failing result.
|
|
`timeoutDetails` reports the last identity, geometry and state.
|
|
- Compose stages that depend on a fixture prerequisite inside
|
|
`Runner::addGated`, so helper-appended stages inherit its first refusal
|
|
before resolving anything; declare restoration with `Runner::addRecovery`
|
|
([gated groups](docs/helpers/test_runner.md#gated-groups-and-recovery-stages)).
|
|
- Assert and log measured values on both passing and failing paths. A helper
|
|
refusal or undecidable reading is not evidence of product success.
|
|
|
|
Read the [runner contract](docs/helpers/test_runner.md) before writing stages;
|
|
it includes the narrowly documented activation exception to a pure wait.
|
|
Startup/session/chats waits are opt-in: select only those the fixture needs.
|
|
|
|
Every scenario first passes the [session gate](docs/helpers/test_session_gate.md),
|
|
which refuses authorized non-Test accounts unless the task explicitly permits
|
|
production legs. Configure `UseTestSession` and its restore stage when the
|
|
fixture needs an account switch. `SetupScenario` only registers stages,
|
|
releases and gate options; the gate does not guard actions taken during setup.
|
|
|
|
## Exact objects and actions
|
|
|
|
Use RTTI-based harness finders, not Qt `findChildren<CustomWidget*>()`.
|
|
Visibility alone does not prove identity, ownership or unobscured geometry.
|
|
Publish exact live objects/actions when descendant searches are ambiguous;
|
|
keep lifetime guards across stages and preserve a window's concrete type.
|
|
Read [object publication and input contracts](docs/helpers/test_widgets.md).
|
|
Resolve another account's or a separate window's controller from the window
|
|
registry with [test_controller_ready](docs/helpers/test_controller_ready.md),
|
|
never from activation history.
|
|
|
|
## Resolving a chat's message list
|
|
|
|
Resolve the section that owns the exact message; do not assume every chat uses
|
|
`HistoryWidget` or that `item->mainView()` is the visible element.
|
|
Read [chat-list resolution](docs/chat-lists.md) for message-row work.
|
|
|
|
## Input helpers
|
|
|
|
Choose the real event receiver and verify its resulting state. Settlement of
|
|
postponed calls does not wait for timers, network or animations. A synthetic
|
|
click is not a lasting hover. Read [input helpers](docs/helpers/test_widgets.md#input-helpers)
|
|
for input, [launch behavior](docs/launch.md) for activation/background painting,
|
|
and the selected module's reference for clipboard, menu or other special input.
|
|
Drive grabbing widgets with [QPA mouse](docs/helpers/test_qpa_mouse.md); keep
|
|
console input out with the [console shield](docs/helpers/test_console_shield.md).
|
|
|
|
## Capture and visual assertions
|
|
|
|
Capture the real paint owner and the complete requested rectangle. Keep
|
|
readiness separate from the expected pixels; save the accepted frame before
|
|
asserting on it. Report logical versus image pixels and DPR explicitly.
|
|
Strict comparisons keep one render owner, origin and extent
|
|
([strict path](docs/helpers/test_capture.md#strict-same-state-comparisons));
|
|
crop a full-owner render only through the
|
|
[checked crop](docs/helpers/test_capture.md#checked-full-owner-crops); bind
|
|
child rects to their [coordinate owner](docs/helpers/test_capture.md#coordinate-owners-of-mapped-rectangles);
|
|
coordinated samplers share a
|
|
[capture scope](docs/helpers/test_post_paint.md#coordinated-samplers-and-receipts).
|
|
Read [capture selection](docs/helpers/test_capture.md), then select only the
|
|
needed [ink](docs/helpers/test_ink.md), [post-paint](docs/helpers/test_post_paint.md),
|
|
[clocked-frame](docs/helpers/test_animation_clock.md) or
|
|
[corner](docs/helpers/test_corner_patch.md) reference.
|
|
Time a whole widget's paint by recording the real owner with
|
|
[paint streams](docs/helpers/test_paint_stream.md) and replaying it in
|
|
optimized Qt; a Debug paint timing is not a paint cost.
|
|
|
|
## Helper catalog
|
|
|
|
Find modules by purpose in the [helper index](docs/helpers/README.md).
|
|
Entries marked **Self-test** validate the harness; do not add them to every
|
|
product scenario.
|
|
|
|
## Building one reliable packed scenario
|
|
|
|
Derive checks from the task and diff; use the most direct real production
|
|
entry point. Pack compatible checks into one launch; split only for a named
|
|
incompatible process-lifetime requirement. After a test flaw, repair all
|
|
visible flaws together. Keep nondestructive states first and closing actions
|
|
last. Read [scenario design](docs/scenarios.md) and, when useful, the
|
|
[minimal overlay example](docs/overlay-example.md).
|
|
|
|
## Account fixture secrets
|
|
|
|
Run only through the workflow's marked test environment. Fixture secrets stay
|
|
in process: never put them in code, prompts, logs or evidence artifacts. Read
|
|
[account fixtures](docs/account-fixtures.md) before using account secrets or a
|
|
funded wallet, including its required reconciliation and secrecy-scan links.
|
|
For public-identity or log-coverage checks, read the separate
|
|
[publication audit contract](docs/helpers/test_publication_identity_scan.md);
|
|
neither establishes fixture secrecy.
|
|
A credential the product hands to an OS launcher, such as a token URL, is
|
|
declared with the launch fuse's
|
|
[private expectation](docs/helpers/test_launch_fuse.md#private-expectations),
|
|
which matches it exactly and prints only its label and `scheme://host`.
|
|
A required missing fixture is a blocker; do not substitute fabricated proof,
|
|
reset the funded wallet or discard a possibly unrewritten rotation.
|
|
|
|
## Media fixtures and fixture gates
|
|
|
|
Metadata alone does not establish playable media. A media-dependent scenario
|
|
must observe real playback and preserve the validated fixture across stages.
|
|
Read [media fixtures](docs/media-fixtures.md) before selecting one.
|
|
|
|
## macOS native notifications
|
|
|
|
Read [notification evidence](docs/macos-notifications.md) before a run posts
|
|
macOS native notifications.
|
|
|
|
## Scenario teardown before quit
|
|
|
|
Register idempotent release of subscriptions, watchers and timers with
|
|
`Runner::onFinish`; a final stage can be skipped by timeout or watchdog.
|
|
Restore asynchronous UI state in a settling stage, not during quit. Read
|
|
[teardown](docs/teardown.md) when retaining state or changing the environment.
|
|
Mutate and restore a server fixture only through the
|
|
[fixture transaction](docs/helpers/test_fixture_transaction.md), which reads
|
|
before writing, waits the server's deadline and keeps a resumable record.
|
|
|
|
## Failure diagnosis
|
|
|
|
Read the actual logs/captures, classify the failure, and search the
|
|
[diagnostic reference](docs/diagnostics.md) for that signature. It is a lookup
|
|
history, not a preflight reading assignment. Preserve prior positive evidence;
|
|
do not weaken an oracle to get past a refusal.
|
|
|
|
## Adding or changing a helper
|
|
|
|
Follow [the documentation format](docs/adding-helpers.md): one short index
|
|
entry, an on-demand module reference, and a precise source-header contract.
|
|
Keep this README under 8 KiB; only universal rules and routing links belong
|
|
here. Examples, platform caveats, self-test procedures and failure histories
|
|
belong in the linked references. Cite symbols and files, never source line
|
|
numbers. The full execution workflow remains in
|
|
[the test loop](../../../.agents/shared/test-loop.md).
|