Repository navigation
Description
Request: #1298
Problem
A team that runs the e2e runner (@e2e-dev/mobile) against a simlock farm needs a device provider: the piece of code the runner asks for one device per test worker. simlock ships none. budgie wrote about 650 lines of its own (budgie-at/budgie#1867); that code now lives in one user's CI toolkit (rnw-community/mobile-ci, packages/e2e-simlock), is not on npm, and is installed with a curl script pinned to that toolkit's tags. simlock has no say over it, and it still carries workarounds for things simlock has since fixed (a local relay for boot and close).
There is also no docs page on running a test suite from a Linux CI runner against a farm. using-devices/remote-agents.mdx lists the raw HTTP calls and using-devices/agent-device.mdx the agent-device address; neither says how to set up secrets, workers, retries and cleanup for a CI job.
Who it is for
A team moving an iOS or Android e2e suite onto a simlock farm, running the tests from a cheap Linux CI runner with a farm URL and an agent token.
Outcome
npm install @simlock/e2e, three lines ine2e.config.ts, and each test worker gets its own device from the farm with the app installed. No relay, no helper scripts, no copied provider code.- A run that ends, fails or is interrupted gives its devices back at once. A run that is killed gives them back within one lease time (3 minutes by default) with no cleanup step.
- A full farm makes the run wait, up to 20 minutes by default, instead of failing.
- One docs page takes a team from "we have a farm" to a green CI run from Linux.
- The provider always has the same version number as the simlock release it was built and tested with.
How it works for the user
flowchart TD
A[CI job on Linux starts the e2e runner] --> B[Runner asks the provider for one device per worker]
B --> C{Farm has a free device?}
C -->|no| D[Provider waits and asks again, up to queueMs]
D --> C
D -->|queueMs over| X[Run fails: no free device]
C -->|yes| E[Provider uploads and installs the app, then extra apps]
E -->|install fails| F[Provider gives the device back and leases one other, once]
F -->|fails again| Y[Run fails: device setup]
E --> G[Tests run; the provider renews each lease]
F --> G
G --> H[Run ends: provider releases every lease]
G -->|job killed| I[Leases run out within ttlMs; the farm takes the devices back]
Before, in the e2e project (from mobile-ci's README):
curl -fsSLO https://raw.githubusercontent.com/rnw-community/mobile-ci/v4.13.2/scripts/fetch-e2e-simlock.sh
bash fetch-e2e-simlock.sh v4.13.2 e2e # again after every npm ciAfter:
npm install --save-dev @simlock/e2e// e2e.config.ts
import { mobile } from "@e2e-dev/mobile";
import { simlockDevices } from "@simlock/e2e";
export default {
targets: [
{
name: "ios",
engine: mobile({
platform: "ios",
device: simlockDevices({
url: process.env.SIMLOCK_URL!,
token: process.env.SIMLOCK_TOKEN!,
platform: "ios",
device: "iPhone 17 Pro",
}),
}),
app: { bundleId: "com.example.app", appPath: "build/Example.app" },
},
],
workers: 4,
};What the run prints through the runner's log, one line each:
simlock: lease 4f0c… granted in 8421 ms (iPhone 17 Pro 6B1E…)
simlock: installed com.example.app in 31877 ms
simlock: no free ios device on the farm; waiting for one
simlock: install on 6B1E… failed (<message>); leasing another device
simlock: lease 4f0c… was ended by the farm; failures on its device are infrastructure, not tests
Errors a user sees (the run fails with them):
simlockDevices: url must be an http(s) URL of the simlock gateway or worker; got "simlock.example.com"
simlock: no free ios device on the farm within 20 min
simlock: could not set up a device after 2 tries: <message>
Examples
simlockDevices(options) at config load. There is no "today": the function is new.
| Input | After |
|---|---|
url: "https://farm.example.com" |
accepted |
url: "https://farm.example.com/" |
accepted, the trailing slash is dropped |
url: "farm.example.com" |
throws simlockDevices: url must be an http(s) URL of the simlock gateway or worker; got "farm.example.com" |
url: "https://farm.example.com/v1" |
throws simlockDevices: url must not end in /v1; got "https://farm.example.com/v1" |
token: "" or missing |
throws simlockDevices: token is required (a simlock agent token) |
platform: "tvos" |
throws simlockDevices: platform must be "ios" or "android"; got "tvos" |
device missing |
throws simlockDevices: device is required (a model the farm lists) |
deviceMode: "fast" |
throws simlockDevices: deviceMode must be "slim" or "full"; got "fast" |
ttlMs: 0, ttlMs: NaN, ttlMs: 29999 |
throws simlockDevices: ttlMs must be a number of at least 30000; got <value> |
ttlMs: 30000 |
accepted; the lease is renewed every 10 s |
queueMs: -1 |
throws simlockDevices: queueMs must be a positive number; got -1 |
installConcurrency: 0 or 1.5 |
throws simlockDevices: installConcurrency must be a whole number of at least 1; got <value> |
extraApps: "a.app" (not a list) |
throws simlockDevices: extraApps must be a list of paths |
an option the provider does not know, e.g. tenant: "x" |
throws simlockDevices: unknown option "tenant" |
What could go wrong
- A team's CI sits behind a proxy that cuts long requests (Cloudflare cuts at 100 s). App uploads larger than that window fail three times and the run fails. Likely for big apps on slow links; the docs page names the limit.
- The runner is at version 0.x and may change its provider interface. A new runner version could refuse the provider until simlock releases a fix. Possible a few times a year.
- A run can fail up to a few seconds after
queueMs, never minutes: the ask in flight is cut when the time is over. - A release publishes one package and fails on the other. The two versions on npm then differ until the release is run again. Unlikely; the release checks both before it publishes either.
- A killed job holds its devices for up to 3 minutes. Other jobs wait that long on a full farm. Expected, and documented.
Words used
- device provider: the object the
e2erunner asks for devices; it hasacquire(get one device for one worker) andrelease. Example:simlockDevices({...}). - worker slot: one of the runner's parallel test workers;
workers: 4means four slots and four devices. - lease: simlock's grant of one device to one holder until a deadline. Example: lease
4f0c…on an iPhone 17 Pro for 3 minutes. - renew (heartbeat): a call that moves a lease's deadline forward. The provider sends one every third of
ttlMs. - agent-device address:
<url>/v1/agent-device, where simlock serves the agent-device tool's own calls; the runner drives devices through it. - agent token: a simlock token of role
agent, made withsimlock token create --role agent. - workspace: one repository that builds several npm packages. Here:
simlockat the root and@simlock/e2eunderpackages/e2e. - device mode:
slim(default, system services cut down) orfull. Example: Apple Pay flows needdeviceMode: "full". - baseline: a prepared device state an operator saved on the farm, named in a lease request to start from it.
Non-goals
- No relay, no test-step helpers, no file or exec helpers, no screenshot or animation options: only leasing, installing, renewing and releasing.
- No release-by-run and no lease-id file. A killed run's devices come back when their leases run out. Release-by-run stays request CI runs: device settings in the lease request, and release every lease of a run #1294.
- No change to the farm: no new HTTP route, operation, config key or protocol change.
- No move of
simlockitself out of the repository root, and no split of the contract or client into packages. - No recording through the provider: the runner records with agent-device.
- No provider for any other runner (Maestro, Detox). The docs page names the raw calls for them.
- mobile-ci's provider is not changed or replaced by us; its owner may switch to this one.
Completion conditions
- A config that passes
simlockDevices(...)to@e2e-dev/mobile'smobile({ device })type-checks inpnpm typecheck. - On a Mac with an iOS runtime: the provider acquires a simulator from a real simlock worker with a real app installed, a close of the session keeps the device, and a release returns it.
- A release dry run builds two tarballs with the same version, and refuses when either version is on npm already or
@simlock/e2eis not on npm at all. pnpm checkruns the provider's type-check, lint, format check and unit tests.- The website has a "Run tests from CI" page under Using devices, and it lists every provider option.
Open questions
Decisions
- ADR 0077 (PR docs(adr): propose 0077, the repository is a workspace and its packages release together (#1562) #1565) — The repository is a workspace and its packages release together under one version: fixes where
@simlock/e2elives, how it is built and checked, and that every release publishes both packages with one version and one tag. - ADR 0070 — Test runners drive a lease through the agent-device front: the provider relies on
bootbeing answered by simlock, onretainOnClose, and on the error reasons and the retriable flag. - ADR 0023 — agent-device is served by an optional edge module: the provider needs a farm where it is on; no change.
- Decided in the session: the provider is its own npm package
@simlock/e2e, not an entry ofsimlock, because a CI job should not install the daemon to get a small provider (maintainer). - Decided in the session:
simlockstays at the repository root and the provider goes underpackages/e2e, because movingsrc/touches every script, hook and doc (maintainer). - Decided in the session: one version for all packages, because the version then says which farm the provider matches (maintainer).
- Decided in the session: a short lease is the only cleanup for a killed run, because it needs nothing new on the farm (maintainer).
- Decided in the session: the provider covers iOS and Android, because both use the same four calls.
- Decided in the session: the docs page is a general "Run tests from CI" page with the
e2erunner as the worked example, because Maestro and raw-HTTP users need the same secrets, cleanup and limits. - Decided in the session: the provider talks to the agent-device address with the user's own
agent-deviceclient (a peer dependency), not to simlock's/v1lease routes, because the runner's workers must use that address anyway and an app install is only accepted there as an upload. - Decided in the session: defaults
ttlMs180000,queueMs1200000,installConcurrency3, taken from mobile-ci's provider, because they are proven on a real farm. - Decided in the session: an unknown option throws, because a typo such as
devciewould otherwise lease the wrong thing silently. - Decided in the session: a failed
releaselogs and resolves, because the runner's cleanup must go on and the lease runs out by itself. - Decided in the session: the package ships compiled JavaScript with type declarations (not TypeScript source as mobile-ci's does), because that is what npm users expect and it needs no loader.
- Decided in the session:
packages/is covered by type-check, lint, format, fallow and unit tests, and left out of mutation testing and the module-manual hook for now, because those two are tuned tosrc/. - Decided in the session: the provider's user docs live on the website; the package README is three lines and a link, because end-user docs live only on the website.
- Decided in the session: before the first release the maintainer creates the
simlockorganisation on npm, publishes a 0.0.0 placeholder of@simlock/e2eby hand and adds its trusted publisher; the release refuses to start until the package exists, and publishes@simlock/e2ebeforesimlock, so a failure there leavessimlockuntouched (maintainer). - Decided in the session: the smallest
ttlMsis 30000, because a shorter lease would run out before its first renewal (maintainer). - Decided in the session: the type check of B12 runs inside
pnpm typecheckwith the runner's types as dev dependencies, not in a temp project installed from npm, because the fast lane must not need the network.
Behaviours
| Id | Behaviour (invoker, action, what it sees) | Seam | Cases | Task |
|---|---|---|---|---|
| B1 | A user calls simlockDevices(options) in the config; a bad option throws at once with the option's name, a good one returns a provider named simlock. |
packages/e2e/src/index.ts simlockDevices |
every row of Examples; defaults applied when ttlMs, queueMs, installConcurrency, extraApps are left out |
#1566 |
| B2 | The runner calls acquire; the provider asks the farm for one lease (I2) and returns a lease the worker can drive (I3). It logs simlock: lease <id> granted in <n> ms (<model> <device id>). |
createProvider(options, loadClient).acquire (I7) with a fake client |
iOS: device id is the UDID from deviceKey; Android: the serial; osVersion, imageTag, deviceMode, deviceBaseline sent only when set; request platform differs from the option: throws simlockDevices leases <platform> devices; the target asked for <other>; the reply has no deviceKey: the lease is released and acquire throws simlock: lease <id> names no device; agent-device cannot be imported: throws simlock: the agent-device package is not installed; add it to your project |
#1567 |
| B3 | The farm is full or cut the request; acquire waits 10 s plus up to 5 s at random, then asks again, until queueMs is over; it then throws simlock: no free <platform> device on the farm within <n> min. It logs simlock: no free <platform> device on the farm; waiting for one once. |
same | error with retriable: true (reasons NO_DEVICE_IN_TIME, SIMLOCK_UNAVAILABLE, WORKER_UNREACHABLE): asks again under a new lease id after releasing the old id; no answer from simlock (dropped connection, an answer that is not JSON): the same; retriable: false or no flag (REFUSED_BY_SIMLOCK, UNAUTHORIZED): throws at once; the runner's signal aborts during a pause or an ask: throws the abort reason, and the id asked with is released; queueMs runs out during an ask: that ask is aborted, its id released, and the error thrown; two retriable errors in a row answered at once: the second ask starts no sooner than 10 s after the first; second ask succeeds: one lease returned. retriable and reason are read from the thrown error's details (X24) |
#1567 |
| B4 | With an appPath in the request, acquire installs the app on the leased device, then each of extraApps in order, and reports installedApp when the request names app. It logs simlock: installed <app or path> in <n> ms. |
same | appPath and app: install, installedApp set; appPath without app: install, no installedApp; no appPath: no install, extraApps still installed; five slots acquiring at once with installConcurrency: 3: never more than three installs in flight |
#1567 |
| B5 | An install that got no answer from simlock, or a retriable error, is sent again to the same device: at most three tries. | same | first try cut, second succeeds: one device, two installs; three cuts: goes to B6 as a farm failure | #1567 |
| B6 | An install that fails otherwise makes acquire release that device and lease one other, once. It logs simlock: install on <device id> failed (<message>); leasing another device. A second failure throws simlock: could not set up a device after 2 tries: <message>. |
same | install refused on device one, fine on device two: lease two returned, lease one released; fails on both: throws, both released; three cuts in B5 or a retriable farm error: no swap, throws the error, lease released | #1567 |
| B7 | While a lease is held the provider renews it every third of ttlMs. A failed renewal logs simlock: renewing lease <id> failed: <message>; a renewal answered LEASE_ENDED_BY_HOST logs simlock: lease <id> was ended by the farm; failures on its device are infrastructure, not tests and stops renewing. |
same, fake timers | ttlMs: 180000: renew every 60 s; ttlMs: 30000: every 10 s; one failure then success: keeps renewing; ended by the farm: one line, no further calls; after release: no further calls |
#1567 |
| B8 | The runner calls release for a lease; the provider stops renewing and releases it at the farm. A failed release logs simlock: releasing lease <id> failed: <message>; it runs out by itself and resolves. |
simlockDevices(...).release |
held lease: one release call; release fails: resolves, line logged; a lease this provider does not hold: resolves, no call | #1567 |
| B9 | On a Mac with an iOS runtime: the provider, made with createProvider (I7) and the agent-device client library of the pinned install (X20), acquires a simulator from a real worker with a real app installed; a close of the session keeps the lease; release ends it. |
e2e/slow-e2e-provider.test.ts (slow lane) |
acquire with an .app and no deviceMode or deviceBaseline (the pinned client is older than the one that sends them); close; the lease is still listed; release; the lease is gone |
#1567 |
| B10 | A contributor runs the repository's checks; the provider's files are type-checked, linted, format-checked, scanned for unused code and unit-tested with the rest. | pnpm typecheck, pnpm lint, pnpm format:check, pnpm fallow, pnpm test:unit; the CI change filter |
a type error under packages/e2e/src fails pnpm typecheck; a test under packages/e2e/src runs in pnpm test:unit; an import from packages/e2e into src/ (or back) fails pnpm lint; a change only under packages/ runs CI's lint and unit jobs |
#1566 |
| B11 | The maintainer runs a release; both packages get the same version, both tarballs are built and checked before anything is published, and both are published. | scripts/release.mjs bump; src/release-pack.test.ts; .github/workflows/release.yml |
bump 0.8.0: root and packages/e2e manifests both say 0.8.0; pack: simlock-0.8.0.tgz and simlock-e2e-0.8.0.tgz, the second holding package/dist/index.js and package/dist/index.d.ts and no test file; @simlock/e2e@0.8.0 on npm already: the plan fails with @simlock/e2e@0.8.0 is on npm already before any tag; @simlock/e2e not on npm at all: the plan fails with @simlock/e2e is not on npm yet: create the simlock organisation, publish a 0.0.0 placeholder by hand and add its trusted publisher, then run the release again before any tag; the release commit holds both manifests at the new version; the GitHub release carries both tarballs and SHA256SUMS.txt |
#1566 |
| B12 | A config that passes simlockDevices(...) as the device of mobile({...}) type-checks against the runner's own types. |
pnpm typecheck over packages/e2e/src/config.sample.ts (left out of the build) |
config with all options; config with only the four required ones | #1566 |
| B13 | A reader opens "Run tests from CI" on the website and finds: making an agent token and storing it as a CI secret, the provider's install and config, every option with its default, workers and how the farm's size limits them, what happens on a full farm, what happens to a killed job, the proxy time limit on uploads, and the raw calls for other runners. | website/src/content/docs/docs/using-devices/ci.mdx; the docs surface check |
a change to packages/e2e/src/index.ts without a change to the page fails the docs surface check |
#1567 |
Stored state
| Id | What and where | Created, changed, deleted by | Listed or swept by | A restart mid-step leaves | Schema step | Task | Used by |
|---|---|---|---|---|---|---|---|
| S1 | version in packages/e2e/package.json, always equal to the root package.json version |
written by scripts/release.mjs bump (B11) in the release commit, with the root one |
src/release-script.test.ts checks the two are equal on every test run |
a bump that wrote one file and died leaves two versions; the test fails and the release workflow re-runs from a clean checkout | none | #1566 | #1567 |
| S2 | Leases held by a run: in the provider's memory only (lease id, renewal timer) | added by acquire (B2), removed by release (B8) or a failed setup (B6) |
the farm lists them (simlock leases); nothing on the CI machine |
a killed run leaves farm leases that run out within ttlMs |
none | #1567 | — |
Interfaces
| Id | What | Shape and bounds | Errors and limits | Where | Task | Used by |
|---|---|---|---|---|---|---|
| I1 | simlockDevices(options): DeviceProvider, the package's one export besides the SimlockDevicesOptions type |
url string, required, http:// or https://, no /v1 suffix; token string, required, non-empty; platform "ios" or "android", required; device string, required, non-empty; osVersion string, optional; imageTag string, optional; deviceMode "slim" or "full", optional; deviceBaseline string, optional; extraApps list of strings, optional, default empty; ttlMs number ≥ 30000, optional, default 180000; queueMs number > 0, optional, default 1200000; installConcurrency whole number ≥ 1, optional, default 3. Returns { name: "simlock", acquire, release }; no record. |
the messages of Examples, word for word; every later failure is a case of B2 to B8 | packages/e2e/src/index.ts |
#1566 | #1567 |
| I2 | Calls the provider sends to <url>/v1/agent-device through createAgentDeviceClient({ daemonBaseUrl, daemonAuthToken, session }) |
allocate: leaseId 32 hex characters, new per ask; tenant "simlock-e2e" (the client wants one; simlock overwrites it); runId the request's; leaseBackend "ios-instance" or "android-instance"; leaseProvider "proxy"; platform; target "mobile"; device; ttlMs; retainOnClose: true; and each of osVersion, imageTag, deviceMode, deviceBaseline when set. heartbeat: the lease's scope and ttlMs. release: the lease's scope. install: sent through a second client made with the lease's scope as well (tenant, runId, leaseId, leaseBackend, leaseProvider, clientId, deviceKey), so the upload and the install name the lease; its fields are platform, udid or serial (the leased one), appPath, and app when known. Session name e2e-<first 12 of runId>-<slot>, with -r1 on the second device of B6. |
simlock holds an allocate open up to 330 s, then answers NO_DEVICE_IN_TIME, retriable; its own errors carry a reason and retriable; an install not sent as an upload is refused with refused: send the app from your machine as an upload (the client uploads a local appPath itself) |
packages/e2e/src/ |
#1567 | — |
| I3 | The DeviceLease returned to the runner |
id the lease id; daemon { baseUrl: "<url>/v1/agent-device", authToken: <token> }; client { tenant, runId, leaseId, leaseBackend, leaseProvider, clientId, deviceKey } taken from the returned lease (its tenantId as tenant, its backend as leaseBackend; clientId the returned one, else the one sent); deviceId the last :-separated part of deviceKey; installedApp only per B4 |
the runner refuses session, daemonBaseUrl and daemonAuthToken inside client, and an installedApp for a request without appPath |
packages/e2e/src/ |
#1567 | — |
| I4 | Package manifest of @simlock/e2e |
name @simlock/e2e; type module; exports . → dist/index.js with types; files dist without tests, README.md; peerDependencies @e2e-dev/mobile >=0.12.5 <1 and agent-device >=0.21.37 (the first whose client sends deviceMode and deviceBaseline); no dependencies; devDependencies @e2e-dev/mobile 0.12.7, its peer e2e, and agent-device 0.21.37, for types only, installed by the root pnpm install; publishConfig.access public; engines.node as the root |
— | packages/e2e/package.json |
#1566 | #1567 |
| I5 | scripts/release.mjs bump <version> and the release workflow's pack, check and publish steps |
bump writes version into the root manifest and into every packages/*/package.json. The tag step commits both manifests with CHANGELOG.md. Pack makes one tarball per package into the same folder; SHA256SUMS.txt lists both, and the GitHub release attaches both. Publish runs npm publish once per tarball, @simlock/e2e first, each with --provenance --access public --tag <dist tag>. |
plan fails with <name>@<version> is on npm already for either package, and with the is not on npm yet message of B11 when @simlock/e2e has no version on npm; the publish job fails with the tarball is <name>@<packed>, not <version> for either |
scripts/release.mjs, .github/workflows/release.yml |
#1566 | — |
| I6 | Workspace wiring | pnpm-workspace.yaml gains packages: ["packages/*"] (the root package stays the workspace root). packages/e2e has tsconfig.json (everything under src, for checks) and tsconfig.build.json (to dist/, tests excluded), as the root has, and a build script. In turbo.json every root task is renamed with the root prefix (//#build:daemon:run and the others; their inputs stay root-relative) and @simlock/e2e#build is added; the root scripts that call turbo name the new ids, and pnpm build runs all of them. The vitest unit project includes packages/*/src/**/*.test.ts. pnpm typecheck also runs tsc -p packages/e2e. pnpm lint passes packages to oxlint and dependency-cruiser, with one rule: nothing under packages/ imports from src/, ui/ or e2e/, and nothing there imports from packages/, except e2e/ test files importing packages/e2e. |
— | repository root | #1566 | #1567 |
| I7 | createProvider(options, loadClient), internal: what simlockDevices calls with a loader that imports agent-device from the user's project |
loadClient: () => Promise<createAgentDeviceClient>; same options and result as I1. Not exported from index.ts; tests and e2e/ import it from packages/e2e/src/provider.ts |
agent-device missing in the user's project: acquire throws simlock: the agent-device package is not installed; add it to your project |
packages/e2e/src/provider.ts |
#1566 | #1567 |
Existing code
Commit d8fadd1.
Searches: rg -n "simlock-\\$VERSION|registry.npmjs.org/simlock" .github (5 hits, all release.yml); rg -n "package.json" scripts/release.mjs (4 hits); rg -n "include" vitest.config.ts (4 hits); rg -ln "\"src\"|src/" lefthook.yml .dependency-cruiser.mjs .fallowrc.json .oxfmtrc tsconfig*.json turbo.json (6 files); rg -n "QUEUE_WAIT_MS" src/agent-device (3 hits); rg -n "retainOnClose" e2e src/agent-device (read e2e/helpers/agent-device.ts); rg -n "simlock@" src/updater src/daemon (3 hits); gh pr list --search "workspace OR packages" (no open PR).
| Id | Code (path:line) | Today | With this feature | Handled by |
|---|---|---|---|---|
| X1 | pnpm-workspace.yaml |
no packages: key; the root is the only package |
gains packages/* |
I6 |
| X2 | website/pnpm-workspace.yaml |
website/ is its own pnpm root with its own lockfile |
unchanged; packages/* does not match it |
I6 |
| X3 | tsconfig.json:12-15 |
rootDir src, include src/**/*.ts |
unchanged; the package has its own tsconfig | I6 |
| X4 | vitest.config.ts:20 |
the unit project includes src/**/*.test.ts and ui/**/*.test.{ts,tsx} |
also packages/*/src/**/*.test.ts |
I6, B10 |
| X5 | package.json:66 |
oxlint src e2e ui && depcruise src e2e ui --ignore-known |
both also take packages |
I6, B10 |
| X6 | .dependency-cruiser.mjs (every rule path starts ^src/, ^ui/src/ or ^(src|dist|e2e|ui)/) |
packages/ is under no rule |
one new rule keeps packages/ and the root code apart |
I6, B10 |
| X7 | .fallowrc.json:25 |
ignorePatterns holds website/** only |
packages/e2e/src/index.ts and packages/e2e/src/config.sample.ts are named as entries, and the type-only dev dependencies of packages/e2e that nothing imports are listed as ignored, so the scan reports nothing for the package |
B10 |
| X8 | .github/workflows/ci.yml:176-178 |
the change filter for the console job lists src/, ui/ and config files |
unchanged for the console job; lint and unit jobs already run on every change | B10 |
| X9 | scripts/release.mjs:83-88 |
bump writes the version into package.json in the current directory |
also into every packages/*/package.json |
I5, S1 |
| X10 | .github/workflows/release.yml:124-127 |
checks registry.npmjs.org/simlock for the version |
checks both package names, and that @simlock/e2e exists on npm |
I5, B11 |
| X11 | .github/workflows/release.yml:169-184 |
one pnpm pack, one tarball, four files checked in it |
a second pack in packages/e2e and its own file check |
I5, B11 |
| X12 | .github/workflows/release.yml:286-303 |
checks the one tarball's version, one npm publish |
checks both, then publishes @simlock/e2e, then simlock |
I5, B11 |
| X13 | src/release-pack.test.ts:44-64 |
packs a fake simlock manifest and expects simlock-<version>.tgz |
also packs packages/e2e and reads its file list |
B11 |
| X14 | src/updater/index.ts:100, src/daemon/update-coordinator.ts:160 |
the self-updater installs and views simlock@<version> |
unchanged: @simlock/e2e is never installed on a farm machine |
— |
| X15 | .agents/scripts/docs-surface-check.mjs:51-62, .agents/scripts/surface-paths.mjs:6-14 |
the surface files are all under src/ |
packages/e2e/src/index.ts is a surface named e2e-provider; a change to it needs a website change |
B13 |
| X16 | src/agent-device/front/allocate.ts:37, :267 |
an allocate waits up to 330 s for a device, then answers 504 timed out waiting for a device; nothing was leased |
unchanged; the provider asks again | B3 |
| X17 | src/agent-device/shared/replies.ts:19-68 |
simlock's own errors carry one of six reasons | unchanged; the provider reads retriable |
B3, B5, B7 |
| X18 | src/agent-device/front/request-rules.ts:29, :292 |
an install is accepted only as an upload | unchanged; agent-device's client uploads a local path | B4 |
| X19 | src/agent-device/AGENTS.md (Front) |
boot is answered by simlock; a lease allocated with retainOnClose survives a close; the caller's tenant is overwritten |
unchanged; this is why the provider needs no relay | B2, B9 |
| X20 | e2e/helpers/agent-device.ts:181-212 |
leaseClient loads agent-device's client library from the pinned install and allocates with retainOnClose |
the slow-lane test of B9 loads the same library and hands it to the provider | B9 |
| X21 | callstack/agent-device v0.21.36:packages/contracts/src/client-lease.ts lines 73-94 |
LeaseAllocateOptions requires tenant and runId, takes leaseId (16-128 hex), retainOnClose; Lease carries deviceKey |
the provider sends these (I2) | I2 |
| X22 | @e2e-dev/mobile@0.12.7 dist/provider.d.ts |
DeviceProvider is name, acquire(DeviceRequest), release(lease, context), optional record; acquire is called once per slot, all at once; a rejected acquire fails the run |
the provider implements it (I1, I3) | I1, I3 |
| X24 | callstack/agent-device v0.21.37:packages/daemon-client/src/daemon-client-rpc.ts lines 108-150 |
the client throws an AppError whose details hold the daemon's details (so details.reason) and retriable |
the provider reads both there | B3, B5, B7 |
| X25 | turbo.json:6-53 |
four tasks named without a package prefix; they run in the one package | renamed to root tasks, since the repository now has two packages | I6 |
| X26 | .github/workflows/release.yml:229-235 |
the tag step runs bump, then commits package.json and CHANGELOG.md |
also commits packages/e2e/package.json |
I5, S1 |
| X27 | .github/workflows/release.yml:329-331 |
the GitHub release attaches simlock-<version>.tgz and SHA256SUMS.txt |
attaches both tarballs | I5 |
| X23 | rnw-community/mobile-ci packages/e2e-simlock/src/provider.ts (main, 2026-11-15) |
the outside provider: same calls, plus a relay, a status poll and a lease-id file | not changed; the source of the defaults | — |
Tasks
flowchart LR
A[ADR 0077, PR #1565] --> B[#1566 workspace, package, release]
B --> C[#1567 provider and docs page]
- The repository builds, checks and releases a second package, @simlock/e2e, with option checking #1566 The repository builds, checks and releases a second package, @simlock/e2e, with option checking — a config that calls
simlockDevicestype-checks and a bad option fails with its name; a release publishes both packages under one version.
Risk:pnpm buildor a release breaks for everyone. - The e2e device provider leases, installs, renews and releases, with a Run tests from CI page #1567 The e2e device provider leases, installs, renews and releases, with a Run tests from CI page — a team runs its e2e suite from Linux CI on farm devices with three lines of config.
Risk: runs fail at device setup on a healthy farm, or devices stay leased after a run.
Completion conditions:
- A config that passes
simlockDevices(...)type-checks: The repository builds, checks and releases a second package, @simlock/e2e, with option checking #1566. - The provider acquires, keeps through a close and releases a real simulator: The e2e device provider leases, installs, renews and releases, with a Run tests from CI page #1567 (slow lane,
e2e/slow-e2e-provider.test.ts). - A release dry run builds two tarballs and refuses a taken or missing package: The repository builds, checks and releases a second package, @simlock/e2e, with option checking #1566.
pnpm checkcovers the provider: The repository builds, checks and releases a second package, @simlock/e2e, with option checking #1566.- The "Run tests from CI" page lists every option: The e2e device provider leases, installs, renews and releases, with a Run tests from CI page #1567.
Open work in the same area:
- CI runs: device settings in the lease request, and release every lease of a run #1294 (request, release every lease of a run): would let the provider free a killed run's devices at once. No dependency; a non-goal here.
- The fleet serves only agent-device users: CLI agents, CI runners and operators each hit a gap #945 (request, remote CLI and upload-once): shares the "CI runner" audience. No dependency.
- feat(backends): register local backend modules #1497, feat(backends): persist device backend ownership #1499, feat(backends): preserve saved baseline ownership #1500 (backends, ADR 0072) and docs(adr): 0076 an iOS clone names only its own folders before its first boot #1564 (ADR 0076): edit
docs/internal/adr/README.md's table, as PR docs(adr): propose 0077, the repository is a workspace and its packages release together (#1562) #1565 does, in different rows. No dependency. - fix(ios): the simctl commands of a simulator's lifecycle wait ios.simulator.lifecycleTimeoutMs, and a create or clone that answers late is deleted (#1546) #1547 (simctl lifecycle timeouts): no shared file.
Written by an agent.
Activity
V3RON commentedon Nov 15, 2026
Design posted: every business section, Decisions (ADR 0077 proposed), Behaviours B1 to B13, Stored state S1 and S2, Interfaces I1 to I6, Existing code X1 to X23.
Written by an agent.
docs(adr): 0077 publishes packages first and needs each on npm (#1562)
docs(adr): accept 0077, not yet implemented (#1562)
V3RON commentedon Nov 15, 2026
Spec updated: design fixed after the check (I2 install scope, I5 release order and npm check, I6 turbo root tasks, I7 added, B3 pause, smallest
ttlMs30000), ADR 0077 accepted, Tasks filled with #1566 and #1567.Written by an agent.
docs(adr): 0077 recovers a half-published release by re-running the p…
V3RON commentedon Nov 15, 2026
Delivery run
Merged: none (the stack #1565 → #1568 → #1572 is open, every PR has passed review and is ready)
Parked: #1567 — needs-hardware: the slow-lane provider test cannot run here, as no agent-device is configured
Waiting: #1566 — on the stack merge, which waits on #1567
Decided: #1565 — how a half-published release recovers → re-run the failed publish job, which skips versions already on npm; #1566 — text-only workflow tests → kept, each pinned to its step's whole condition; #1567 — how a cut upload is recognised → no simlock
details.reason, never message text; #1567 — sign-in errors and refused uploads with no reason → count as cuts: three tries, no swapWritten by an agent.
V3RON commentedon Nov 15, 2026
Delivery run
Merged: none. The gate refused the stack #1565 → #1568 → #1572 on a CodeQL alert in #1568.
Parked: #1566 — CodeQL fix dd8dc62 left R3 open: its regression test also passes the old regex. The review round cap is spent.
Waiting: #1567 — on #1566 (hardware passed at 90c6d6c, review passed, ADR 0077 Accepted on the top branch)
Decided: #1565 — half-published release recovery → re-run the failed publish job, which skips versions already on npm; #1566 — text-only workflow tests → kept, each pinned to the whole condition of its step; #1567 — how a cut upload is recognised → no simlock
details.reason, never message text; #1567 — sign-in errors and refused uploads with no reason → count as cuts: three tries, no swapWritten by an agent.
docs(adr): propose 0077, the repository is a workspace and its packag…
feat(e2e): the device provider leases, installs, renews and releases,…
github-actions commentedon Nov 15, 2026
Closing: all 2 sub-issues are closed. The PR that closed the last one walks the completion conditions (delivery rule 9); reopen this if one does not hold on
main. Flip its ADRs to Accepted if delivery has not.V3RON commentedon Nov 15, 2026
Delivery run
Merged: #1565 (ADR 0077), #1568 (#1566), #1572 (#1567)
Parked: none (the maintainer approved two runs past the limits: R3 after the review cap, the Fallow fix after the second red gate)
Waiting: none
Decided: #1565: how a half-published release recovers → re-run the failed publish job, which skips versions already on npm; #1566: text-only workflow tests → kept, each pinned to its step's whole condition; #1567: how a cut upload is recognised → no simlock
details.reason, never message text; #1567: sign-in errors and refused uploads with no reason → count as cuts: three tries, no swapWritten by an agent.