19 KiB
test_fixture_transaction
Type: Reusable API (with its own self-test). Source contract: test_fixture_transaction.h.
Use when
An overlay mutates a server fixture that it must restore - privacy rules
(account.getPrivacy / account.setPrivacy), a username, a global privacy
setting - in one or several legs of a campaign. Test::OpenFixtureTransaction
reads canonical state before any write, sends no write when the state already
equals the requested one, accepts a write only when a fresh complete read
equals it, waits the server's own not-before deadline on a rate refusal before
one fresh-read retry, and keeps the complete original in an ignored record a
later launch resumes. It is one fixture's read/compare/write obligation, not
account automation: the caller owns the state, its equality, the
authorization and the target.
For a local in-memory setting use test_notify_override; for controlled replies into a real session, test_rpc_fixture; wallet custody is test_gram_reconcile.
Preconditions and limits
- The caller defines the fixture.
FixtureStateis an opaqueQByteArrayholding the complete canonical state, andequalis its complete equality, including what absence and order mean: whether people order matters, whether a rule that lists nobody equals an absent rule. The transaction compares nothing itself. - No credentials in the state: it is persisted in the record. Keep user ids
and rebuild input users (access hashes) from the live session inside
write. transport.readandtransport.writeanswerdoneorfail(const MTP::Error &)at most once per call, on the main thread, possibly synchronously. A write'sdoneis not equality: the transaction always reads again.- Real requests go through
api().request(...)with.handleFloodErrors()(or.handleAllErrors()). With the default handling aFLOOD_WAIT_<n>never reachesfail:MTP::Instanceresends the same request by itself after the wait, a write with no fresh read and no recorded deadline. The fake-transport self-test does not prove a caller's routing. authorizeis required and read before every request; a non-empty answer refuses that request. It is the caller's account authorization (for example: the exact Test session the scenario runs on still exists), and its text is logged, so it names a reason, never a secret. The transaction never picks an account: the transport andauthorizedecide which one is written.targetnames the account and the fixture key, for example the Test user's id and the privacy key. It is stored in the record, compared on load and never logged.labelis public,[A-Za-z0-9_-]+, one per fixture: it names the record file and every row.- Deadlines are wall-clock milliseconds since the epoch
(
QDateTime::currentMSecsSinceEpoch(); only the self-test passes aFixtureClock), so a recorded deadline survives a relaunch, whichcrl::now()would not. An early timer is re-checked and sends nothing. maxWait(defaultTest::kFixtureMaxWait, 60 s) bounds an in-process wait; an operation waits for a deadline at most once.- A stage awaiting an operation (
until!busy()) needs a timeout abovemaxWaitplus the requests' own time, for exampleTest::kFixtureMaxWait + crl::time(30000), andTDESKTOP_TEST_WATCHDOG(120 s by default) must cover every such wait of the run. A stage timeout or the watchdog releases the transaction and leaves the obligation for a later launch. - Main thread only, one operation at a time:
transition()orrestore()whilebusy()is a contract violation.
Minimal use
An overlay sketch against the real API; no Telegram translation unit
compiles it (the self-test compiles the API with a fake transport).
PhonePrivacyState, PhonePrivacyEqual, PhonePrivacyInput, NobodyState,
ScenarioSession and AppendPhoneHiddenChecks stand for the overlay's own
code: the canonical state of MTPaccount_PrivacyRules as rule kinds and user
ids, its complete equality, the input rules rebuilt from the live session,
the requested state, the exact Test session the scenario runs on, and the
dependent checks.
constexpr auto kFixtureStageTimeout = Test::kFixtureMaxWait
+ crl::time(30000);
[[nodiscard]] Test::FixtureTransactionArgs PhonePrivacyArgs(
not_null<Main::Session*> session) {
const auto weak = base::make_weak(session);
const auto key = MTP_inputPrivacyKeyPhoneNumber();
return {
.label = u"phone-number-privacy"_q,
.target = u"user-%1:phone-number-privacy"_q.arg(
session->userId().bare),
.authorize = [=] {
const auto strong = weak.get();
return (strong && strong->isTestMode())
? QString()
: u"the scenario's Test session is gone"_q;
},
.transport = {
// authorize() was read just before each call.
.read = [=](
Fn<void(Test::FixtureState)> done,
Fn<void(const MTP::Error &)> fail) {
weak.get()->api().request(MTPaccount_GetPrivacy(
key
)).done([=](const MTPaccount_PrivacyRules &result) {
done(PhonePrivacyState(result));
}).fail([=](const MTP::Error &error) {
fail(error);
}).handleFloodErrors().send();
},
.write = [=](
const Test::FixtureState &state,
Fn<void()> done,
Fn<void(const MTP::Error &)> fail) {
const auto strong = weak.get();
strong->api().request(MTPaccount_SetPrivacy(
key,
PhonePrivacyInput(strong, state)
)).done([=] {
done();
}).fail([=](const MTP::Error &error) {
fail(error);
}).handleFloodErrors().send();
},
},
.equal = PhonePrivacyEqual,
};
}
void SetupScenario(not_null<Runner*> runner) {
struct State {
std::shared_ptr<Test::FixtureTransaction> fixture;
QString gate;
};
const auto state = std::make_shared<State>();
const auto session = Test::UseTestSession(runner);
runner->waitEvent(u"launch_finished"_q);
runner->waitForSessionReady();
runner->add({
.name = u"phone privacy fixture: open"_q,
.run = [=] {
state->fixture = Test::OpenFixtureTransaction(
runner,
PhonePrivacyArgs(ScenarioSession()));
if (state->fixture->result().pending) {
// An earlier launch left it mutated: restore first.
state->fixture->restore();
}
},
.until = [=] { return !state->fixture->busy(); },
.then = [=] {
const auto &result = state->fixture->result();
const auto ready = !result.pending
&& (result.outcome != Test::FixtureOutcome::Refused);
Test::Check(
ready,
u"fixture gate: phone privacy fixture ready"_q,
u"reason=[%1] writes=%2"_q
.arg(result.reason)
.arg(result.writes));
if (!ready) {
state->gate = u"fixture gate: phone privacy not ready"_q;
}
},
.timeout = kFixtureStageTimeout,
});
runner->addGated([=] { return state->gate; }, [&] {
runner->add({
.name = u"phone privacy fixture: nobody"_q,
.run = [=] { state->fixture->transition(NobodyState()); },
.until = [=] { return !state->fixture->busy(); },
.then = [=] {
const auto &result = state->fixture->result();
const auto applied
= (result.outcome == Test::FixtureOutcome::Equal)
|| (result.outcome == Test::FixtureOutcome::Written);
Test::Check(
applied,
u"fixture gate: phone privacy is nobody"_q,
u"reason=[%1] writes=%2 waits=%3"_q
.arg(result.reason)
.arg(result.writes)
.arg(result.waits));
if (!applied) {
state->gate = u"fixture gate: phone privacy not "
"applied"_q;
}
},
.timeout = kFixtureStageTimeout,
});
AppendPhoneHiddenChecks(runner); // Dependent: inherits the gate.
runner->addRecovery({
.name = u"phone privacy fixture: restore"_q,
.skipReason = [=] {
return state->fixture->result().pending
? QString()
: u"applies=0: no phone privacy obligation"_q;
},
.run = [=] { state->fixture->restore(); },
.until = [=] { return !state->fixture->busy(); },
.then = [=] {
const auto &result = state->fixture->result();
Test::Check(
!result.pending,
u"phone privacy fixture: the original restored"_q,
u"reason=[%1] writes=%2"_q
.arg(result.reason)
.arg(result.writes));
},
.timeout = kFixtureStageTimeout,
});
});
Test::AppendTestSessionRestore(runner, session);
}
The restoration is declared with addRecovery, so a refused transition never
skips it (gated groups);
its own skipReason is the policy: restore while the record is pending.
A campaign with several legs keeps one transaction per fixture: each further
transition() of the instance that owns the obligation keeps the first
original, and one restoration at the end, or between legs, puts it back.
Readings and refusals
result() is the one reading: operation, outcome, reason, this
operation's reads, writes and waits, and the record as it stands,
pending and notBefore (0 when no deadline was ever recorded). It is filled
at construction from the loaded record (operation None) and final once
busy() turns false. Equal and Written both mean a fresh read equalled
the target; every other outcome decides nothing about the fixture, and a
refusal is never a PASS.
| Outcome | Meaning and reasons |
|---|---|
Equal |
A fresh read taken before any further write equalled the target: no write was needed (a write refused earlier in the same operation still counts in writes). |
Written |
A write was sent and a fresh complete read after it equalled the target. |
Unresolved |
verify-unequal (the read after a write differs), rate-retry-exhausted (a second rate refusal in one operation), deadline-beyond-bound (the deadline is more than maxWait away), record-not-persisted (a deadline or a cleared obligation could not be written), released (release() during the operation), or the server's error type for any other failure, with no wait. The obligation stays as recorded. |
Refused |
No request was sent where it stopped: invalid-label, no-authorization, incomplete-arguments, malformed-record, foreign-record (the record names another target), released, pending-restoration (a transition while a record loaded from an earlier invocation is pending), no-obligation (a restore with no original this instance may write), record-not-persisted (the obligation could not be written, so the write was not sent), unauthorized: <authorize text>. |
A rate refusal is FLOOD_WAIT_<n> or FLOOD_PREMIUM_WAIT_<n> in
error.type(): the deadline becomes the refusal time plus n seconds (never
earlier than one already recorded), is persisted, and the operation waits for
it and retries once from a fresh read. FLOOD_WAIT_X, a n beyond INT_MAX
and every other error end the operation at once; nothing stays scheduled
after an Unresolved finish.
Rows go to the test log only, as NOTE: rows, never verdicts; they never
carry the state, the original, the target or the record path, and deadlines
are milliseconds from now:
FIXTURE_TRANSACTION: label=<l> op=<none|transition|restore> outcome=<none|equal|written|unresolved|refused> reason=[<r>] reads=<n> writes=<n> waits=<n> pending=<0|1> notBeforeInMs=<ms|none>
FIXTURE_TRANSACTION: label=<l> op=<op> rate=[<error type>] notBeforeInMs=<ms>
FIXTURE_TRANSACTION: label=<l> released busy=<0|1> pending=<0|1> notBeforeInMs=<ms|none>
The first is written at construction when the arguments or the record refuse
or a pending record was loaded, and once per finished operation; the second
on each rate refusal, after the deadline is recorded; the third by
release() when it stopped an operation or an obligation is pending.
Lifetime and cleanup
The record is cWorkingDir() + "test_fixture_obligations/<label>.json", in
the live portable copy: out/Debug/TelegramForcePortable/ normally,
<dir>/TelegramForcePortable/ under test-run --portable-root <dir>. That
copy is repository-ignored, is reused by every later launch on the same marked
copy (SETUP never deletes a marked copy), belongs to the account the fixture
belongs to, and already holds that account's private data. The run's
EvidenceDir() would be lost to the next run; a task's .local/ would let
another task on the same account capture the mutated state as its original;
work/ and evidence/ are tracked.
It is one compact JSON object written atomically through QSaveFile:
schema (test-fixture-obligation-1), label, target, pending,
notBeforeMs (epoch milliseconds, 0 for none) and, once captured,
original (base64 of the complete original state). Loading fails closed: a
wrong schema or label, a non-string target, a non-boolean pending, a
negative or non-numeric notBeforeMs, an original that is not valid base64,
or pending without an original is malformed-record; another target is
foreign-record. Both refuse every operation, and the instance never writes
that file.
The record is written at three points only: before each write (pending with
the original), on each rate refusal (the deadline), and when a restore's fresh
read equals the original (pending cleared). A no-op transition writes no
file, and an Equal transition leaves an obligation this instance owns
pending.
The obligation's lifecycle:
- A transition's first read becomes the original only while nothing is
pending, so a retry read after a refused or applied write never records
mutated state as the original. The record turns pending before the first
write is sent; an
authorizerefusal or a failed save before the write records nothing and sends nothing. - Further transitions of the instance that owns the obligation keep the first original and only move to the new requested state.
- A record left pending by an earlier launch is loaded at construction
(
result().pending,result().notBeforefrom the file) and must be restored first:transition()refusespending-restoration, andrestore()waits for the recorded deadline before its fresh read (or endsdeadline-beyond-boundat once when it is more thanmaxWaitaway). restore()clearspendingonly on a fresh read equal to the original, directly or after its write. Repeating it on the same instance is a fresh-read no-op (Equal, no write).- A resolved record keeps its original but authorizes no restore by a later
instance (
no-obligation, no request), so a stale original is never written over a newer account state.
Never delete or hand-edit a pending record: it holds the only copy of the
original, and the account stays mutated until it is restored. A malformed or
foreign record blocks its label until a person compares it with the account
and removes it. test-account-reset discards the live copy and the record
with it, so restore before resetting; a --portable-root sandbox has its own
live copy and record, so a campaign that mutates an account fixture keeps one
root until its record is resolved.
OpenFixtureTransaction registers a Runner::onFinish release holding the
transaction weakly, so every finish path - completion, skip-to-end, a stage
timeout, the watchdog - calls release(). It cancels the deadline timer,
makes every pending request answer and scheduled callback a no-op, turns a
running operation into Unresolved released, refuses later operations
(released) and never writes the record. Destroying the last
shared_ptr invalidates the continuations the same way. The release restores
nothing: restoration is an asynchronous stage, and an interrupted one stays
pending in the record for the next launch (teardown).
Verification
Test::AppendFixtureTransactionSelfTest(runner) drives the shipped
transaction through OpenFixtureTransaction with a fake local transport and,
except one leg, a fake wall clock. The fake server only stores state, stamps
requests and answers; only the caller's equality is self-test logic
(privacy-rule-shaped literal states: rule order meaningful, people order not,
a rule listing nobody differs from an absent rule). It needs no session,
network, account or fixture secret, writes its records under
EvidenceDir()/fixture-transaction-self-test/ (removed first, never the live
copy's folder), and every Check is expected to PASS. Its stages, each with
its own label:
- arm: the record folder is fresh, under the evidence directory and not the live folder;
- equality (
ft-equal): an equal read sends no write and writes no record; - necessary write (
ft-write,ft-partial): read-write-read, the record pending with the original when the write is sent, a second transition keeping the first original, its restore byte-equal; a partial write endsverify-unequalwith the obligation kept; - not-before deadline (
ft-rate,ft-rate-read): aFLOOD_WAIT_13write refusal records refusal + 13000, nothing is sent on an early timer or one millisecond before, the retry at the deadline reads first; a refused read waits the same way; - default wall-clock timer (
ft-real-clock): an emptyFixtureClockand aFLOOD_WAIT_1, the one asynchronous stage (about a second); - equal read at the deadline (
ft-rate-equal): no second write, pending cleared; - bounded refusal (
ft-exhausted,ft-zero,ft-bound,ft-error,ft-error-400): a second refusal,FLOOD_WAIT_0twice,FLOOD_WAIT_3600,FLOOD_WAIT_Xand a 400 error each end unresolved with the original and the latest deadline kept and nothing scheduled; - teardown (
ft-resume,ft-held,ft-destroyed): release while waiting, a held read answer delivered after release, a destroyed owner; - later invocation (
ft-resume): the deadline rewritten on disk is what a new instance reports and waits for; a transition refusespending-restoration; the restore is byte-equal; repeating it is a no-op; a third instance on the resolved record refusesno-obligation; - exact and unequal originals (
ft-ctl-*): reordered people restore asEqual; an absent rule, an extra person, swapped rules and a present empty rule over an absent one are written; - authorization and identity (
ft-auth,ft-auth-late,ft-malformed,bad/label): a refusing or withdrawnauthorizesends nothing more and records no obligation; a foreign or malformed record refuses every operation and stays byte for byte; an unsafe label refuses; - finish ownership (
ft-finish): a restore left waiting at the end, checked from anonFinishregistered after the transaction's own; - log secrecy: from the arm offset,
test_log.txtholds no person id, target, state text or base64 original (counts by kind only), while the same scan finds the target and the original in the record files, and no self-test label has a record in the live folder.
Each falsifier is a Check in the same run: a write on an equal read, a
request before a deadline, a third request after a second refusal, a write
after release, or a sentinel in the log turns that leg FAIL. Proposed, not
part of the self-test: proving a consumer's .handleFloodErrors() routing by
delivering Test::DeliverControlledRpcError(..., 420, "FLOOD_WAIT_<n>") to a
harmless request on a Test session.
Related guidance
Runner gated groups; teardown; session gate; account fixtures; failure diagnosis.