206 lines
9 KiB
C++
206 lines
9 KiB
C++
/*
|
|
This file is part of Telegram Desktop,
|
|
the official desktop application for the Telegram messaging service.
|
|
|
|
For license and copyright information please follow this link:
|
|
https://github.com/telegramdesktop/tdesktop/blob/master/LEGAL
|
|
*/
|
|
#pragma once
|
|
|
|
#include "base/timer.h"
|
|
|
|
class QImage;
|
|
class QWidget;
|
|
|
|
namespace Test {
|
|
|
|
inline constexpr auto kDefaultStageTimeout = crl::time(10000);
|
|
inline constexpr auto kStartupStageTimeout = crl::time(30000);
|
|
|
|
// One scenario step. Runs |run| once after prerequisites from earlier stages,
|
|
// polls the pure readiness observer |until| on the event loop till it returns
|
|
// true (immediately ready when null), then runs |then| assertions/actions.
|
|
// Expected product results belong in |then|, not |until|. A stage past its
|
|
// |timeout| fails the scenario and finishes early — the scenario always ends
|
|
// in TEST_COMPLETE and quit, never a hang. A stage whose |skipReason| returns
|
|
// a non-empty string does not apply: the runner writes TEST_RESULT: N/A with
|
|
// that reason, skips |run|, |until| and |then|, and moves to the next stage
|
|
// in the same turn, so a false gate never waits and never times out. A stage
|
|
// appended inside Runner::addGated also inherits that group's gate, read
|
|
// before its own |skipReason|.
|
|
struct Stage {
|
|
QString name;
|
|
Fn<QString()> skipReason;
|
|
Fn<void()> run;
|
|
Fn<bool()> until;
|
|
Fn<void()> then;
|
|
crl::time timeout = kDefaultStageTimeout;
|
|
Fn<QString()> timeoutDetails;
|
|
};
|
|
|
|
class Runner final {
|
|
public:
|
|
void add(Stage stage);
|
|
|
|
// One fixture prerequisite shared by a composed group of stages. Calls
|
|
// |compose| once, synchronously, before start(); every stage appended
|
|
// while it runs (through add, the sugar waits, actOnWidget,
|
|
// captureWidget, captureAndInspect or any helper given the runner)
|
|
// inherits |gate|. When such a stage begins, the open groups' gates are
|
|
// read outermost first, then the stage's own skipReason. The first
|
|
// non-empty answer of a group's gate is kept for every later stage of
|
|
// that group: a gate that later answers another reason or empty changes
|
|
// nothing. A non-empty answer writes TEST_RESULT: N/A: <stage> - <reason>
|
|
// and skips |run|, |until| and |then|, so no widget is resolved, no
|
|
// readiness polled, no action dispatched and no capture taken. Work that
|
|
// |compose| itself does while appending is not a stage and is not gated.
|
|
// Stages appended after it returns, addRecovery stages and onFinish
|
|
// releases do not inherit; the session gate's refusal still replaces
|
|
// every stage's reason at start(). The prerequisite deciding |gate| must
|
|
// be settled by an earlier stage (await an asynchronous answer in that
|
|
// stage's |until|). Usage: docs/helpers/test_runner.md.
|
|
void addGated(Fn<QString()> gate, Fn<void()> compose);
|
|
|
|
// Appends |stage| with only its own skipReason (its recovery policy),
|
|
// even while an addGated composition is open, so a failed prerequisite
|
|
// never swallows a restoration stage. The session gate still skips it.
|
|
void addRecovery(Stage stage);
|
|
|
|
// Sugar stages over the common waits.
|
|
void waitEvent(
|
|
const QString &event,
|
|
crl::time timeout = kStartupStageTimeout);
|
|
void waitForSessionReady(crl::time timeout = kStartupStageTimeout);
|
|
void waitForChatsLoaded(crl::time timeout = kStartupStageTimeout);
|
|
void waitForChatsLoadedStrict(crl::time timeout = kStartupStageTimeout);
|
|
|
|
// Polls an exact target and an optional pure readiness predicate, then
|
|
// runs the action once against the same lifetime-guarded widget. This
|
|
// avoids eager stage actions and resolve-again races. Inside addGated the
|
|
// stage inherits the group's gate.
|
|
void actOnWidget(
|
|
const QString &name,
|
|
Fn<QWidget*()> resolve,
|
|
Fn<void(QWidget*)> action,
|
|
Fn<bool(QWidget*)> ready = {},
|
|
crl::time timeout = kDefaultStageTimeout,
|
|
Fn<QString(QWidget*)> readinessDetails = {});
|
|
|
|
// Resolves an exact widget on every tick, waits until the harness can
|
|
// prepare a valid painted frame and the optional task predicate agrees,
|
|
// then saves that same frame. Use this for full boxes, layer owners, and
|
|
// animated surfaces instead of capture-from-then timing guesses. Inside
|
|
// addGated the stage inherits the group's gate.
|
|
void captureWidget(
|
|
const QString &name,
|
|
Fn<QWidget*()> resolve,
|
|
Fn<bool(QWidget*)> ready = {},
|
|
crl::time timeout = kDefaultStageTimeout,
|
|
Fn<QString(QWidget*)> readinessDetails = {});
|
|
|
|
// Saves the same accepted frame as captureWidget, then gives that exact
|
|
// widget and image to assertions. Keep readiness limited to identity and
|
|
// paint availability; geometry/raster expectations belong in |inspect|
|
|
// so a mismatch is a FAIL with actual values, never a timeout.
|
|
// |skipReason| becomes the capture stage's own Stage::skipReason: a
|
|
// non-empty answer when the stage begins writes TEST_RESULT: N/A and
|
|
// skips it; left empty the stage is unchanged. Inside addGated the stage
|
|
// inherits the group's gate; |skipReason| is read after it.
|
|
void captureAndInspect(
|
|
const QString &name,
|
|
Fn<QWidget*()> resolve,
|
|
Fn<bool(QWidget*)> ready,
|
|
Fn<void(QWidget*, const QImage &)> inspect,
|
|
crl::time timeout = kDefaultStageTimeout,
|
|
Fn<QString(QWidget*)> readinessDetails = {},
|
|
Fn<QString()> skipReason = {});
|
|
|
|
// Release point for per-scenario timers, rpl::lifetimes, watchers, and
|
|
// raw cross-stage pointers. finish() runs every registered callback
|
|
// exactly once on every path that reaches it — stage timeout, watchdog,
|
|
// skip-to-end, and normal completion — after _finished is set and the
|
|
// ticker/watchdog are cancelled, before the post-quit fuse is armed and
|
|
// before kFinishDrainDelay is scheduled. The drain still runs so a fused
|
|
// file-launch can observe its fuse; these callbacks neither skip that
|
|
// drain nor wait for it, and they run before Complete() and Core::Quit().
|
|
// They also run when a teardown stage already ran, so they must be safe
|
|
// to call after teardown. A registration made after finish() has already
|
|
// run executes immediately and is never silently dropped. The
|
|
// Test-session helper's finish verification (FinishSessionGate in
|
|
// test_session_gate.h) runs after every callback registered before or
|
|
// during finish(), and before the post-quit fuse and the drain. Only
|
|
// while a switch back's post-switch drain is outstanding - that
|
|
// verification switched an account back, or the watchdog finished the
|
|
// runner while the helper's restore stage was still waiting its drain -
|
|
// does finish() also wait what is left of that drain, yielding to the
|
|
// event loop, and take its fresh verification
|
|
// (FinishSessionGateAfterDrain) before running the drain, Complete() and
|
|
// Core::Quit() once; a timer that arrives before the drain's recorded end
|
|
// waits the rest again, so neither the verification nor the completion
|
|
// comes early. The post-quit fuse is armed before that wait, its
|
|
// deadline extended by it. Without the helper, or when it is already
|
|
// settled (nothing was switched back, or the restore stage finished its
|
|
// drain and its fresh check), finish() goes on at once.
|
|
void onFinish(Fn<void()> callback);
|
|
|
|
[[nodiscard]] bool empty() const;
|
|
|
|
// Logs SCENARIO_START, arms the watchdog, then runs the session gate
|
|
// (test_session_gate.h) before the first stage begins: it logs every
|
|
// account's environment and, when it refuses, writes one
|
|
// "fixture gate: session gate" FAIL and gives every stage its skip
|
|
// reason, so each writes TEST_RESULT: N/A, none of their callbacks runs
|
|
// and the run still reaches finish() and TEST_COMPLETE.
|
|
void start();
|
|
|
|
private:
|
|
void tick();
|
|
void beginStage();
|
|
void completeStage();
|
|
void finish();
|
|
|
|
std::vector<Stage> _stages;
|
|
std::vector<Fn<QString()>> _inheritedGates;
|
|
int _index = 0;
|
|
bool _started = false;
|
|
bool _finished = false;
|
|
crl::time _stageStarted = 0;
|
|
base::Timer _ticker;
|
|
base::Timer _watchdog;
|
|
std::vector<Fn<void()>> _onFinish;
|
|
|
|
};
|
|
|
|
// Defined by test/test_scenario.cpp. The per-task test overlay replaces that
|
|
// file with a scenario built from the task's test design; the repository
|
|
// copy registers nothing.
|
|
void SetupScenario(not_null<Runner*> runner);
|
|
|
|
// A permanent scenario module that is compiled in only on request (such as
|
|
// the localization capture behind TDESKTOP_L10N_CAPTURE) registers itself
|
|
// here from a static initializer. Start() asks each provider in turn; the
|
|
// first one that returns true has registered its stages, and SetupScenario
|
|
// is not called. A provider returns false when its own switch (usually an
|
|
// environment variable) is not set.
|
|
void RegisterScenarioProvider(Fn<bool(not_null<Runner*>)> provider);
|
|
|
|
// The finish-release hook measuring itself. One Runner calls finish() once,
|
|
// so the overlay selects the path. Timeout and Watchdog emit a harness FAIL
|
|
// by construction. registerRelease=false is the timeout control that leaves
|
|
// the 5 ms timer ticking; do not pack that control into a scenario that must
|
|
// exit cleanly.
|
|
enum class FinishReleasePath {
|
|
Timeout,
|
|
Watchdog,
|
|
Complete,
|
|
CompleteWithTeardown,
|
|
SkipAll,
|
|
LateRegister,
|
|
};
|
|
|
|
void AppendFinishReleaseSelfTest(
|
|
not_null<Runner*> runner,
|
|
FinishReleasePath path,
|
|
bool registerRelease = true);
|
|
|
|
} // namespace Test
|