ZaStoGram_desktop/Telegram/SourceFiles/test/test_chat_show_place.h
John Preston a44f62dbe3 [ai] Record the chat-list place helper's executed checks
Task: 2026/10/27/show-or-scroll-off-several-chat-list-messages-and-prove-they-stayed-in-the-harness
2026-11-05 17:12:55 +04:00

356 lines
15 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/basic_types.h"
#include "data/data_msg_id.h"
#include "data/data_peer_id.h"
#include <QtCore/QPointer>
#include <QtCore/QRect>
#include <QtCore/QString>
#include <memory>
#include <vector>
class HistoryItem;
class QWidget;
namespace HistoryView {
class Element;
} // namespace HistoryView
namespace Test {
class Runner;
// Places several messages of one chat list wholly in view together, or
// wholly above or below it, and proves they stayed there for a window.
// Usage, limits, rows and refusals: docs/helpers/test_chat_show_place.md.
// Where every message of one call goes, judged on its whole own view, in
// the list's own coordinates and logical pixels:
// - OnScreen: wholly inside the list's visible message area
// (ChatListShowVisibleArea) and, mapped into the owning scroll, inside
// that area's clip there;
// - OffAbove: the view's bottom at or above the area's top;
// - OffBelow: the view's top at or below the area's bottom.
// The off placements are the lists' own visibility rule: a view is shown
// while top + height > areaTop && top < areaBottom. For them a message
// whose list shows no own view of it counts as off.
enum class ChatListPlacement {
OnScreen,
OffAbove,
OffBelow,
};
// |list| follows ChatListShowTarget's rules: a HistoryInner, a
// HistoryView::ListWidget or an AdminLog::InnerWidget, the owned widget of
// its Ui::ElasticScroll. |items| name the messages; each is looked up
// again through the list's session on every sample, and so is the list's
// own view of it (never item->mainView() taken on trust).
struct ChatListPlaceTarget {
QWidget *list = nullptr;
std::vector<FullMsgId> items;
};
// The caller's visibility reading of one message, and its details. |view|
// is the list's own current view of |item|, or null, valid only during
// the call: keep no pointer to it. Both must only read: they are called
// on many samples, by the placement stage and by its record after it,
// across the caller's later stages until the record ends. The reading
// must be the product's fresh answer, never a cache. For a widget card
// that is Tgw::Runtime::queryVisible() (private; read it with the
// file-private accessor idiom) or membership in
// Tgw::Runtime::WatchingOnScreen(), never Tgw::Runtime::_visible.
using ChatListPlaceVisible = Fn<bool(
not_null<HistoryItem*> item,
const HistoryView::Element *view)>;
using ChatListPlaceDetails = Fn<QString(
not_null<HistoryItem*> item,
const HistoryView::Element *view)>;
// |name| labels the stage ("place in chat list: <name>") and its rows.
// |resolve| runs once, when the stage begins, so a list or messages from
// an earlier stage can be named. |visible| is the reading above, asked on
// every settled placed sample and on every record sample; true is
// expected for OnScreen and false for the off placements.
// |visibleDetails| is printed beside every answer; null prints none.
// |resolve| and |visible| are required. |timeout| is the helper's own
// deadline, in ms from the stage's run.
struct ChatListPlaceArgs {
QString name;
ChatListPlacement placement = ChatListPlacement::OnScreen;
Fn<ChatListPlaceTarget()> resolve;
ChatListPlaceVisible visible;
ChatListPlaceDetails visibleDetails;
Fn<QString()> skipReason;
crl::time timeout = crl::time(10000);
};
// Every refusal's CHAT_LIST_PLACE row carries each message's last
// geometry and reading (element=none, visible=none when never read), each
// alive message's reading asked once more on the deciding sample unless
// the refusal is no-list. The reasons of cannot-fit and cannot-move-off
// carry them for every message, that of reading-disagrees for each
// message that disagreed; other reasons may carry less: read the row.
// - no-list: no list, not one of the three lists, not owned by a
// Ui::ElasticScroll, or destroyed while the helper waited;
// - no-target: no message id, an id the list's session does not know, or
// a message destroyed while the helper waited;
// - no-view: a message had no own view when the stage began (nothing is
// scrolled), or an on placement's view was lost and not shown again by
// the deadline;
// - cannot-fit (OnScreen only): on a usable layout that read the same for
// the settle time, or at the deadline on the last usable one, the views'
// union band is taller than the visible area, or a view lies outside it
// horizontally;
// - cannot-move-off (off only): on such a layout, with the messages not
// already all off on the asked side, the scroll top that puts every
// view wholly on that side, 8 px past the edge, is outside
// [0, scrollTopMax()]. Nothing is scrolled: the helper never scrolls to
// an edge to load more;
// - out-of-place: the messages fit or could move, but at the deadline they
// were not all placed, the layout stayed pending, or the placed geometry
// had not settled;
// - reading-disagrees: placed and settled at the deadline, but some
// message's reading disagreed (true off, false on).
enum class ChatListPlaceRefusal {
None,
NoList,
NoTarget,
NoView,
CannotFit,
CannotMoveOff,
OutOfPlace,
ReadingDisagrees,
};
// What one sample saw of one message. |element| (the view's bounds, empty
// without a view) and |viewport| (the list's visible message area) are in
// the list's own coordinates; |scrollTop| is the owning scroll's. |placed|
// means where the placement asks. |visible| is the caller's reading,
// |asked| says whether it was read on that sample and |details| are its
// details.
struct ChatListPlaceMark {
crl::time at = 0;
QRect element;
QRect viewport;
QString details;
int scrollTop = 0;
bool alive = false;
bool viewShown = false;
bool placed = false;
bool visible = false;
bool asked = false;
};
// One message of the placement. |initial| is read when the stage begins,
// before any scroll; |last| is the latest sample, from the placement or
// from the record after it. |changes| starts with the accepted mark and
// gets one more mark each time |alive|, |viewShown|, |placed| or
// |visible| changes. |readings| and |disagreements| count the placement
// gate's answers and the ones against the placement.
struct ChatListPlaceItem {
FullMsgId id;
ChatListPlaceMark initial;
ChatListPlaceMark last;
std::vector<ChatListPlaceMark> changes;
int readings = 0;
int disagreements = 0;
};
// The reading the placement stage fills; read it from a later stage.
// |name|, |placement| and |timeout| are filled when the stage is appended,
// the rest while it runs; a skipped stage leaves |finished| false.
// Coordinates, all logical pixels: |band| (the union of the shown views)
// and |viewport| in the list's own, |effective| (the visible area mapped
// into the owning scroll and clipped to it) in the scroll's. |target| is
// the last scroll top asked; |scrollRequests| counts corrections asked of
// the scroll, |scrolls| those that moved it and |generation| the geometry
// changes seen. |placedAt| is the acceptance time (crl::now()) and the
// record's start; |samples| counts record samples since then, |maxGapMs|
// is the longest gap between them and |lastSampleAt| the latest one.
// The record keeps filling after the stage finished, until
// Runner::onFinish, the list's destruction or the destruction of every
// placed message; then |recording| is false and |recordEnded| set, with
// |recordEndedAt| and |recordEnd| saying when and which. Stays only read
// it.
struct ChatListPlace {
QString name;
QPointer<QWidget> list;
QString kind;
QString listIdentity;
QString reason;
QString recordEnd;
std::vector<ChatListPlaceItem> items;
QRect band;
QRect viewport;
QRect effective;
ChatListPlacement placement = ChatListPlacement::OnScreen;
ChatListPlaceRefusal refusal = ChatListPlaceRefusal::None;
crl::time timeout = 0;
crl::time elapsedMs = 0;
crl::time placedAt = 0;
crl::time lastSampleAt = 0;
crl::time recordEndedAt = 0;
crl::time maxGapMs = 0;
int scrollTop = 0;
int scrollTopMax = 0;
int target = 0;
int scrollRequests = 0;
int scrolls = 0;
int generation = 0;
int samples = 0;
bool settled = false;
bool pending = false;
bool finished = false;
bool recording = false;
bool recordEnded = false;
[[nodiscard]] bool placed() const {
return finished && (refusal == ChatListPlaceRefusal::None);
}
};
// on, off-above, off-below.
[[nodiscard]] QString ChatListPlacementName(ChatListPlacement placement);
// none, no-list, no-target, no-view, cannot-fit, cannot-move-off,
// out-of-place, reading-disagrees.
[[nodiscard]] QString ChatListPlaceRefusalName(ChatListPlaceRefusal refusal);
// The one CHAT_LIST_PLACE row the stage Notes, in ordinary integers; its
// fields are listed in the module reference.
[[nodiscard]] QString ChatListPlaceText(const ChatListPlace &reading);
// Appends the stage "place in chat list: <name>" and returns its reading.
// The stage's run resolves the target, refuses what it cannot place and
// makes the first scroll. Its until only observes, and accepts once, on
// one sample: every message is placed on the asked side; the views, their
// geometry, the visible area, the scroll top and range and the pending
// layout read the same for 400 ms; and the caller's reading agrees for
// every message. A helper-owned timer makes the later scroll corrections,
// each from a fresh sample. The helper's deadline is max(timeout, 0) after
// the run, and the stage's runner timeout kDefaultStageTimeout more, so a
// refusal is a named reading, never a stage timeout. It never Passes or
// Fails: treat a refusal as a fixture gate. An accepted placement starts
// the record, which calls the reading on each of its samples until
// Runner::onFinish, the list's destruction or the destruction of every
// placed message.
[[nodiscard]] std::shared_ptr<const ChatListPlace> AppendPlaceInChatList(
not_null<Runner*> runner,
ChatListPlaceArgs args);
// - not-placed: the placement did not finish accepted; the reason names
// its refusal, or says it did not finish (skipped or not run);
// - did-not-stay: inside the window a message left its placement or was
// destroyed, or the record ended before the window's end (the list or
// every message destroyed, or the run finishing);
// - reading-disagrees: the geometry held, but a message's reading
// disagreed inside the window.
// The earliest deviation decides; on one sample, geometry wins.
enum class ChatListStayRefusal {
None,
NotPlaced,
DidNotStay,
ReadingDisagrees,
};
// |name| labels the stage ("stayed in chat list: <name>") and its row.
// |place| is a reading AppendPlaceInChatList returned; it is required.
// |hold| is the window's least length, in ms from the placement's
// acceptance; 0 ends the window when this stage runs.
struct ChatListStayArgs {
QString name;
std::shared_ptr<const ChatListPlace> place;
crl::time hold = 0;
Fn<QString()> skipReason;
};
// One message over the window. |deviation| is its first mark inside the
// window that left the placement, was destroyed or read against
// |expectedVisible|; |deviation.at| 0 means none. |last| is its record
// mark at the decision. |window| holds its record's marks in
// [from, till], the accepted mark first, and |changes| counts the ones
// after it: its changes in (from, till].
struct ChatListStayItem {
FullMsgId id;
ChatListPlaceMark deviation;
ChatListPlaceMark last;
std::vector<ChatListPlaceMark> window;
int changes = 0;
bool expectedVisible = false;
bool stayed = false;
};
// The reading the stay stage fills; read it from a later stage. The
// window is [from, windowEnd]: |from| is the placement's acceptance and
// |windowEnd| max(this stage's run, from + hold). |till| is the record
// sample the stay decided on, at or after |windowEnd| unless a deviation
// or the record's end decided first; the judgement reads only marks up
// to it. |from| and |till| are crl::now() values, so a consumer brackets
// its own product rows with them. |samples| and |maxGapMs| are the
// record's at the decision.
struct ChatListStay {
QString name;
QString placeName;
QString reason;
std::vector<ChatListStayItem> items;
ChatListPlacement placement = ChatListPlacement::OnScreen;
ChatListStayRefusal refusal = ChatListStayRefusal::None;
crl::time hold = 0;
crl::time from = 0;
crl::time till = 0;
crl::time windowEnd = 0;
crl::time maxGapMs = 0;
int samples = 0;
bool finished = false;
[[nodiscard]] bool stayed() const {
return finished && (refusal == ChatListStayRefusal::None);
}
};
// none, not-placed, did-not-stay, reading-disagrees.
[[nodiscard]] QString ChatListStayRefusalName(ChatListStayRefusal refusal);
// The one CHAT_LIST_STAY row the stage Notes; its window= lists every
// mark inside the window, and its fields are listed in the module
// reference.
[[nodiscard]] QString ChatListStayText(const ChatListStay &reading);
// Appends the stage "stayed in chat list: <name>" and returns its reading.
// The window is [placedAt, max(this stage's run, placedAt + hold)]: right
// after the placement with |hold| it is a fixed-length window, and after
// the consumer's own stages with |hold| 0 it spans them. The stage decides
// at the record's first sample at or after the window's end, or at once
// on a deviation already recorded. It only reads the record, so several
// stays may judge one placement, each window starting at its acceptance.
// The stage's runner timeout is max(hold, 0) plus kDefaultStageTimeout.
// It never Passes or Fails: treat a refusal as a fixture gate, and judge
// the consumer's own product rows between |from| and |till|.
[[nodiscard]] std::shared_ptr<const ChatListStay> AppendStayedInChatList(
not_null<Runner*> runner,
ChatListStayArgs args);
// The module's behavioral self-test, appended by an overlay's
// SetupScenario after its session and chats-loaded waits. |chat| is a
// chat test_widget_fixture accepts (its requirements are the fixture's),
// opened in its legacy HistoryInner. Only local messages are injected
// there: two widget cards and one tall text filler above and one below
// them; nothing is sent. The legs: three accepted placements (on, off
// below, off above) with a held stay each, two continuity refusals on
// those same records (an excursion and a flipped reading) and three
// placement refusals (a stale reading, cannot fit, cannot move off). The
// fixture's teardown follows the legs, and its release is registered
// with Runner::onFinish before anything changes; stages, rows and
// verdict: docs/helpers/test_chat_show_place.md.
void AppendChatListPlaceSelfTest(not_null<Runner*> runner, PeerId chat);
} // namespace Test