ZaStoGram_desktop/Telegram/SourceFiles/test/docs/launch.md
John Preston cee5c94af7 [ai] Add a stress kit runner and a Release test harness
Task: 2026/10/30/run-the-widget-stress-kit-at-v0-4-0-on-a-release-build-without-lto
2026-11-05 17:12:56 +04:00

6.6 KiB

Launch, activation and background painting

Harness guide · Helper index

On macOS a default workspace.py test-run launch of an app bundle's main executable does not activate the client: it launches the bundle through LaunchServices in the background, with Qt's own launch activation switched off (.agents/shared/test-loop.md, Launch activation; the report reads launch_method: "background"). The client starts as an inactive application and its windows open behind the frontmost application's. A window shown already covered reads isExposed() true until the window server first reports a change for it, so exposed=1 is no proof that it is on screen; after such a change a covered window reads unexposed and gets no paints. Drive focus-routed actions with ForceWindowActive, keep a window a stage needs painted exposed with KeepWindowExposed either way, and use test-run --activate when genuine OS activation is the subject. Product flows that raise or activate a top-level window - Ui::PopupMenu, Ui::SeparatePanel::showAndActivate(), Window::Controller::activate(), DropText into a shown field - still request activation of the client on macOS, and so do the not-marking-read, separate-panel-walk and popup-menu self-tests. After a background launch the window server may grant or refuse that request: on this host it granted it about 11 s after launch in two default runs and refused it about 20 s after launch in a third, under a condition those runs did not establish (2026/10/08/launch-the-testagent-client-without-activating-it, Runs 4, 8 and 9). A granted request takes the key window from the frontmost application. After a refused one the client stays inactive and the frontmost application keeps its key window, but the client's window may still be ordered in front of the frontmost application's window by the request's own window ordering: in Run 9 above the primary window stayed covered after its restore, while with an overlay that made the client's own application-activation calls no-ops, reproducing that refusal under another stage sequence, the inactive primary window was in front for about 4 s after the not-marking-read self-test's restore through Window::Controller::activate(), until a later request put it behind again (2026/10/09/keep-background-testagent-runs-on-macos-unthrottled-and-painting, Runs 0 and 3). So the scenario's own activation is no reliable route to OS activation under the default. A client the launch did not activate is a background application, which macOS may nap and whose timers it may coalesce: in background runs on this host without a hold, a sampler's heartbeat gaps grew to 100-290 ms after about 15 s of normal cadence (2026/10/01/animate-gram-card-sending-and-settle-effects, Run 1), and a 4 ms precise sampler ticked every 50-1000 ms from about the 80th second (2026/10/02/show-the-input-method-composition-in-the-gram-send-amount, Run 1). On a locked console macOS napped such a client without a hold, from about 30 s after process start (2026/10/09/keep-background-testagent-runs-on-macos-unthrottled-and-painting, Runs 0 and 4), but another application's window covering the client did not guarantee it: on an unlocked console, a client without a hold that the frontmost application's window covered kept an exact 16 ms timer cadence over 60 s and over 300 s (Runs 1 and 2). Those runs did not establish what made macOS nap the client. So on macOS the harness holds one user-initiated, latency-critical NSProcessInfo activity (NSActivityUserInitiatedAllowingIdleSystemSleep | NSActivityLatencyCritical; idle system sleep stays allowed) for the whole -testagent run: Test::ApplyStartupOverrides() (test_agent.cpp) begins it early in Application::run(), before Test::Start(), and never ends it, so it lasts until the process exits, a watchdog or stage-timeout ending included. The log says once which case a run is in: a held run reads NOTE: TDESKTOP_TEST_APP_NAP=[] applied: hold=active ..., and a run without the hold reads hold=off with the reason. An overlay no longer holds an activity of its own: the per-overlay BeginLatencyActivity of the 2026/10/07/animate-the-sending-row-for-a-collectible-transfer overlay is history, and a second activity is harmless but redundant. A campaign whose subject is background scheduling itself (App Nap, timer coalescing, throttled-timer behaviour) launches with test-run --env TDESKTOP_TEST_APP_NAP=allow, and its log then reads hold=off source=environment; any other non-empty value is logged as rejected and the hold is kept. Off macOS nothing reads TDESKTOP_TEST_APP_NAP and nothing is held.

Read input targeting for the actual event route, window exposure for painting and console state when diagnosing a refusal.

Release builds with the harness

The harness is compiled in Debug builds. The CMake option TDESKTOP_RELEASE_TEST_HARNESS, OFF by default, also compiles it into the Release configuration, for local measurements of an optimized build: it defines TDESKTOP_RELEASE_TEST_HARNESS for the whole Telegram target in Release only, so Debug, MinSizeRel and RelWithDebInfo stay unchanged. Configuring it ON together with DESKTOP_APP_ENABLE_LTO, the official release builds' setting, fails; such a binary is never shipped. Switch it by reconfiguring the existing tree, and back OFF when done:

C:\Telegram\ThirdParty\CMake\bin\cmake.exe -S <source> -B <source>\out -DTDESKTOP_RELEASE_TEST_HARNESS=ON
C:\Telegram\ThirdParty\CMake\bin\cmake.exe -S <source> -B <source>\out -DTDESKTOP_RELEASE_TEST_HARNESS=OFF

The definition is on every Release compile command, so the first Release build after either switch rebuilds every Telegram object.

  • Harness translation units are gated #if defined _DEBUG || defined TDESKTOP_RELEASE_TEST_HARNESS. An overlay hunk in a product file must use the same condition to be compiled in such a build; one under #ifdef _DEBUG is left out.
  • test_wallet_ready.cpp stays Debug-only: it calls the Debug-only Wallet::Session::debugClearNetworkState().
  • Where a harness header says "Debug build", "Debug-only" or "the Release branch", read a build with the harness and one without it.
  • out/Release has no golden folder: launch with workspace.py test-run --portable-root <dir>, with <dir>/test_TelegramForcePortable copied from the Debug golden (.agents/shared/test-loop.md, wallet-custody limit included).
  • -testagent turns on debug logging and the deadlock detector's ping thread in every configuration (core/launcher.cpp, core/sandbox.cpp), an observer cost inside any measurement.