Repository navigation
Description
Part of #1562.
Scope
The provider works. After this PR a team installs @simlock/e2e, passes simlockDevices({...}) to the e2e runner, and each worker gets a device from the farm with the app installed: the provider waits on a full farm, retries a cut upload, swaps a device that cannot be set up, renews while the run lives and releases at the end. The website gains the "Run tests from CI" page.
If this goes wrong, a user notices a run that fails at device setup on a healthy farm, or devices that stay leased after a run ended.
Technical spec
Commit d8fadd1.
Rows
- Behaviours: B2, B3, B4, B5, B6, B7, B8, B9, B13
- Stored state: S2
- Interfaces: I2, I3 (uses I1, I4, I6, I7)
- Existing code: X15, X16, X17, X18, X19, X20, X21, X22, X23, X24
Facts
| # | Fact | Source |
|---|---|---|
| F1 | The slow-lane helpers make an agent token and load agent-device's client library from the pinned install. | e2e/helpers/agent-device.ts:101, e2e/helpers/agent-device.ts:197 |
| F2 | The slow lane installs the Appduct fixture app from target.app. |
e2e/slow-agent-device.test.ts:226 |
| F3 | A slow-lane file is run with scripts/slow-e2e.sh <file>. |
scripts/slow-e2e.sh:4 |
| F4 | The agent-device client's allocate sends its options and returns the lease normalised: leaseId, tenantId, runId, backend, and deviceKey, clientId when present. |
v0.21.36:packages/client/src/lease-client.ts lines 20-29 and 80-90 |
| F5 | The website sidebar lists Using devices pages one doc(...) line each. |
website/astro.config.mjs:98-104 |
| F6 | The token steps a CI page links to exist: simlock token create --role agent --label ci-runner-3. |
src/cli/commands/token.ts:14; shown to users at website/src/content/docs/docs/using-devices/remote-agents.mdx:27 |
| F7 | The agent-device page documents the 330 s wait and the error reasons the new page refers to. | website/src/content/docs/docs/using-devices/agent-device.mdx:131, website/src/content/docs/docs/using-devices/agent-device.mdx:212-224 |
Modules touched
Searches: rg -n "createProvider|simlockDevices" packages e2e, rg -n "using-devices/" website/astro.config.mjs.
packages/e2e/src/provider.tsand new files beside it for the queue, the install and the renewal, with their testse2e/slow-e2e-provider.test.ts(new),e2e/helpers/agent-device.ts(export the library loader for the provider)website/src/content/docs/docs/using-devices/ci.mdx(new),website/astro.config.mjs(sidebar), links fromusing-devices/remote-agents.mdxandusing-devices/agent-device.mdxpackages/e2e/README.md(link to the page).agents/scripts/docs-surface-check.mjs,.agents/scripts/surface-paths.mjsand their tests (src/docs-surface-check.test.ts)
Rules in play
- ADR 0077 §3: the provider imports nothing from
src/; the slow-lane test undere2e/imports the provider, the one allowed direction. - ADR 0070 §1, §2, §4: no
bootorclosehandling in the provider;retainOnClose: trueon every allocate; retry decisions readretriable, never message text. docs/internal/agent-rules/documentation.mdrule 9: the page ships in this PR with the provider.docs/internal/agent-rules/testing.md: fake timers for the queue and the renewal; no real sleep in the fast lane.docs/internal/agent-rules/toolchain.md(slow lane): B9 needs the "agent-device through simlock" machine checks with iOS.
Tests
The seam is createProvider(options, loadClient) with a fake client that records calls and answers from a script; model the fake on the injected client in rnw-community/mobile-ci packages/e2e-simlock/test/provider.test.ts, and the slow-lane test on e2e/slow-agent-device.test.ts.
- B2: the runner calls
acquire: iOS UDID fromdeviceKey; Android serial; optional fields sent only when set; platform mismatch throws; nodeviceKeyreleases and throws;agent-devicecannot be imported throws. - B3: the farm is full or cut the request: retriable error asks again under a new id after releasing the old; no answer does the same; not retriable throws at once; abort during a pause or an ask;
queueMsover during an ask; two instant retriable errors are 10 s apart; second ask succeeds. - B4:
acquireinstalls:appPathwithapp;appPathwithoutapp; noappPathbutextraApps; five slots withinstallConcurrency: 3never exceed three in flight. - B5: a cut install is sent again: cut then fine; three cuts. A cut is recognised the way B3 recognises "no answer from simlock": by the error's shape (no simlock
details.reasonon it), never by its message text, so an upload whose answer is not JSON is retried and a test where the client error says something else is still retried (decided in delivery, pending the maintainer). - B6: a failed install swaps once: fails on one, fine on two; fails on both; three cuts or a retriable farm error do not swap. An error with no simlock
details.reason(a sign-in error, or an upload simlock refused, whose reason the client drops) counts as a cut: sent three times, then thrown with no swap; the comments inpackages/e2e/src/errors.tsandinstall.tsname these cases (decided in delivery, pending the maintainer). - B7: the provider renews: 180000 gives 60 s; 30000 gives 10 s; a failure then success; ended by the farm; none after
release. - B8: the runner calls
release: held lease; failed release resolves and logs; unknown lease. - B9: on a Mac with an iOS runtime,
e2e/slow-e2e-provider.test.ts: acquire with the fixture app;close; lease still listed; release; lease gone. - B13: the docs page: the docs surface check fails for a change to
packages/e2e/src/index.tswith no website change (a case in the check's own test).
Done when
pnpm checkpasses.- On a Mac with an iOS runtime:
scripts/slow-e2e.sh e2e/slow-e2e-provider.test.tspasses. pnpm --dir website buildpasses and the built site hasdocs/using-devices/ci/.- The page lists every option of I1 with its default;
grep -c "installConcurrency\|queueMs\|ttlMs\|deviceBaseline\|deviceMode\|imageTag\|osVersion\|extraApps" website/src/content/docs/docs/using-devices/ci.mdxprints at least 8.
Out of scope
- Release-by-run and a lease-id file (CI runs: device settings in the lease request, and release every lease of a run #1294).
- A relay, test-step helpers, exec and file helpers, recording.
- Any change to the product's code under
src/; the one file touched there is the check's test,src/docs-surface-check.test.ts.
Depends on
Written by an agent.
Activity
test: acquire sends the optional fields only when set, refuses a plat…
feat(e2e): acquire sends the set options, refuses a mismatch, a namel…
test: a full or cutting farm makes acquire wait and ask again until q…
feat(e2e): acquire installs the app and extra apps, at most installCo…
test: a cut install is sent again to the same device, at most three t…
feat(e2e): a cut install is sent again, at most three tries (#1567)
test: a failed install swaps the device once; a cut install or a retr…
feat(e2e): a device whose install failed is released and swapped once (…
test: the provider renews a held lease every third of ttlMs until it …
feat(e2e): a held lease is renewed every third of ttlMs and released …
10 remaining items
test(e2e): the swap's deadline and the install probes fail on a named…
test(e2e): the abort test fails on a named assertion when a queued in…
docs(e2e): the missing-reason comments name the sign-in and refused-u…
V3RON commentedon Nov 15, 2026
Handoff
Done: #1572 is built, audited, and passed review: round 1, round 2 and a final fix-check, with all six blocking findings fixed. The PR is ready and tops the feature stack, #1565 → #1568 → #1572. Three decisions are pending the maintainer: #1565's half-published-release recovery, #1568's text-pinned workflow tests, and #1572's no-reason-means-cut rule, each in a
## Decision takencomment.Not done: Done when line 2,
scripts/slow-e2e.sh e2e/slow-e2e-provider.test.ts, and the matching #1562 completion condition. The audit could not probe that test, and the probe needs a slow-lane run: makereleaseinpackages/e2e/src/provider.tsreturn early, then check that the finallistLeasesassertion fails.Findings: none open. One review note is posted on #1572.
Blocked on: a Mac with an iOS runtime and
SIMLOCK_E2E_AGENT_DEVICEset, or.slow-lane.env. Run the test there, or re-rundeliver 1562on that machine. The stack then merges withmerge-pr.sh 1572after ADR 0077 flips to Accepted.Written by an agent.
test(e2e): the slow provider test drives the lease through the client…
test(e2e): the slow provider test reads the lease's optional daemon (#…
docs(adr): 0077 is Accepted (#1567)
feat(e2e): the device provider leases, installs, renews and releases,…