ZaStoGram_desktop/Telegram/SourceFiles/test/test_controller_ready.h
John Preston ed84a10945 [ai] Resolve test controllers by account and session
Task: 2026/10/19/resolve-test-controllers-by-account-and-session
2026-10-26 23:47:48 +04:00

270 lines
12 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
// Usage, refusals and cleanup: docs/helpers/test_controller_ready.md.
#include "base/weak_ptr.h"
#include "test/test_runner.h"
#include "window/window_separate_id.h"
#include <QtCore/QString>
namespace Main {
class Session;
} // namespace Main
namespace Window {
class Controller;
class SessionController;
} // namespace Window
namespace Test {
// Exact account/session controller readings for -testagent overlays: which
// registered Window::Controller and Window::SessionController show one
// requested session (in the account's primary window, or in one exact
// window), and whether that controller is ready right now.
//
// The registry is Core::Application's window map, read through
// Core::Application::enumerateWindows. Windows enter it in
// ensureSeparateWindowFor (and at startup), are re-keyed by checkWindowId
// and leave it in closeWindow.
//
// Activation history is Core::Application::windowStack(), together with
// activeWindow() and activePrimaryWindow(). It changes only in
// setLastActiveWindow: at startup, in checkWindowId while no window is
// active, in closeWindow, and in windowActivated when the OS reports a
// window active. A background -testagent launch may never activate a
// just-created window, so here activation history is a diagnostic fact,
// never the registry. windowFor() falls back to the active primary window,
// so it is no exact lookup either.
//
// Every reading is pure: it activates, switches and creates nothing, runs
// no product action and sends no request. It never calls
// Window::Controller::account() (it asserts on the startup window),
// Main::Session::tryResolveWindow() (it may activate an account) or
// windowFor().
//
// Only Test-environment sessions are accepted: the session gate
// (test_session_gate.h) admitted no other, and a controller resolved here
// need not be the one the gate read.
//
// An accepted reading does not prove a painted, exposed or unobscured
// frame, OS activation or focus (KeepWindowExposed in
// test_window_exposure.h, ForceWindowActive in test_widgets.h).
//
// Main thread only.
// An identity handle, never dereferenced. Two handles name the same object
// only while that object is alive. A never-bound handle is null(); the
// handle of a destroyed object is empty() and matches nothing, so a new
// object created at a reused address never revives it.
using ControllerHandle = base::weak_ptr<const base::has_weak_ptr>;
// What a caller asks for: the account and session to find and, when
// |exactWindow| is set, the one registered window that must show them.
struct ControllerRequest {
ControllerHandle account;
ControllerHandle session;
ControllerHandle window;
bool exactWindow = false;
};
// The one-argument form asks for the account's Primary-type registered
// window. The two-argument form asks for exactly |window| and sets
// exactWindow, so a closed or never-bound window refuses as
// destroyed-window and never falls back to another window. Both take
// account = &session->account(), and leave account and session unbound
// when |session| is null. Safe to call from a poll.
[[nodiscard]] ControllerRequest ExactController(Main::Session *session);
[[nodiscard]] ControllerRequest ExactController(
Main::Session *session,
const base::weak_ptr<Window::Controller> &window);
// One registered window as the decision sees it, read from the registry or
// built by a caller-controlled fixture:
// - window: the Window::Controller; account: the account its id() names;
// session: that account's maybeSession();
// - controller: its sessionController(); shownSession: that controller's
// session();
// - target: the same controller, typed; filled only by the real reader;
// - type: id().type;
// - accountIndex: the Main::Domain storage index of account, or -1;
// - activation: the recency rank in windowStack(), 0 being the most recent
// (activeWindow()), or -1 when the window is absent from it;
// - test: whether session is on the Test environment (isTestMode());
// - visible, minimized, sized: the widget's isVisible(), isMinimized() and
// a non-empty size();
// - locked: Window::Controller::locked() (a passcode or terms lock);
// - activePrimary: whether this window is activePrimaryWindow().
// activation and activePrimary are facts; no decision reads them.
struct ControllerEntry {
ControllerHandle window;
ControllerHandle account;
ControllerHandle session;
ControllerHandle controller;
ControllerHandle shownSession;
base::weak_ptr<Window::SessionController> target;
Window::SeparateType type = Window::SeparateType::Primary;
int accountIndex = -1;
int activation = -1;
bool test = false;
bool visible = false;
bool minimized = false;
bool sized = false;
bool locked = false;
bool activePrimary = false;
};
// Names (ControllerRefusalName), in decision order; the first that applies
// is the reading's refusal:
// 1. no-session: the requested session handle is empty (never bound, or
// its session destroyed);
// 2. with an exact window requested:
// - destroyed-window: its handle is empty (never bound, or closed);
// - wrong-window: it is alive but not registered;
// - wrong-account: it is registered for another account;
// without one:
// - no-registered-window: the account has no Primary-type registered
// window. This is an absent controller, whatever activation history
// says; a registered window missing from windowStack() is not refused
// for that and reads activation=absent;
// 3. wrong-session: the window's account shows another session or none, or
// its SessionController shows another session;
// 4. non-test: the session is not on the Test environment;
// 5. unready: no SessionController, or an empty widget size;
// 6. locked: Window::Controller::locked(), a passcode or terms lock;
// 7. hidden: the widget is not visible, or is minimized.
// Only the identity re-check of an accepted reading (ActOnController's,
// before its action) can give, after destroyed-window (its window closed):
// - replaced-session: its session was destroyed;
// - replaced-window: its SessionController was destroyed, or a fresh
// decision accepts another window or controller.
// none means accepted; not-evaluated is the default and never accepts.
enum class ControllerRefusal {
None,
NotEvaluated,
NoSession,
DestroyedWindow,
WrongWindow,
WrongAccount,
NoRegisteredWindow,
WrongSession,
NonTest,
Unready,
Locked,
Hidden,
ReplacedWindow,
ReplacedSession,
};
[[nodiscard]] QString ControllerRefusalName(ControllerRefusal refusal);
// One decision. |entry| is the registered window the decision selected: a
// fresh decision leaves it empty for no-session, no-registered-window,
// destroyed-window and wrong-window, and a re-checked reading that refuses
// before deciding again keeps the retained entry. |registered| counts the
// windows read, |accountWindows| the registered windows naming the
// requested account, |activationSize| is the size of windowStack(), and
// |dispatched| is set only when the action ran.
// accepted() describes the moment of the reading. controller() is
// entry.target.get() only when accepted(), else null; it is null too once
// that controller is destroyed, so a retained reading never yields a stale
// or replacement controller.
struct ControllerReading {
ControllerRequest request;
ControllerEntry entry;
ControllerRefusal refusal = ControllerRefusal::NotEvaluated;
int registered = 0;
int accountWindows = 0;
int activationSize = 0;
bool dispatched = false;
[[nodiscard]] bool accepted() const;
[[nodiscard]] Window::SessionController *controller() const;
};
// Decides |request| over one fresh read of the registry: for every
// registered window its id(), sessionController(), locked() and widget
// visibility, minimized state and size, its account's maybeSession() and
// storage index and that session's isTestMode(), with windowStack() and
// activePrimaryWindow() copied in as facts. Pure; safe in a Stage's
// |until|.
[[nodiscard]] ControllerReading ResolveController(
const ControllerRequest &request);
// The reading as one line, in this format (wrapped here):
// controller verdict=<accepted|refused> refusal=<name>
// request=[window=<account-primary|exact-live|exact-gone>
// session=<live|none>] registered=<n> accountWindows=<n>
// activationSize=<n> entry=[none|index=<i|none>
// type=<Primary|Archive|Chat|Forum|Community|SavedSublist|SharedMedia>
// test=<0|1> session=<same|other|none> controller=<present|none>
// shown=<same|other|none> visible=<0|1> minimized=<0|1> sized=<0|1>
// locked=<0|1> activation=<rank|absent> activePrimary=<0|1>]
// dispatched=<0|1>
// session= and shown= compare with the requested session; window=,
// session= and every handle-derived entry field read liveness when the
// text is made. It prints storage indices and counts only, never a user
// id, uniqueId(), name, peer or address.
[[nodiscard]] QString ControllerReadingText(const ControllerReading &reading);
// Appends one stage, "act on controller: <name>".
// - Its |until| builds |request|() and calls ResolveController on every
// poll. Every refusal is "not ready yet" (as Runner::actOnWidget treats
// an unresolved widget); the stage's timeoutDetails is the last reading's
// text, so a timeout names the refusal. |request| must only read.
// - Its |then| runs in the same runner tick as the accepting poll
// (Runner::completeStage), so the re-check there is an identity guard,
// not a second wait: against a fresh registry read it requires the same
// live window, controller and session, then calls |action| exactly once
// with that controller and writes
// NOTE: CONTROLLER_READY: act=[<name>] <text>
// Otherwise it writes one
// TEST_RESULT: FAIL: act on controller: <name> - accepted controller
// changed before the action: <text>
// and does not call |action|.
// - Inside Runner::addGated the stage inherits the group's gate.
// - It opens, activates and switches nothing: a caller opens or activates
// a window in an earlier stage, under the session gate's rule that no
// stage switches the primary window or domain().active() to another
// account.
void ActOnController(
not_null<Runner*> runner,
const QString &name,
Fn<ControllerRequest()> request,
Fn<void(not_null<Window::SessionController*>)> action,
crl::time timeout = kDefaultStageTimeout);
// This helper measuring itself.
// - Fixture legs, needing no session, feed caller-controlled registries of
// local identity objects through the same decision the real reader
// feeds: two Test controllers of which activation history holds only one
// are both accepted, an account without a registered window refuses as
// no-registered-window, each refusal is checked beside its accepted
// counterpart, and a retained reading never becomes valid for a
// replacement controller, session or window.
// - Live legs open an Archive window of the primary window's Test session
// (the product's "Archive -> New window" route), resolve both windows by
// registry, check that polls change neither the registry nor activation
// history, act once per accepted target through ActOnController, refuse
// wrong-account, wrong-session, wrong-window and absent targets without
// acting, then close the Archive window and check that its retained
// reading, and a request for it, refuse as destroyed-window.
// - Prerequisites: an unlocked Test session in the primary window, and
// launch_finished awaited by the overlay. Without that session it writes
// one fixture-gate FAIL and the live stages read N/A; an Archive window
// that already existed makes the close leg N/A.
// - Side effects: it opens and closes that Archive window, with the OS
// activation request, presence update and local saved-window bookkeeping
// the product does for it; it sends no request of its own.
// Expected verdict on a copy with that session: no FAIL and no N/A.
void AppendControllerReadySelfTest(not_null<Runner*> runner);
} // namespace Test