ZaStoGram_desktop/Telegram/SourceFiles/test/docs/overlay-example.md
John Preston c7992a02bc [ai] Read button and toast states, toast paint and glyph ink
Task: 2026/10/19/read-button-and-toast-states-painted-toasts-and-glyph-ink-in-the-harness
2026-10-26 23:47:47 +04:00

79 lines
4.7 KiB
Markdown

# Overlay APIs and minimal scenario
[Harness guide](../README.md) · [Helper index](helpers/README.md)
- `test_runner.h` — the staged scenario engine: `Stage{name, run, until, then, timeout}`,
`waitEvent`, `waitForSessionReady`, the normal bounded non-fatal `waitForChatsLoaded()`, and
explicit strict `waitForChatsLoadedStrict()`; timing out an ordinary `Stage` ends the whole
scenario, while the wall-clock watchdog (default 120s; `TDESKTOP_TEST_WATCHDOG` override in seconds, 1..600, otherwise the default; the armed duration is logged at scenario start)
guarantees `TEST_COMPLETE` + quit on every exit path including timeout. `actOnWidget` waits for
and lifetime-guards the exact target before acting once. `captureAndInspect` saves the accepted
prepared frame and then runs numeric/raster assertions against that same widget and image.
`addGated(gate, compose)` gives every stage appended while `compose` runs, helper stages
included, an inherited fixture gate whose first refusal the whole group keeps, and
`addRecovery` appends a restoration stage that keeps only its own `skipReason` inside such a
group (see [gated groups](helpers/test_runner.md#gated-groups-and-recovery-stages)).
- `test_log.h` — evidence dir from `TDESKTOP_TEST_EVIDENCE_DIR` (the workspace `test-run`
helper sets it), flushed absolute-path logging, `Step/Pass/Fail/Check/Note`, `CheckNear`
tolerance assertions, `LogGeometry`, the standard markers.
- `test_widgets.h` — `FindAll<T>`/`FindFirst<T>`/`FindVisible<T>` (the `dynamic_cast`-based
finders that avoid the guaranteed `findChildren<CustomWidget*>` crash), `Click`, `TypeText`,
`CommitText`, `PressKey`, `Drag`, and `Wheel` via real Qt events, plus generation-counted,
lifetime-guarded `PublishLiveWidget` / `PublishLiveAction` seams for exact layer-owned objects,
and `ReadButtonState` / `ButtonStateDetails`, a `Ui::AbstractButton`'s own disabled flag read
beside `isEnabled()` - the readiness of a button target, because `setDisabled()` leaves
`isEnabled()` true ([button state](helpers/test_widgets.md#a-buttons-own-disabled-state));
each delivered event runs with postponed-call processing
deferred and is followed by a drain of every pending `Ui::PostponeCall` to empty, so
postponed input fix-ups AND their own change handling are settled when the helper returns;
wrap programmatic `setText` in `Test::Settle`.
- `test_capture.h` — `CaptureWidget`/`CaptureRect` (visibility check, `QWidget::grab()` so
floating elements and locked desktops cannot occlude, automatic blank-image FAIL, geometry
log, `SCREENSHOT` marker), plus `PreparedWidgetCapture`; `Runner::captureWidget` polls an
exact target until it has a valid painted frame and saves that same accepted frame,
`Crop`/`Zoom`/`ContactSheet` for tight same-scale evidence.
- `test_ink.h`, `test_style.h`, and `test_panel.h` — painted-ink/contrast measurement, settled
palette baselines, and detection of a `Ui::SeparatePanel` show-animation cache.
- `test_messages.h`, `test_transfer.h`, `test_open_handoff.h`, and `test_launch_fuse.h` — direct
sent-message, document-transfer, document-open, and safely blocked OS-launch oracles. Prefer
these established task-specific observers over reconstructing the same state in a scenario.
- `test_agent.h` — `Test::Fire(name)` / `HasFired(name)` named waitpoints;
`launch_finished` fires at the end of `Application::run()`. `TDESKTOP_TEST_SCALE` is applied
by the harness at startup, and on macOS the harness holds the App Nap opt-out for the whole run
(`TDESKTOP_TEST_APP_NAP=allow` leaves it off; see [launch behavior](launch.md)).
- `test_scenario.cpp` — the overlay-owned slot: it defines `Test::SetupScenario(runner)` and
is a no-op in the repository.
A minimal scenario shape:
```cpp
void SetupScenario(not_null<Runner*> runner) {
runner->waitEvent(u"launch_finished"_q);
runner->actOnWidget(
u"click the published button"_q,
[] { return Test::ReadLiveWidget(u"task.button"_q).widget; },
[](QWidget *widget) { Test::Click(widget); },
[](QWidget *widget) {
return Test::ReadButtonState(widget).usable();
},
Test::kDefaultStageTimeout,
[](QWidget *widget) {
return Test::ButtonStateDetails(Test::ReadButtonState(widget));
});
runner->captureAndInspect(
u"target_surface"_q,
[] { return Test::ReadLiveWidget(u"task.surface"_q).widget; },
[](QWidget *widget) {
return widget->property("contentGeneration").toInt() > 0;
},
[](QWidget *widget, const QImage &image) {
Test::LogGeometry(u"surface"_q, widget->geometry());
Test::Check(
image.width() >= widget->width(),
u"capture covers the surface width"_q,
u"image=%1 widget=%2"_q
.arg(image.width())
.arg(widget->width()));
});
}
```