ZaStoGram_desktop/Telegram/SourceFiles/test/test_runner.h

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