Compare commits

..
Author SHA1 Message Date
Brent Vatne 0352b3e5fc Address the PR review, and clean up after interrupted local captures
From a three-model review of this PR:
- EAS Simulator sessions now start during the repack, so they ask for 20
  minutes on top of the capture's own, and retry with the plan's maximum
  when that is refused.
- doctor checks each target where it runs (local or EAS Simulator,
  Argent or agent-device), not only the config's top level.
- A local review's reports list only the targets it ran, so the Viewer
  offers no link to a report that does not exist.
- A setup step that wedges the controller runs setup again from the
  start; if it wedges again, routes go on but say setup did not complete,
  in every appearance.
- Agent-mode taps and readiness bounds map between an upright landscape
  screenshot and the portrait axes of an opened iPhone Duo.
- Emulator port locks live in the user's Explore cache, and a lock taken
  over from a process that died is broken by one capture at a time.
- Argent's tool-server installs with npm ci from a lockfile Explore ships,
  so every dependency is pinned, and neither npm nor stopping the server
  sees a capture's tokens.
- A target whose capture worker died fails the shared builds it owned,
  so the targets waiting on them stop.

Every local capture records what it starts (simulator, emulator,
agent-device daemon, Argent tool-server); a local review first stops
what a capture stopped hard left running.
2026-10-17 14:37:46 -07:00
Brent Vatne 7bf12bcf42 Open a route again when the emulator's adb connection drops
Each local emulator's adb connection drops once, about half a minute
after it boots (adb's log: "connection terminated: read failed"), and
the same is seen on EAS. A route whose open hit that failed outright:
agent-device's "device not found" is not retryable. Once the device
answers again, the route now opens again from the app's root, recorded
in controller-retries.jsonl.
2026-10-17 14:37:35 -07:00
Brent Vatne f904120f78 Wait for the root link to settle before each route's link
The one-call reset sent a route's link straight after the root link. On
iOS a link that lands while the previous route's sheet is still being
dismissed can leave the app unable to present a sheet until it is
relaunched: euxy's share link, opened right after its share sheet, never
showed its own, on either attempt. The base waited for the screen to
settle after the root link; captures do again (expo/expo#51740).
2026-10-17 14:37:11 -07:00
Brent Vatne 9a548cf2e8 Use agent-device 0.21.28
The latest release, with fixes for iPhone Duo's viewport and fold and for
iOS 27. The pinned version, its tarball integrity, the dev dependency and
the CI guide move together.
2026-10-17 14:36:58 -07:00
Brent Vatne 40b581d385 Repack on this machine with a local simulator
A local simulator already needs Xcode or the Android SDK, which is all a
repack needs, so it now repacks on this machine unless capture.repack
says eas. --repack eas|local chooses for one run. The default resolves
where it is used, and the capture recipe keys it as resolved, so configs
on EAS Simulator keep their baselines. doctor checks that a local Android
repack has the SDK build-tools and Java.

Fixes found running it:
- A local repack is not uploaded, so it has no EAS build ID, and every
  frame was dropped from the bundle. Frames and the bundle now name the
  native EAS build it repacked, which the review checks them against.
- Head and base reserve emulator ports from worker threads of one
  process, and both could take over the same stale lock. Reservations now
  run one at a time under a mutex directory.

The docs no longer say a local repack is uploaded with eas upload.
2026-10-17 08:44:45 -07:00
Brent Vatne c7f7dc800d Keep a Screens card's notes and status dot with its route
"Changed in dark" and "via" notes were drawn after the card, outside it.
They are now in the card's footer under the route. The status dot was
placed from the card's bottom, so a card stretched to a taller row showed
it a line below the route; it is now placed from the top of the footer.

Also corrects the docs and help that said a local simulator works with
agent-device only and that Argent captures one appearance: that holds on
EAS Simulator only.
2026-10-17 08:44:39 -07:00
Brent Vatne 8e576c5f57 Stop a local emulator adb has lost
An emulator whose console port closed is not listed by adb and ignores
emu kill, so cleanup took it for stopped while it kept running. After emu
kill, any Explore emulator process still on the capture's console port is
signalled, SIGTERM then SIGKILL.
2026-10-17 07:52:16 -07:00
Brent Vatne deed8e9cc1 Capture an opened foldable's screenshots upright through Argent
Argent reads the opened iPhone Duo's inner panel on its portrait axes, so
the screen it reports has the screenshot's shape and the transpose check
never fired. The capture now tells the Argent bridge the target's pose;
an opened iOS foldable asks Argent for a LandscapeRight screenshot, and
its recordings, which Argent cannot turn, are turned clockwise with ffmpeg
when they come back portrait.
2026-10-17 07:52:16 -07:00
Brent VatneandClaude Opus 5.5 a3f1ad2ffa Recover when Argent cannot read the app after a fold
After a fold, Argent's accessibility reader can stay on a foldable's dark outer panel and never
read the app. Locally the capture runs that reader, so it starts a fresh tool-server (whose reader
starts on the lit panel) and opens the app again; if that fails too, it restarts SpringBoard as
well, the recovery XcodeBuildMCP#537 reports for this panel. A third failure is reported.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
2026-10-16 23:58:16 -07:00
Brent VatneandClaude Opus 5.5 91b2b49d61 Recover from a setup step that leaves another app in front
On the closed iPhone Duo, a tap on the sheet's Done button, which main still draws under the status
pill, brought up the system instead of the app and failed setup, and with it every route. Like a
stuck controller, it now costs that step: the app starts again and the routes go on by app link.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
2026-10-16 23:52:09 -07:00
Brent VatneandClaude Opus 5.5 490123d380 Turn the opened iPhone Duo's launch recording upright too
Argent records the opened panel in the same portrait orientation as its screenshots. When a
recording's shape is the transpose of the screen, the bridge turns it a quarter clockwise with
ffmpeg, which observing a launch already needs; without ffmpeg it is left as it is.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
2026-10-16 23:39:14 -07:00
Brent VatneandClaude Opus 5.5 87106f6672 Capture on a local simulator or emulator, several targets per config, and faster, sturdier runs
Local devices (`capture.simulator: local`, `--simulator local`): each commit gets an iOS
simulator (simctl) or Android emulator (Android SDK) of its own on this machine, removed
afterwards. The app's URL scheme is pre-approved, a foldable's pose is checked by its lit
display, and Argent runs locally through a tool-server of the capture's own (installed on first
use, pinned and integrity-checked); the host switches the appearance Argent cannot.

Targets (`targets:` in config.yaml): named captures, several per platform (a phone, a foldable
closed and open), each its own report with its own label, device, pose, controller and
simulator. `--target`, `config:targets`, matrix workflows, artifacts, baselines, PR comment
records, saved runs, hosted listings and the Viewer's switcher are keyed by target; configs
without targets keep their platform-named ids and byte-identical names.

Speed: devices and EAS sessions start while the app is repacked (the app is installed through
the controller, never uploaded), a review's targets run at once (`--parallel N`) and share each
commit's build, and a route needs one root open and no appstate.

Sturdiness: a controller that stops answering costs one route or setup step (the app restarts,
recorded in controller-recoveries.jsonl), a target that fails costs only its own report, local
daemons and tool-servers are stopped, and emulators skip ports agent-device still claims.
Argent's opened iPhone Duo screenshots are turned upright.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
2026-10-16 23:34:42 -07:00
82 changed files with 447 additions and 5315 deletions

No files matched your search

+80 -97
View File
@@ -1,6 +1,6 @@
# Expo Explore
Explore maps your app: a screenshot of every screen, connected by the taps between them. On each pull request it captures the screens the PR changes, before and after, on EAS Simulator, and posts a visual review. On your Mac it can also run on a local simulator.
Explore maps your app: a screenshot of every screen, connected by the taps between them. On each pull request it captures the screens the PR changes, before and after, on EAS Simulator, and posts a visual review.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/readme-hero-dark.png">
@@ -53,76 +53,52 @@ which look like regressions. For each regression, name the source file to fix.
<details>
<summary><strong>Requirements</strong></summary>
- To review a change: Expo SDK 57 or newer, with Expo Router (57 or newer) or React Navigation (6 or newer), and an Expo account, since Explore builds the app on EAS. An EAS build profile per platform: `ios.simulator: true` for iOS, `android.buildType: apk` (not a development build) for Android. Its EAS environment cannot have secret-visibility or file variables.
- To explore a build: a simulator build of any app, and a Claude Code or Codex login (or an API key). On a local simulator it needs no Expo account.
- Somewhere to run the app: EAS Simulator (in preview, [join the waitlist](https://expo.dev/services/simulators)), which CI uses; or a [local simulator](#simulator) on your Mac: Xcode 26 or newer for iOS (the default devices are iPhone 17 models) and, for Android, the Android SDK with `ANDROID_HOME` set (emulator, platform-tools, cmdline-tools and a system image; to review a change, also build-tools and a JDK 17).
- Node.js 24.12 or newer. For CI, admin access to the GitHub repository.
- An iOS app, an Android app, or both. Explore is in v0; Android capture is newer than iOS.
- Expo SDK 57 or newer, with Expo Router (57 or newer) or React Navigation (6 or newer).
- An EAS build profile per platform: `ios.simulator: true` for iOS, `android.buildType: apk` for Android. Its EAS environment cannot have secret-visibility variables.
- EAS Simulator access (in preview, [join the waitlist](https://expo.dev/services/simulators)).
- Node.js 24.12 or newer, and admin access to the GitHub repository.
</details>
## Quick start
Paste this into Claude Code or Codex from your app's directory. It reviews a change to your app, before and after, or, if you point it to a build, maps every screen of that build:
Review a change to your own app, on your machine. You need an Expo SDK 57+ app with Expo Router or React Navigation, Node.js 24.12+, and EAS Simulator access ([join the waitlist](https://expo.dev/services/simulators)). No API keys, no CI.
```text
Show me Expo Explore working on this app, with npx @expo/explore. If I point you to a
build (.app, .tar.gz, simulator .ipa, or .apk), explore it: follow
https://unpkg.com/@expo/explore/skills/explore-binary/SKILL.md. If this is not an Expo
project, ask me for a simulator build and explore that. Otherwise review a change to
this app: follow the "Review a change on this machine" section of
https://unpkg.com/@expo/explore/skills/explore-setup/SKILL.md. If the app cannot build
for the iOS Simulator on EAS yet, set that up (an EAS project, ios.bundleIdentifier, an
"explore" profile with ios.simulator: true) and ask me before you commit it. If I have
no EAS Simulator access, pass --simulator local (it needs Xcode; exploring an .apk needs
the Android SDK instead). If I have no uncommitted changes, change some text near the
top of a screen. If the app needs a sign-in, ask me for a test account the way the skill
describes, never for a password in chat. Open the report, and if I need to log in to
something first, tell me the command.
```
From your app's directory:
You need Node.js 24.12+. Reviewing a change needs an Expo account and an Expo SDK 57+ app with Expo Router or React Navigation: it is built on EAS and captured on EAS Simulator ([join the waitlist](https://expo.dev/services/simulators)) or, with Xcode, on a simulator on your Mac. Exploring a build needs a Claude Code or Codex login, and EAS Simulator or a simulator on your Mac; on your Mac, no Expo account. No API keys, no CI.
<details>
<summary><strong>Run it yourself</strong></summary>
There are two ways to use Explore: review a change to your Expo app, which needs an Expo account, or explore an iOS or Android build of any app directly, which needs no Expo account when it runs on your Mac.
**Review a change**, from your app's directory:
1. Make the app buildable on EAS, if it is not yet:
1. **Make the app buildable on EAS, if it is not yet.**
```sh
npx eas-cli@latest login
npx eas-cli@latest init
```
Then set `ios.bundleIdentifier` in your app config, add a simulator profile to `eas.json`, and commit. The "before" is where your branch left the default branch: on the default branch, your last commit.
Then set `ios.bundleIdentifier` in your app config, add a simulator profile to `eas.json`, and commit. The review builds your last commit as the "before".
```json
{ "build": { "explore": { "ios": { "simulator": true } } } }
```
2. Edit some text near the top of a screen (Explore captures the first screenful) and run:
2. **Change a screen, then review the change.** Edit some text near the top of a screen (Explore captures the first screenful) and run:
```sh
npx @expo/explore capture # on EAS Simulator
npx @expo/explore capture --simulator local # or on a simulator on your Mac
npx @expo/explore capture
```
Explore builds your last commit and your uncommitted changes on EAS, captures the screens the changes can affect, before and after, and opens the report in your browser. The first run waits for an EAS build; later runs reuse it while your native code is unchanged. A [local simulator](#simulator) is one Explore creates on your Mac and removes afterwards.
Explore builds your last commit and your uncommitted changes on EAS, captures the screens the changes can affect, before and after, on EAS Simulator, and opens the report in your browser. The first run waits for an EAS build; later runs reuse it while your native code is unchanged.
**Explore a build:**
Or paste this into Claude Code or Codex from your app's directory:
```sh
npx @expo/explore explore:binary ./my-app.apk # Android APK
npx @expo/explore explore:binary ./my-app.app # iOS simulator build (.app, .tar.gz, or simulator .ipa)
npx @expo/explore explore:binary ./my-app.app --simulator local # on a simulator on your Mac
```text
Show me an Expo Explore review of a change to this app. Follow the "Review a change on
this machine" section of https://unpkg.com/@expo/explore/skills/explore-setup/SKILL.md.
If the app cannot build for the iOS Simulator on EAS yet, set that up (an EAS project,
ios.bundleIdentifier, an "explore" profile with ios.simulator: true) and ask me before
you commit it. If I have no uncommitted changes, change some text near the top of a
screen. Then run npx @expo/explore capture and open the report.
```
Explore starts an EAS Simulator, installs the build, taps through the app with your Claude Code or Codex login, and prints a link to the hosted report. With `--simulator local` it runs on a simulator or emulator it creates on your Mac, needs no Expo account, and opens the report in your browser. Its [options](#options) are below.
</details>
Every run is kept on your machine for 30 days. `npx @expo/explore reports` lists your local reviews, explorations and uploaded reports with their commits, and reopens or hosts one without capturing again:
<picture>
@@ -139,12 +115,12 @@ npx @expo/explore capture --committed # HEAD alone
npx @expo/explore capture --base v1.3.0 --head v1.4.0 --scope all --upload
```
- It checks out both commits as temporary worktrees, installs their dependencies, captures every configured platform or [target](#targets) on EAS Simulator or a [local simulator](#simulator), and opens the report in a local Viewer. `--target` or `--platform` picks some; they run at once, at most `--parallel N` at a time. `--upload` hosts it for 30 days (`--expires-in` changes that) and prints the link; `report:upload <report.zip>` hosts one you already have.
- It checks out both commits as temporary worktrees, installs their dependencies, captures every configured platform on EAS Simulator (`--platform` picks one), and opens the report in a local Viewer. `--upload` hosts it and prints the link; `report:upload <report.zip>` hosts one you already have.
- Your checkout, index and branches are never touched. Your uncommitted changes, untracked files included, are reviewed as `eas build` would upload them; `--committed`, or `cli.requireCommit: true` in `eas.json`, leaves them out.
- It runs both commits' code on your machine, as you: installing their dependencies, evaluating the app config, and bundling the JavaScript. That is what checking them out and running them would do, so review only commits you would run, and someone else's branch only if you trust it.
- Installs run without credential environment variables, which keeps tokens out of reach of a registry a commit's `.npmrc` names; that is not a sandbox. A registry that needs `${NPM_TOKEN}` in the project's `.npmrc` must be authenticated in your own `~/.npmrc`.
- Captures are cached in `~/.cache/expo-explore`, so the same base is not captured twice (`--no-cache` skips it); a capture unused for 30 days goes, and the cache stays under 2 GB. Ctrl+C stops the run's simulator sessions and local devices; when a run is stopped harder than that, the next local run stops what it left running.
- Like a CI review, it builds on EAS (reusing a matching build) and, unless it captures on a local simulator, runs EAS Simulator sessions: expect several minutes and EAS usage.
- Captures are cached in `~/.cache/expo-explore`, so the same base is not captured twice (`--no-cache` skips it); a capture unused for 30 days goes, and the cache stays under 2 GB. Ctrl+C stops the run's simulator sessions.
- Like a CI review, it builds on EAS (reusing a matching build) and runs simulator sessions: expect several minutes and EAS usage.
- Saved runs take up to 2 GB in all, the oldest going first. `reports add <report.zip>` keeps a report you downloaded, such as a PR's `explore-review` artifact.
</details>
@@ -153,22 +129,44 @@ Explore uses its defaults until you run `npx @expo/explore setup`, which writes
## Map every screen of any app
Pointed to a build, the [quick start](#quick-start) maps every screen of it, with no source and no config: one card per screen it reached, connected by the taps between them. For apps behind a sign-in, see [Sign-in and other app state](#sign-in-and-other-app-state).
To map every screen of an app instead, with no config, paste this into Claude Code or Codex from your app's directory. It explores a build you point to, or an Expo project straight from its source:
```text
Show me Expo Explore working on this app. Follow
https://unpkg.com/@expo/explore/skills/explore-binary/SKILL.md and run Explore with
npx @expo/explore. If I point you to a build, explore that. Otherwise, if this is an
Expo project, run it from source without making a new build; if it is not, get a
simulator build of it. If the app needs a sign-in, ask me for a test account the way
the skill describes, never for a password in chat. Give me the report link, and if I
need to log in to something first, tell me the command.
```
For apps behind a sign-in, see [Sign-in and other app state](#sign-in-and-other-app-state).
<details>
<summary><strong>Run it yourself</strong></summary>
```sh
npx @expo/explore explore:binary ./my-app.apk # Android APK
npx @expo/explore explore:binary ./my-app.app # iOS simulator build (.app, .tar.gz, or simulator .ipa)
```
Explore starts an EAS Simulator, installs the build, taps through the app with your Claude Code or Codex login, and prints a link to the hosted report.
</details>
<details>
<summary id="options"><strong>What it needs, and its options</strong></summary>
- A `claude` or `codex` login, or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`.
- EAS Simulator access and an EAS login (`eas whoami`), or `--simulator local` to run on a [local simulator](#simulator) with no EAS login.
- A simulator build. A device `.ipa`, an `.aab`, an unsigned APK, or an APK without native libraries for the emulator (x86_64 on EAS Simulator, `arm64-v8a` locally on Apple silicon; a universal APK has both) is rejected before a device starts.
- An EAS login (`eas whoami`) and a `claude` or `codex` login, or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`.
- A simulator build. A device `.ipa` or an `.aab` is rejected before a session starts.
- Platform, bundle id, name, and version are read from the build; you pass nothing else.
- A run stops after 15 minutes, 40 screens, or 150 actions (`--max-duration-minutes`, `--max-screens`, `--max-actions`).
- Buttons that delete, pay, sign out, send, or leave the app are never tapped. `--allow-destructive "Reset filters"` allows one by its exact label.
- Buttons that delete, pay, sign out, send, or leave the app are never tapped. `--allow-destructive "Clear cache"` allows one by label.
- `--hints "…"` tells the model what to focus on or how to sign in ([details](#sign-in-and-other-app-state)).
- On EAS Simulator the report is hosted, and the link lasts 7 days (`--expires-in` takes 1d to 90d, or never); `--no-upload` keeps it local. On a local simulator it opens in the local Viewer (`--no-open` or `--json` skips that; `view --dir <folder>` opens it later), and `--upload` hosts it, which needs an EAS login. `--json` prints the result for scripts.
- For a link that stays the same from run to run, pass `--alias NAME` and set `EXPLORE_PREVIEW_TOKEN` to a fixed token of 32 characters from a–z and 2–7 (`LC_ALL=C tr -dc a-z2-7 </dev/urandom | head -c 32`).
- EAS Simulator sessions and hosted reports run under an EAS project named `expo-explore` in your account, created on first use (`--owner` and `--project` pick another).
- Read a local result with `npx @expo/explore view --dir <folder>`, `screen:list`, or `gap:list`.
- The hosted link lasts 7 days (`--expires-in 30d|never`). `--no-upload` keeps the report local, and `--json` prints the result for scripts.
- For a link that stays the same from run to run, pass `--alias NAME` and set `EXPLORE_PREVIEW_TOKEN` to a fixed 32-character token.
- Read a local result with `expo-explore view --dir <folder>`, `screen:list`, or `gap:list`.
</details>
@@ -190,7 +188,7 @@ npx @expo/explore explore:session <session-id> --env-file path/.env.eas-simulato
<details>
<summary><strong>What a run without source shows</strong></summary>
One card per screen the run reached, laid out by how many taps it took, with the tapped control on each edge. There is no before and after; that needs the app's source: [`capture`](#quick-start) on your machine, or [CI](#set-up-ci).
One card per screen the run reached, laid out by how many taps it took, with the tapped control on each edge. There is no before and after; that needs [CI](#set-up-ci).
![The Map of an exploration report for the euxy app: one card per screen the run reached, laid out by taps from the launch screen, each edge labelled with the control that was tapped](docs/screenshots/readme-exploration-light.png)
@@ -202,7 +200,7 @@ Explore runs in your repository's GitHub Actions in two ways, both from the same
### Review on every PR
Each pull request gets a comment linking its report: the screens it added, removed or changed, before and after, on each platform or device ([target](#targets)) you capture. Paste this into Claude Code or Codex from your app's repository:
Each pull request gets a comment linking its report: the screens it added, removed or changed, before and after, on each platform you capture. Paste this into Claude Code or Codex from your app's repository:
```text
Set up this app for Expo Explore CI reviews. Follow
@@ -226,9 +224,9 @@ report:
# project: acme-explore # default <repository name>-explore, created on first run
```
- The generated workflows already have the `deploy` job; it runs once `hosting: eas` is set.
- Run `expo-explore setup --workflows` after enabling it to add the `deploy` job.
- A [comparison of two commits](#compare-any-two-commits) links its hosted report from the run's summary instead of a PR comment. `capture --upload` on your machine deploys to the same project with your `eas login`.
- `expo-explore report:upload <report.zip>...` hosts reports already on your machine the same way: a review's reports (one per platform or target, from `capture --output` or a downloaded `explore-review` artifact) or an `explore:binary` report.
- `expo-explore report:upload <report.zip>...` hosts reports already on your machine the same way: a review's reports (one per platform, from `capture --output` or a downloaded `explore-review` artifact) or an `explore:binary` report.
- `EXPO_TOKEN` must be able to create the EAS project, so use a [robot user's](https://docs.expo.dev/accounts/programmatic-access/) token.
- The report is encrypted, and only a request carrying the link's token can open it. Treat the link like a shared file link; see [report access](docs/private-review.md#hosted-previews).
@@ -240,11 +238,11 @@ report:
The prompt above walks through these steps with you. To do them yourself:
1. Run `npx @expo/explore setup` in your app's directory (in a monorepo, add `--project apps/mobile`). It writes `.expo-explore/config.yaml` and the workflows.
2. Run `npx @expo/explore doctor` and fix each problem it reports, until it exits 0. `doctor --capture` captures the committed app once, to check every screen before your first PR (with several targets, pass `--target`).
2. Run `npx @expo/explore doctor` and fix each problem it reports, until it exits 0. `doctor --capture` captures the committed app on EAS once, to check every screen before your first PR.
3. Set the repository secrets `doctor` lists:
- `EXPO_TOKEN`: create it in [Expo access tokens](https://expo.dev/settings/access-tokens). For [hosted previews](#hosted-previews), use a [robot user](https://docs.expo.dev/accounts/programmatic-access/) that can create projects.
- A secret for each `{{secret:NAME}}` in your setup steps. Run `npx @expo/explore setup --workflows` after you add one.
4. Commit and merge to the default branch. **Expo Explore baseline** runs on that push (or run it from GitHub Actions).
4. Commit, merge to the default branch, and run **Expo Explore baseline** from GitHub Actions.
5. Open a PR. **Expo Explore review** runs and posts a comment with the report. To see a whole review of your branch first, run `npx @expo/explore capture` on your machine.
A failed run shows an error code and a next action in the PR comment; see [CI troubleshooting](docs/quickstart-ci.md#diagnose-a-failed-run).
@@ -266,7 +264,7 @@ Both modes use the same comparison rules and report. You can change modes later.
**To use agent mode:**
1. Create an [Anthropic](https://platform.claude.com/settings/keys) or [OpenAI](https://platform.openai.com/api-keys) API key.
2. Set `mode: agent`, `agent.provider` (`anthropic` or `openai`), an `agent.model` your account can use, and `agent.instructions`: the path of a file in the repository that tells the agent how to use the app.
2. Set `mode: agent` and an `agent.model` your account can use.
3. Store the key as the repository secret `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. A key that is not workspace-scoped also needs the `ANTHROPIC_WORKSPACE_ID` variable.
4. Export the key and run `expo-explore doctor --check-model`.
@@ -313,19 +311,17 @@ targets:
android: { platform: android, device: pixel_7, bundleId: com.example.myapp, easProfile: explore-android }
```
- A target takes the `app` fields it does not set, and `device.name` when it is of `app.platform`; a target of another platform sets its own `bundleId` and `easProfile` (an Android one's device defaults to `pixel_7`). `pose` is `closed`, `half-open` or `open`. `label` names it in reports (by default its device and pose).
- Ids are up to 32 lowercase letters, digits and dashes, start with a letter, and are not `base`, `head` or `report`. A config names at most 8 targets. A config with `platforms` has one target per platform, named `ios` and `android`.
- A target takes the flat `app` and `device` fields it does not set; a target of another platform than `app.platform` sets its own `bundleId` and `easProfile`. `label` names it in reports (by default its device and pose).
- Ids are lowercase letters, digits and dashes. A config with `platforms` has one target per platform, named `ios` and `android`.
- The workflows run one capture job per target, the PR comment has a section per target, and each report links its sibling targets' reports.
- A target can also set its own `controller` and `simulator` over `capture`'s, such as Android on agent-device beside iOS targets on Argent. `--controller` and `--simulator` override every target's for one run.
- `capture --target duo-open` reviews one target on this machine; `--platform ios` the iOS ones. On your machine a review's targets run at once (at most `--parallel N`), and targets of one platform and EAS profile share each commit's build; in CI each target is its own job. A target that fails outright costs only its own report.
- A device controller that stops answering on one screen costs that route, up to three times per capture: Explore restarts the app, goes on with the next route, and records what happened in `capture-diagnostics/controller-recoveries.jsonl`.
- `capture --target duo-open` reviews one target on this machine; `--platform ios` the iOS ones.
</details>
<details>
<summary id="controller"><strong>Device controller: agent-device or Argent</strong></summary>
Explore drives the simulator with [agent-device](https://github.com/callstackincubator/agent-device) by default. To use [Argent](https://github.com/software-mansion/argent) instead, set it in the config or pass it for one run:
Explore drives EAS Simulator with [agent-device](https://github.com/callstackincubator/agent-device) by default. To use [Argent](https://github.com/software-mansion/argent) instead, set it in the config or pass it for one run:
```yaml
capture:
@@ -339,16 +335,16 @@ npx @expo/explore explore:binary ./app.apk --controller argent
Explore pins each controller's version and starts the EAS session with it. Reports and baselines record the controller, and a review compares captures made with the same one.
Neither controller is installed with Explore. The first run that needs one downloads its pinned npm release (agent-device 1.6 MB, Argent 27 MB), checks it against the integrity hash Explore pins, and keeps it in `~/.cache/expo-explore/controllers` (`EXPLORE_CONTROLLER_CACHE` moves it). Behind a private registry, set `EXPLORE_NPM_REGISTRY` to a mirror of it.
Neither controller is installed with Explore. The first run that needs one downloads its pinned npm release (agent-device 1.4 MB, Argent 27 MB), checks it against the integrity hash Explore pins, and keeps it in `~/.cache/expo-explore/controllers` (`EXPLORE_CONTROLLER_CACHE` moves it). Behind a private registry, set `EXPLORE_NPM_REGISTRY` to a mirror of it.
Argent cannot switch the simulator's appearance yet ([software-mansion/argent#1509](https://github.com/software-mansion/argent/pull/1509)), so an Argent capture on EAS Simulator records one appearance: the one the app forces, else light. Explore warns when it skips one. On a [local simulator](#simulator) the host switches it, so every appearance the config asks for is captured.
Argent cannot switch the simulator's appearance yet ([software-mansion/argent#1509](https://github.com/software-mansion/argent/pull/1509)), so an Argent capture on EAS Simulator records one appearance: the one the app forces, else light. Explore warns when it skips one. On a [local simulator](#simulator) the host switches it, so both are captured.
</details>
<details>
<summary id="simulator"><strong>Local simulator instead of EAS Simulator</strong></summary>
To capture on your Mac instead of EAS Simulator, pass it for one run, or set it in a config you use only on your Mac:
To capture on your Mac instead of EAS Simulator, set it in the config or pass it for one run:
```yaml
capture:
@@ -359,22 +355,16 @@ capture:
npx @expo/explore capture --simulator local
```
CI runs on GitHub's Ubuntu runners and captures on EAS Simulator, so keep `simulator: local` out of the config you commit.
For each commit, Explore starts a device of its own and removes it afterwards; head and base each get one:
- **iOS:** a simulator of the configured device with Xcode's newest runtime that runs it. `DEVELOPER_DIR` picks another Xcode, such as one that adds iPhone Duo. Explore approves the app's URL scheme on it, so links open without iOS asking "Open in …?", and checks a foldable's pose by the shape of its lit display.
- **Android:** an emulator of the configured device profile (such as `pixel_7`), from the newest Google APIs system image installed for this machine (`arm64-v8a` on Apple silicon), in a private AVD folder. The APK must ship native libraries for that ABI; a universal build does. It needs the SDK's emulator, platform-tools and cmdline-tools, with `ANDROID_HOME` set.
- **Android:** an emulator of the configured device profile (such as `pixel_7`), from the newest Google APIs system image installed for this machine (`arm64-v8a` on Apple silicon), in a private AVD folder. The APK must ship native libraries for that ABI; a universal build does.
`explore:binary --simulator local` starts one the same way for the build it explores, needs no EAS login, and opens the report in the local Viewer (`--upload` hosts it).
Builds still run on EAS. The app is repacked with the route observer on your machine as well, so it is never uploaded; on Android that needs the SDK's build-tools and a JDK. `capture.repack: eas` (or `--repack eas`) keeps the repack in a hosted EAS job. `doctor --simulator local` checks that Xcode and the Android SDK can start each device, and that Android can be repacked locally.
For a review, builds still run on EAS. The app is repacked with the route observer on your machine as well, so it is never uploaded; on Android that needs the SDK's build-tools and a JDK. `capture.repack: eas` (or `--repack eas`) keeps the repack in a hosted EAS job. `doctor --simulator local` checks that Xcode and the Android SDK can start each device, and that Android can be repacked locally.
With `--controller argent`, Explore installs Argent's tool-server on first use (with its dependencies, about 165 MB, in the controller cache) and starts one per device. The host switches the appearance, so a local Argent capture records light and dark. Reports record where they were captured, and a baseline is reused only by a review captured the same way.
With `--controller argent`, Explore installs Argent's tool-server on first use with `npm ci` from a lockfile Explore ships, so every dependency is pinned (about 160 MB, in the controller cache), and starts one per device. The host switches the appearance, so a local Argent capture records every appearance the config asks for. Reports record where they were captured, and a baseline is reused only by a review captured the same way.
A foldable folds before the app first opens (`pose` on a [target](#targets)); with agent-device on a local simulator it folds just after, since agent-device folds only inside a session. With Argent, an opened iPhone Duo is captured upright, in landscape. After a fold, Argent's reader can stay on the panel that went dark; Explore then restarts its tool-server, and if that is not enough SpringBoard as well, and opens the app again.
Each capture records what it starts on your Mac (simulators, emulators, controller daemons, tool-servers) and removes it when it ends. If a review or a local `explore:binary` run is stopped hard, the next local one stops what it left running; nothing Explore did not record is touched.
A review's targets run at once, the targets of a platform sharing each commit's build; `--parallel N` runs at most N at a time. A device controller that stops answering on one screen costs that route: Explore restarts the app, goes on with the next route, and records what happened in `capture-diagnostics/controller-recoveries.jsonl`. A target that fails outright costs its own report; the others still open.
</details>
@@ -444,17 +434,13 @@ jobs:
- Pick whatever `base` the event calls for: `main` for a release branch, yesterday's tag for a nightly, the last stable tag for a release candidate.
- `scope` and `expires-in` are optional and override `exploration.scope` and `report.preview.expiresAfter` for that run. Without them a comparison captures what a PR review would (`scope: changes` captures only screens whose source changed), and the hosted link expires like a PR's.
- The run summary links each target's report (**Open** and **zip**, like a PR comment) and, with hosting, the hosted report.
- The run summary links each platform's report (**Open** and **zip**, like a PR comment) and, with hosting, the hosted report.
- `setup --workflows` installs it from 0.19.0; `npx @expo/explore@latest setup --workflows` adds it to an existing setup. The caller grants `contents: read` and `actions: read`; `secrets: inherit` passes `EXPO_TOKEN` and any app-test secrets.
- Call it once per workflow run. A called workflow runs inside its caller's run, so a second call in the same run would reuse the first one's artifact names; use separate workflows instead.
- When the baseline workflow captured `base` in the last 30 days, with the same config and Explore version, that capture is reused and only `head` is captured. The report artifact is kept 30 days; only a hosted link with `expires-in: never` lasts longer.
- When the baseline workflow captured `base` in the last 30 days, that capture is reused and only `head` is captured. The report artifact is kept 30 days; only a hosted link with `expires-in: never` lasts longer.
</details>
## Flows: capture what a user does, not only where a link lands
When one frame per route is not enough (a payment, a sign-up, a wizard), give Explore the app's own [`e2e`](https://e2e.tester.army) tests and set `mode: flows` (or add `flows:` beside deterministic capture). Explore runs them on its simulator session on both revisions; every `app.screenshot("label")` in a test is a frame the review compares, each flow is a journey in the Viewer, and a flow that fails keeps the frames it took and names the step that failed. There is no Explore flow language to learn, and `explore capture --flows e2e/checkout.e2e.ts` runs just the flows you name; every step in the review links to its line in the test file. See [Flows](docs/quickstart-ci.md#flows-the-apps-e2e-tests-as-capture). Set `flows.frames: steps` to also take a frame after every step of a flow, not only where it calls `app.screenshot`.
## Sign-in and other app state
Each run starts on a fresh install. Tell Explore how to get past what the app needs: with `--hints` when running without source, or with [setup steps or agent instructions](docs/quickstart-ci.md#when-the-config-needs-setup-steps) in CI.
@@ -479,7 +465,7 @@ If the sign-in can't be typed (one-time codes, email links, Sign in with Apple o
| Needs data to show a screen | A test account that has it, and a hint saying where ("open the first project") |
| Asks for a permission | Explore denies it. Allow it by hand on a session, then run `explore:session` |
| Has a paywall | An account that already has the entitlement; purchase buttons are never tapped |
| Has a safe button that looks destructive | `--allow-destructive "Reset filters"` |
| Has a safe button that looks destructive | `--allow-destructive "Clear cache"` |
| Is large | [Raise the budgets](#options) (15 minutes, 40 screens, 150 actions by default) and use `--hints` to set priorities |
When a run stops early, `gap:list --dir <output>` says what blocked it.
@@ -505,7 +491,7 @@ The same link answers differently depending on who asks. It already carries the
- Anything that does not ask for HTML (`curl`, `fetch`, agents' URL tools) gets a Markdown index of the report, also at `/llms.txt`.
- The index links to a read-only JSON API under `/api/v1`: `/screens?status=modified,accessibility-only,added,removed`, `/screens/<id>`, `/transitions`, and `/raw` for the report file.
- Reports without source also expose `/journeys`, `/gaps`, and `/frontier`.
- A link to several targets takes `?target=<id>` and serves the first without it; `/reports.json` lists them (`?platform=ios|android` from older links still works). Expired links' report and API routes answer `410`.
- Multi-platform reports take `?platform=ios|android`. Expired links answer `410`.
```sh
curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status, review}'
@@ -518,7 +504,7 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
1. The review workflow runs on open, non-draft PRs from the repository whose author has write access. Bots such as Devin go under `ci.trustedAuthors` in `.expo-explore/config.yaml`.
2. Explore reads the diff and your router source to pick the affected screens.
3. It builds both revisions on EAS (reusing a build with the same native fingerprint) and captures each screen on EAS Simulator (or, on your machine, a local simulator), reusing a baseline of the base commit when one exists.
3. It builds both revisions and captures each screen on EAS Simulator, reusing a baseline of the base commit when one exists.
4. It compares the captures. A screen with a source change is **Modified** if its captures differ.
5. It uploads the report to GitHub Actions and posts a PR comment.
@@ -531,16 +517,13 @@ Reports and baselines are kept for 30 days and diagnostics for 7. Hosted deploym
<details>
<summary><strong>Known limitations</strong></summary>
- Android capture has had less use than iOS. The default Android device is `pixel_7`.
- Android capture has had less use than iOS. The first Android device is `pixel_7`.
- PRs from forks are not reviewed.
- Each route gets one capture per appearance (`capture.appearance: auto`, the default, captures light and dark when the app's `userInterfaceStyle` is `automatic`). Other states, such as modals, are planned.
- Each route gets one capture per appearance (light and dark with `capture.appearance: auto`). Other states, such as modals, are planned.
- The launch is captured once per appearance and compared like any screen. The comment says how long the splash stayed as it first appeared, when it first changed (a native launch screen handing over to an app-drawn one, an animation starting on it), and when the first screen settled. `capture.launch: video` adds a recording; a launch too fast to observe is reported as "no splash observed".
- On Android the splash usually shows only in the recording, which needs `ffmpeg`. The generated workflows install it.
- Hosted acceptance of agent mode with an API key is incomplete.
- With `capture.controller: argent` on EAS Simulator, each capture records one appearance (see [device controller](#controller)).
- On EAS Simulator, an opened iPhone Duo can fail to capture when Argent's reader stays on the cover panel after the fold. A [local simulator](#simulator) recovers from it.
- A local simulator runs only on your machine; the CI workflows capture on EAS Simulator.
- `explore:session` explores EAS Simulator sessions only.
</details>
+2 -2
View File
@@ -12,11 +12,11 @@ The Viewer reads the ZIP supplied by the reviewer; it has no hosted artifact dow
## Hosted previews
Hosted previews are off by default. When `report.preview.hosting: eas` is set, the review workflow's `deploy` job uploads each run's reports (one per captured platform or target) to an [EAS Hosting](https://docs.expo.dev/eas/hosting/introduction/) deployment in your Expo account, and the comment shows an **Explore report** link that opens it directly, in place of the **Open** drop page. The GitHub artifact and **zip** stay as they are.
Hosted previews are off by default. When `report.preview.hosting: eas` is set, the review workflow's `deploy` job uploads each run's reports (one per captured platform) to an [EAS Hosting](https://docs.expo.dev/eas/hosting/introduction/) deployment in your Expo account, and the comment shows an **Explore report** link that opens it directly, in place of the **Open** drop page. The GitHub artifact and **zip** stay as they are.
**What a reviewer needs.** Only the link. It looks like `https://acme-explore--k7f3z0d1q8.expo.app/p/f6r2…` and carries a 160-bit token generated for that run. It opens the Viewer and the report for one PR revision; it does not show the repository, other runs, or anything else in the Expo account.
**Several platforms or targets.** One deployment holds every target's report (a config without `targets` has one per platform). The link opens the first one (`?target=<id>` selects another, and `?platform=ios` or `?platform=android` from older links still works); the Viewer's menu lists the others from `/p/<token>/reports.json`, which names each target, its platform, label, device, and change count and nothing else. Every report and the listing sit behind the same token and expiry.
**Several platforms.** One deployment holds every platform's report. The link opens the primary platform's report (`?platform=ios` or `?platform=android` selects one); the Viewer's platform menu lists the others from `/p/<token>/reports.json`, which names each platform, its device, and its change count and nothing else. Every report and the listing sit behind the same token and expiry.
**What is protected, and how.**
+2 -59
View File
@@ -90,7 +90,7 @@ The capture profile can be a release build; a development client is not supporte
The generated `.expo-explore/config.yaml` lives in the application directory. Commit it with the app:
```yaml
mode: deterministic # deterministic (route links) | flows (setup, then the app's e2e tests) | agent
mode: deterministic
app:
platform: ios # ios | android
bundleId: com.example.myapp # Android: the application id (android.package)
@@ -144,7 +144,7 @@ targets:
android: { platform: android, device: pixel_7, bundleId: com.example.myapp, easProfile: explore-android }
```
A target's id (up to 32 lowercase letters, digits and dashes, starting with a letter; not `base`, `head`, `report` or `install-…`; at most 8 per config) takes the place of the platform everywhere a capture is named: `--target duo-open`, `explore-capture-<run>-<attempt>-duo-open`, `explore-baseline-<sha>-duo-open`. `expo-explore config:targets` prints the list the workflows use as their matrix. Fields a target leaves out come from `app` and `device`; a target of another platform than `app.platform` sets its own `bundleId` and `easProfile`. A config with `platforms` has one target per platform, named `ios` and `android`, so its names do not change. `--platform` still selects a target when only one has that platform.
A target's id (lowercase letters, digits and dashes; not `base`, `head` or `report`) takes the place of the platform everywhere a capture is named: `--target duo-open`, `explore-capture-<run>-<attempt>-duo-open`, `explore-baseline-<sha>-duo-open`. `expo-explore config:targets` prints the list the workflows use as their matrix. Fields a target leaves out come from `app` and `device`; a target of another platform than `app.platform` sets its own `bundleId` and `easProfile`. A config with `platforms` has one target per platform, named `ios` and `android`, so its names do not change. `--platform` still selects a target when only one has that platform.
Use the actual bundle identifier, scheme, profile, and available simulator device name. `scheme` is optional when static app configuration supplies it. `navigation.entry` resolves ambiguous entry modules; it does not list screens.
@@ -265,63 +265,6 @@ Do not assume a failed full run is cheap to repeat: inspect its diagnostic and
correct the specific failure first. Respect a user's request to stop paid runs;
offline tests do not establish live cost or complete capture acceptance.
### Flows: the app's e2e tests as capture
Deterministic capture shows one frame per route. A flow shows the screens a user actually passes through: sign-up,
sending money, checking out. Explore does not define a flow language for this; a flow is a test file of the
[`e2e`](https://e2e.tester.army) package, written and run the way the app's own e2e suite is, and Explore runs it on
the simulator session it already holds, on both revisions, after `setup`.
```yaml
mode: flows # or keep mode: deterministic and add flows: to capture the routes and the flows
flows:
tests:
- e2e/**/*.e2e.ts # paths or globs from the app directory
# frames: steps # also take a frame after every step; the default keeps only the frames the flows take with app.screenshot
```
```ts
// e2e/send-money.e2e.ts
import { expect, test } from "e2e";
test("send money to a contact", async ({ app, device, screen }) => {
await device.openLink("myapp://send/contacts");
await app.screenshot("contacts"); // a frame the review compares across revisions
await screen.getByText("Alex Rivera").tap();
await screen.getByTestId("send-amount-input").fill("25");
await app.screenshot("amount");
await screen.getByTestId("send-amount-continue").tap();
await expect(screen.getByTestId("send-confirm")).toBeVisible();
await app.screenshot("review");
});
```
Every `app.screenshot(label)` is a frame the review compares across revisions; the label names it. For a long flow, set
`flows.frames: steps` and Explore also takes a frame after every step (a tap, a fill, an assertion), named by its step
number, so the Flows view shows the whole journey rather than only the checkpoints. Per-step frames cost one screenshot
per step, so a 30-step flow takes about a minute longer per revision and appearance.
- A flow starts by opening the app: `await app.open()` for a plain launch, or `device.openLink("myapp://…")` for a deep
link. The flows run in their own agent-device session on Explore's simulator, which begins with no app in the
foreground (e2e's mobile engine is built that way: "a test launches the pinned app with `app.open()`").
- Every `app.screenshot(label)` is a frame of the review, `flow:<file>/<test>/<label>`, compared pixel by pixel
between base and head like a route. The Viewer lists each flow as a journey through its frames; the PR comment has
one line per flow.
- A flow that fails keeps the frames it took and the report names the step that failed (`failed on head at step 5
(locator.tap getByText("Alex Rivera"))`); the capture goes on with the next flow. A flow is review evidence, not a
gate: the workflow does not fail because a flow did.
- `agent.act("…")` steps run when the config has an `agent` block with its provider key in the environment; e2e's
replay cache (`.e2e/cache`, committed) then replays them without a model on later runs. Locator-only flows need no
model.
- The flows run as the reviewed commit's own code, in a child process with the capture's narrowed environment, under
the same trust rule as the capture itself (same-repository PRs by authors with write access, or `ci.trustedAuthors`).
- `e2e` writes its report inside the app directory while the flows run (`.expo-explore-flows/`); Explore removes it
before the checkout is verified clean.
- A target or platform can run its own flows: `targets.fold.flows: { tests: [e2e/fold/*.e2e.ts] }` (or `platforms.android.flows`) replaces the top-level `flows` for that target; the others keep it. Within one file, e2e's own `test.describe(..., { platforms: ["ios"] })` already keeps a test to a platform, so a shared list usually suffices.
- To run a few flows without touching the config, name them on the command line: `explore capture --flows e2e/sequencer.e2e.ts,e2e/patterns.e2e.ts` (files or globs, comma-separated) runs those e2e files as the whole capture — flows mode, no route frames — whatever `mode:` says.
- The flows run once per appearance in `capture.appearance` (so twice for `[light, dark]`, after the light pass): a frame the dark pass takes shows up in Compare as the dark pair of its light frame; the Flows view lists the light frames and the steps once.
- Every step the review shows links to its line in the e2e file at the head commit (the Flows view and, for a frame, the inspector's Flow section), when the review names a GitHub repository.
### Agent mode
Keep the app, navigation, device, scope, and capture settings above, then explicitly select agent mode:
+134 -1081
View File
File diff suppressed because it is too large. Load diff
+1 -3
View File
@@ -50,7 +50,7 @@
"test:node": "node --test test/node/*.test.mjs",
"test:hosting": "npm --prefix viewer-host run typecheck && npm --prefix viewer-host test",
"test:viewer:artifacts": "node --test test/browser/artifact-report.browser.mjs test/browser/artifact-cache.browser.mjs",
"test:viewer:browser": "node --test test/browser/flows-view.browser.mjs test/browser/screenshot-image.browser.mjs test/browser/inspector-notes.browser.mjs test/browser/inspector-variants.browser.mjs test/browser/inspector-source-navigation.browser.mjs test/browser/map-edge-presentation.browser.mjs test/browser/local-ci-view.browser.mjs test/browser/report-viewer.browser.mjs",
"test:viewer:browser": "node --test test/browser/screenshot-image.browser.mjs test/browser/inspector-notes.browser.mjs test/browser/inspector-variants.browser.mjs test/browser/inspector-source-navigation.browser.mjs test/browser/map-edge-presentation.browser.mjs test/browser/local-ci-view.browser.mjs test/browser/report-viewer.browser.mjs",
"test:viewer:e2e": "npm run test:viewer:browser && playwright test",
"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p viewer/tsconfig.json --noEmit",
"lint": "eslint .",
@@ -61,12 +61,10 @@
"readme:screenshots": "node scripts/readme-screenshots.mjs"
},
"dependencies": {
"@e2e-dev/mobile": "0.12.3",
"@expo/repack-app": "0.10.1",
"@types/node": "^22.19.19",
"@zip.js/zip.js": "2.16.0",
"ajv": "^8.17.1",
"e2e": "0.21.2",
"pngjs": "7.0.0",
"typescript": "^5.9.3",
"yaml": "^2.9.0",
+7 -7
View File
@@ -1,6 +1,6 @@
---
name: explore-binary
description: Explore a prebuilt mobile app archive (Android .apk, iOS simulator .app, .tar.gz, or simulator .ipa) with Expo Explore. Runs `expo-explore explore:binary`, which installs the archive in a fresh EAS Simulator session (or, with `--simulator local`, on a simulator or emulator it starts on this Mac, with no EAS login), drives it with the local claude or codex login, writes an exploration map and report, and hosts the report on EAS Hosting or opens it in the local Viewer. Use when asked to "run @expo/explore for some.app/.apk", to map or smoke-test an app you only have as a build, or to get screenshots of every screen of a binary. `expo-explore explore:session` does the exploration half alone against an EAS Simulator session you already started (app already installed; result opens in the local Viewer). Also explores an Expo project from its source with no new build: its development build (or Expo Go) on an EAS Simulator, loading JavaScript from a tunneled local dev server. Not for device .ipa files.
description: Explore a prebuilt mobile app archive (Android .apk, iOS simulator .app, .tar.gz, or simulator .ipa) with Expo Explore. Runs `expo-explore explore:binary`, which installs the archive in a fresh EAS Simulator session, drives it with the local claude or codex login, writes an exploration map and report, hosts the report on EAS Hosting, and prints the link. Use when asked to "run @expo/explore for some.app/.apk", to map or smoke-test an app you only have as a build, or to get screenshots of every screen of a binary. `expo-explore explore:session` does the exploration half alone against an EAS Simulator session you already started (app already installed; result opens in the local Viewer). Also explores an Expo project from its source with no new build: its development build (or Expo Go) on an EAS Simulator, loading JavaScript from a tunneled local dev server. Not for device .ipa files.
---
# Explore a prebuilt app
@@ -11,25 +11,25 @@ One command, run from any directory:
npx @expo/explore explore:binary ./path/to/app.apk --json
```
Accepted inputs: Android `.apk`; iOS simulator builds as a `.app` directory, a `.tar.gz`/`.tgz` of one, or an `.ipa` that contains a simulator build. An iOS device `.ipa` and an Android `.aab` are rejected before any device starts (`ARCHIVE_NOT_SIMULATOR`, `ARCHIVE_AAB_UNSUPPORTED`); ask for a simulator build or a universal APK instead.
Accepted inputs: Android `.apk`; iOS simulator builds as a `.app` directory, a `.tar.gz`/`.tgz` of one, or an `.ipa` that contains a simulator build. An iOS device `.ipa` and an Android `.aab` are rejected before any session starts (`ARCHIVE_NOT_SIMULATOR`, `ARCHIVE_AAB_UNSUPPORTED`); ask for a simulator build or a universal/x86_64 APK instead.
Platform, bundle id, app name and version are read from the archive; do not pass them unless Explore asks.
## Before running
- Where it runs. By default on EAS Simulator, which needs an EAS login: `eas whoami` succeeds, or `EXPO_TOKEN` is set. The session and the hosted report live under that account (`--owner` picks one when the login has several, `--project` renames the default `expo-explore` project). Without EAS Simulator access, or without an Expo account, pass `--simulator local`: Explore creates a simulator (iOS, needs Xcode) or an emulator (Android, needs the Android SDK with platform-tools, cmdline-tools, the emulator and a system image for this Mac, and `ANDROID_HOME`) and removes it afterwards. An APK must then ship native libraries for this Mac's ABI (`arm64-v8a` on Apple silicon); a universal one does.
- EAS login: `eas whoami` succeeds, or `EXPO_TOKEN` is set. The session and the hosted report live under that account (`--owner` picks one when the login has several, `--project` renames the default `expo-explore` project).
- A model: Explore tries `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` when set, then the local `claude` login (Claude Code), then the local `codex` login, and uses the first that passes a preflight request. `--provider` or `--model` limits it to that one choice. If none passes, the run stops before a simulator is started.
- Node 24.12 or newer.
## What happens
1. Archive inspection and compatibility checks (size, simulator build, emulator ABI, sha256).
2. `eas simulator:start` of an empty agent-device session (an `argent` one with `--controller argent`), verified by exact session id before use. With `--simulator local`: a new simulator or emulator on this Mac instead, with the app's URL schemes approved so its links open without a prompt.
3. `agent-device install` of the archive straight into the session (Argent: `reinstall-app`; locally `simctl install` or `adb install`), then `open <bundle id>`.
2. `eas simulator:start` of an empty agent-device session (an `argent` one with `--controller argent`), verified by exact session id before use.
3. `agent-device install` of the archive straight into the session (Argent: `reinstall-app`), then `open <bundle id>`.
4. The model explores through a small tool set (observe, act, capture, finish); app text is treated as untrusted and destructive controls (delete, reset, sign out, purchase, send, share) are blocked outside the model.
5. The map and screenshots are written under `--output` (default `./explore-<archive>-<timestamp>`), plus `report/` for the Viewer.
6. The report is sealed and deployed to EAS Hosting (`--no-upload` skips this; `--expires-in 7d|30d|never`). With `--simulator local` it opens in the local Viewer instead, which keeps running until stopped; `--json` and `--no-open` skip it, so with `--json` open it afterwards with `view --dir <output>` (in the background, since it serves until stopped). `--upload` hosts it, and that needs an EAS login.
7. The exact session is stopped, or the local device deleted; a failure to stop reports `SESSION_CLEANUP_FAILED` with the command to stop it by hand. A local device a hard-stopped run left behind is removed by the next local run.
6. The report is sealed and deployed to EAS Hosting (`--no-upload` skips this; `--expires-in 7d|30d|never`).
7. The exact session is stopped; a failure to stop reports `SESSION_CLEANUP_FAILED` with the id to stop by hand.
Budgets default to 15 minutes, 40 screens, 150 actions (`--max-duration-minutes`, `--max-screens`, `--max-actions`). Steer the model with `--hints "focus on the onboarding and settings"`, skip onboarding with `--launch-url myapp://home`, and allow a specific risky control with `--allow-destructive "Clear cache"`.
+5 -6
View File
@@ -5,7 +5,7 @@ description: Set up Expo Explore CI reviews in deterministic or agent mode. Star
# Set up Expo Explore
Make the app ready for CI capture in the user's chosen mode, using its real configuration and source. This is the shared **local authoring skill** for both modes.
Make the app ready for CI capture in the user's chosen mode, using its real configuration and source. This is the shared **local authoring skill** for both modes. Android capture is not available yet.
Explore's tools are app-agnostic: `expo-explore setup` and `expo-explore doctor` know routes, parameters, links and source redirects, but not what the app means by them. **Your job is the app-specific part**: read this app's source to learn which flows (sign-in, onboarding, a subscription, a feature flag, a permission, a record that must exist, …) each screen needs, and write that into this app's `config.yaml` or instructions. Look for what the app actually has; do not assume the flows of another app, and do not impose an account or persona schema.
@@ -164,12 +164,11 @@ npx @expo/explore capture --base v1.3.0 --head v1.4.0 --scope all
- It runs both commits' code as the user (dependency installs, the app config, bundling). Before reviewing a branch the user did not write, say so and ask; credential-free installs are not a sandbox.
- Logins: `EXPO_TOKEN` and the provider's API key when they are set; otherwise the user's `eas login` and their local `claude` or `codex` login for the configured provider. If `eas whoami` fails, tell them to run `eas login`.
- Without `--head`, the head is HEAD plus the working tree's changes, untracked non-ignored files included, which is what `eas build` uploads. It lists them; check that list for secrets the user would not want built. `--committed` reviews HEAD alone, and an `eas.json` with `cli.requireCommit: true` leaves the changes out unless `--uncommitted` is passed.
- Every configured platform or target is reviewed, at once, unless `--target` or `--platform` picks some (`--parallel N` caps how many run together). It opens the report in a local Viewer; `--upload` hosts it instead and prints the link, `--no-open` or `--json` only prints the report paths.
- Without EAS Simulator access, add `--simulator local` (or `capture.simulator: local`): each commit is captured on a simulator Explore creates on this Mac (Xcode) or an emulator (Android SDK), and the app is repacked there too. The native build still comes from EAS. `npx @expo/explore doctor --simulator local` checks that this machine can start each device.
- Every configured platform is reviewed unless `--platform` picks one. It opens the report in a local Viewer; `--upload` hosts it instead and prints the link, `--no-open` or `--json` only prints the report paths.
- Every run is kept on this machine for 30 days: `npx @expo/explore reports list` (or `--json`) shows them, `reports open <id|latest>` reopens one in the local Viewer, and `reports upload <id>` hosts it without capturing again. Run bare in a terminal, `reports` is an arrow-key picker for the user.
- To host a report after the fact, run `npx @expo/explore report:upload <report.zip>...` with the paths it printed (or the `--output` directory's `<target>/report.zip`), one per platform or target. It uses the same project as `--upload` and does not capture again.
- Captures are cached in `~/.cache/expo-explore`, so a second review of the same base does not capture it again (`--no-cache` skips the cache). Ctrl+C stops the simulator sessions and local devices the review started; after a harder stop, the next local review stops what was left running.
- It builds on EAS and, unless it captures locally, runs EAS Simulator sessions, like a CI review: expect several minutes and EAS usage per run.
- To host a report after the fact, run `npx @expo/explore report:upload <report.zip>...` with the paths it printed (or the `--output` directory's `<platform>/report.zip`), one per platform. It uses the same project as `--upload` and does not capture again.
- Captures are cached in `~/.cache/expo-explore`, so a second review of the same base does not capture it again (`--no-cache` skips the cache). Ctrl+C stops the EAS Simulator sessions the review started.
- It builds on EAS and runs simulator sessions, like a CI review: expect several minutes and EAS usage per run.
## Compare any two commits
+3 -3
View File
@@ -1,6 +1,6 @@
---
name: readme-refresh
description: Refresh Expo Explore's README.md with euxy (github.com/brentvatne/euxy) as the reference app. Regenerate every screenshot in docs/screenshots from a current euxy review report and PR comment, then re-read the README as a first-time user: the top level only says what Explore does, links the live euxy example, gives one quick-start prompt to copy that reviews a change to your own app or explores a build you point it to, and one for setting up CI; everything else lives in collapsibles. Use after a Viewer or PR-comment change that the README shows, a new command or setting, or a release that made a README claim stale. Not for the docs/ guides or the shipped skills.
description: Refresh Expo Explore's README.md with euxy (github.com/brentvatne/euxy) as the reference app. Regenerate every screenshot in docs/screenshots from a current euxy review report and PR comment, then re-read the README as a first-time user: the top level only says what Explore does, links the live euxy example, gives numbered quick-start steps for reviewing a change to your own app, a prompt to copy for exploring any build, and one for setting up CI; everything else lives in collapsibles. Use after a Viewer or PR-comment change that the README shows, a new command or setting, or a release that made a README claim stale. Not for the docs/ guides or the shipped skills.
---
# Refresh the README
@@ -60,8 +60,8 @@ Look at every PNG you produced before committing, light and dark: the selected s
Read the README top to bottom once without opening a collapsible. At that level it may only answer, in this order:
1. What Explore is (one short paragraph), the hero image, and the link to the live euxy example (`explore-example--euxy.expo.app`, redeployed on every merge to main by `.github/workflows/example-report.yml`). Under it, one table row of three pictures with a one-line caption each: Compare, Screens, and the PR comment (which says it needs CI), then the agent prompt collapsed as **Ask an agent about a report**. The hero is a zoomed Map framed as a window on a stage (`stagedWindow` in the script); the three below are plain.
2. **Quick start**: one path. A single prompt to paste into Claude Code or Codex that reviews a change to the reader's own Expo app through the explore-setup skill's "Review a change on this machine" section, or, when they point it to a build (or the app is not an Expo project), explores a simulator build through the explore-binary skill. Then one sentence on what each case needs (a review needs an Expo account, is built on EAS, and is captured on EAS Simulator or a local simulator; exploring a build needs a Claude Code or Codex login and EAS Simulator or a local simulator, and no Expo account locally). Then one **Run it yourself** collapsible with both by hand: the numbered steps for a review, with nothing optional in them (make the app buildable on EAS: login, init, bundle identifier, a simulator profile named `explore`, and commit, since the before build is the last commit; then edit a screen near its top and run `capture`, or `capture --simulator local`), and the `explore:binary` commands, including `--simulator local`. Then the `reports` picker image (`readme-reports-*.png`) with one sentence on saved runs, at the top level, and one collapsible for other commits (`--committed`, `--base`/`--head`) and what a review does on the machine. Run the steps on a fresh `create-expo-app` before changing them.
3. **Map every screen of any app**: one sentence on what exploring a build shows (pointing back to the quick start, which runs it), then its collapsibles: its options, exploring a session already started, and what a run without source shows.
2. **Quick start**: the smallest set of steps to see a review of the reader's own Expo app on their machine, numbered and with nothing optional in them: make the app buildable on EAS (login, init, bundle identifier, a simulator profile named `explore`) and commit (the before build is the last commit), then edit a screen near its top and run `capture`, which reviews uncommitted changes as `eas build` would upload them and uses setup's defaults when there is no config. After the steps, a prompt that has Claude Code or Codex do the same through the explore-setup skill's "Review a change on this machine" section. Then the `reports` picker image (`readme-reports-*.png`) with one sentence on saved runs, at the top level, and one collapsible for other commits (`--committed`, `--base`/`--head`) and what a review does on the machine. Run the steps on a fresh `create-expo-app` before changing them.
3. **Map every screen of any app**: one sentence and a prompt to paste into Claude Code or Codex that gets a simulator build of any app (Expo or not, or just a build) and runs `explore:binary` on it. Each section keeps its own "Run it yourself"; never put one section between another's prompt and its collapsibles.
4. **Set up CI**: one sentence, then two subsections, each a sentence on what it gives and a prompt to paste: **Review on every PR** (the setup prompt, then a few grouped collapsibles: Hosted previews first, then Manual setup (the setup prompt's steps done by hand, in order: setup, doctor, secrets, baseline, first PR), Capture modes: deterministic or agent, iOS, Android, or both, Keep your setup current) and **Compare any two commits** (a prompt that follows the explore-setup skill's "Compare any two commits" section, the ways to snapshot a release as bullets, then the comparison workflow collapsed).
Lead with prompts, not explanations: a reader should be able to copy something and see Explore work. Everything else, the manual commands, requirements, options, the manual setup, capture modes, hosted previews, iOS and Android, agent mode, repository settings, how agents read a report, how it works, limitations, contributing, goes into a `<details>` block under the section it belongs to, with a `<summary>` that says what the reader will find. Keep bullets to one or two sentences. Group related collapsibles rather than adding one per topic, so a section shows a handful, not nine. Requirements sit collapsed right under the example report link. Keep the collapsibles' `id` attributes that other docs link to (`#hosted-previews`, `#platforms`, `#compare`, `#agents`); the Terms and How agents read a report collapsibles live under Additional information, and keep the Inspiration section (screenmap and Revyl's Atlas).
+3 -6
View File
@@ -164,13 +164,10 @@ export async function readArchiveIcon(archive: InspectedArchive): Promise<Buffer
}
}
/**
* Explore's EAS Android emulator is x86_64 with no 32-bit support, and a local one runs this Mac's ABI; an APK that
* ships native libraries only for other ABIs fails to install there.
*/
/** Explore's EAS Android emulator is x86_64 with no 32-bit support; an APK that ships only ARM or x86 libraries fails to install there. */
export function assertEmulatorCompatible(archive: InspectedArchive, emulatorAbis: readonly string[] = ["x86_64"]): void {
if (archive.platform === "ios") {
if (!archive.simulator) throw archiveError("ARCHIVE_NOT_SIMULATOR", `${basename(archive.path)} is an iOS device build; it cannot run on a simulator.`,
if (!archive.simulator) throw archiveError("ARCHIVE_NOT_SIMULATOR", `${basename(archive.path)} is an iOS device build; it cannot run on the EAS Simulator.`,
"Build for the simulator (an EAS profile with ios.simulator: true) and pass that .app, .tar.gz, or simulator .ipa.");
return;
}
@@ -180,7 +177,7 @@ export function assertEmulatorCompatible(archive: InspectedArchive, emulatorAbis
}
if (archive.abis.length && !archive.abis.some(abi => emulatorAbis.includes(abi))) {
throw archiveError("ARCHIVE_ABI_UNSUPPORTED", `The APK ships native libraries only for ${archive.abis.join(", ")}; the emulator needs ${emulatorAbis.join(" or ")}.`,
`Build a universal APK or one that includes ${emulatorAbis[0]} native libraries.`, { abis: archive.abis, emulatorAbis: [...emulatorAbis] });
"Build a universal APK or one that includes x86_64 native libraries.", { abis: archive.abis, emulatorAbis: [...emulatorAbis] });
}
}
+62 -167
View File
@@ -13,10 +13,7 @@ import { executeCaptureSetup } from "../capture/setup-actions.js";
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, assertSimulatorSessionIdentity, assertSimulatorStopped, readSimulatorDotenvHandoff,
assertAttachedSimulatorSession, connectionController, controllerVersion, resolveAttachedSimulatorSession, simulatorOsVersion, simulatorStartFailure, type ActiveSimulatorRuntime, type SimulatorConnection } from "../capture/simulator.js";
import { argentControllerInvocation } from "../capture/controller-invocation.js";
import { agentDeviceLauncher, ensureArgentToolServer, ensureController } from "../shared/controller-cache.js";
import { agentDeviceClaims, approveLinkScheme, createLocalSimulator, deleteLocalEmulator, deleteLocalSimulator, hostEmulatorAbi, installOnLocalEmulator, installOnLocalSimulator, startLocalArgentServer,
startLocalEmulator, stopLocalAgentDevice, stopLocalArgentServer, waitForLocalEmulator, waitForLocalSimulator, type LocalArgentServer } from "../capture/local-simulator.js";
import { openLocalCaptureRecord, sweepLocalCaptures } from "../capture/local-registry.js";
import { agentDeviceLauncher, ensureController } from "../shared/controller-cache.js";
import { DEFAULT_ANDROID_DEVICE } from "../config/explore-config.js";
import { createExplorationInputs } from "../config/exploration-inputs.js";
import { ExploreStore, getCoverage } from "../map/store.js";
@@ -53,8 +50,6 @@ export type BinaryExploreOptions = {
project?: string;
/** The session's device controller; agent-device unless Argent is chosen. explore:session takes it from the session. */
controller?: "agent-device" | "argent";
/** Where the app runs: an EAS Simulator session (the default), or a simulator or emulator this run starts on this machine, with no EAS login. */
simulator?: "eas" | "local";
environment?: NodeJS.ProcessEnv;
runner?: typeof defaultRunner;
createSession?: (config: CiAgentSessionConfig, options: { env: NodeJS.ProcessEnv; auth: ModelAuth }) => CiAgentSession;
@@ -76,8 +71,8 @@ export type BinaryExploreResult = {
/** The command and environment that reach a session's controller: agent-device's CLI with its daemon, or the Argent bridge. */
type ControllerInvocation = { command: string; environment: NodeJS.ProcessEnv };
async function argentInvocation(connection: SimulatorConnection, work: string, platform: Platform, environment: NodeJS.ProcessEnv, bundleId?: string, device?: string): Promise<ControllerInvocation> {
return argentControllerInvocation({ directory: work, connection, platform, environment: baseEnvironment(environment), sourceEnvironment: environment, ...(bundleId ? { bundleId } : {}), ...(device ? { device } : {}) });
async function argentInvocation(connection: SimulatorConnection, work: string, platform: Platform, environment: NodeJS.ProcessEnv, bundleId?: string): Promise<ControllerInvocation> {
return argentControllerInvocation({ directory: work, connection, platform, environment: baseEnvironment(environment), sourceEnvironment: environment, ...(bundleId ? { bundleId } : {}) });
}
/** The daemon refuses a second session on a busy device; the caller's own `agent-device` session (from install/open) is reused instead. */
@@ -272,16 +267,11 @@ export type ConnectedSessionExploration = {
urlSchemes?: readonly string[];
/** The app's icon from the archive for the Viewer header. */
appIcon?: Buffer;
/**
* A simulator or emulator on this machine instead of an EAS session: the controller drives it by its UDID or adb
* serial (agent-device with a daemon of its own in `stateDirectory`, or a local Argent tool-server pinned to it).
*/
local?: { deviceId: string; osVersion: string; stateDirectory: string };
};
/** Drives an agent-device daemon we already hold a connection to: optional install, open, then the model-led exploration. */
export async function exploreConnectedSession(ctx: ConnectedSessionExploration): Promise<{ runtime: ActiveSimulatorRuntime; exploration: BlackBoxExplorerResult }> {
const { connection, platform, device, bundleId, app, install, work, runner, environment, secrets, inputs, say, now, limits, store, map, model, sessionJson, launchUrl, hints, allowDestructive, local } = ctx;
const { connection, platform, device, bundleId, app, install, work, runner, environment, secrets, inputs, say, now, limits, store, map, model, sessionJson, launchUrl, hints, allowDestructive } = ctx;
const controllerSession = ctx.controllerSession ?? CONTROLLER_SESSION;
const controllerKind = connectionController(connection);
const controllerName = controllerKind === "argent" ? "Argent" : "agent-device";
@@ -289,18 +279,15 @@ export async function exploreConnectedSession(ctx: ConnectedSessionExploration):
let agentDevice: string;
let controllerEnvironment: NodeJS.ProcessEnv;
if (controllerKind === "argent") {
({ command: agentDevice, environment: controllerEnvironment } = await argentInvocation(connection, work, platform, environment, bundleId, local?.deviceId));
({ command: agentDevice, environment: controllerEnvironment } = await argentInvocation(connection, work, platform, environment, bundleId));
} else {
const controllerConfig = join(work, "agent-device.json");
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
// A local device has no EAS daemon: agent-device runs its own, in a state directory of this run's.
controllerEnvironment = { ...baseEnvironment(environment), AGENT_DEVICE_CONFIG: controllerConfig,
...(local ? { AGENT_DEVICE_STATE_DIR: local.stateDirectory } : { AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken }),
AGENT_DEVICE_SESSION: controllerSession, AGENT_DEVICE_SESSION_LOCK: "reject", AGENT_DEVICE_PLATFORM: platform };
controllerEnvironment = { ...baseEnvironment(environment), AGENT_DEVICE_CONFIG: controllerConfig, AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl,
AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken, AGENT_DEVICE_SESSION: controllerSession, AGENT_DEVICE_SESSION_LOCK: "reject", AGENT_DEVICE_PLATFORM: platform };
agentDevice = agentDeviceLauncher(environment);
}
// A local device is named for Explore, so it is picked by its UDID or serial rather than its model name.
const deviceArgs = local ? [platform === "ios" ? "--udid" : "--serial", local.deviceId] : platform === "ios" ? ["--device", device] : [];
const deviceArgs = platform === "ios" ? ["--device", device] : [];
const controller = (args: string[], timeoutMs = 90_000): CommandResult => {
// Session flags go before a `--` separator so model-chosen text (`type -h`, a URL, a label) is never read as a flag.
const separator = args.indexOf("--");
@@ -317,17 +304,16 @@ export async function exploreConnectedSession(ctx: ConnectedSessionExploration):
try { controller(["install", install.path, "--json"], 15 * 60_000); }
catch (error) { throw binaryError("APP_INSTALL_FAILED", `${controllerName} could not install the app: ${failureText(error)}`, "Check that the archive is a simulator build for this platform and under the size limit, then rerun.", { sessionId: connection.sessionId }); }
}
// On a local device, the first open also builds agent-device's iOS runner.
const opened = controller(["open", bundleId, "--level", "full", "--json"], local ? 15 * 60_000 : 2 * 60_000);
const opened = controller(["open", bundleId, "--level", "full", "--json"], 2 * 60_000);
const openedDevice = openedSimulatorDevice(opened.stdout, bundleId, "initial app open", platform, controllerSession);
const data = controllerData(opened.stdout, "initial app open");
const deviceData = data.device && typeof data.device === "object" ? data.device as Record<string, unknown> : {};
const observed = (key: string): string => { const value = deviceData[key] ?? data[key]; return typeof value === "string" && value.trim() ? value : "unknown"; };
const runtime = { provider: local ? "local-simulator" : "eas-simulator", controller: controllerKind, controllerPackageVersion: controllerVersion(controllerKind), easCliVersion: "unknown", platform, controllerDeviceId: openedDevice.deviceId,
deviceModel: local ? device : openedDevice.deviceModel, osVersion: local ? local.osVersion : observed("osVersion"), locale: observed("locale"), orientation: observed("orientation") === "landscape" ? "landscape" : "portrait",
const runtime = { provider: "eas-simulator", controller: controllerKind, controllerPackageVersion: controllerVersion(controllerKind), easCliVersion: "unknown", platform, controllerDeviceId: openedDevice.deviceId,
deviceModel: openedDevice.deviceModel, osVersion: observed("osVersion"), locale: observed("locale"), orientation: observed("orientation") === "landscape" ? "landscape" : "portrait",
colorScheme: observed("colorScheme") === "dark" ? "dark" : "light" } as ActiveSimulatorRuntime;
// Argent's `open` reports the OS version itself (list-devices); agent-device's comes from the session's preview.
if (!local && (runtime.osVersion === "unknown" || controllerKind !== "argent")) try { runtime.osVersion = await simulatorOsVersion(sessionJson(), runtime.controllerDeviceId, fetch, platform); } catch { /* descriptive only */ }
if (runtime.osVersion === "unknown" || controllerKind !== "argent") try { runtime.osVersion = await simulatorOsVersion(sessionJson(), runtime.controllerDeviceId, fetch, platform); } catch { /* descriptive only */ }
map.run.deviceId = runtime.controllerDeviceId;
map.run.environment = { deviceModel: runtime.deviceModel, osVersion: runtime.osVersion, locale: runtime.locale, orientation: runtime.orientation, colorScheme: runtime.colorScheme };
map.run.status = "exploring";
@@ -586,75 +572,6 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
}
}
type LocalDevice = NonNullable<ConnectedSessionExploration["local"]>;
/**
* Starts a simulator or emulator on this machine for one run, installs the app, and hands the explorer a connection
* to it; everything is stopped afterwards. They are the devices `capture --simulator local` starts, recorded the same
* way, so the next local run stops what a run stopped hard left behind.
*/
async function withLocalDevice(options: { archive: InspectedArchive; installPath: string; platform: Platform; device: string; bundleId: string;
controller: "agent-device" | "argent"; tag: string; work: string; runner: typeof defaultRunner; environment: NodeJS.ProcessEnv; secrets: readonly string[]; say: (message: string) => void; now?: () => number },
explore: (connection: SimulatorConnection, local: LocalDevice) => Promise<void>): Promise<void> {
const { archive, installPath, platform, device, bundleId, controller, tag, work, runner, say } = options;
const environment = baseEnvironment(options.environment);
const agentDevice = agentDeviceLauncher(options.environment);
const stateDirectory = join(work, "agent-device-state");
const record = await openLocalCaptureRecord(options.environment, work);
let udid: string | undefined, serial: string | undefined, argent: LocalArgentServer | undefined;
let primaryError: unknown;
try {
let osVersion: string;
if (platform === "ios") {
say(`starting a local ${device} simulator`);
const created = await createLocalSimulator({ runner, device, name: `Explore ${device} (binary ${tag})`, cwd: work, environment,
created: async id => { udid = id; await record.update({ udid: id }); } });
osVersion = created.osVersion;
waitForLocalSimulator({ runner, udid: created.udid, cwd: work, environment });
// Links in the app's own schemes open without iOS asking first.
for (const scheme of archive.urlSchemes) approveLinkScheme({ runner, udid: created.udid, scheme, bundleId, cwd: work, environment });
say("installing the app");
installOnLocalSimulator({ runner, udid: created.udid, app: installPath, cwd: work, environment });
} else {
say(`starting a local ${device} emulator`);
const name = `explore-binary-${tag}`;
const started = await startLocalEmulator({ runner, device, name, directory: work, cwd: work, environment,
...(controller === "agent-device" ? { claimed: (candidate: string) => agentDeviceClaims({ runner, agentDevice, serial: candidate, cwd: work, environment }) } : {}),
started: async id => { serial = id; await record.update({ serial: id, avd: name }); } });
osVersion = waitForLocalEmulator({ runner, serial: started.serial, device, apiLevel: started.apiLevel, directory: work, cwd: work, environment, ...(options.now ? { now: options.now } : {}) });
say("installing the APK");
installOnLocalEmulator({ runner, serial: started.serial, apk: installPath, cwd: work, environment });
}
const deviceId = (udid ?? serial)!;
let connection: SimulatorConnection = { sessionId: `local-${deviceId}`, daemonBaseUrl: "", daemonAuthToken: "" };
if (controller === "argent") {
// Argent drives the device through a tool-server of this run's own.
const cli = await ensureArgentToolServer({ environment: options.environment, progress: say });
argent = await startLocalArgentServer({ runner, cli, directory: work, cwd: work, environment, ...(options.now ? { now: options.now } : {}) });
await record.update({ argent: { pid: argent.pid, cli: argent.cli, home: argent.home } });
connection = { ...connection, daemonBaseUrl: argent.url, daemonAuthToken: argent.token, controller: "argent" };
}
await explore(connection, { deviceId, osVersion, stateDirectory });
} catch (error) { primaryError = error; throw error; }
finally {
try {
if (argent) stopLocalArgentServer(argent);
// Its own agent-device daemon lets go of the device before it goes.
if (controller === "agent-device") runner({ command: agentDevice, args: ["close", "--session", CONTROLLER_SESSION, "--json"], cwd: work,
environment: { ...environment, AGENT_DEVICE_STATE_DIR: stateDirectory }, timeoutMs: 60_000, allowFailure: true });
await stopLocalAgentDevice(stateDirectory);
if (serial) { say(`stopping the local emulator ${serial}`); await deleteLocalEmulator({ runner, serial, cwd: work, environment }); }
if (udid) { say(`deleting the local simulator ${udid}`); deleteLocalSimulator({ runner, udid, cwd: work, environment }); }
// Everything is stopped; a cleanup that threw leaves the record for the next run's sweep.
await record.close();
} catch (error) {
throw new CiError({ code: "SESSION_CLEANUP_FAILED", stage: "cleanup", message: `The local ${serial ? "emulator" : "simulator"} Explore started could not be stopped.`,
nextAction: serial ? `Stop it with: adb -s ${serial} emu kill` : udid ? `Delete it with: xcrun simctl delete ${udid}` : "Rerun explore:binary --simulator local; it stops what this run left.",
details: { ...(serial ? { serial } : {}), ...(udid ? { udid } : {}), ...(primaryError ? { originalFailure: serializeCiError(primaryError, { secrets: options.secrets }) } : {}) }, cause: error });
}
}
}
export async function runBinaryExploration(options: BinaryExploreOptions): Promise<BinaryExploreResult> {
const startedAt = Date.now();
const now = options.now ?? Date.now;
@@ -663,21 +580,18 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
const runner = options.runner ?? defaultRunner;
const limits = validatedLimits(options);
const inputs = hintInputs(options.hints, environment);
const local = options.simulator === "local";
// A local emulator runs this Mac's ABI (arm64-v8a on Apple silicon); EAS's runs x86_64.
const emulatorAbi = local ? hostEmulatorAbi() : "x86_64";
say("inspecting the archive");
const archive = await inspectArchive(options.archive);
assertEmulatorCompatible(archive, [emulatorAbi]);
assertEmulatorCompatible(archive);
if (options.platform && options.platform !== archive.platform) throw binaryError("ARCHIVE_PLATFORM_MISMATCH", `The archive is an ${archive.platform} build but --platform ${options.platform} was requested.`, "Drop --platform or pass a matching archive.");
if (!local && !environment.EXPO_TOKEN?.trim() && !environment.EXPO_SESSION_SECRET?.trim() && !(await easLoggedIn(runner, environment))) {
if (!environment.EXPO_TOKEN?.trim() && !environment.EXPO_SESSION_SECRET?.trim() && !(await easLoggedIn(runner, environment))) {
throw binaryError("EXPO_LOGIN_REQUIRED", "No EAS login was found.", "Run `eas login` or set EXPO_TOKEN, then rerun explore:binary.");
}
const platform = archive.platform;
const bundleId = options.bundleId ?? archive.bundleId;
const device = options.device ?? (platform === "ios" ? DEFAULT_IOS_DEVICE : DEFAULT_ANDROID_DEVICE);
say(`${archive.appName} ${archive.version ?? ""} (${bundleId}, ${platform}, ${(archive.bytes / 1048576).toFixed(0)} MB, sha256 ${archive.sha256.slice(0, 12)})`);
if (archive.missingLibs?.length && emulatorAbi === "x86_64") say(`warning: lib/x86_64 lacks ${archive.missingLibs.slice(0, 4).join(", ")}${archive.missingLibs.length > 4 ? ` and ${archive.missingLibs.length - 4} more` : ""} that another ABI ships; the app may stop with UnsatisfiedLinkError on the emulator`);
if (archive.missingLibs?.length) say(`warning: lib/x86_64 lacks ${archive.missingLibs.slice(0, 4).join(", ")}${archive.missingLibs.length > 4 ? ` and ${archive.missingLibs.length - 4} more` : ""} that another ABI ships; the app may stop with UnsatisfiedLinkError on the emulator`);
const model = await preflightModelSession(options, environment, say);
@@ -687,7 +601,7 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
const work = await realpath(await mkdtemp(join(tmpdir(), "expo-explore-binary-")));
const easEnvironment = { ...baseEnvironment(environment), ...(environment.EXPO_TOKEN ? { EXPO_TOKEN: environment.EXPO_TOKEN } : {}), ...(environment.HOME ? { HOME: environment.HOME } : {}), CI: "1", EXPO_NO_TELEMETRY: "1" };
const easBin = packageBin("eas-cli", "eas");
if (!local) await lstat(easBin).catch(() => { throw binaryError("EXPLORE_TOOLS_MISSING", "The EAS CLI that Explore pins is not installed.", "Reinstall @expo/explore with optional dependencies."); });
await lstat(easBin).catch(() => { throw binaryError("EXPLORE_TOOLS_MISSING", "The EAS CLI that Explore pins is not installed.", "Reinstall @expo/explore with optional dependencies."); });
const eas = (args: string[], timeoutMs = 5 * 60_000): CommandResult & { status: number } => {
try { return { ...runner({ command: process.execPath, args: [easBin, ...args], cwd: work, environment: easEnvironment, timeoutMs }), status: 0 }; }
catch (error) { return { stdout: "", stderr: error instanceof Error ? error.message : String(error), status: 1 }; }
@@ -701,11 +615,6 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
const controller = options.controller ?? "agent-device";
// Fetched before the paid session starts, so a blocked download costs nothing.
if (!options.runner) await ensureController(controller, { environment, progress: say });
if (local) {
// What an earlier local run stopped hard left running (a simulator, an emulator, a daemon) goes first.
const swept = await sweepLocalCaptures({ environment, runner, cwd: work }).catch(() => [] as string[]);
if (swept.length) say(`stopped what an interrupted local run left running: ${swept.join(", ")}`);
}
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: archive.appName, platform, controller, exploration: "black-box", bundleId, status: "draft",
createdAt: new Date(now()).toISOString(), updatedAt: new Date(now()).toISOString(),
build: { ...(archive.version ? { version: archive.version } : {}), ...(archive.buildNumber ? { number: archive.buildNumber } : {}), hash: archive.sha256, source: "local" },
@@ -713,71 +622,57 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
try {
let installPath = archive.path;
if (archive.kind === "ios-tgz" || archive.kind === "ios-ipa") { say("unpacking the iOS bundle"); installPath = await extractIosBundle(archive, join(work, "bundle")); }
const appIcon = await readArchiveIcon(archive);
const exploreOn = (connection: SimulatorConnection, sessionJson: () => string, localDevice?: LocalDevice) => exploreConnectedSession({ connection, platform, device, bundleId,
...(appIcon ? { appIcon } : {}), app: { name: archive.appName, ...(archive.version ? { version: archive.version } : {}) },
// A local device has the app installed by simctl or adb before the controller starts.
...(localDevice ? { local: localDevice } : { install: { path: installPath, kind: archive.kind } }),
work, runner, environment, secrets: [environment.EXPO_TOKEN ?? "", connection.daemonAuthToken, ...inputs.values].filter(Boolean), inputs, say, now, limits, store, map, model,
urlSchemes: archive.urlSchemes, sessionJson,
...(options.launchUrl ? { launchUrl: options.launchUrl } : {}), ...(options.hints ? { hints: options.hints } : {}), ...(options.allowDestructive ? { allowDestructive: options.allowDestructive } : {}) });
if (local) {
const tag = map.run.id.replace(/-/g, "").slice(0, 8);
await withLocalDevice({ archive, installPath, platform, device, bundleId, controller, tag, work, runner, environment, say, secrets: inputs.values, ...(options.now ? { now: options.now } : {}) },
async (connection, localDevice) => {
sessionId = connection.sessionId;
({ runtime, exploration } = await exploreOn(connection, () => "", localDevice));
});
} else {
if (!owner) {
const who = eas(["whoami"], 60_000);
owner = who.status === 0 ? whoamiAccounts(who.stdout)[0] ?? "" : "";
if (!owner) throw binaryError("EXPO_LOGIN_REQUIRED", "EAS did not report an account for this login.", "Run `eas login` (or set EXPO_TOKEN) and rerun, or pass --owner.");
}
await writeFile(join(work, "package.json"), JSON.stringify({ name: project, version: "0.0.0", private: true }), { mode: 0o600 });
await writeFile(join(work, "app.json"), JSON.stringify({ expo: { name: project, slug: project, owner, web: { output: "server" } } }), { mode: 0o600 });
const init = eas(["init", "--force", "--non-interactive", "--json"], 2 * 60_000);
const appJson = JSON.parse(await readFile(join(work, "app.json"), "utf8")) as { expo?: { extra?: { eas?: { projectId?: string } } } };
const projectId = appJson.expo?.extra?.eas?.projectId;
if (init.status !== 0 || !projectId) throw binaryError("EXPLORE_PROJECT_FAILED", `EAS could not create or link @${owner}/${project}: ${lastLine(init.stderr || init.stdout)}`,
"Give this login permission to create projects under the owner, or pass --project with an existing slug.", { owner, project });
const projectIdentity = { name: project, slug: project, owner, projectId };
say(`starting an EAS Simulator session (${device}, ${limits.maxDurationMinutes} min)`);
const sessionName = `explore-binary-${createHash("sha256").update(`${archive.sha256}:${map.run.id}`).digest("hex").slice(0, 16)}`;
const dotenvPath = join(work, SIMULATOR_DOTENV_FILE_NAME);
await writeFile(dotenvPath, SIMULATOR_DOTENV_HEADER, { flag: "wx", mode: 0o600 });
let startError: unknown;
try {
const started = eas(["simulator:start", "--name", sessionName, "--platform", platform, "--device", device, "--type", controller, "--package-version", controllerVersion(controller), "--public-link",
"--max-duration-minutes", String(limits.maxDurationMinutes + 5), "--out-config-type", "dotenv", "--non-interactive"], 20 * 60_000);
if (started.status !== 0) throw new Error(started.stderr || started.stdout || "eas simulator:start failed");
} catch (error) { startError = error; }
const handoff = await readSimulatorDotenvHandoff(dotenvPath);
const secrets = [environment.EXPO_TOKEN ?? "", ...(handoff.connection ? [handoff.connection.daemonAuthToken] : []), ...inputs.values].filter(Boolean);
const startFailure = startError ? simulatorStartFailure(startError, secrets) : undefined;
if (handoff.sessionId) {
try { assertSimulatorSessionIdentity(eas(["simulator:get", "--id", handoff.sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout, handoff.sessionId, sessionName, projectIdentity, handoff.connection, platform); }
catch (error) { throw new CiError({ code: "SESSION_HANDOFF_UNVERIFIED", stage: "session", message: "The EAS handoff could not prove ownership of the exact simulator session. The private handoff was preserved.",
nextAction: "Inspect the EAS session list; confirm ownership before stopping the reported session.", details: { handoffDirectory: work, reportedSessionId: handoff.sessionId, ...(startFailure ? { startFailure } : {}) }, cause: error }); }
sessionId = handoff.sessionId;
}
if (!sessionId) throw new CiError({ code: startFailure ? "SIMULATOR_START_FAILED" : "SESSION_HANDOFF_UNVERIFIED", stage: "session",
message: startFailure ? `EAS simulator:start failed: ${startFailure.message}` : "EAS did not provide a verifiable simulator session.",
nextAction: "Inspect the EAS start failure and session list; verify a session's exact ID and ownership before cleanup.", details: { handoffDirectory: work, ...(startFailure ? { startFailure } : {}) }, cause: startError });
if (startFailure) throw new CiError({ code: "SIMULATOR_START_FAILED", stage: "session", message: `EAS simulator:start failed after the session was verified: ${startFailure.message}`,
nextAction: "Inspect the start failure; Explore stops the verified session before returning.", details: { sessionId, startFailure }, cause: startError });
if (handoff.validationError) throw handoff.validationError;
if (!handoff.connection) throw new Error("Simulator handoff is missing its controller connection");
await rm(dotenvPath, { force: true });
({ runtime, exploration } = await exploreOn(handoff.connection, () => eas(["simulator:get", "--id", handoff.connection!.sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout));
if (!owner) {
const who = eas(["whoami"], 60_000);
owner = who.status === 0 ? whoamiAccounts(who.stdout)[0] ?? "" : "";
if (!owner) throw binaryError("EXPO_LOGIN_REQUIRED", "EAS did not report an account for this login.", "Run `eas login` (or set EXPO_TOKEN) and rerun, or pass --owner.");
}
await writeFile(join(work, "package.json"), JSON.stringify({ name: project, version: "0.0.0", private: true }), { mode: 0o600 });
await writeFile(join(work, "app.json"), JSON.stringify({ expo: { name: project, slug: project, owner, web: { output: "server" } } }), { mode: 0o600 });
const init = eas(["init", "--force", "--non-interactive", "--json"], 2 * 60_000);
const appJson = JSON.parse(await readFile(join(work, "app.json"), "utf8")) as { expo?: { extra?: { eas?: { projectId?: string } } } };
const projectId = appJson.expo?.extra?.eas?.projectId;
if (init.status !== 0 || !projectId) throw binaryError("EXPLORE_PROJECT_FAILED", `EAS could not create or link @${owner}/${project}: ${lastLine(init.stderr || init.stdout)}`,
"Give this login permission to create projects under the owner, or pass --project with an existing slug.", { owner, project });
const projectIdentity = { name: project, slug: project, owner, projectId };
say(`starting an EAS Simulator session (${device}, ${limits.maxDurationMinutes} min)`);
const sessionName = `explore-binary-${createHash("sha256").update(`${archive.sha256}:${map.run.id}`).digest("hex").slice(0, 16)}`;
const dotenvPath = join(work, SIMULATOR_DOTENV_FILE_NAME);
await writeFile(dotenvPath, SIMULATOR_DOTENV_HEADER, { flag: "wx", mode: 0o600 });
let startError: unknown;
try {
const started = eas(["simulator:start", "--name", sessionName, "--platform", platform, "--device", device, "--type", controller, "--package-version", controllerVersion(controller), "--public-link",
"--max-duration-minutes", String(limits.maxDurationMinutes + 5), "--out-config-type", "dotenv", "--non-interactive"], 20 * 60_000);
if (started.status !== 0) throw new Error(started.stderr || started.stdout || "eas simulator:start failed");
} catch (error) { startError = error; }
const handoff = await readSimulatorDotenvHandoff(dotenvPath);
const secrets = [environment.EXPO_TOKEN ?? "", ...(handoff.connection ? [handoff.connection.daemonAuthToken] : []), ...inputs.values].filter(Boolean);
const startFailure = startError ? simulatorStartFailure(startError, secrets) : undefined;
if (handoff.sessionId) {
try { assertSimulatorSessionIdentity(eas(["simulator:get", "--id", handoff.sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout, handoff.sessionId, sessionName, projectIdentity, handoff.connection, platform); }
catch (error) { throw new CiError({ code: "SESSION_HANDOFF_UNVERIFIED", stage: "session", message: "The EAS handoff could not prove ownership of the exact simulator session. The private handoff was preserved.",
nextAction: "Inspect the EAS session list; confirm ownership before stopping the reported session.", details: { handoffDirectory: work, reportedSessionId: handoff.sessionId, ...(startFailure ? { startFailure } : {}) }, cause: error }); }
sessionId = handoff.sessionId;
}
if (!sessionId) throw new CiError({ code: startFailure ? "SIMULATOR_START_FAILED" : "SESSION_HANDOFF_UNVERIFIED", stage: "session",
message: startFailure ? `EAS simulator:start failed: ${startFailure.message}` : "EAS did not provide a verifiable simulator session.",
nextAction: "Inspect the EAS start failure and session list; verify a session's exact ID and ownership before cleanup.", details: { handoffDirectory: work, ...(startFailure ? { startFailure } : {}) }, cause: startError });
if (startFailure) throw new CiError({ code: "SIMULATOR_START_FAILED", stage: "session", message: `EAS simulator:start failed after the session was verified: ${startFailure.message}`,
nextAction: "Inspect the start failure; Explore stops the verified session before returning.", details: { sessionId, startFailure }, cause: startError });
if (handoff.validationError) throw handoff.validationError;
if (!handoff.connection) throw new Error("Simulator handoff is missing its controller connection");
await rm(dotenvPath, { force: true });
const appIcon = await readArchiveIcon(archive);
({ runtime, exploration } = await exploreConnectedSession({ connection: handoff.connection, platform, device, bundleId, ...(appIcon ? { appIcon } : {}), app: { name: archive.appName, ...(archive.version ? { version: archive.version } : {}) },
install: { path: installPath, kind: archive.kind }, work, runner, environment, secrets, inputs, say, now, limits, store, map, model, urlSchemes: archive.urlSchemes,
sessionJson: () => eas(["simulator:get", "--id", handoff.connection!.sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout,
...(options.launchUrl ? { launchUrl: options.launchUrl } : {}), ...(options.hints ? { hints: options.hints } : {}), ...(options.allowDestructive ? { allowDestructive: options.allowDestructive } : {}) }));
} catch (error) {
primaryError = toCiError(error, { code: "EXPLORE_BINARY_FAILED", stage: "exploration", nextAction: "Inspect the diagnostic, correct the failing prerequisite, and rerun explore:binary." });
} finally {
// A local device is stopped by withLocalDevice; only the work directory is left.
if (local) await rm(work, { recursive: true, force: true });
else if (sessionId) {
if (sessionId) {
try {
say(`stopping simulator session ${sessionId}`);
assertSimulatorStopped(eas(["simulator:stop", "--id", sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout, sessionId);
+1 -1
View File
@@ -16,7 +16,7 @@ export async function prepareCiExploration(config: ExploreConfig, project: strin
if (!active) return { instructionsSha256: instructions?.sha256, agent: undefined };
const inputs = createExplorationInputs({ ...(instructions ? { instructions: instructions.text } : {}),
...(config.setup ? { setup: config.setup } : {}), environment });
if (config.mode !== "agent") return { instructionsSha256: undefined, agent: undefined };
if (config.mode === "deterministic") return { instructionsSha256: undefined, agent: undefined };
if (!options.subscription) assertExecutionMode(config, environment);
const tracked = spawnSync("git", ["-C", project, "ls-files", "--error-unmatch", "--", config.agent!.instructions!], { encoding: "utf8" });
if (tracked.status !== 0) throw new CiError({ code: "AGENT_INSTRUCTIONS_UNCOMMITTED", stage: "preflight",
-101
View File
@@ -1,101 +0,0 @@
/**
* Reads what an e2e run (the `e2e` package's `report.json`) says about each flow: its status, its steps, and the
* frames `app.screenshot(label)` took. Nothing here touches a device; the worker produces the report and the host
* turns these summaries into bundle evidence.
*/
import type { FlowStatus, FlowStepStatus } from "../../contracts/capture.js";
export type FlowFrameSummary = { key: string; label: string; path: string; stepIndex: number; capturedAt: string };
export type FlowStepSummary = { api: string; label: string; status: FlowStepStatus; durationMs: number; frame?: string; error?: { code: string; message: string };
/** The line of the test file the step was called from, when e2e recorded one. */
line?: number };
export type FlowTestSummary = {
id: string; file: string; title: string; status: FlowStatus; durationMs: number;
error?: { code: string; message: string };
/** The line of the test file the test is declared on, when e2e recorded one. */
line?: number;
steps: FlowStepSummary[];
frames: FlowFrameSummary[];
};
const FLOW_STATUSES: readonly FlowStatus[] = ["passed", "failed", "skipped", "flaky", "timed-out", "interrupted", "blocked"];
const STEP_STATUSES: readonly FlowStepStatus[] = ["passed", "failed", "blocked", "timed-out", "cancelled"];
const isRecord = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === "object" && !Array.isArray(value);
const text = (value: unknown, fallback = ""): string => typeof value === "string" ? value : fallback;
const count = (value: unknown): number => typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.round(value) : 0;
/** A path segment from free text: lower case, `-` between words, at most 64 characters, never empty. */
export function flowSlug(value: string): string {
const slug = value.toLowerCase().replace(/\.e2e\.[cm]?[jt]sx?$/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64).replace(/-+$/, "");
return slug || "flow";
}
/** The flow's identity across revisions: its file (without `tests/` and the extension) and its title, both slugged. */
export function flowId(file: string, titlePath: readonly string[]): string {
const stem = file.replace(/\\/g, "/").replace(/^(\.\/)?(tests?|e2e|flows)\//, "");
return `${flowSlug(stem)}/${flowSlug(titlePath.join(" "))}`;
}
function serializedError(value: unknown): { code: string; message: string } | undefined {
if (!isRecord(value)) return undefined;
return { code: text(value.code, "ERROR").slice(0, 64), message: text(value.message).slice(0, 2_000) };
}
/** Every selected test of the report, with the attempt the run counted (the last one). */
/** A frame the worker took after a step ended, when the capture asks for a frame per step. */
export type StepFrameFile = { stepIndex: number; path: string; capturedAt: string };
export function summarizeFlowReport(report: unknown, stepFrames?: ReadonlyMap<string, readonly StepFrameFile[]>): FlowTestSummary[] {
if (!isRecord(report) || !isRecord(report.run) || !Array.isArray(report.run.results)) throw new Error("The e2e report has no run results");
const artifacts = new Map<string, Record<string, unknown>>();
const summaries: FlowTestSummary[] = [];
for (const result of report.run.results) {
if (!isRecord(result) || result.selected === false) continue;
const file = text(result.file);
const titlePath = Array.isArray(result.titlePath) ? result.titlePath.filter((part): part is string => typeof part === "string") : [];
const attempts = Array.isArray(result.attempts) ? result.attempts.filter(isRecord) : [];
const attempt = attempts.at(-1);
for (const artifact of Array.isArray(attempt?.artifacts) ? attempt.artifacts : []) if (isRecord(artifact) && typeof artifact.id === "string") artifacts.set(artifact.id, artifact);
const status = FLOW_STATUSES.includes(result.status as FlowStatus) ? result.status as FlowStatus : "failed";
const steps: FlowStepSummary[] = [];
const frames: FlowFrameSummary[] = [];
const keys = new Map<string, number>();
for (const step of Array.isArray(attempt?.steps) ? attempt.steps.filter(isRecord) : []) {
const summary: FlowStepSummary = { api: text(step.api, "step").slice(0, 64), label: text(step.label).slice(0, 256),
status: STEP_STATUSES.includes(step.status as FlowStepStatus) ? step.status as FlowStepStatus : "failed", durationMs: count(step.durationMs) };
const error = serializedError(step.error);
if (error) summary.error = error;
if (isRecord(step.source) && step.source.file === file && Number.isSafeInteger(step.source.line) && (step.source.line as number) > 0) summary.line = step.source.line as number;
if (summary.api === "app.screenshot" && summary.status === "passed" && Array.isArray(step.artifacts) && step.artifacts.length === 1) {
const artifact = artifacts.get(String(step.artifacts[0]));
if (artifact?.kind === "screenshot" && typeof artifact.path === "string") {
const base = flowSlug(summary.label || "screenshot");
const seen = (keys.get(base) ?? 0) + 1;
keys.set(base, seen);
const key = seen === 1 ? base : `${base}-${seen}`;
summary.frame = key;
frames.push({ key, label: summary.label, path: artifact.path, stepIndex: steps.length, capturedAt: text(step.startedAt) });
}
}
steps.push(summary);
}
// Per-step frames fill in the steps that took no frame of their own, in the step's place.
for (const file of stepFrames?.get(text(result.testId) || text(result.id)) ?? []) {
const step = steps[file.stepIndex];
if (!step || step.frame !== undefined) continue;
const base = `step-${file.stepIndex + 1}`;
const seen = (keys.get(base) ?? 0) + 1;
keys.set(base, seen);
const key = seen === 1 ? base : `${base}-${seen}`;
step.frame = key;
frames.push({ key, label: `${file.stepIndex + 1}. ${step.label || step.api}`.slice(0, 80), path: file.path, stepIndex: file.stepIndex, capturedAt: file.capturedAt });
}
frames.sort((a, b) => a.stepIndex - b.stepIndex);
const summaryError = serializedError(attempt?.error);
const line = isRecord(result.source) && result.source.file === file && Number.isSafeInteger(result.source.line) && (result.source.line as number) > 0 ? result.source.line as number : undefined;
summaries.push({ id: flowId(file, titlePath), file, title: titlePath.join(" › "), status, durationMs: count(attempt?.durationMs),
...(summaryError ? { error: summaryError } : {}), ...(line ? { line } : {}), steps, frames });
}
return summaries;
}
-140
View File
@@ -1,140 +0,0 @@
/**
* Runs the app's e2e flows on the capture's device and turns the frames they took into bundle evidence. The flows
* are the `e2e` package's test files; Explore adds nothing to their language. A flow that fails keeps the frames it
* took before failing, and the capture goes on: flows are review evidence, not a gate.
*/
import { createHash } from "node:crypto";
import { copyFile, lstat, mkdir, readFile, readdir, realpath, rm, writeFile, mkdtemp, rmdir } from "node:fs/promises";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
import { homeIndicatorBandPercent, statusBarBandPercent, type BundleFlow, type FlowFrame } from "../../contracts/capture.js";
import { assertDecodedPng, contentSha256 } from "../../shared/png-evidence.js";
import { CONTROLLER_SESSION } from "../common.js";
import type { CommandRunner } from "../run.js";
import type { SimulatorConnection } from "../simulator.js";
import type { FlowsRequest, FlowsResult } from "./worker.js";
export const FLOWS_WORKER = fileURLToPath(new URL("./worker-main.js", import.meta.url));
/** The agent-device session the flows drive the device under, beside Explore's own locked session. */
/**
* The agent-device session the flows use: Explore's own. A daemon lets one session hold a device; a second session name
* connects but cannot open the app ("Device is already in use by session expo-explore-runtime", seen on EAS Simulator).
*/
export const FLOWS_SESSION = CONTROLLER_SESSION;
/** Where e2e writes while the flows run, inside the app directory as e2e requires; removed once the frames are copied out. */
export const FLOWS_OUTPUT_DIRECTORY = ".expo-explore-flows";
const MAX_FRAME_BYTES = 30 * 1024 * 1024;
export type RunFlowsOptions = {
project: string;
tests: readonly string[];
platform: "ios" | "android";
bundleId: string;
connection?: SimulatorConnection | undefined;
/** The local agent-device daemon's state directory when the capture has no session daemon. */
stateDir?: string | undefined;
deviceId?: string | undefined;
/** The capture's private directory: the request, e2e's output and report go under it. */
workDirectory: string;
/** The bundle directory the frames are exported into, under `flows/`. */
outputDirectory: string;
runner: CommandRunner;
environment: NodeJS.ProcessEnv;
timeoutMs: number;
agent?: { provider: "openai" | "anthropic"; model: string } | undefined;
/** `steps`: a frame after every step of every flow, not only where a flow calls app.screenshot. */
frames?: "checkpoints" | "steps" | undefined;
progress?: ((message: string) => void) | undefined;
/** Tests only: an engine module in place of agent-device. */
engineModule?: string | undefined;
};
export type FlowsOutcome = { flows: Record<string, BundleFlow>; failure?: { code: string; message: string } };
/** The relative bundle path of a flow frame. */
export const flowFramePath = (flowId: string, key: string): string => `flows/${flowId}/${key}.png`;
export async function runFlows(options: RunFlowsOptions): Promise<FlowsOutcome> {
const say = options.progress ?? (() => {});
const work = join(options.workDirectory, "flows");
await mkdir(work, { recursive: true, mode: 0o700 });
// e2e keeps its report and screenshots inside the project it tests, so they live in the app directory while the
// flows run and leave with the frames copied out: the capture's checkout must be clean again when it ends.
// The sides of one commit share a checkout across platforms, so each run gets its own directory under it.
const root = join(options.project, FLOWS_OUTPUT_DIRECTORY);
const existing = await lstat(root).catch(() => undefined);
if (existing && !existing.isDirectory()) return { flows: {}, failure: { code: "FLOWS_OUTPUT_EXISTS", message: `${FLOWS_OUTPUT_DIRECTORY} exists in the app directory and is not a directory; remove it and rerun.` } };
await mkdir(root, { recursive: true, mode: 0o700 });
const output = await mkdtemp(join(root, `${options.platform}-`));
try { return await executeFlows(options, work, output, say); }
finally {
await rm(output, { recursive: true, force: true });
// The last run out removes the directory; a concurrent run's files keep it (ENOTEMPTY).
await rmdir(root).catch(async () => {
const left = await readdir(root).catch(() => []);
if (left.length) say(`${FLOWS_OUTPUT_DIRECTORY} still holds ${left.slice(0, 3).join(", ")}${left.length > 3 ? ", …" : ""} (another run, or a late writer)`);
});
}
}
async function executeFlows(options: RunFlowsOptions, work: string, output: string, say: (message: string) => void): Promise<FlowsOutcome> {
const request: FlowsRequest = {
projectRoot: options.project, tests: [...options.tests], platform: options.platform, bundleId: options.bundleId, session: FLOWS_SESSION,
output, timeoutMs: options.timeoutMs, frames: options.frames ?? "checkpoints",
...(options.connection ? { daemon: { baseUrl: options.connection.daemonBaseUrl } } : options.stateDir ? { stateDir: options.stateDir } : {}),
...(options.deviceId ? { deviceId: options.deviceId } : {}),
...(options.agent ? { agent: options.agent } : {}),
...(options.engineModule ? { engineModule: options.engineModule } : {}),
};
const requestPath = join(work, "request.json");
await writeFile(requestPath, JSON.stringify(request), { mode: 0o600 });
say(`running ${options.tests.length} flow ${options.tests.length === 1 ? "file" : "files"} with e2e`);
// The worker's exit code is e2e's: 1 for failed tests, which is a result here, not a fault.
const result = options.runner({ command: process.execPath, args: [FLOWS_WORKER, requestPath], cwd: options.project,
environment: { ...options.environment, E2E_TELEMETRY_DISABLED: "1", ...(options.connection?.daemonAuthToken ? { EXPLORE_FLOWS_DAEMON_TOKEN: options.connection.daemonAuthToken } : {}) },
timeoutMs: options.timeoutMs + 120_000, allowFailure: true });
let summary: FlowsResult;
try { summary = JSON.parse(await readFile(join(output, "explore-flows.json"), "utf8")) as FlowsResult; }
catch {
// The worker prints the error and its stack; the message is the error lines, not the frames.
const message = (result.stderr || result.stdout).trim().split("\n").filter(line => line.trim() && !/^\s+at /.test(line)).slice(0, 4).join("\n").slice(0, 2_000);
say(`the flows did not run: ${message || "the e2e worker wrote no result"}`);
return { flows: {}, failure: { code: "FLOWS_NOT_RUN", message: message || "The e2e worker wrote no result." } };
}
const artifactsRoot = await realpath(summary.artifactsRoot).catch(() => resolve(summary.artifactsRoot));
const flows: Record<string, BundleFlow> = {};
for (const test of summary.tests) {
const frames: Record<string, FlowFrame> = {};
for (const frame of test.frames) {
try {
const source = await realpath(resolve(artifactsRoot, frame.path));
if (isAbsolute(frame.path) || relative(artifactsRoot, source).startsWith("..") || source.split(sep).includes("..")) throw new Error("outside the e2e artifacts");
const info = await lstat(source);
if (!info.isFile() || info.size > MAX_FRAME_BYTES) throw new Error("not a bounded regular file");
const png = await readFile(source);
assertDecodedPng(png, `Flow frame ${test.id}/${frame.key}`);
const path = flowFramePath(test.id, frame.key);
await mkdir(join(options.outputDirectory, dirname(path)), { recursive: true });
await copyFile(source, join(options.outputDirectory, path));
frames[frame.key] = { path, sha256: createHash("sha256").update(png).digest("hex"), width: png.readUInt32BE(16), height: png.readUInt32BE(20),
contentSha256: contentSha256(png, { top: statusBarBandPercent(options.platform), bottom: homeIndicatorBandPercent(options.platform) }),
capturedAt: Number.isFinite(Date.parse(frame.capturedAt)) ? frame.capturedAt : new Date().toISOString() };
} catch (error) {
say(`flow ${test.id}: frame ${frame.key} was not kept (${(error as Error).message})`);
const step = test.steps[frame.stepIndex];
if (step) delete step.frame;
}
}
flows[test.id] = { file: test.file, title: test.title, status: test.status, durationMs: test.durationMs, ...(test.error ? { error: test.error } : {}),
steps: test.steps.map(step => ({ ...step, ...(step.frame && !frames[step.frame] ? { frame: undefined } : {}) })).map(({ frame, ...rest }) => frame ? { ...rest, frame } : rest),
frames };
const taken = Object.keys(frames).length;
say(`flow ${test.title}: ${test.status}${taken ? `, ${taken} ${taken === 1 ? "frame" : "frames"}` : ""}${test.error ? ` (${test.error.code}: ${test.error.message.split("\n")[0]})` : ""}`);
}
if (summary.stepFrames) {
const { taken, failed, firstError } = summary.stepFrames;
say(`${taken} step ${taken === 1 ? "frame" : "frames"} taken${failed ? `, ${failed} not taken (${firstError})` : ""}`);
}
const failure = summary.errors[0];
return { flows, ...(failure && !summary.tests.length ? { failure: { code: failure.code, message: failure.message } } : {}) };
}
-7
View File
@@ -1,7 +0,0 @@
/** The flows worker's entry: `node worker-main.js <request.json>`. */
import { runFlowsWorker } from "./worker.js";
const requestPath = process.argv[2];
if (!requestPath) { console.error("usage: flows worker <request.json>"); process.exit(2); }
try { await runFlowsWorker(requestPath); }
catch (error) { console.error((error as Error).stack ?? String(error)); process.exitCode = 1; }
-167
View File
@@ -1,167 +0,0 @@
import { createHash } from "node:crypto";
/**
* Runs the app's e2e flows (the `e2e` package) on the device Explore already drives. A child process of the capture:
* the flows are the reviewed commit's own test code, so they run with the narrowed environment the capture gives
* them and never inside Explore's process. Reads one request file, writes one result file next to it.
*/
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join, relative } from "node:path";
import { run, type RunEventSink } from "e2e/runner";
import { createAgentDeviceClient } from "agent-device";
import type { E2EConfig } from "e2e";
import type { EngineHandle } from "e2e/engine";
import { mobile, type DeviceProvider } from "@e2e-dev/mobile";
import { summarizeFlowReport, type StepFrameFile } from "./report.js";
export type FlowsRequest = {
projectRoot: string;
tests: string[];
platform: "ios" | "android";
bundleId: string;
/** The agent-device session name the flows drive the device under; Explore's own session stays locked to its commands. */
session: string;
/** Where e2e writes its report and screenshots; inside the capture's private directory. */
output: string;
timeoutMs: number;
/** `steps` takes a frame after every step of a flow; `checkpoints` keeps only the frames the flows take with app.screenshot. */
frames: "checkpoints" | "steps";
/** Explore's EAS session daemon; the token comes through `EXPLORE_FLOWS_DAEMON_TOKEN`. */
daemon?: { baseUrl: string };
/** A local agent-device daemon's state directory, when the capture runs a simulator on this machine. */
stateDir?: string;
/** The device inside that daemon: a simulator UDID or an adb serial. */
deviceId?: string;
agent?: { provider: "openai" | "anthropic"; model: string };
/** Tests only: a module whose `engine()` export replaces the agent-device engine. */
engineModule?: string;
};
export type FlowsResult = {
status: string; exitCode: number;
errors: Array<{ code: string; message: string }>;
artifactsRoot: string;
tests: ReturnType<typeof summarizeFlowReport>;
/** Per-step frames (`frames: steps`): how many were taken, how many failed and the first failure. */
stepFrames?: { taken: number; failed: number; firstError?: string };
};
/** Hands e2e the device Explore holds instead of leasing one: same daemon, same simulator, another session name. */
export function exploreDevice(request: FlowsRequest, token: string | undefined): DeviceProvider {
return {
name: "expo-explore",
async acquire() {
if (request.daemon) return { id: "explore-session", daemon: { baseUrl: request.daemon.baseUrl, ...(token ? { authToken: token } : {}) }, ...(request.deviceId ? { deviceId: request.deviceId } : {}) };
if (request.stateDir) return { id: "explore-local", client: { stateDir: request.stateDir }, ...(request.deviceId ? { deviceId: request.deviceId } : {}) };
throw new Error("The flows request names neither a session daemon nor a local daemon state directory");
},
async release() { /* Explore stops its own session once the capture is done. */ },
};
}
async function agentModel(agent: NonNullable<FlowsRequest["agent"]>, environment: NodeJS.ProcessEnv): Promise<unknown> {
const name = agent.provider === "anthropic" ? "@ai-sdk/anthropic" : "@ai-sdk/openai";
const key = agent.provider === "anthropic" ? environment.ANTHROPIC_API_KEY : environment.OPENAI_API_KEY;
if (!key) throw new Error(`agent.act in a flow needs ${agent.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"} in the capture environment`);
let module: Record<string, unknown>;
try { module = await import(name) as Record<string, unknown>; }
catch { throw new Error(`agent.act in a flow needs ${name} installed next to @expo/explore (e2e builds the model with the AI SDK)`); }
const create = module[agent.provider === "anthropic" ? "createAnthropic" : "createOpenAI"] as (options: { apiKey: string }) => (model: string) => unknown;
return create({ apiKey: key })(agent.model);
}
export async function runFlowsWorker(requestPath: string, environment: NodeJS.ProcessEnv = process.env): Promise<void> {
const request = JSON.parse(await readFile(requestPath, "utf8")) as FlowsRequest;
const token = environment.EXPLORE_FLOWS_DAEMON_TOKEN;
const engine: EngineHandle = request.engineModule
? ((await import(request.engineModule)) as { engine: () => EngineHandle }).engine()
: mobile({ platform: request.platform, device: exploreDevice(request, token), session: request.session, videoTouches: false });
const config: E2EConfig = {
targets: [{ name: request.platform, engine, app: { bundleId: request.bundleId } }],
// The configured suite is exactly the files the config names; nothing else in the app is collected.
tests: request.tests,
output: request.output,
timeout: request.timeoutMs,
retries: 0,
workers: 1,
cache: "read-only",
...(request.agent ? { agents: { default: { model: await agentModel(request.agent, environment) as never } } } : {}),
};
const controller = new AbortController();
const expiry = setTimeout(() => controller.abort(), request.timeoutMs + 60_000);
const stepFrames = request.frames === "steps" && !request.engineModule ? stepFrameRecorder(request, token) : undefined;
try {
const result = await run({ cwd: request.projectRoot, config, interruptSignal: controller.signal, ...(stepFrames ? { onEvent: stepFrames.onEvent } : {}) });
// e2e closes its device session as the run ends; a frame still settling keeps the shot it has instead of asking for another.
stepFrames?.stop();
const stepResult = stepFrames ? await stepFrames.finish() : undefined;
const frames = stepResult?.frames;
const report = result.report as unknown as { run: { errors?: unknown[] } };
const output: FlowsResult = { status: result.status, exitCode: result.exitCode,
errors: (report.run.errors ?? []).flatMap(error => error && typeof error === "object" ? [{ code: String((error as { code?: unknown }).code ?? "ERROR"), message: String((error as { message?: unknown }).message ?? "") }] : []),
artifactsRoot: join(request.output, "results"), tests: summarizeFlowReport(result.report, frames),
...(stepResult ? { stepFrames: { taken: [...stepResult.frames.values()].reduce((n, files) => n + files.length, 0), failed: stepResult.failures.length,
...(stepResult.failures[0] ? { firstError: stepResult.failures[0] } : {}) } } : {}) };
await writeFile(join(request.output, "explore-flows.json"), JSON.stringify(output), { mode: 0o600 });
} finally { clearTimeout(expiry); }
}
/**
* Takes a frame of the flows' session after every step ends, through the same daemon e2e drives it on. e2e does not wait
* for a reporter, so the frame shows the device as the next step begins; a frame that fails is skipped, not fatal.
*/
/**
* The step ends while the app may still be settling (a list easing into place, a control fading in), and a frame shot
* at that instant is a near-duplicate of its neighbours that never folds. Shoot again after a short pause until two
* shots agree, within a bounded number of tries; the last shot is kept either way.
*/
export async function settledScreenshot(client: { capture: { screenshot(options: { path: string }): Promise<unknown> } }, file: string,
options: { pauseMs?: number; tries?: number; sleep?: (ms: number) => Promise<void>; /** False once the device is about to go away: keep the shot in hand. */ more?: () => boolean } = {}): Promise<{ tries: number; settled: boolean }> {
const pauseMs = options.pauseMs ?? 150; const maxTries = options.tries ?? 4;
const sleep = options.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
const digest = async () => createHash("sha256").update(await readFile(file)).digest("hex");
await client.capture.screenshot({ path: file });
let previous = await digest();
for (let tries = 1; tries < maxTries; tries++) {
await sleep(pauseMs);
if (options.more && !options.more()) return { tries, settled: false };
await client.capture.screenshot({ path: file });
const current = await digest();
if (current === previous) return { tries: tries + 1, settled: true };
previous = current;
}
return { tries: maxTries, settled: false };
}
export function stepFrameRecorder(request: FlowsRequest, token: string | undefined): { onEvent: RunEventSink; stop: () => void; finish: () => Promise<{ frames: Map<string, StepFrameFile[]>; failures: string[] }> } {
const root = join(request.output, "results");
const directory = join(root, "explore-step-frames");
// @e2e-dev/mobile drives the device as `<session>-<slot>` and Explore runs one worker, so the flows' session is `<session>-0`.
const client = createAgentDeviceClient({
session: `${request.session}-0`,
...(request.daemon ? { daemonBaseUrl: request.daemon.baseUrl, daemonAuthToken: token } : { stateDir: request.stateDir, daemonBaseUrl: "", daemonAuthToken: "", daemonTransport: "auto" }),
} as Parameters<typeof createAgentDeviceClient>[0]);
const frames = new Map<string, StepFrameFile[]>();
const pending: Promise<void>[] = [];
const failures: string[] = [];
let ready: Promise<void> | undefined;
let stopped = false;
return {
stop() { stopped = true; },
onEvent(event) {
if (event.type !== "step" || event.progress.phase !== "end" || event.progress.status !== "passed") return;
const { testId } = event;
const stepIndex = event.progress.identity?.stepIndex;
if (stepIndex === undefined) return;
const file = join(directory, `${testId.replace(/[^A-Za-z0-9._-]+/g, "_")}-${stepIndex}.png`);
ready ??= mkdir(directory, { recursive: true }).then(() => undefined);
pending.push(ready
.then(() => settledScreenshot(client, file, { more: () => !stopped }))
.then(() => { (frames.get(testId) ?? frames.set(testId, []).get(testId)!).push({ stepIndex, path: relative(root, file), capturedAt: new Date().toISOString() }); })
.catch(error => {
const message = `step frame ${stepIndex + 1} of ${testId} was not taken: ${(error as Error).message}`;
failures.push(message); process.stderr.write(`explore: ${message}\n`);
}));
},
async finish() { await Promise.all(pending); return { frames, failures }; },
};
}
+1 -13
View File
@@ -92,7 +92,7 @@ export function approveLinkScheme(options: { runner: CommandRunner; udid: string
}
/** The pixel size of a PNG, from its header. */
export function pngSize(bytes: Buffer): { width: number; height: number } | undefined {
function pngSize(bytes: Buffer): { width: number; height: number } | undefined {
if (bytes.length < 24 || bytes.toString("latin1", 12, 16) !== "IHDR") return undefined;
return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
}
@@ -186,18 +186,6 @@ export async function assertLocalEmulatorCompatible(apk: string, abi: string): P
nextAction: `Build an APK that includes ${abi} (a universal build does), or capture Android on EAS Simulator with --simulator eas.` });
}
/**
* Whether agent-device still holds a claim on an emulator serial, one an interrupted run left behind: it refuses
* such a serial even when it reports the claim as stale, so startLocalEmulator skips that port.
*/
export function agentDeviceClaims(options: { runner: CommandRunner; agentDevice: string; serial: string; cwd: string; environment: NodeJS.ProcessEnv }): boolean {
const status = options.runner({ command: options.agentDevice, args: ["device", "status", "--platform", "android", "--serial", options.serial, "--json"],
cwd: options.cwd, environment: options.environment, timeoutMs: 30_000, allowFailure: true });
let data: { claims?: unknown[]; hiddenStaleClaims?: number } | undefined;
try { data = (JSON.parse(status.stdout) as { data?: typeof data }).data; } catch { return false; }
return (data?.claims?.length ?? 0) + (data?.hiddenStaleClaims ?? 0) > 0;
}
/**
* Creates an AVD of the configured device profile (such as pixel_7) and starts it without a window. It boots in the
* background while a capture repacks the app; waitForLocalEmulator waits for it afterwards.
+24 -134
View File
@@ -3,7 +3,6 @@ import { assertNoCaptureHealthIssues, captureHealthIssues, partitionCaptureHealt
import { type RouteResetSetting } from "./route-reset.js";
import { defaultReadinessSeconds } from "./readiness.js";
import { captureLaunch, ffmpegRecordingTools, launchDirectory, type LaunchSetting, type RecordingTools } from "./launch-capture.js";
import { FLOWS_OUTPUT_DIRECTORY, flowFramePath, runFlows } from "./flows/run-flows.js";
import { createHash } from "node:crypto";
import { copyFile, lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
@@ -20,15 +19,15 @@ import { type CiAgentRuntimeOptions } from "./agent/runtime.js";
import { EAS_CLI_VERSION, CONTROLLER_SESSION, isRecord, parseJson, baseEnvironment, nonEmpty } from "./common.js";
import { lstatIfExists, isWithin, temporaryCaptureDirectory, absoluteContractFile, readContractJson, assertNoSymlinkAncestors } from "./fs-safety.js";
import { loadAppIcon, loadCachedAppIcon, storeAppIcon } from "./app-icon.js";
import { controllerCommandFailure, defaultRunner, runAgentControllerCommand } from "./controller.js";
import { defaultRunner, runAgentControllerCommand } from "./controller.js";
import { silentProgress, type Progress } from "../shared/progress.js";
import { assertCaptureEasProfile, assertSimulatorAvailable, fingerprintFrom, hasEasEnvironmentFetchFailure, nativeBuildFrom, existingBuild, repackProfileFrom, prepareExactSourceBuild, type RepackMode } from "./eas-build.js";
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, simulatorSessionName, simulatorStartFailure, readSimulatorDotenvHandoff, assertSimulatorSessionIdentity, assertSimulatorStopped, collectRuntime, controllerVersion, simulatorOsVersion, type ActiveSimulatorRuntime, type SimulatorConnection } from "./simulator.js";
import { argentControllerInvocation } from "./controller-invocation.js";
import { sharedBuild } from "./shared-build.js";
import { LOCAL_EMULATOR_STATE_PREFIX, LOCAL_SIMULATOR_STATE_PREFIX, agentDeviceClaims, assertLocalEmulatorCompatible, createLocalSimulator, startLocalEmulator, waitForLocalEmulator, waitForLocalSimulator, deleteLocalEmulator,
import { LOCAL_EMULATOR_STATE_PREFIX, LOCAL_SIMULATOR_STATE_PREFIX, assertLocalEmulatorCompatible, createLocalSimulator, startLocalEmulator, waitForLocalEmulator, waitForLocalSimulator, deleteLocalEmulator,
deleteLocalSimulator, hostEmulatorAbi, installOnLocalEmulator, installOnLocalSimulator, approveLinkScheme, localPoseShown,
pngSize, setLocalEmulatorAppearance, setLocalSimulatorAppearance, startLocalArgentServer, stopLocalAgentDevice, stopLocalArgentServer, type LocalArgentServer } from "./local-simulator.js";
setLocalEmulatorAppearance, setLocalSimulatorAppearance, startLocalArgentServer, stopLocalAgentDevice, stopLocalArgentServer, type LocalArgentServer } from "./local-simulator.js";
import { ensureArgentToolServer } from "../shared/controller-cache.js";
import { openLocalCaptureRecord } from "./local-registry.js";
import { type UnattributedSetting } from "./unattributed.js";
@@ -83,8 +82,6 @@ export type CiMapOptions = {
progress?: Progress;
/** Stops the capture between steps (before the build, the session and each route); a session it started is still stopped. */
signal?: AbortSignal;
/** The app's e2e flows to run after the routes (`only`: instead of them), as paths or globs from the app directory. */
flows?: { tests: readonly string[]; only?: boolean; frames?: "checkpoints" | "steps"; agent?: { provider: "openai" | "anthropic"; model: string } };
};
export type SimulatorRuntimeMetadata = {
provider: "eas-simulator" | "local-simulator"; controller: "agent-device" | "argent"; controllerPackageVersion: string;
@@ -101,6 +98,10 @@ export type CiMapResult = {
};
function parseJsonOrUndefined(text: string): unknown {
try { return JSON.parse(text); } catch { return undefined; }
}
/**
* Minutes an EAS session is asked for beyond the capture's own budget. The session starts beside the repack, and the
* capture deadline only starts once the app is installed, so the session also has to outlast a slow or queued hosted
@@ -192,7 +193,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
const route = row[`${side}Surface`];
return route ? [route] : [];
});
const routes = options.flows?.only ? [] : inventory.filter(route => selected.has(route.id));
const routes = inventory.filter(route => selected.has(route.id));
const setup = revisionSetup(options.setup ?? [], plan, side);
const runner = options.runner ?? defaultRunner;
const sourceEnvironment = options.environment ?? process.env;
@@ -202,13 +203,8 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
const easEnvironment = { ...restrictedEnvironment, ...(options.expoToken ? { EXPO_TOKEN: options.expoToken } : {}) };
const assertCheckout = () => {
const call = (args: string[]) => runner({ command: "git", args, cwd: project, environment: restrictedEnvironment, timeoutMs: 30_000 }).stdout.trim();
const head = call(["rev-parse", "HEAD"]);
// Explore's own flows scratch directory is not a change to the application; it is removed when the flows end.
const changes = call(["status", "--porcelain", "--untracked-files=normal", "--", ".", `:(exclude)${FLOWS_OUTPUT_DIRECTORY}`]);
if (head !== options.gitCommit || changes) {
const detail = head !== options.gitCommit ? `HEAD is ${head.slice(0, 12) || "unreadable"}, the plan recorded ${options.gitCommit.slice(0, 12)}`
: `changed: ${changes.split("\n").slice(0, 3).join(", ")}${changes.split("\n").length > 3 ? ", …" : ""}`;
throw new CiError({ code: "SOURCE_CHECKOUT_CHANGED", stage: "source", message: `The application checkout differs from its recorded commit (${detail}).`,
if (call(["rev-parse", "HEAD"]) !== options.gitCommit || call(["status", "--porcelain", "--untracked-files=normal"])) {
throw new CiError({ code: "SOURCE_CHECKOUT_CHANGED", stage: "source", message: "The application checkout differs from its recorded commit.",
nextAction: "Use a clean checkout at the exact plan commit. Capture output must stay outside the application." });
}
};
@@ -231,8 +227,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
// Launch evidence waits in a work directory until the export directory exists.
const launch: Record<string, { root: string; record: BundleLaunchCapture }> = {};
const launchWorkDirectory = await mkdtemp(join(tmpdir(), "expo-explore-launch-"));
// Flow frames land here first: the export directory must not exist until the map is exported into it.
const flowsWorkDirectory = await mkdtemp(join(tmpdir(), "expo-explore-flows-"));
const acceptedFrames: Record<string, AgentAcceptedFrame> = {};
if (options.reuseDirectory) {
const cacheRoot = await realpath(options.reuseDirectory);
@@ -334,9 +328,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
+ (routes.length - missingRoutes.length ? `, ${routes.length - missingRoutes.length} reused from the baseline` : "")
+ (missingRoutes.length ? `, ${missingRoutes.length} to capture` : ""));
let captureFailure: unknown;
let flowRecords: CaptureBundle["flows"] | undefined;
let flowsFailure: CaptureBundle["flowsFailure"] | undefined;
const captureStartedAt = (options.now ?? Date.now)();
const finish = async (): Promise<CiMapResult> => {
if (!(await store.exists())) await store.initialize(map, false);
const incomplete = captureFailure !== undefined || selectedIds.some(id => outcomes[id]?.status !== "captured" || outcomes[id]?.landing !== "verified")
@@ -395,16 +386,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
launchRecords[scheme] = record;
}
await rm(launchWorkDirectory, { recursive: true, force: true });
for (const flow of Object.values(flowRecords ?? {})) {
for (const frame of Object.values(flow.frames)) {
const source = join(flowsWorkDirectory, frame.path);
await assertNoSymlinkAncestors(flowsWorkDirectory, source, "flow frame");
await mkdir(join(outputDirectory, dirname(frame.path)), { recursive: true });
await copyFile(source, join(outputDirectory, frame.path));
if (createHash("sha256").update(await readFile(join(outputDirectory, frame.path))).digest("hex") !== frame.sha256) throw new Error(`Exported flow frame ${frame.path} does not match the captured file`);
}
}
await rm(flowsWorkDirectory, { recursive: true, force: true });
const storedIcon = appIcon ? await storeAppIcon(outputDirectory, appIcon) : undefined;
const bundle: CaptureBundle = { contract: "explore.bundle", side, gitCommit: options.gitCommit, easBuildId: frameBuildId, completedAt: map.run.completedAt,
easProjectId: projectId, platform: options.platform, profile: options.easProfile, appName: app.name, ...(controller === "argent" ? { controller } : {}), ...(storedIcon ? { appIcon: storedIcon } : {}),
@@ -412,8 +393,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
runtimeProfile: metadata ? { deviceModel: metadata.deviceModel, osVersion: metadata.osVersion, locale: metadata.locale,
orientation: metadata.orientation, colorScheme: metadata.colorScheme, ...(metadata.colorSchemes ? { colorSchemes: metadata.colorSchemes.join(",") } : {}) } : null, images, outcomes, procedure: { reset: options.reset ?? "root-link", readinessSeconds: options.readinessSeconds ?? defaultReadinessSeconds(options.platform) },
...(Object.keys(launchRecords).length ? { launch: launchRecords } : {}),
...(flowRecords && Object.keys(flowRecords).length ? { flows: flowRecords } : {}),
...(flowsFailure ? { flowsFailure } : {}),
...(options.agent ? { captureContexts: Object.fromEntries(selectedIds.filter(id => outcomes[id]?.status === "captured" && options.agent!.contexts[id])
.map(id => [id, options.agent!.contexts[id]!])), agentAcceptance: { policy: AGENT_ACCEPTANCE_POLICY,
frames: Object.fromEntries(Object.keys(images).map(id => [id, acceptedFrames[id]!])) } } : {}) };
@@ -428,7 +407,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
simulatorSessionId: sessionId ?? null, simulatorRuntime: metadata, mapDirectory, outputDirectory,
runStatus: routes.length === 0 ? "complete" : map.run.status, app, outcomes };
};
if (!options.flows && (!missingRoutes.length || !options.agent && !missingRoutes.some(hasConcreteRoutePath))) {
if (!missingRoutes.length || !options.agent && !missingRoutes.some(hasConcreteRoutePath)) {
for (const route of missingRoutes) outcomes[route.id] = { ...unavailableRoute(route), attempts: 0, landing: "unverified" };
return finish();
}
@@ -451,7 +430,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
...(profile.projectIdentity.buildNumber ? { buildNumber: profile.projectIdentity.buildNumber } : {}) };
projectId = profile.projectIdentity.projectId;
appIcon = await loadAppIcon(project, configValue.appConfig, options.platform) ?? appIcon;
if (!scheme && !options.agent && !options.flows) {
if (!scheme && !options.agent) {
for (const route of missingRoutes) outcomes[route.id] = { ...unavailableRoute(route), attempts: 0, landing: "unverified" };
return finish();
}
@@ -496,7 +475,13 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
say(`starting a local ${options.device} emulator`);
localEmulatorStart = await startLocalEmulator({ runner, device: options.device, name: `explore-${side}-${options.gitCommit.slice(0, 8)}`, directory: simulatorProject,
cwd: simulatorProject, environment: restrictedEnvironment,
...(controller === "agent-device" ? { claimed: (serial: string) => agentDeviceClaims({ runner, agentDevice: options.agentDeviceCommand, serial, cwd: simulatorProject, environment: restrictedEnvironment }) } : {}),
// agent-device refuses a serial an interrupted run still claims, even one it reports as stale, so that port is skipped.
...(controller === "agent-device" ? { claimed: (serial: string) => {
const status = runner({ command: options.agentDeviceCommand, args: ["device", "status", "--platform", "android", "--serial", serial, "--json"],
cwd: simulatorProject, environment: restrictedEnvironment, timeoutMs: 30_000, allowFailure: true });
const data = (parseJsonOrUndefined(status.stdout) as { data?: { claims?: unknown[]; hiddenStaleClaims?: number } } | undefined)?.data;
return (data?.claims?.length ?? 0) + (data?.hiddenStaleClaims ?? 0) > 0;
} } : {}),
// Recorded as soon as it starts, so an interrupted review stops it too.
started: async serial => {
localEmulator = serial;
@@ -705,40 +690,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
...(options.sleep ? { sleep: options.sleep } : {}) })) throw new CiError({ code: "CONTROLLER_FOLD_UNVERIFIED", stage: "session",
message: `${options.device} did not show the ${options.devicePose} display after folding: ${(folded.stderr || folded.stdout).trim().split("\n").at(-1) ?? ""}`.trim(),
nextAction: "Rerun; if it persists, check that this Xcode's simulator supports folding the device." });
} else {
// agent-device folds only inside a session, and `install` opens none (SESSION_NOT_FOUND on EAS Simulator when the
// fold came first): the app opens once to start the session. Argent's bridge folds without one.
// A foldable's first open on EAS Simulator has timed out inside the controller once (`xcrun timed out`); one retry.
for (let attempt = 0; controller !== "argent"; attempt += 1) {
try {
runner({ command: controllerCommand, args: ["open", options.bundleId, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 5 * 60_000 });
break;
} catch (error) {
if (attempt > 0) throw error;
say(`the app did not open before the fold (${(error as Error).message.split("\n")[0]}); opening it again`);
}
}
const folded = runner({ command: controllerCommand, args: ["fold", options.devicePose, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000, allowFailure: true });
const failure = foldFailure(folded.stdout);
if (failure) {
// On EAS Simulator agent-device dispatches the pose but cannot read the hinge back, so the lit display's shape
// confirms the pose instead: the inner one is landscape when open, the outer one portrait when closed.
if (!/hinge/i.test(failure)) throw controllerCommandFailure(folded.stdout, "fold");
const file = join(simulatorProject, "pose.png");
runner({ command: controllerCommand, args: ["screenshot", file, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
const size = pngSize(await readFile(file).catch(() => Buffer.alloc(0)));
await rm(file, { force: true });
const shown = options.devicePose === "open" ? size !== undefined && size.width > size.height
: options.devicePose === "closed" ? size !== undefined && size.height > size.width : true;
if (!shown) throw new CiError({ code: "CONTROLLER_FOLD_UNVERIFIED", stage: "session",
message: `${options.device} did not show the ${options.devicePose} display after folding: ${failure}`,
nextAction: "Rerun; if it persists, check that this EAS Simulator image supports folding the device." });
say(`${options.device} shows the ${options.devicePose} display (the controller could not read the hinge back)`);
}
}
} else fold();
}
runtimeStage = "runtime";
setStage(runtimeStage);
@@ -786,16 +738,13 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
// Every pass sets the appearance explicitly, so a capture does not inherit whatever the simulator last used.
const passes: CaptureBundle["outcomes"][] = [];
const recordingTools = launchSetting === "off" ? undefined : options.recordingTools === undefined ? ffmpegRecordingTools() : options.recordingTools ?? undefined;
// Argent cannot switch the appearance yet (software-mansion/argent#1509): on EAS its single pass runs as the device
// starts, and on this machine the host switches it.
const applyAppearance = (colorScheme: ColorScheme): void => {
if (controller !== "argent") runner({ command: controllerCommand, args: [...appearanceArgs(colorScheme), "--session", CONTROLLER_SESSION, ...deviceArgs(runtime!), "--platform", options.platform],
for (const [index, colorScheme] of colorSchemes.entries()) {
// Argent cannot switch the appearance yet (software-mansion/argent#1509): on EAS its single pass runs as the device
// starts, and on this machine the host switches it.
if (controller !== "argent") runner({ command: controllerCommand, args: [...appearanceArgs(colorScheme), "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
else if (localSimulator) setLocalSimulatorAppearance({ runner, udid: localSimulator, scheme: colorScheme, cwd: simulatorProject, environment: restrictedEnvironment });
else if (localEmulator) setLocalEmulatorAppearance({ runner, serial: localEmulator, scheme: colorScheme, cwd: simulatorProject, environment: restrictedEnvironment });
};
for (const [index, colorScheme] of colorSchemes.entries()) {
applyAppearance(colorScheme);
// A scheme change recreates the Android activity in place, and the sheets it re-presents lose their inset; a
// relaunch starts the app in the new scheme, the same way the first pass did.
if (launchSetting !== "off") {
@@ -824,57 +773,6 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
}
runtime.colorScheme = colorSchemes[0]!;
Object.assign(outcomes, mergeSchemeOutcomes(passes, colorSchemes));
if (options.flows) {
runtimeStage = "flows";
// The flows run in the primary appearance, which the last route pass may have left.
if (colorSchemes.length > 1) applyAppearance(colorSchemes[0]!);
// The flows share the deadline the routes had; a flow that fails or runs out of time keeps the frames it took.
const remainingMs = Math.max(60_000, options.maxDurationMinutes * 60_000 - ((options.now ?? Date.now)() - captureStartedAt));
// A daemon lets one agent-device session hold the device, and e2e names its own (`<session>-<slot>`): Explore
// hands the device over by closing its session. The app and the state setup put in it stay on the device.
if (controller !== "argent") runner({ command: options.agentDeviceCommand, args: ["close", "--session", CONTROLLER_SESSION, "--json"], cwd: simulatorProject,
environment: controllerEnvironment, timeoutMs: 60_000, allowFailure: true });
const flowRunOptions = { project, tests: options.flows.tests, platform: options.platform, bundleId: options.bundleId, connection,
...(connection ? {} : { stateDir: join(simulatorProject, "agent-device-state") }), deviceId: runtime.controllerDeviceId,
workDirectory: simulatorProject, runner, environment: controllerEnvironment,
agent: options.flows.agent, frames: options.flows.frames ?? "checkpoints", progress: say, ...(options.environment?.EXPLORE_FLOWS_ENGINE_MODULE ? { engineModule: options.environment.EXPLORE_FLOWS_ENGINE_MODULE } : {}) };
const result = await runFlows({ ...flowRunOptions, outputDirectory: flowsWorkDirectory, timeoutMs: remainingMs });
flowRecords = result.flows;
flowsFailure = result.failure;
if (result.failure) say(`the flows did not run: ${result.failure.message}`);
// The other appearances run the flows again; a frame the primary pass took joins its record as `<key>@<scheme>`
// (the launch convention), so Compare pairs it by appearance. A pass that fails only leaves its frames missing.
for (const colorScheme of colorSchemes.slice(1)) {
if (flowsFailure || controller === "argent" || !Object.keys(flowRecords).length) break;
const schemeRemainingMs = options.maxDurationMinutes * 60_000 - ((options.now ?? Date.now)() - captureStartedAt);
if (schemeRemainingMs < 60_000) { say(`no time left for the ${colorScheme} flows`); break; }
say(`flows in ${colorScheme}`);
// Explore's session comes back to switch the appearance and relaunch the app in it, then hands the device over again.
runner({ command: controllerCommand, args: ["open", options.bundleId, "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 5 * 60_000 });
applyAppearance(colorScheme);
runner({ command: controllerCommand, args: ["open", options.bundleId, "--relaunch", "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform, "--level", "full", "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
runner({ command: options.agentDeviceCommand, args: ["close", "--session", CONTROLLER_SESSION, "--json"], cwd: simulatorProject,
environment: controllerEnvironment, timeoutMs: 60_000, allowFailure: true });
const schemeDirectory = await mkdtemp(join(tmpdir(), `expo-explore-flows-${colorScheme}-`));
try {
const pass = await runFlows({ ...flowRunOptions, outputDirectory: schemeDirectory, timeoutMs: schemeRemainingMs });
if (pass.failure) say(`the ${colorScheme} flows did not run: ${pass.failure.message}`);
for (const [flowId, flow] of Object.entries(pass.flows)) {
const record = flowRecords[flowId];
if (!record) continue;
for (const [key, frame] of Object.entries(flow.frames)) {
if (!record.frames[key]) continue;
const path = flowFramePath(flowId, `${key}@${colorScheme}`);
await mkdir(join(flowsWorkDirectory, dirname(path)), { recursive: true });
await copyFile(join(schemeDirectory, frame.path), join(flowsWorkDirectory, path));
record.frames[`${key}@${colorScheme}`] = { ...frame, path };
}
}
} finally { await rm(schemeDirectory, { recursive: true, force: true }); }
}
}
} catch (error) { primaryError = toCiError(error, { code: `CAPTURE_${runtimeStage.toUpperCase()}_FAILED`, stage: runtimeStage,
nextAction: "Inspect the capture diagnostic, correct the failing prerequisite, and rerun Explore." }); }
finally {
@@ -946,11 +844,3 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
say(`${captured} of ${selectedIds.length} ${selectedIds.length === 1 ? "route" : "routes"} captured`);
return finish();
}
/** The message of a `fold --json` the controller reported as failed, or undefined when it succeeded. */
function foldFailure(stdout: string): string | undefined {
try {
const parsed = JSON.parse(stdout) as { success?: boolean; error?: { message?: string } };
return parsed.success === false ? String(parsed.error?.message ?? "fold failed") : undefined;
} catch { return undefined; }
}
-1
View File
@@ -35,7 +35,6 @@ export function captureRecipeConfig(config: ExploreConfig, instructionsSha256?:
app: { platform: config.app.platform, bundleId: config.app.bundleId, easProfile: config.app.easProfile,
...(config.app.scheme === undefined ? {} : { scheme: config.app.scheme }) },
device: config.device, parameters: config.parameters, setup: config.setup ?? [],
...(config.flows ? { flows: config.flows } : {}),
// The repack as it resolves, so a config that leaves it to the default keeps the recipe it had when the default was written out.
capture: { ...config.capture, repack: captureRepack(config) },
// agent-device recipes stay as they were; an Argent capture is keyed to the Argent release that drove it.
+1 -33
View File
@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
import { readFileSync } from "node:fs";
import { lstat, mkdir, readdir, readFile, realpath } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, relative, sep } from "node:path";
import { join, sep } from "node:path";
import { CiError, toCiError } from "../shared/ci-errors.js";
import type { CaptureBundle } from "../contracts/capture.js";
import type { SourceCapturePlan } from "../source/capture-plan.js";
@@ -10,7 +10,6 @@ import type { CommandRunner } from "../capture/run.js";
import { runBaselineCi } from "./pipeline.js";
import { DEFAULT_EXPLORE_CONFIG_PATH, captureRepack, configTargets, readExploreConfig, readExploreInstructions, resolveTargetConfig, withRunOverrides, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
import { explorationSecretNames } from "../config/exploration-inputs.js";
import { FLOWS_OUTPUT_DIRECTORY } from "../capture/flows/run-flows.js";
import { controllerCached } from "../shared/controller-cache.js";
import { androidTools, hostEmulatorAbi, localSimulatorTarget, localSystemImage } from "../capture/local-simulator.js";
import { ARGENT_VERSION } from "../shared/argent-version.js";
@@ -92,36 +91,6 @@ export function referencedSecretNames(config: ExploreConfig, instructions?: stri
...(config.setup ?? []).map(action => action.action === "fill" || action.action === "type" ? action.text : "")].join("\n"));
}
/** `**` crosses directories, `*` and `?` stay inside a segment; the rest is literal. */
function globToRegExp(glob: string): RegExp {
const source = glob.split("**").map(part => part.split("*").map(piece => piece.split("?").map(ch => ch.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("[^/]")).join("[^/]*")).join("(?:.*)");
return new RegExp(`^${source.replace(/^\(\?:\.\*\)\//, "(?:.*/)?")}$`);
}
/** The flows the capture would run: each entry of flows.tests names a committed file, and the app can import `e2e`. */
async function flowChecks(project: string, config: ExploreConfig): Promise<DoctorCheck[]> {
if (!config.flows) return [];
const checks: DoctorCheck[] = [];
const files = (await readdir(project, { recursive: true, withFileTypes: true }).catch(() => []))
.filter(entry => entry.isFile() && !relative(project, entry.parentPath).split(sep).includes("node_modules"))
.map(entry => relative(project, join(entry.parentPath, entry.name)).split(sep).join("/"));
const unmatched = config.flows.tests.filter(pattern => /[*?]/.test(pattern) ? !files.some(file => globToRegExp(pattern).test(file)) : !files.includes(pattern));
const matched = new Set(config.flows.tests.flatMap(pattern => /[*?]/.test(pattern) ? files.filter(file => globToRegExp(pattern).test(file)) : files.includes(pattern) ? [pattern] : []));
checks.push(unmatched.length
? { step: 4, id: "flows-tests", status: "fail", code: "FLOWS_TESTS_MISSING", message: `flows.tests names no file for ${unmatched.map(pattern => `"${pattern}"`).join(", ")}.`,
nextAction: "Point flows.tests at the app's committed e2e test files (for example e2e/**/*.e2e.ts), or add the files." }
: { step: 4, id: "flows-tests", status: "pass", message: `flows.tests matches ${matched.size} e2e test file${matched.size === 1 ? "" : "s"}.` });
const e2ePackage = await readFile(join(project, "node_modules", "e2e", "package.json"), "utf8").then(text => JSON.parse(text) as { version?: string }).catch(() => undefined);
checks.push(e2ePackage
? { step: 4, id: "flows-e2e", status: "pass", message: `The app resolves e2e ${e2ePackage.version ?? ""}`.trim() + "." }
: { step: 4, id: "flows-e2e", status: "warn", code: "FLOWS_E2E_UNRESOLVED", message: "The app's node_modules has no e2e package; its test files import it.",
nextAction: "Add e2e to the app's devDependencies and install (the capture installs the committed lockfile)." });
if (await lstat(join(project, FLOWS_OUTPUT_DIRECTORY)).catch(() => undefined)) checks.push({ step: 4, id: "flows-output", status: "warn", code: "FLOWS_OUTPUT_EXISTS",
message: `${FLOWS_OUTPUT_DIRECTORY} is in the app directory; a capture writes e2e's output there and removes it when it ends.`,
nextAction: `Remove ${FLOWS_OUTPUT_DIRECTORY} (a previous run was interrupted) and keep it out of the commit.` });
return checks;
}
function routeChecks(config: ExploreConfig, report: RouteEntryReport): DoctorCheck[] {
const checks: DoctorCheck[] = [];
const deterministic = config.mode === "deterministic";
@@ -539,7 +508,6 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
try {
routes = readRouteEntry(project, config);
checks.push(...routeChecks(config, routes));
checks.push(...await flowChecks(project, config));
} catch (error) {
checks.push(fromError(5, "routes", error, { code: "SOURCE_ANALYSIS_FAILED", nextAction: "Commit the app source and check navigation.provider and navigation.entry." }));
}
+1 -3
View File
@@ -48,8 +48,6 @@ export type LocalReviewOptions = {
parallel?: number | undefined;
scope?: string | undefined;
expiresIn?: string | undefined;
/** e2e files or globs to run as the capture instead of the config's mode (`--flows`). */
flows?: readonly string[] | undefined;
/** `--controller`: the device controller for both sides, over the config's `capture.controller`. */
controller?: string | undefined;
/** `--simulator`: `local` runs both sides on simulators this Mac creates, over the config's `capture.simulator`. */
@@ -460,7 +458,7 @@ export async function runLocalReview(options: LocalReviewOptions): Promise<Local
});
// The targets run at once, as CI runs them in parallel jobs: each on its own simulators, with its own output.
const captureTarget = async (target: RunTarget): Promise<LocalReviewReport> => {
const config = withRunOverrides(resolveTargetConfig(rawConfig, { target: target.id }), { scope: options.scope, expiresIn: options.expiresIn, flows: options.flows, controller: options.controller, simulator: options.simulator, repack: options.repack });
const config = withRunOverrides(resolveTargetConfig(rawConfig, { target: target.id }), { scope: options.scope, expiresIn: options.expiresIn, controller: options.controller, simulator: options.simulator, repack: options.repack });
const platform = target.platform;
const output = join(work, target.id); await mkdir(output);
outputs.push(output);
+5 -15
View File
@@ -1,5 +1,4 @@
import type { RunTarget } from "../types.js";
import { FLOWS_OUTPUT_DIRECTORY } from "../capture/flows/run-flows.js";
import { spawnSync } from "node:child_process";
import { mkdir, open, readFile, realpath, writeFile } from "node:fs/promises";
import { join, relative, resolve, isAbsolute } from "node:path";
@@ -41,17 +40,10 @@ function requireSecret(environment: NodeJS.ProcessEnv, name: string): string {
return value;
}
function assertCheckout(project: string, sha: string): void {
// Explore's own flows scratch directory (another target's flows may be running in the same checkout) is not a change.
const checks = [
[["rev-parse", "HEAD"], sha],
[["status", "--porcelain", "--untracked-files=normal", "--", ".", `:(exclude)${FLOWS_OUTPUT_DIRECTORY}`], ""],
] as const;
for (const [args, expected] of checks) {
for (const [args, expected] of [[ ["rev-parse", "HEAD"], sha ], [["status", "--porcelain", "--untracked-files=normal"], ""]] as const) {
const result = spawnSync("git", ["-C", project, ...args], { encoding: "utf8" });
const observed = result.stdout.trim();
if (result.status !== 0 || observed !== expected) throw new CiError({
code: "SOURCE_CHECKOUT_MISMATCH", stage: "preflight",
message: `Source checkout does not match ${sha} (${args[0] === "rev-parse" ? `HEAD is ${observed.slice(0, 12) || "unreadable"}` : `changed: ${observed.split("\n").slice(0, 3).join(", ")}`}).`,
if (result.status !== 0 || result.stdout.trim() !== expected) throw new CiError({
code: "SOURCE_CHECKOUT_MISMATCH", stage: "preflight", message: `Source checkout does not match ${sha}.`,
nextAction: "Check out the exact recorded commit and remove generated changes from the source checkout." });
}
}
@@ -78,7 +70,6 @@ function captureOptions(config: ExploreConfig, environment: NodeJS.ProcessEnv, r
maxScreens: 5000, maxActions: config.capture.maxActions, maxDurationMinutes: config.capture.maxMinutes,
setup: config.setup ?? [], forceFreshBuild: false, confirmExternalRun: true, confirmTrustedSource: true, repack: captureRepack(config), appearance: config.capture.appearance, launch: config.capture.launch, reset: config.capture.reset, unattributed: config.capture.unattributed, ...(config.capture.readinessSeconds !== undefined ? { readinessSeconds: config.capture.readinessSeconds } : {}), ...(config.capture.controller ? { controller: config.capture.controller } : {}),
...(config.capture.simulator ? { simulator: config.capture.simulator } : {}),
...(config.flows ? { flows: { tests: config.flows.tests, only: config.mode === "flows", ...(config.flows.frames ? { frames: config.flows.frames } : {}), ...(config.agent ? { agent: { provider: config.agent.provider, model: config.agent.model } } : {}) } } : {}),
environment, ...(runner ? { runner } : {}), easCommand: packageBin("eas-cli", "eas"), agentDeviceCommand: agentDeviceLauncher(environment), repackCommand: packageBin("@expo/repack-app", "repack-app") };
}
/**
@@ -301,8 +292,7 @@ export async function runCiReview(options: {
done: { base: 0, head: 0 }, baseFromCache: false };
await assertCurrentHead(); await postComment();
stage = "preflight";
// A side with routes to capture, or flows to run, needs the token, the installed dependencies and a session.
const active = plan.headCaptureSurfaceIds.length + plan.baseCaptureSurfaceIds.length > 0 || config.flows !== undefined;
const active = plan.headCaptureSurfaceIds.length + plan.baseCaptureSurfaceIds.length > 0;
if (active && !options.useLocalEasSession) requireSecret(environment, "EXPO_TOKEN");
const exploration = await prepareCiExploration(config, projects.head, environment, active,
{ ...(options.agentSessionFactory ? { createSession: options.agentSessionFactory } : {}),
@@ -487,7 +477,7 @@ export async function runBaselineCi(options: { platform?: ExplorePlatform; proje
const plan = await buildVerifiedPlan({ baseProject: options.project, headProject: options.project,
baseSha: options.sha, headSha: options.sha, config: options.config, output, scope: "all" });
progress(planSummary(plan, true));
const active = plan.headCaptureSurfaceIds.length > 0 || options.config.flows !== undefined;
const active = plan.headCaptureSurfaceIds.length > 0;
if (active && !options.useLocalEasSession) requireSecret(environment, "EXPO_TOKEN");
let usagePhase: AgentUsagePhase = "preflight";
const exploration = await prepareCiExploration(options.config, options.project, environment, active,
-2
View File
@@ -91,8 +91,6 @@ export async function buildVerifiedPlan(options: {
changedFiles: internal,
externalChanges: external,
mode: options.scope ?? config.exploration.scope,
// Flows mode keeps the route inventory for the map and the navigation context, and captures none of it.
...(config.mode === "flows" ? { captureRoutes: false } : {}),
...(config.exploration.exclude ? { exclude: config.exploration.exclude } : {}),
provider: config.navigation.provider,
...(config.navigation.entry ? { entry: config.navigation.entry } : {}),
+3 -3
View File
@@ -85,14 +85,14 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
validate: {},
export: { output: "value" },
"export:web": {catalog:"value",output:"value"},
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", compare:"value", output:"value", config:"value", parallel:"value", target:"value", platform:"value", controller:"value", simulator:"value", repack:"value", flows:"value", scope:"value", "expires-in":"value",
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", compare:"value", output:"value", config:"value", parallel:"value", target:"value", platform:"value", controller:"value", simulator:"value", repack:"value", scope:"value", "expires-in":"value",
base:"value", head:"value", project:"value", committed:"boolean", uncommitted:"boolean", "include-untracked":"boolean", upload:"boolean", "no-open":"boolean", "no-cache":"boolean", port:"value" },
"explore:binary": { archive:"value", output:"value", platform:"value", controller:"value", simulator:"value", device:"value", "bundle-id":"value", "launch-url":"value", hints:"value", "allow-destructive":"value",
"explore:binary": { archive:"value", output:"value", platform:"value", controller:"value", device:"value", "bundle-id":"value", "launch-url":"value", hints:"value", "allow-destructive":"value",
"max-duration-minutes":"value", "max-screens":"value", "max-actions":"value", provider:"value", model:"value", owner:"value", project:"value",
upload:"boolean", "no-upload":"boolean", "expires-in":"value", alias:"value", "no-open":"boolean", port:"value" },
upload:"boolean", "no-upload":"boolean", "expires-in":"value", alias:"value" },
"explore:session": { session:"value", "env-file":"value", "bundle-id":"value", "app-name":"value", "app-version":"value", output:"value", platform:"value", controller:"value", device:"value", "launch-url":"value", hints:"value",
"allow-destructive":"value", "max-duration-minutes":"value", "max-screens":"value", "max-actions":"value", provider:"value", model:"value", owner:"value", project:"value",
upload:"boolean", "expires-in":"value", alias:"value", "no-open":"boolean", port:"value" },
+6 -16
View File
@@ -39,17 +39,12 @@ export async function exploreBinary(): Promise<void> {
const platform = flag("platform") === undefined ? undefined : oneOf("platform", ["ios", "android"] as const);
const provider = flag("provider") === undefined ? undefined : oneOf("provider", ["anthropic", "openai"] as const);
const controller = flag("controller") === undefined ? undefined : oneOf("controller", ["agent-device", "argent"] as const);
const simulator = flag("simulator") === undefined ? "eas" : oneOf("simulator", ["eas", "local"] as const);
// On EAS Simulator the report is hosted unless --no-upload; locally it opens in the Viewer unless --upload, so a
// local run needs no Expo account at all.
const upload = simulator === "local" ? has("upload") : !has("no-upload");
const port = flag("port") === undefined ? undefined : nonNegativeInteger("port");
const started = Date.now();
const say = (message: string) => { process.stderr.write(`[explore ${Math.round((Date.now() - started) / 1000)}s] ${message}\n`); };
const allowDestructive = flags("allow-destructive").flatMap(value => value.split(",")).map(value => value.trim()).filter(Boolean);
if (upload) await assertHostingExport();
if (!has("no-upload")) await assertHostingExport();
const result = await runBinaryExploration({
archive: resolve(process.cwd(), archive), output: outputDirectory, progress: say, simulator,
archive: resolve(process.cwd(), archive), output: outputDirectory, progress: say,
...(platform ? { platform } : {}), ...(provider ? { provider } : {}), ...(controller ? { controller } : {}),
...(flag("device") ? { device: flag("device")! } : {}), ...(flag("bundle-id") ? { bundleId: flag("bundle-id")! } : {}),
...(flag("launch-url") ? { launchUrl: flag("launch-url")! } : {}), ...(flag("hints") ? { hints: flag("hints")! } : {}),
@@ -63,16 +58,15 @@ export async function exploreBinary(): Promise<void> {
const report = await writeExplorationReport(result, join(outputDirectory, "report"));
await keepReports(async () => [{ platform: result.archive.platform, zip: await zipReportDirectory(report.reportPath) }]);
let hosted: Awaited<ReturnType<typeof deployExplorationReport>> | undefined;
if (upload) {
if (!has("no-upload")) {
say("hosting the report on EAS Hosting");
const owner = result.session.owner || flag("owner");
hosted = await deployExplorationReport({ reportPath: report.reportPath, platform: result.archive.platform, project: flag("project") ?? DEFAULT_BINARY_PROJECT, ...(owner ? { owner } : {}), expiresAfterDays, ...stableLinkOptions() });
hosted = await deployExplorationReport({ reportPath: report.reportPath, platform: result.archive.platform, project: flag("project") ?? DEFAULT_BINARY_PROJECT, owner: result.session.owner, expiresAfterDays, ...stableLinkOptions() });
say(`report: ${hosted.previewUrl}${hosted.expiresAt ? ` (expires ${hosted.expiresAt})` : ""}`);
}
const summary = { ok: true,
app: { name: result.archive.appName, bundleId: result.archive.bundleId, platform: result.archive.platform, ...(result.archive.version ? { version: result.archive.version } : {}) },
archive: { path: result.archive.path, kind: result.archive.kind, sha256: result.archive.sha256, bytes: result.archive.bytes },
device: { model: result.runtime.deviceModel, osVersion: result.runtime.osVersion }, session: { id: result.session.id, simulator, ...(simulator === "eas" ? { owner: result.session.owner, project: result.session.project } : {}) },
device: { model: result.runtime.deviceModel, osVersion: result.runtime.osVersion }, session: { id: result.session.id, owner: result.session.owner, project: result.session.project },
model: result.model, exploration: { stopReason: result.exploration.stopReason, ...(result.exploration.summary ? { summary: result.exploration.summary } : {}),
screens: result.exploration.screens, observations: result.exploration.observations, actions: result.exploration.actions, durationMs: result.durationMs },
map: result.mapPath, report: report.reportPath, ...(hosted ? { url: hosted.previewUrl, expiresAt: hosted.expiresAt, deploymentUrl: hosted.deploymentUrl, ...(hosted.aliasUrl ? { aliasUrl: hosted.aliasUrl } : {}) } : {}),
@@ -81,11 +75,7 @@ export async function exploreBinary(): Promise<void> {
console.log(`${summary.app.name} (${summary.app.bundleId}, ${summary.app.platform}) explored on ${summary.device.model} ${summary.device.osVersion}: ${summary.exploration.screens} screens, ${summary.exploration.actions} actions, stopped because ${summary.exploration.stopReason}.`);
if (hosted) console.log(`Hosted report: ${hosted.previewUrl}${hosted.expiresAt ? ` (expires ${hosted.expiresAt})` : ""}`);
console.log(`Local report: ${report.reportPath}`);
if (simulator === "eas" || hosted || has("no-open")) { console.log(`Next: ${summary.next.join(" | ")}`); return; }
const viewer = await startViewerServer({ root: outputDirectory, ...(port === undefined ? {} : { port }) });
console.log(`Viewer: ${viewer.url} (Ctrl+C to stop)`);
openViewerInBrowser(viewer.url);
await waitForViewerShutdown(viewer);
console.log(`Next: ${summary.next.join(" | ")}`);
}
/** `--env-file` wins; otherwise the `.env.eas-simulator` that `eas simulator:start --out-config-type dotenv` wrote in the current directory, unless the environment already carries a session. */
-1
View File
@@ -250,7 +250,6 @@ async function localReview(): Promise<void> {
...(parallel ? { parallel } : {}),
// --include-untracked is accepted from before untracked files were included by default.
committed: has("committed"), uncommitted: has("uncommitted"), ...(platform ? { platform } : {}),
...(has("flows") ? { flows: required("flows").split(",") } : {}),
scope: flag("scope"), expiresIn: flag("expires-in"), controller: flag("controller"), simulator: flag("simulator"), repack: flag("repack"), cache: !has("no-cache"), configPath: flag("config"), progress: stderrProgress() });
if (has("output")) {
for (const report of result.reports) {
+7 -10
View File
@@ -17,10 +17,10 @@ const GET_STARTED = `Get started (run these in the Expo app's directory):
(--offline skips EAS and GitHub; --check-model sends one small request with the local provider key)
doctor --capture [--project DIRECTORY] [--output DIRECTORY] [--target ID | --platform ios|android] [--controller agent-device|argent] [--simulator eas|local] [--repack eas|local] [--yes]
(captures the committed HEAD like the baseline workflow, with your eas login, and reports each route)
capture [--base REF] [--head REF | --committed] [--target ID | --platform ios|android] [--parallel N] [--scope all|changes] [--flows FILE[,FILE]]
capture [--base REF] [--head REF | --committed] [--target ID | --platform ios|android] [--parallel N] [--scope all|changes]
[--controller agent-device|argent] [--simulator eas|local] [--repack eas|local] [--upload [--expires-in 7d|30d|never]] [--no-open] [--no-cache] [--output DIRECTORY] [--project DIRECTORY]
(on this machine: checks out both commits in temporary worktrees, captures them with your eas login (in agent
mode, also your local claude or codex login), and opens the report; the head is HEAD with your uncommitted changes, as eas build
(on this machine: checks out both commits in temporary worktrees, captures them with your eas login and your
local claude or codex login, and opens the report; the head is HEAD with your uncommitted changes, as eas build
uploads them (--committed, or cli.requireCommit in eas.json, leaves them out); the base defaults to where HEAD
left the default branch;
without .expo-explore/config.yaml it uses the defaults setup would write;
@@ -43,22 +43,19 @@ const GET_STARTED = `Get started (run these in the Expo app's directory):
(hosts reports already on this machine on EAS Hosting behind one link, with your eas login: one per platform
of the same review, from capture:review --output or a downloaded explore-review artifact, or one explore:binary report)`;
const BINARY = `Prebuilt apps (no source needed; runs with your local claude or codex login):
explore:binary <app.apk | app.app | app.tar.gz | simulator .ipa> [--output DIRECTORY] [--simulator eas|local] [--no-upload] [--json]
const BINARY = `Prebuilt apps (no source needed; runs on EAS Simulator with your local claude or codex login):
explore:binary <app.apk | app.app | app.tar.gz | simulator .ipa> [--output DIRECTORY] [--no-upload] [--json]
(installs the archive in a fresh EAS Simulator session, lets the model explore it, writes a map
and report under --output, hosts the report on EAS Hosting, and prints the link)
--simulator local runs it on a simulator or emulator it starts on this machine instead, with no EAS login,
and opens the report in the local Viewer (--upload hosts it instead, --no-open skips the Viewer, --port N);
iOS needs Xcode, Android the SDK (ANDROID_HOME) with platform-tools, cmdline-tools, the emulator and a system image for this Mac
Flags, all optional: --device NAME --bundle-id ID --launch-url URL --hints "what to focus on"
--controller agent-device|argent (the device controller; agent-device by default)
--controller agent-device|argent (the session's device controller; agent-device by default)
(a sign-in in --hints is written as {{secret:NAME}}: Explore types the value of the environment variable NAME,
and the model and the report only see the reference)
--max-duration-minutes N --max-screens N --max-actions N --provider anthropic|openai --model ID
--owner ACCOUNT --project SLUG --expires-in 7d|30d|never --allow-destructive "Label,Other label"
--alias NAME (one EAS Hosting host per app that always serves the newest run; with EXPLORE_PREVIEW_TOKEN
set to a fixed 32-character token, the hosted link is the same every run)
(iOS needs a simulator build; a device .ipa and Android .aab are rejected before any device starts)
(iOS needs a simulator build; a device .ipa and Android .aab are rejected before any session starts)
explore:session [SESSION_ID] [--bundle-id ID] [--output DIRECTORY] [--upload] [--json]
(explores an app that is already installed on an EAS Simulator session you started — run it where
"eas simulator:start --type agent-device --out-config-type dotenv" (or --type argent) wrote .env.eas-simulator,
+12 -56
View File
@@ -48,9 +48,7 @@ export const DEFAULT_ANDROID_DEVICE = "pixel_7";
export const DEVICE_POSES = ["closed", "half-open", "open"] as const;
export type DevicePose = typeof DEVICE_POSES[number];
export type PlatformConfig = { device?: string; bundleId?: string; easProfile?: string;
/** This platform's flows, over the top-level `flows` (e2e's own `platforms` option filters tests within a file). */
flows?: { tests: string[]; frames?: "checkpoints" | "steps" } };
export type PlatformConfig = { device?: string; bundleId?: string; easProfile?: string };
/**
* One named capture target (`targets.<id>`): a platform's device, optionally in a pose, captured as its own report.
@@ -58,9 +56,7 @@ export type PlatformConfig = { device?: string; bundleId?: string; easProfile?:
*/
export type TargetConfig = { platform: ExplorePlatform; device?: string; pose?: DevicePose; bundleId?: string; easProfile?: string; label?: string;
/** This target's device controller and simulator, over `capture.controller` and `capture.simulator`. */
controller?: "agent-device" | "argent"; simulator?: "eas" | "local";
/** This target's flows, over the top-level `flows`: a foldable may run its own journeys, a phone the common ones. */
flows?: { tests: string[]; frames?: "checkpoints" | "steps" } };
controller?: "agent-device" | "argent"; simulator?: "eas" | "local" };
/**
* A target id names directories, report files, CI artifacts and URL parameters, so it is short and plain. `base` and
@@ -75,8 +71,7 @@ export function isTargetId(value: unknown): value is string {
/** Source discovery never consumes a user-authored screen inventory. */
export type ExploreConfig = {
/** `flows` runs setup and the configured flows only; `deterministic` with `flows` runs the route links and then the flows. */
mode: "deterministic" | "agent" | "flows";
mode: "deterministic" | "agent";
app: { name?: string; platform: ExplorePlatform; bundleId: string; easProfile: string; scheme?: string };
navigation: { provider: "auto" | "expo-router" | "react-navigation"; entry?: string };
/**
@@ -107,8 +102,6 @@ export type ExploreConfig = {
simulator?: "local" };
parameters?: Record<string, Record<string, string>>;
setup?: ExploreSetupAction[];
/** The app's e2e flows (test files of the `e2e` package) the capture runs on each revision, as paths or globs from the app directory. */
flows?: { tests: string[]; frames?: "checkpoints" | "steps" };
agent?: { provider: "openai" | "anthropic"; model: string; instructions?: string };
/** Hosted previews: one token-gated EAS Hosting deployment per review, see docs/private-review.md. */
report?: { preview?: { hosting: "eas"; /** null: the link never expires; the deployment lives until someone deletes it. */ expiresAfterDays: number | null; owner?: string; project?: string } };
@@ -278,34 +271,10 @@ function parameters(value: unknown): Record<string, Record<string, string>> {
}));
}
/** The flows the capture runs: the app's e2e test files. `flows` mode needs them; agent mode has no room for them yet. */
function flowsConfig(value: unknown, mode: ExploreConfig["mode"]): ExploreConfig["flows"] {
if (value === undefined) {
if (mode === "flows") fail("flows.tests is required in flows mode", "flows", "List the e2e test files (or globs) the capture runs, for example `flows: { tests: [e2e/**/*.e2e.ts] }`.");
return undefined;
}
if (mode === "agent") fail("flows cannot be combined with agent mode", "flows", "Use mode: flows, or mode: deterministic with flows, so the agent and the flows do not drive the device at once.");
return flowTests(value, "flows");
}
/** `{ tests: [...] }` at `label`: e2e files or globs inside the app directory. Targets and platforms carry their own. */
function flowTests(value: unknown, label: string): NonNullable<ExploreConfig["flows"]> {
const input = record(value, label);
exactKeys(input, ["tests", "frames"], label);
const tests = Array.isArray(input.tests) ? input.tests : input.tests === undefined ? [] : [input.tests];
if (!tests.length || tests.length > 100) fail(`${label}.tests must list between 1 and 100 test files or globs`, `${label}.tests`);
if (input.frames !== undefined && input.frames !== "checkpoints" && input.frames !== "steps") fail(`${label}.frames must be "checkpoints" (frames where the flows call app.screenshot) or "steps" (a frame after every step)`, `${label}.frames`);
return { ...(input.frames === "steps" ? { frames: "steps" as const } : {}), tests: tests.map((entry, index) => {
const path = text(entry, `${label}.tests[${index}]`, 512);
if (isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\u0000-\u001f]/.test(path)) fail(`${label}.tests[${index}] must be a path or glob inside the app directory`, `${label}.tests[${index}]`);
return path.replace(/\\/g, "/");
}) };
}
/** Validate and normalize plain data; credential validation is a separate execution gate. */
export function validateExploreConfig(value: unknown): ExploreConfig {
const root = record(value, "config");
exactKeys(root, ["mode", "app", "navigation", "device", "platforms", "targets", "exploration", "capture", "parameters", "setup", "flows", "agent", "report", "ci"], "config");
exactKeys(root, ["mode", "app", "navigation", "device", "platforms", "targets", "exploration", "capture", "parameters", "setup", "agent", "report", "ci"], "config");
const app = record(root.app, "app");
exactKeys(app, ["name", "platform", "bundleId", "easProfile", "scheme"], "app");
const device = record(root.device, "device");
@@ -319,7 +288,7 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
exactKeys(capture, ["maxMinutes", "maxActions", "repack", "appearance", "launch", "reset", "unattributed", "readinessSeconds", "controller", "simulator"], "capture");
const controller = literal(capture.controller, ["agent-device", "argent"] as const, "capture.controller", "agent-device");
const simulator = literal(capture.simulator, ["eas", "local"] as const, "capture.simulator", "eas");
const mode = literal(root.mode, ["deterministic", "agent", "flows"] as const, "mode", "deterministic");
const mode = literal(root.mode, ["deterministic", "agent"] as const, "mode", "deterministic");
const name = optionalText(app.name, "app.name", 128);
const scheme = app.scheme === undefined ? undefined : customScheme(app.scheme, "app.scheme");
const platform = literal(app.platform, EXPLORE_PLATFORMS, "app.platform", "ios");
@@ -328,7 +297,6 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
const platforms = platformsConfig(root.platforms, platform);
const targets = targetsConfig(root.targets, platform);
if (platforms && targets) fail("Use targets or platforms, not both", "targets", "Move each platforms entry into targets, with its platform.");
if (mode === "agent" && [...Object.values(platforms ?? {}), ...Object.values(targets ?? {})].some(entry => entry.flows)) fail("flows cannot be combined with agent mode", "flows", "Use mode: flows, or mode: deterministic with flows, so the agent and the flows do not drive the device at once.");
let agent: ExploreConfig["agent"];
if (root.agent !== undefined || mode === "agent") {
const input = record(root.agent, "agent");
@@ -341,7 +309,6 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
if (mode === "agent" && !agent.instructions) fail("agent.instructions is required in agent mode", "agent.instructions",
"Use the explore-setup skill to write app-specific instructions and set agent.instructions to their repository-relative path.");
}
const flows = flowsConfig(root.flows, mode);
const report = reportConfig(root.report);
const ci = ciConfig(root.ci);
return {
@@ -376,7 +343,6 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
},
...(root.parameters === undefined ? {} : { parameters: parameters(root.parameters) }),
...(root.setup === undefined ? {} : { setup: setupActions(root.setup, scheme) }),
...(flows === undefined ? {} : { flows }),
...(agent === undefined ? {} : { agent }),
...(report === undefined ? {} : { report }),
...(ci === undefined ? {} : { ci }),
@@ -405,16 +371,15 @@ function platformsConfig(value: unknown, primary: ExplorePlatform): ExploreConfi
for (const platform of entries) {
const label = `platforms.${platform}`;
const entry = mapping[platform] === null ? {} : record(mapping[platform], label);
exactKeys(entry, ["device", "bundleId", "easProfile", "flows"], label);
exactKeys(entry, ["device", "bundleId", "easProfile"], label);
const device = optionalText(entry.device, `${label}.device`, 128);
const flows = entry.flows === undefined ? undefined : flowTests(entry.flows, `${label}.flows`);
const bundleId = entry.bundleId === undefined ? undefined : applicationId(entry.bundleId, `${label}.bundleId`);
const easProfile = entry.easProfile === undefined ? undefined : profileName(entry.easProfile, `${label}.easProfile`);
if (platform !== primary && (bundleId === undefined || easProfile === undefined)) {
fail(`${label} needs bundleId and easProfile`, label,
`Set ${label}.bundleId to the app's ${platform === "android" ? "android.package" : "ios.bundleIdentifier"} and ${label}.easProfile to an eas.json profile that builds a ${platform === "android" ? "signed APK (android.buildType: apk)" : "simulator app (ios.simulator: true)"}.`);
}
result[platform] = { ...(device === undefined ? {} : { device }), ...(bundleId === undefined ? {} : { bundleId }), ...(easProfile === undefined ? {} : { easProfile }), ...(flows === undefined ? {} : { flows }) };
result[platform] = { ...(device === undefined ? {} : { device }), ...(bundleId === undefined ? {} : { bundleId }), ...(easProfile === undefined ? {} : { easProfile }) };
}
return result;
}
@@ -430,8 +395,7 @@ function targetsConfig(value: unknown, primary: ExplorePlatform): ExploreConfig[
const label = `targets.${id}`;
if (!isTargetId(id)) fail(`${label}: a target id is lowercase letters, digits and dashes, starts with a letter, and is not base, head or report`, label);
const entry = record(mapping[id], label);
exactKeys(entry, ["platform", "device", "pose", "bundleId", "easProfile", "label", "controller", "simulator", "flows"], label);
const flows = entry.flows === undefined ? undefined : flowTests(entry.flows, `${label}.flows`);
exactKeys(entry, ["platform", "device", "pose", "bundleId", "easProfile", "label", "controller", "simulator"], label);
const platform = literal(entry.platform, EXPLORE_PLATFORMS, `${label}.platform`);
const device = optionalText(entry.device, `${label}.device`, 128);
const pose = entry.pose === undefined ? undefined : literal(entry.pose, DEVICE_POSES, `${label}.pose`);
@@ -446,7 +410,7 @@ function targetsConfig(value: unknown, primary: ExplorePlatform): ExploreConfig[
}
result[id] = { platform, ...(device === undefined ? {} : { device }), ...(pose === undefined ? {} : { pose }), ...(bundleId === undefined ? {} : { bundleId }),
...(easProfile === undefined ? {} : { easProfile }), ...(name === undefined ? {} : { label: name }),
...(controller === undefined ? {} : { controller }), ...(simulator === undefined ? {} : { simulator }), ...(flows === undefined ? {} : { flows }) };
...(controller === undefined ? {} : { controller }), ...(simulator === undefined ? {} : { simulator }) };
}
return result;
}
@@ -498,7 +462,7 @@ export function resolveTargetConfig(config: ExploreConfig, selection: { target?:
void _controller; void _simulator;
const controller = entry.controller ?? config.capture.controller ?? "agent-device";
const simulator = entry.simulator ?? config.capture.simulator ?? "eas";
return { ...rest, target: chosen, ...(entry.flows ? { flows: entry.flows } : {}),
return { ...rest, target: chosen,
capture: { ...capture, ...(controller === "argent" ? { controller } : {}), ...(simulator === "local" ? { simulator } : {}) },
app: { ...config.app, platform: entry.platform, bundleId: entry.bundleId ?? config.app.bundleId, easProfile: entry.easProfile ?? config.app.easProfile },
device: { name: entry.device ?? (primary ? config.device.name : DEFAULT_ANDROID_DEVICE),
@@ -531,7 +495,7 @@ export function resolvePlatformConfig(config: ExploreConfig, platform: ExplorePl
const primary = platform === config.app.platform;
const { platforms: _platforms, ...rest } = config;
void _platforms;
return { ...rest, ...(entry.flows ? { flows: entry.flows } : {}),
return { ...rest,
app: { ...config.app, platform, bundleId: entry.bundleId ?? (primary ? config.app.bundleId : fail(`platforms.${platform}.bundleId is required`)),
easProfile: entry.easProfile ?? (primary ? config.app.easProfile : fail(`platforms.${platform}.easProfile is required`)) },
device: { name: entry.device ?? (primary ? config.device.name : platform === "android" ? DEFAULT_ANDROID_DEVICE : config.device.name),
@@ -544,16 +508,8 @@ export function resolvePlatformConfig(config: ExploreConfig, platform: ExplorePl
* every screen (`scope: all`) and keep its hosted link (`expiresIn: never`). `expiresIn` changes nothing when the
* config hosts no report.
*/
export function withRunOverrides(config: ExploreConfig, overrides: { scope?: string | undefined; expiresIn?: string | undefined; controller?: string | undefined; simulator?: string | undefined; repack?: string | undefined ; flows?: readonly string[] | undefined }): ExploreConfig{
export function withRunOverrides(config: ExploreConfig, overrides: { scope?: string | undefined; expiresIn?: string | undefined; controller?: string | undefined; simulator?: string | undefined; repack?: string | undefined }): ExploreConfig {
let result = config;
if (overrides.flows !== undefined) {
// --flows FILE[,FILE]: run these e2e files as the capture, and nothing else (flows mode), whatever config.yaml says.
const tests = overrides.flows.map(entry => entry.trim()).filter(Boolean);
if (!tests.length) fail("--flows needs at least one e2e test file or glob", "--flows");
for (const path of tests) if (isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\u0000-\u001f]/.test(path)) fail(`--flows ${path} must be a path or glob inside the app directory`, "--flows");
if (result.mode === "agent") fail("--flows cannot be combined with agent mode", "--flows");
result = { ...result, mode: "flows", flows: { tests: tests.map(path => path.replace(/\\/g, "/")) } };
}
if (overrides.repack !== undefined) {
if (overrides.repack !== "eas" && overrides.repack !== "local") fail("--repack must be eas or local", "--repack");
result = { ...result, capture: { ...result.capture, repack: overrides.repack } };
+2 -55
View File
@@ -62,37 +62,6 @@ export type BundleLaunchCapture = {
video?: LaunchVideo;
};
/** A frame a flow took with `app.screenshot(label)`; stored and verified like a launch frame. */
/** `contentSha256` hashes the pixels between the system bands, so frames that differ only by the clock fold together in the Viewer. */
export type FlowFrame = LaunchFrame & { contentSha256?: string };
/** A flows run that produced no flow records: the e2e worker failed before any test ran. */
export type FlowsFailure = { code: string; message: string };
export type FlowStatus = "passed" | "failed" | "skipped" | "flaky" | "timed-out" | "interrupted" | "blocked";
export type FlowStepStatus = "passed" | "failed" | "blocked" | "timed-out" | "cancelled";
export type BundleFlowStep = {
/** The e2e step API (`locator.tap`, `expect.toBeVisible`, `app.screenshot`, `agent.act`). */
api: string; label: string; status: FlowStepStatus; durationMs: number;
/** The key under `frames` of the screenshot this step took. */
frame?: string;
error?: { code: string; message: string };
/** The line of the test file the step was called from, when e2e recorded one. */
line?: number;
};
/**
* One flow (an e2e test) the capture ran on this revision: its outcome, its steps, and the frames it took. The frames
* are review surfaces of their own (`flow:<id>/<key>`), never attributed to a source route.
*/
export type BundleFlow = {
file: string; title: string; status: FlowStatus; durationMs: number;
error?: { code: string; message: string };
/** The line of the test file the test is declared on, when e2e recorded one. */
line?: number;
steps: BundleFlowStep[];
frames: Record<string, FlowFrame>;
};
/** The review surface id of a flow frame. */
export const flowSurfaceId = (flowId: string, key: string): string => `flow:${flowId}/${key}`;
export type LaunchFilmstrip = LaunchFrame & {
/** When each tile was on screen, in milliseconds from the launch transition (negative before it). */
frameTimesMs: number[];
@@ -115,10 +84,6 @@ export type CaptureBundle = {
outcomes: Record<string, CaptureOutcome>;
/** Launch evidence per appearance (`light`/`dark`), when the capture observed the app launch. */
launch?: Record<string, BundleLaunchCapture>;
/** The app's e2e flows run on this revision, by flow id, when the config names flows. */
flows?: Record<string, BundleFlow>;
/** Why the flows produced no records at all (the e2e worker did not run, or collected no test), when the config names flows. */
flowsFailure?: FlowsFailure;
/** How route frames were produced; absent in bundles from before `capture.reset` existed (root-link was not applied). */
procedure?: { reset: "root-link" | "none"; readinessSeconds?: number };
/** Committed destination goals used for this capture, including cached evidence. */
@@ -267,20 +232,6 @@ export type PublicLaunchEvidence = {
base?: PublicLaunchSide; head?: PublicLaunchSide;
visual?: PublicVisualVerdict;
};
/** A flow frame as published: the capture's record with its stored URL. */
export type PublicFlowFrame = Omit<FlowFrame, "path"> & { url: string };
export type PublicFlowSide = Omit<BundleFlow, "frames" | "file" | "title"> & { frames: Record<string, PublicFlowFrame> };
/**
* One flow across the two revisions: its outcome on each side and its frames in step order. A frame is compared when
* both sides took it; a side that failed before a frame simply lacks it.
*/
export type PublicFlowEvidence = {
/** The flow id (`<file>/<title>`, slugged); its frames are the surfaces `flow:<id>/<key>`. */
id: string; title: string; file: string;
base?: PublicFlowSide; head?: PublicFlowSide;
/** A secondary-appearance frame is `<key>@<scheme>` with its `colorScheme`, taken by a second run of the flow in that appearance. */
frames: Array<{ key: string; id: string; label: string; visual?: PublicVisualVerdict; colorScheme?: "light" | "dark" }>;
};
export type PublicReview = {
contract: "explore.review";
pullRequest: ReviewPresentation; mode: "all" | "changes"; createdAt: string;
@@ -310,10 +261,6 @@ export type PublicReview = {
navigation?: { base: NavigationGraph; head: NavigationGraph };
/** The app launch per appearance, kept apart from source routes: it has no route or navigation. */
launch?: PublicLaunchEvidence[];
/** The app's e2e flows the capture ran, kept apart from source routes like the launch. */
flows?: PublicFlowEvidence[];
/** A side whose flows did not run at all, with e2e's reason; the review still carries the other side's flows. */
flowsFailure?: { base?: FlowsFailure; head?: FlowsFailure };
surfaces: Array<{
id: string; status: "added" | "modified" | "removed" | "unchanged";
base: SourceRoute | null; head: SourceRoute | null;
@@ -336,7 +283,7 @@ export function validateCapturePlan(value: unknown): SourceCapturePlan {
const p = value as SourceCapturePlan;
if (!p || p.contract !== "explore.plan"
|| !/^[a-f0-9]{40}$/.test(p.baseSha) || !/^[a-f0-9]{40}$/.test(p.headSha)
|| !["all", "changes"].includes(p.mode) || (p.captureRoutes !== undefined && p.captureRoutes !== false)
|| !["all", "changes"].includes(p.mode)
|| !Array.isArray(p.surfaces) || p.surfaces.length > 5000) throw new Error("Invalid source capture plan");
const ids = new Set<string>();
for (const s of p.surfaces) {
@@ -367,7 +314,7 @@ export function validateCapturePlan(value: unknown): SourceCapturePlan {
const context = graph ? new Set(navigationCaptureContext(graph, seeds, routes)) : undefined;
for (const surface of p.surfaces) {
const entry = surface[`${side}Surface`];
const selected = Boolean(p.captureRoutes !== false && entry && entry.kind !== "redirect" && !excluded.has(surface.id)
const selected = Boolean(entry && entry.kind !== "redirect" && !excluded.has(surface.id)
&& (p.mode === "all" || (context ? context.has(surface.id) : surface.status !== "unchanged")));
if (surface[`${side}Capture`] !== selected) throw new Error("Capture selection disagrees with source and navigation context");
}
+1 -55
View File
@@ -1,5 +1,5 @@
import { projectReviewPresentation } from "./review.js";
import { LAUNCH_SURFACE_ID, flowSurfaceId, launchSurfaceId, type PublicFlowSide, type PublicLaunchSide, type PublicReview, type PublicVisualVerdict } from "./capture.js";
import { LAUNCH_SURFACE_ID, launchSurfaceId, type PublicLaunchSide, type PublicReview, type PublicVisualVerdict } from "./capture.js";
import { SOURCE_IMPACT_KINDS, validateSourceChangeSummary } from "./source-change.js";
import { validateNavigationGraph } from "./navigation-graph.js";
import { validateSourceRoute } from "./source-route.js";
@@ -127,59 +127,6 @@ function validLaunchSide(side: unknown): boolean {
&& /^[a-f0-9]{64}$/.test(video.sha256) && Number.isSafeInteger(video.bytes) && video.bytes > 0 && video.mimeType === "video/mp4"
&& (video.durationMs === undefined || (Number.isSafeInteger(video.durationMs) && video.durationMs >= 0))));
}
const FLOW_STATUSES = new Set(["passed", "failed", "skipped", "flaky", "timed-out", "interrupted", "blocked"]);
const STEP_STATUSES = new Set(["passed", "failed", "blocked", "timed-out", "cancelled"]);
const validFlowFrame = (value: unknown): boolean => Boolean(value) && typeof value === "object"
&& Object.keys(value as object).every(key => ["url", "sha256", "width", "height", "capturedAt", "contentSha256"].includes(key))
&& typeof (value as { url: unknown }).url === "string" && /^[a-f0-9]{64}$/.test(String((value as { sha256: unknown }).sha256))
&& ((value as { contentSha256?: unknown }).contentSha256 === undefined || /^[a-f0-9]{64}$/.test(String((value as { contentSha256: unknown }).contentSha256)))
&& Number.isSafeInteger((value as { width: unknown }).width) && Number.isSafeInteger((value as { height: unknown }).height)
&& Number.isFinite(Date.parse(String((value as { capturedAt: unknown }).capturedAt)));
function validFlowSide(value: unknown): value is PublicFlowSide {
if (!value || typeof value !== "object" || Object.keys(value).some(key => !["status", "durationMs", "error", "line", "steps", "frames"].includes(key))) return false;
const side = value as PublicFlowSide;
return FLOW_STATUSES.has(side.status) && Number.isSafeInteger(side.durationMs) && side.durationMs >= 0
&& (side.line === undefined || (Number.isSafeInteger(side.line) && side.line > 0))
&& (side.error === undefined || (typeof side.error?.code === "string" && typeof side.error.message === "string"))
&& Array.isArray(side.steps) && side.steps.length <= 10_000 && side.steps.every(step => step && typeof step === "object"
&& Object.keys(step).every(key => ["api", "label", "status", "durationMs", "frame", "error", "line"].includes(key))
&& (step.line === undefined || (Number.isSafeInteger(step.line) && step.line > 0))
&& typeof step.api === "string" && typeof step.label === "string" && STEP_STATUSES.has(step.status) && Number.isSafeInteger(step.durationMs)
&& (step.frame === undefined || (typeof step.frame === "string" && Object.hasOwn(side.frames, step.frame))))
&& side.frames !== null && typeof side.frames === "object" && Object.entries(side.frames).every(([key, frame]) => /^[a-z0-9-]+(?:@(?:light|dark))?$/.test(key) && validFlowFrame(frame));
}
/** Flow evidence is one entry per flow either side ran, with a verdict only for frames both sides took. */
const validFlowsFailure = (value: unknown): boolean => Boolean(value) && typeof value === "object" && Object.keys(value as object).every(key => key === "code" || key === "message")
&& typeof (value as { code: unknown }).code === "string" && typeof (value as { message: unknown }).message === "string" && (value as { message: string }).message.length <= 4_000;
function assertFlowEvidence(review: PublicReview, enforceComparisonEvidence: boolean): void {
if (review.flowsFailure !== undefined) {
const failure = review.flowsFailure;
if (!failure || typeof failure !== "object" || !Object.keys(failure).length || Object.keys(failure).some(key => key !== "base" && key !== "head")
|| Object.values(failure).some(value => !validFlowsFailure(value))) throw new Error("Public flows failure is invalid");
}
const flows = review.flows;
// Reports from before flow evidence carry a structural `flows` object (source-derived groups); it is not evidence.
if (flows === undefined || (flows !== null && typeof flows === "object" && !Array.isArray(flows))) return;
if (!Array.isArray(flows) || flows.length === 0 || flows.length > 1_000) throw new Error("Public flow evidence is invalid");
const ids = new Set<string>();
for (const entry of flows) {
if (!entry || typeof entry !== "object" || Object.keys(entry).some(key => !["id", "title", "file", "base", "head", "frames"].includes(key))
|| typeof entry.id !== "string" || !/^[a-z0-9-]+\/[a-z0-9-]+$/.test(entry.id) || ids.has(entry.id)
|| typeof entry.title !== "string" || typeof entry.file !== "string"
|| (!entry.base && !entry.head) || (entry.base !== undefined && !validFlowSide(entry.base)) || (entry.head !== undefined && !validFlowSide(entry.head))
|| !Array.isArray(entry.frames)) throw new Error("Public flow evidence is invalid");
ids.add(entry.id);
const keys = new Set<string>();
for (const frame of entry.frames) {
if (!frame || typeof frame !== "object" || Object.keys(frame).some(key => !["key", "id", "label", "visual", "colorScheme"].includes(key))
|| (frame.colorScheme !== undefined && (frame.colorScheme !== "light" && frame.colorScheme !== "dark" || !frame.key.endsWith(`@${frame.colorScheme}`)))
|| typeof frame.key !== "string" || keys.has(frame.key) || frame.id !== flowSurfaceId(entry.id, frame.key) || typeof frame.label !== "string"
|| (!entry.base?.frames[frame.key] && !entry.head?.frames[frame.key])) throw new Error("Public flow evidence is invalid");
keys.add(frame.key);
if (frame.visual !== undefined) assertVisualVerdict(frame.visual, enforceComparisonEvidence, Boolean(entry.base?.frames[frame.key] && entry.head?.frames[frame.key]));
}
}
}
/** Launch evidence is one entry per captured appearance, with a verdict only when both sides observed a splash. */
function assertLaunchEvidence(review: PublicReview, enforceComparisonEvidence: boolean): void {
const launch = review.launch;
@@ -386,7 +333,6 @@ function validatePublicReview(review: PublicReview, enforceComparisonEvidence: b
}
if (review.runtime.appIcon !== undefined) assertAppIcon(review.runtime.appIcon);
assertLaunchEvidence(review, enforceComparisonEvidence);
assertFlowEvidence(review, enforceComparisonEvidence);
const ids = new Set<string>();
const sideBuildIds = { base: new Set<string>(), head: new Set<string>() };
for (const surface of review.surfaces) {
+1 -19
View File
@@ -20,7 +20,7 @@ export type PublicCommentState = {
phase: PublicCommentPhase;
pullRequest: ReviewPresentation;
mode: "all" | "changes";
executionMode: "deterministic" | "agent" | "flows";
executionMode: "deterministic" | "agent";
/** Repository-relative path of the reviewed configuration file. */
configPath: string;
links: ViewerLinks;
@@ -194,23 +194,6 @@ function previewExpiry(expiresAt: number): string {
* (source-unchanged screens captured in another runtime state) and app-wide source changes that
* left some screens without a visible difference.
*/
/** "Flow Send money: passed, 4 frames, 1 changed" — one line per e2e flow the capture ran. */
function flowLines(review: PublicReview): string[] {
const notRun = ((["head", "base"] as const).filter(side => review.flowsFailure?.[side]))
.map(side => `Flows did not run on ${side}: ${plainText(review.flowsFailure![side]!.message, 200)}.`);
return [...notRun, ...(Array.isArray(review.flows) ? review.flows : []).map(entry => {
const side = (name: "base" | "head") => {
const flow = entry[name];
if (!flow) return `not run on ${name}`;
const failed = flow.steps.find(step => step.status !== "passed");
return `${flow.status} on ${name}${failed && flow.status !== "passed" ? ` at step ${flow.steps.indexOf(failed) + 1} (${plainText(failed.api, 40)} ${plainText(failed.label, 80)})` : ""}`;
};
const compared = entry.frames.filter(frame => frame.visual);
const changed = compared.filter(frame => frame.visual?.verdict === "modified").length;
const frames = entry.frames.length ? `${plural(entry.frames.length, "frame")}${compared.length ? `, ${changed ? `${changed} changed` : "none changed"}` : ""}` : "no frames";
return `Flow ${plainText(entry.title, 80)}: ${side("head")}; ${frames}${entry.base && entry.head && entry.base.status === "passed" && entry.head.status !== "passed" ? ` (was ${side("base")})` : ""}.`;
})];
}
/** "Launch: splash unchanged for 3.1 s" — the app launch per appearance, kept apart from the screen rows. */
function launchLine(review: PublicReview): string | undefined {
const launch = review.launch ?? [];
@@ -242,7 +225,6 @@ function contextLines(review: PublicReview): string[] {
const lines: string[] = [];
const launch = launchLine(review);
if (launch) lines.push(launch);
lines.push(...flowLines(review));
if (variants > 0) lines.push(`${plural(variants, "screen")} ${variants === 1 ? "differs" : "differ"} only in runtime state (screen variants); no source change reaches ${variants === 1 ? "it" : "them"}.`);
if (appWide.length > 0) {
const named = files.length ? ` (${files.slice(0, 5).map(path => `\`${plainText(path, 120).replace(/`/g, "")}\``).join(", ")}${files.length > 5 ? ", …" : ""})` : "";
+17 -29
View File
@@ -577,7 +577,7 @@ export async function deployExplorationReport(options: ExplorationDeployOptions)
message: "An EAS login is required to host the report", nextAction: "Run `eas login` or set EXPO_TOKEN, then rerun with --upload." });
if (!/^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$/.test(options.project)) throw previewError("PREVIEW_PROJECT_INVALID", `Invalid EAS project slug: ${options.project}`, "Pass --project as a lowercase slug such as expo-explore.");
if (options.alias !== undefined && !HOSTING_ALIAS.test(options.alias)) throw previewError("PREVIEW_ALIAS_INVALID", `Invalid EAS Hosting alias: ${options.alias}`, "Pass --alias as a lowercase slug such as bluesky.");
if (options.token !== undefined && !HOSTED_TOKEN.test(options.token)) throw previewError("PREVIEW_TOKEN_INVALID", "EXPLORE_PREVIEW_TOKEN must be 32 characters of a-z and 2-7.", "Generate one with `LC_ALL=C tr -dc a-z2-7 </dev/urandom | head -c 32` and set EXPLORE_PREVIEW_TOKEN, or unset it for a random token.");
if (options.token !== undefined && !HOSTED_TOKEN.test(options.token)) throw previewError("PREVIEW_TOKEN_INVALID", "EXPLORE_PREVIEW_TOKEN must be 32 characters of a-z and 2-7.", "Generate one with `openssl rand 20 | base32 | tr A-Z a-z` and set EXPLORE_PREVIEW_TOKEN, or unset it for a random token.");
const exportPath = resolve(options.exportPath ?? PREVIEW_EXPORT_PATH);
await assertExport(exportPath);
let zip: Uint8Array;
@@ -765,40 +765,16 @@ async function verifyDeployment(check: { origin: string; token: string; reports:
"Check EAS Hosting availability and rerun the deploy job.", { retryable: true, cause: error });
}
};
// What the token serves differs from what was deployed: a listing or report that does not match, or undefined.
const mismatch = async (): Promise<CiError | undefined> => {
for (const expected of check.reports) {
const report = await get(`/p/${check.token}/report.zip${expected.query}`);
const bytes = report.status === 200 ? new Uint8Array(await report.arrayBuffer()) : new Uint8Array();
if (report.status !== 200 || bytes.byteLength !== expected.bytes || createHash("sha256").update(bytes).digest("hex") !== expected.sha256) {
return deployError("PREVIEW_VERIFY_FAILED", "The hosted preview did not serve the exact report that was deployed.",
"Rerun the deploy job; the deployment's sealed key or ciphertext did not match.", { details: { status: report.status, report: expected.query } });
}
}
if (check.listing !== undefined) {
const list = await get(`/p/${check.token}/reports.json`);
const body = list.status === 200 ? await list.text() : "";
if (list.status !== 200 || body !== check.listing) return deployError("PREVIEW_VERIFY_FAILED", "The hosted preview did not list the targets that were deployed.",
"Rerun the deploy job; the deployment's report listing did not match.", { details: { status: list.status } });
}
return undefined;
};
const started = check.now();
let liveAfterMs = 0;
for (;;) {
// A browser's request: the token page negotiates, and anything that does not ask for HTML gets the Markdown index.
const shell = await get(`/p/${check.token}`, "text/html");
const serving = shell.status === 200 && (shell.headers.get("content-type") ?? "").startsWith("text/html");
// An alias with a fixed token (the example report) serves the token page from the deployment it still points at, so
// it has moved only once it serves this deployment's listing and reports as well.
const stale = serving && check.alias ? await mismatch() : undefined;
if (serving && !stale) { liveAfterMs = check.now() - started; break; }
if (shell.status === 200 && (shell.headers.get("content-type") ?? "").startsWith("text/html")) { liveAfterMs = check.now() - started; break; }
const waitedMs = check.now() - started;
if (waitedMs > check.timeoutMs) {
// An alias that does not serve the token page yet still points at an earlier deployment; the deployment itself not serving is a failed deployment.
if (check.alias) throw deployError("PREVIEW_ALIAS_BEHIND", stale
? `The alias ${check.origin} still serves an earlier deployment ${Math.round(waitedMs / 1000)} s after eas deploy returned.`
: `The alias ${check.origin} still answers HTTP ${shell.status} ${Math.round(waitedMs / 1000)} s after eas deploy returned.`,
if (check.alias) throw deployError("PREVIEW_ALIAS_BEHIND", `The alias ${check.origin} still answers HTTP ${shell.status} ${Math.round(waitedMs / 1000)} s after eas deploy returned.`,
"Nothing to do: the alias catches up on its own, and the next push verifies it again.", { retryable: true, details: { origin: check.origin, status: shell.status, waitedMs } });
throw deployError("PREVIEW_VERIFY_FAILED", `The hosted preview did not become available (HTTP ${shell.status}).`,
"Rerun the deploy job; if the deployment keeps failing verification, inspect it in the EAS Hosting dashboard.", { retryable: true, details: { origin: check.origin, status: shell.status, waitedMs } });
@@ -809,8 +785,20 @@ async function verifyDeployment(check: { origin: string; token: string; reports:
if (api.status !== 200 || !(api.headers.get("content-type") ?? "").startsWith("application/json")) {
throw deployError("PREVIEW_VERIFY_FAILED", `The hosted preview did not answer the agent API (HTTP ${api.status}).`, "Rerun the deploy job; if the deployment keeps failing verification, inspect it in the EAS Hosting dashboard.", { retryable: true });
}
// The deployment itself serves exactly what was deployed or it failed; the alias was checked while it was polled.
if (!check.alias) { const failure = await mismatch(); if (failure) throw failure; }
for (const expected of check.reports) {
const report = await get(`/p/${check.token}/report.zip${expected.query}`);
const bytes = report.status === 200 ? new Uint8Array(await report.arrayBuffer()) : new Uint8Array();
if (report.status !== 200 || bytes.byteLength !== expected.bytes || createHash("sha256").update(bytes).digest("hex") !== expected.sha256) {
throw deployError("PREVIEW_VERIFY_FAILED", "The hosted preview did not serve the exact report that was deployed.",
"Rerun the deploy job; the deployment's sealed key or ciphertext did not match.", { details: { status: report.status, report: expected.query } });
}
}
if (check.listing !== undefined) {
const list = await get(`/p/${check.token}/reports.json`);
const body = list.status === 200 ? await list.text() : "";
if (list.status !== 200 || body !== check.listing) throw deployError("PREVIEW_VERIFY_FAILED", "The hosted preview did not list the targets that were deployed.",
"Rerun the deploy job; the deployment's report listing did not match.", { details: { status: list.status } });
}
const other = check.token.endsWith("a") ? `${check.token.slice(0, -1)}b` : `${check.token.slice(0, -1)}a`;
// Errors name each probe by its shape: the near-miss token differs from the real one in its last character only.
for (const [path, shape] of [["/", "/"], [`/p/${other}`, "/p/<wrong token>"], [`/p/${other}/report.zip`, "/p/<wrong token>/report.zip"],
+2 -47
View File
@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
import { lstat, readFile, realpath } from "node:fs/promises";
import { isAbsolute, relative, resolve, sep } from "node:path";
import { assertDecodedPng } from "../shared/png-evidence.js";
import { assertAgentAcceptance, validateCapturePlan, type AppIconImage, type BundleLaunchCapture, type CaptureBundle, type CaptureOutcome, type CapturedImage, type LaunchFilmstrip, type LaunchFrame, type PublicFlowEvidence, type PublicFlowSide, type PublicLaunchSide, type PublicReview, flowSurfaceId, homeIndicatorBandPercent, launchSurfaceId, statusBarBandPercent } from "../contracts/capture.js";
import { assertAgentAcceptance, validateCapturePlan, type AppIconImage, type BundleLaunchCapture, type CaptureBundle, type CaptureOutcome, type CapturedImage, type LaunchFilmstrip, type LaunchFrame, type PublicLaunchSide, type PublicReview, homeIndicatorBandPercent, launchSurfaceId, statusBarBandPercent } from "../contracts/capture.js";
import { COLOR_SCHEMES } from "../capture/appearance.js";
import { launchDirectory } from "../capture/launch-capture.js";
import { APP_ICON_FILE, APP_ICON_MAX_SIZE } from "../capture/app-icon.js";
@@ -235,21 +235,6 @@ async function uploadSide(store: ScreenshotStore, directory: string, expectedCom
launch[scheme] = { ...rest, ...(splash ? { splash: await frame(splash, "splash") } : {}), settled: await frame(settled, "settled"),
...(publicFilmstrip ? { filmstrip: publicFilmstrip } : {}), ...(publicVideo ? { video: publicVideo } : {}) };
}
const flows: Record<string, PublicFlowSide> = {};
for (const [flowId, flow] of Object.entries(bundle.flows ?? {})) {
if (!/^[a-z0-9-]+\/[a-z0-9-]+$/.test(flowId)) throw new Error("Capture bundle flow id is invalid");
const frames: PublicFlowSide["frames"] = {};
for (const [key, value] of Object.entries(flow.frames)) {
if (!/^[a-z0-9-]+(?:@(?:light|dark))?$/.test(key)) throw new Error("Capture bundle flow frame key is invalid");
const bytes = await evidenceFile(value.path); assertDecodedPng(bytes, "Flow frame");
if (value.sha256 !== createHash("sha256").update(bytes).digest("hex") || value.width !== bytes.readUInt32BE(16) || value.height !== bytes.readUInt32BE(20)
|| !Number.isFinite(Date.parse(value.capturedAt)) || (value.contentSha256 !== undefined && !SHA256.test(value.contentSha256))) throw new Error("Flow frame provenance mismatch");
const { path: _, ...metadata } = value;
frames[key] = { ...metadata, url: await store.put(`${prefix}/flow-${flowId.replace("/", "-")}-${key}.png`, bytes, "image/png") };
}
const { frames: _frames, file: _file, title: _title, ...rest } = flow;
flows[flowId] = { ...rest, frames };
}
let appIcon: AppIconImage | undefined;
if (bundle.appIcon) {
const iconPath = resolve(directory, bundle.appIcon.path);
@@ -262,32 +247,7 @@ async function uploadSide(store: ScreenshotStore, directory: string, expectedCom
const { path: _, ...metadata } = bundle.appIcon;
appIcon = { ...metadata, url: await store.put(`${prefix}/${APP_ICON_FILE}`, bytes, "image/png") };
}
return { bundle, images, appIcon, launch, flows, ...(bundle.flowsFailure ? { flowsFailure: bundle.flowsFailure } : {}) };
}
/** Every flow either side ran, head's order first; a frame row for each key a side took, in head's step order. */
function publicFlows(base: { bundle: CaptureBundle; flows: Record<string, PublicFlowSide> }, head: { bundle: CaptureBundle; flows: Record<string, PublicFlowSide> },
assessments: CaptureReviewOptions["assessments"]): PublicFlowEvidence[] {
const ids = [...new Set([...Object.keys(head.flows), ...Object.keys(base.flows)])];
const schemes = bundleColorSchemes(head.bundle);
return ids.map(id => {
const record = head.bundle.flows?.[id] ?? base.bundle.flows?.[id];
const keys = [...new Set([...(head.bundle.flows?.[id]?.steps ?? []).flatMap(step => step.frame ? [step.frame] : []),
...(base.bundle.flows?.[id]?.steps ?? []).flatMap(step => step.frame ? [step.frame] : [])])];
// A checkpoint frame is named by its `app.screenshot(label)`; a per-step frame by its step number and what the step did.
const labelOf = (key: string) => {
const steps = (head.bundle.flows?.[id] ?? base.bundle.flows?.[id])?.steps ?? [];
const index = steps.findIndex(step => step.frame === key);
const step = steps[index];
if (!step) return key;
return step.api === "app.screenshot" ? step.label || key : `${index + 1}. ${step.label || step.api}`.slice(0, 80);
};
return { id, title: record?.title ?? id, file: record?.file ?? "",
...(base.flows[id] ? { base: base.flows[id] } : {}), ...(head.flows[id] ? { head: head.flows[id] } : {}),
frames: keys.flatMap(key => [key, ...schemes.slice(1).map(scheme => `${key}@${scheme}`)]
.filter(frameKey => frameKey === key || head.flows[id]?.frames[frameKey] || base.flows[id]?.frames[frameKey])
.map(frameKey => { const surface = flowSurfaceId(id, frameKey); const visual = assessments?.[surface]?.visual; const scheme = frameKey.slice(key.length + 1);
return { key: frameKey, id: surface, label: labelOf(key), ...(visual ? { visual } : {}), ...(scheme ? { colorScheme: scheme as "light" | "dark" } : {}) }; })) };
});
return { bundle, images, appIcon, launch };
}
export type CaptureReviewOptions = {
plan: unknown; pullRequest: unknown; baseDirectory: string; headDirectory: string;
@@ -359,8 +319,6 @@ async function constructCaptureReview(options: CaptureReviewOptions, store: Scre
...(base.launch[scheme] ? { base: base.launch[scheme]! } : {}), ...(head.launch[scheme] ? { head: head.launch[scheme]! } : {}),
...(assessment?.visual ? { visual: assessment.visual } : {}) };
}) } : {}),
...(Object.keys(head.flows).length || Object.keys(base.flows).length ? { flows: publicFlows(base, head, options.assessments) } : {}),
...(base.flowsFailure || head.flowsFailure ? { flowsFailure: { ...(base.flowsFailure ? { base: base.flowsFailure } : {}), ...(head.flowsFailure ? { head: head.flowsFailure } : {}) } } : {}),
surfaces: plan.surfaces.flatMap(s => appearancePairs(s.id, colorSchemes, baseColorSchemes).map(({ id, scheme, baseId }) => {
const assessment = options.assessments?.[id];
// The bundle records one outcome per route; a secondary appearance's surface carries that outcome only when the
@@ -412,9 +370,6 @@ export async function prepareCaptureReview(options: CaptureReviewOptions): Promi
for (const record of Object.values(bundle.launch ?? {})) {
for (const file of [record.splash, record.settled, record.video]) if (file) assets.set(file.sha256, { sha256: file.sha256, path: resolve(directory, file.path) });
}
for (const flow of Object.values(bundle.flows ?? {})) {
for (const frame of Object.values(flow.frames)) assets.set(frame.sha256, { sha256: frame.sha256, path: resolve(directory, frame.path) });
}
}
// Only the head icon names the app in the review header.
const icon = review.runtime.appIcon && (await readCaptureBundle(options.headDirectory)).appIcon;
+1 -25
View File
@@ -1,6 +1,6 @@
import { unattributedIssue } from "../capture/health.js";
import { appearancePairs, bundleColorSchemes } from "../capture/appearance.js";
import { flowSurfaceId, homeIndicatorBandPercent, launchSurfaceId, statusBarBandPercent } from "../contracts/capture.js";
import { homeIndicatorBandPercent, launchSurfaceId, statusBarBandPercent } from "../contracts/capture.js";
import { readFileSync, statSync } from "node:fs";
import { stat } from "node:fs/promises";
import { isAbsolute, resolve } from "node:path";
@@ -556,30 +556,6 @@ export async function assessPublicEvidence(options: {
}
}
// Flow frames compare like screens when both revisions took the same frame of the same flow.
for (const [flowId, headFlow] of Object.entries(options.head.bundle.flows ?? {})) {
const baseFlow = options.base.bundle.flows?.[flowId];
if (!baseFlow || !visualAvailable) continue;
for (const [key, headFrame] of Object.entries(headFlow.frames)) {
const baseFrame = baseFlow.frames[key];
if (!baseFrame || now() > deadline) continue;
const id = flowSurfaceId(flowId, key);
const basePath = localEvidencePath(options.base, baseFrame.path); const headPath = localEvidencePath(options.head, headFrame.path);
if (!basePath || !headPath) continue;
try {
const { measurement, ignoredTop, ignoredBottom } = ignoreSystemBands(await measure(basePath, headPath), { top: statusBarBandPercent(options.platform), bottom: homeIndicatorBandPercent(options.platform) });
const visual = visualVerdict(assessVisualMeasurements({ baselineSamples: 1, currentSamples: 1, requiredSamples: 1,
baselineWithin: [], currentWithin: [], crossBuild: [measurement], representative: measurement }), threshold);
if (ignoredTop > 0) visual.ignoredStatusBarRegions = ignoredTop;
if (ignoredBottom > 0) visual.ignoredHomeIndicatorRegions = ignoredBottom;
surfaces[id] = { visual };
} catch (error) {
comparisonError(id, error, { code: "VISUAL_COMPARISON_FAILED", stage: "compare",
message: "Flow frame comparison failed.", nextAction: "Check the flow frames and the agent-device comparison diagnostics, then rerun comparison.", retryable: true });
}
}
}
return {
surfaces,
summary: {
-15
View File
@@ -1,5 +1,3 @@
import { createRequire } from "node:module";
import { createHash } from "node:crypto";
import { Buffer } from "node:buffer";
import { inflateSync } from "node:zlib";
import { STATUS_BAR_BAND_PERCENT } from "../contracts/capture.js";
@@ -95,16 +93,3 @@ export function assertDecodedPng(contents: Buffer, label: string): void {
if (decoded[row * (rowBytes + 1)]! > 4) throw new Error(`${label} has an invalid PNG row filter`);
}
}
/**
* SHA-256 of a frame's pixels between the system bands (status bar above, home indicator below), so two frames that
* differ only by the clock or the indicator's inversion hash alike. Decodes with pngjs; `bands` are percentages of the height.
*/
export function contentSha256(png: Buffer, bands: { top: number; bottom: number }): string {
const { PNG } = createRequire(import.meta.url)("pngjs") as { PNG: { sync: { read(buffer: Buffer): DecodedFrame } } };
const frame = PNG.sync.read(png);
const rowBytes = frame.width * 4;
const first = Math.min(frame.height, Math.floor(frame.height * bands.top / 100));
const last = Math.max(first, frame.height - Math.ceil(frame.height * bands.bottom / 100));
return createHash("sha256").update(`${frame.width}x${last - first}:`).update(frame.data.subarray(first * rowBytes, last * rowBytes)).digest("hex");
}
+3 -8
View File
@@ -21,8 +21,6 @@ export type CapturePlanOptions = DiscoverRouteOptions & {
changedFiles: SourceChange[];
externalChanges?: SourceChange[];
mode?: CaptureMode;
/** False when the capture runs flows only: every route stays in the inventory and the navigation context, none is captured. */
captureRoutes?: boolean;
/** Routes named in exploration.exclude: kept in the map and its navigation context, never captured. */
exclude?: string[];
navigation?: Pick<DiscoverRouteOptions, "provider" | "entry">;
@@ -33,8 +31,6 @@ export type SourceCapturePlan = {
baseSha: string;
headSha: string;
mode: CaptureMode;
/** Present, as false, when the plan captures no route (flows mode): the inventory and navigation are kept, no surface is captured. */
captureRoutes?: false;
conservative: boolean;
unresolved: string[];
diagnostics: { base: string[]; head: string[] };
@@ -163,12 +159,11 @@ export function createSourceCapturePlan(options: CapturePlanOptions): SourceCapt
const seeds = definitions.filter(route => route.status !== "unchanged").map(route => route.id);
const selected = { base: new Set(navigationCaptureContext(navigation.base, seeds, baseRoutes)), head: new Set(navigationCaptureContext(navigation.head, seeds, headRoutes)) };
const excluded = excludedSurfaceIds(definitions, options.exclude ?? []);
const captureRoutes = options.captureRoutes ?? true;
const surfaces = definitions.map(route => ({ ...route,
baseCapture: Boolean(captureRoutes && route.baseSurface && route.baseSurface.kind !== "redirect" && !excluded.includes(route.id) && (mode === "all" || selected.base.has(route.id))),
headCapture: Boolean(captureRoutes && route.headSurface && route.headSurface.kind !== "redirect" && !excluded.includes(route.id) && (mode === "all" || selected.head.has(route.id))),
baseCapture: Boolean(route.baseSurface && route.baseSurface.kind !== "redirect" && !excluded.includes(route.id) && (mode === "all" || selected.base.has(route.id))),
headCapture: Boolean(route.headSurface && route.headSurface.kind !== "redirect" && !excluded.includes(route.id) && (mode === "all" || selected.head.has(route.id))),
}));
return { contract: "explore.plan", baseSha: options.baseSha, headSha: options.headSha, mode, ...(captureRoutes ? {} : { captureRoutes: false as const }), conservative, unresolved, surfaces, navigation,
return { contract: "explore.plan", baseSha: options.baseSha, headSha: options.headSha, mode, conservative, unresolved, surfaces, navigation,
diagnostics: { base: baseInventory.diagnostics, head: headInventory.diagnostics },
inventorySurfaceIds: surfaces.map(route => route.id), baseCaptureSurfaceIds: surfaces.filter(route => route.baseCapture).map(route => route.id), headCaptureSurfaceIds: surfaces.filter(route => route.headCapture).map(route => route.id),
...(excluded.length ? { excludedSurfaceIds: excluded } : {}),
-137
View File
@@ -1,137 +0,0 @@
import assert from "node:assert/strict";
import { mkdtemp, readFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
import { chromium, expect } from "@playwright/test";
import { BlobReader, BlobWriter, Uint8ArrayReader, Uint8ArrayWriter, ZipReader, ZipWriter } from "@zip.js/zip.js";
import { startReportViewer } from "../ci/lib/report-viewer.mjs";
// The recorded Meow review with one e2e flow added: "send money to a contact" passed on base with three frames and
// failed on head at step 8 with two, so the Flows view shows a compared pair, a base-only frame and a stopped side.
const REPORT = new URL("../fixtures/example-review-artifact.zip", import.meta.url);
const FLOW = JSON.parse(await readFile(new URL("../fixtures/flows/public-review-flow.json", import.meta.url), "utf8"));
async function reportWithFlow(flowsFailure, flow = FLOW) {
const reader = new ZipReader(new BlobReader(new Blob([await readFile(REPORT)])));
const writer = new ZipWriter(new BlobWriter("application/zip"), { useWebWorkers: false });
for (const entry of await reader.getEntries()) {
const bytes = await entry.getData(new Uint8ArrayWriter());
if (entry.filename !== "review.json") { await writer.add(entry.filename, new Uint8ArrayReader(bytes), { level: 0 }); continue; }
const report = JSON.parse(new TextDecoder().decode(bytes));
report.review = { ...report.review, flows: [flow], ...(flowsFailure ? { flowsFailure } : {}) };
await writer.add("review.json", new Uint8ArrayReader(new TextEncoder().encode(JSON.stringify(report))), { level: 6 });
}
await reader.close();
return Buffer.from(await (await writer.close()).arrayBuffer());
}
async function openReport(t, bytes, viewport = { width: 1440, height: 900 }) {
const cacheDir = await mkdtemp(join(tmpdir(), "explore-flows-viewer-"));
const { server, url } = await startReportViewer({ bytes, port: "free", watch: false, cacheDir });
const browser = await chromium.launch({ headless: true });
t.after(async () => { await browser.close(); await server.close(); await rm(cacheDir, { recursive: true, force: true }); });
const page = await browser.newPage({ viewport });
const errors = [];
page.on("pageerror", error => errors.push(error.message));
return { page, url, errors };
}
test("the Flows view shows each flow's outcome per side, its frames and steps, and opens a frame in the inspector", async t => {
const { page, url, errors } = await openReport(t, await reportWithFlow());
await page.goto(`${url}#/flows`);
const card = page.getByRole("region", { name: "send money to a contact" });
await expect(card).toBeVisible();
await expect(card).toContainText("flows/send-money.e2e.ts");
await expect(card.locator(".flow-outcome", { hasText: "After" })).toContainText("failed at step 8");
await expect(card.locator(".flow-outcome", { hasText: "Before" })).toContainText("passed");
await expect(card.locator(".flow-failure")).toContainText('expect.toBeVisible getByTestId("send-confirm")');
// Both sides took contacts and amount; only base reached review.
await expect(card.locator(".flow-frame-caption", { hasText: "contacts" })).toBeVisible();
const contacts = card.locator(".flow-frame", { has: page.locator(".flow-frame-caption", { hasText: "contacts" }) });
// One After | Before toggle per flow flips every frame of the strip; no badge sits on the frames themselves.
await expect(contacts).toHaveAttribute("data-side", "head");
await expect(contacts.locator(".flow-frame-flip")).toHaveCount(0);
const review = card.locator(".flow-frame", { has: page.locator(".flow-frame-caption", { hasText: "review" }) });
await expect(review.locator(".flow-frame-missing")).toContainText("Not reached");
await expect(card).toContainText("Not reached after");
await expect(card.locator("img")).toHaveCount(2, "After: contacts and amount; review was not reached");
const toggle = card.locator(".flow-side-toggle");
await toggle.getByRole("radio", { name: "Before" }).click();
await expect(contacts).toHaveAttribute("data-side", "base");
await expect(contacts.locator(".flow-frame-image")).toHaveAttribute("alt", /Before$/);
await expect(review.locator(".flow-frame-image")).toBeVisible();
await expect(card.locator("img")).toHaveCount(3, "Before: all three frames");
await toggle.getByRole("radio", { name: "After" }).click();
await expect(contacts).toHaveAttribute("data-side", "head");
await expect(card.locator("img")).toHaveCount(2, "After again: contacts and amount");
for (const image of await card.locator("img").all()) {
expect(await image.evaluate(element => element.naturalWidth), "every frame decodes from the report's assets").toBeGreaterThan(0);
}
const steps = card.locator("ol.flow-steps").first().locator("li");
await expect(steps).toHaveCount(8);
await expect(steps.nth(7)).toHaveClass(/failed/);
// A frame opens in the inspector, beside the flow.
await card.locator(".flow-frame-button").first().click();
await expect(page).toHaveURL(/#\/flows\/flow:send-money/);
await expect(page.getByRole("complementary", { name: "Inspector panel" })).toContainText("send money to a contact › contacts");
// The inspector explains the frame by its flow, not by a route transition: the step, the steps around it, the e2e source.
const inspector = page.getByRole("complementary", { name: "Inspector panel" });
await expect(inspector.locator(".flow-section")).toContainText("Frame from step 3 of 8");
await expect(inspector.locator(".transition-section")).toHaveCount(0);
await expect(inspector.locator(".flow-section-step-row").nth(2)).toHaveClass(/current/);
await expect(inspector.locator(".flow-section-step-row").nth(2).locator("a")).toHaveAttribute("href", /github\.com\/expo\/explore-playground\/blob\/[0-9a-f]{40}\/flows\/send-money\.e2e\.ts#L6$/);
await expect(card.locator(".flow-file a")).toHaveAttribute("href", /send-money\.e2e\.ts#L3$/);
assert.deepEqual(errors, []);
});
test("flow frames leave the Screens tree while the Changes count keeps the compared frames", async t => {
const { page, url } = await openReport(t, await reportWithFlow());
await page.goto(`${url}#/screens`);
await expect(page.getByRole("toolbar", { name: "Canvas tools" }).getByRole("button", { name: "Screens", exact: true })).toBeVisible();
await expect(page.locator(".screens-view, main").first()).not.toContainText("send money to a contact");
await expect(page.getByRole("toolbar", { name: "Canvas tools" }).getByRole("button", { name: "Flows", exact: true })).toBeVisible();
});
test("a side whose flows did not run is announced on the Flows view, and the tab stays reachable", async t => {
const failure = { head: { code: "FLOWS_NOT_RUN", message: "Error: Cannot find module 'e2e/runner'" } };
const { page, url } = await openReport(t, await reportWithFlow(failure));
await page.goto(`${url}#/flows`);
const alert = page.getByRole("alert");
await expect(alert).toContainText("The flows did not run");
await expect(alert).toContainText("FLOWS_NOT_RUN");
await expect(alert).toContainText("Cannot find module 'e2e/runner'");
await expect(page.getByRole("region", { name: "send money to a contact" })).toBeVisible();
});
test("on a phone the Flows tab lists the flow with its frames as a filmstrip", async t => {
const { page, url } = await openReport(t, await reportWithFlow(), { width: 390, height: 844 });
await page.goto(`${url}#/flows`);
const card = page.getByRole("region", { name: "send money to a contact" });
await expect(card).toBeVisible();
const strip = card.locator(".flow-filmstrip");
const widths = await strip.evaluate(element => ({ scroll: element.scrollWidth, client: element.clientWidth }));
assert.ok(widths.scroll > widths.client, `the filmstrip scrolls sideways (${widths.scroll} > ${widths.client})`);
for (const button of await card.getByRole("button").all()) {
const box = await button.boundingBox();
assert.ok(box && box.width >= 44 && box.height >= 44, `touch target ${JSON.stringify(box)}`);
}
});
test("a step frame identical to the previous frame on every side folds into it; checkpoints never fold", async t => {
const flow = structuredClone(FLOW);
const contacts = flow.frames.findIndex(frame => frame.key === "contacts");
const twin = key => ({ key, id: `${FLOW.frames[contacts].id.replace(/contacts$/, key)}`, label: `${key === "step-6" ? "6" : "7"}. expect.toBeVisible getByText("Alex Rivera")` });
flow.frames.splice(contacts + 1, 0, twin("step-6"), twin("step-7"));
for (const side of ["head", "base"]) for (const key of ["step-6", "step-7"]) flow[side].frames[key] = { ...flow[side].frames.contacts };
flow.base.frames["step-7"] = { ...flow.base.frames.amount };
const { page, url, errors } = await openReport(t, await reportWithFlow(undefined, flow));
await page.goto(`${url}#/flows`);
const card = page.getByRole("region", { name: "send money to a contact" });
const captions = card.locator(".flow-frame-caption strong");
await expect(captions).toHaveText([/^contacts$/, /^7\. expect/, /^amount$/, /^review$/], "step-6 (same picture on both sides) folds into contacts; step-7 differs on base, so it shows");
const folded = card.locator(".flow-frame", { has: page.locator(".flow-frame-caption", { hasText: "contacts" }) }).locator(".flow-frame-same");
await expect(folded).toHaveText("+1");
await expect(folded).toHaveAttribute("title", /6\. expect\.toBeVisible/);
assert.deepEqual(errors, []);
});
+1 -1
View File
@@ -74,7 +74,7 @@ npm run ci:local -- \
--scope all
```
`--mode` (default `deterministic`) selects `deterministic.yaml`, `agent.yaml` or `flows.yaml`; `--scope`
`--mode` (default `deterministic`) selects `deterministic.yaml` or `agent.yaml`; `--scope`
overrides the config's `exploration.scope`. `--run-id NAME` selects a readable ID and refuses
overwrite. `--plan-only` runs the production planner, checks the expectations at plan level, and
validates each setup step's `requiresRoute` against both revisions, without installation,
-18
View File
@@ -1,18 +0,0 @@
// The wallet app's e2e flow. Explore runs it on both revisions after setup signed the review account in;
// each app.screenshot is a frame the review compares, and a failing step keeps the frames before it.
import { expect, test } from "e2e";
test("send money to a contact", async ({ app, device, screen }) => {
await device.openLink("explore-example-wallet://send/contacts");
await expect(screen.getByTestId("contacts-list")).toBeVisible();
await app.screenshot("contacts");
await screen.getByText("Alex Rivera").tap();
await expect(screen.getByTestId("send-amount-input")).toBeVisible();
await screen.getByTestId("send-amount-input").fill("25");
await app.screenshot("amount");
await screen.getByTestId("send-amount-continue").tap();
await expect(screen.getByTestId("send-confirm")).toBeVisible();
await app.screenshot("review");
});
+24 -1141
View File
File diff suppressed because it is too large. Load diff
-1
View File
@@ -40,7 +40,6 @@
"@babel/core": "^7.20.0",
"@types/react": "~19.2.4",
"babel-preset-expo": "~57.0.8",
"e2e": "0.21.2",
"typescript": "~6.0.3"
}
}
+2 -2
View File
@@ -4,7 +4,7 @@ import { basename, join } from 'node:path';
import { parseArgs } from 'node:util';
export const MATRIX_USAGE = 'Usage: npm run ci:local:matrix -- --app APP (--cells SCENARIO:MODE:SCOPE,... | --scenarios A,B [--modes deterministic,agent] [--scopes all,changes]) [--parallel N] [--prefix NAME] [--plan-only]';
const MODES = ['deterministic', 'agent', 'flows'];
const MODES = ['deterministic', 'agent'];
const SCOPES = ['all', 'changes'];
const list = value => (value ?? '').split(',').map(item => item.trim()).filter(Boolean);
@@ -33,7 +33,7 @@ export function parseMatrixArguments(args, now = new Date()) {
const cells = requested.map(({ scenario, mode, scope }) => {
if (!MODES.includes(mode)) throw new Error(`Unknown mode in matrix: ${mode}`);
if (!SCOPES.includes(scope)) throw new Error(`Unknown scope in matrix: ${scope}`);
const name = `${basename(scenario)}-${mode === 'deterministic' ? 'det' : mode}-${scope}`;
const name = `${basename(scenario)}-${mode === 'deterministic' ? 'det' : 'agent'}-${scope}`;
if (seen.has(name)) throw new Error(`Duplicate matrix cell: ${name}`);
seen.add(name);
return { name, scenario: scenarioPath(values.app, scenario), mode, scope, runId: `${prefix}-${name}` };
+1 -1
View File
@@ -6,7 +6,7 @@ import { lstat, readFile, realpath } from 'node:fs/promises';
import { dirname, isAbsolute, join, normalize, resolve, sep } from 'node:path';
import { parse, stringify } from 'yaml';
const MODES = ['deterministic', 'agent', 'flows'];
const MODES = ['deterministic', 'agent'];
const SCOPES = ['all', 'changes'];
const STATUSES = ['added', 'removed', 'modified', 'needs-review', 'unchanged', 'variant'];
+2 -2
View File
@@ -346,13 +346,13 @@ export async function runLocalCi(input) {
return { run, metadata };
}
export const USAGE = 'Usage: npm run ci:local -- --app APP --scenario SCENARIO [--mode deterministic|agent|flows] [--scope all|changes] [--run-id ID] [--plan-only]';
export const USAGE = 'Usage: npm run ci:local -- --app APP --scenario SCENARIO [--mode deterministic|agent] [--scope all|changes] [--run-id ID] [--plan-only]';
export function parseRunArguments(args) {
const { values } = parseArgs({ args, options: { app: { type: 'string' }, scenario: { type: 'string' }, mode: { type: 'string' }, scope: { type: 'string' },
'run-id': { type: 'string' }, 'plan-only': { type: 'boolean' } } });
if (!values.app || !values.scenario) throw new Error(USAGE);
if (values.mode && !['deterministic', 'agent', 'flows'].includes(values.mode)) throw new Error('--mode must be deterministic, agent or flows');
if (values.mode && !['deterministic', 'agent'].includes(values.mode)) throw new Error('--mode must be deterministic or agent');
if (values.scope && !['all', 'changes'].includes(values.scope)) throw new Error('--scope must be all or changes');
return { app: values.app, scenario: values.scenario, mode: values.mode ?? 'deterministic', ...(values.scope ? { scope: values.scope } : {}),
runId: values['run-id'], planOnly: values['plan-only'] };
-41
View File
@@ -1,41 +0,0 @@
# Flows Explore config for the wallet app: setup signs in, then the e2e flows under flows/ run on the same session.
# The flows are plain e2e tests (https://e2e.tester.army); every `app.screenshot(label)` is a compared frame.
mode: flows
app:
name: Wallet
platform: ios
bundleId: com.expo-explore.example.wallet
easProfile: explore
scheme: explore-example-wallet
navigation:
provider: expo-router
device:
name: iPhone 17
capture:
maxMinutes: 30
maxActions: 300
flows:
tests:
- e2e/*.e2e.ts
setup:
- action: open
url: explore-example-wallet://onboarding/currency
ready: { identifier: currency-continue, enabled: true }
- action: tap
identifier: currency-continue
ready: { identifier: auth-name }
- action: open
url: explore-example-wallet://auth/sign-up
ready: { label: Create your account }
- action: fill
identifier: auth-name
text: Review User
- action: fill
identifier: auth-email
text: [email protected]
- action: fill
identifier: auth-password
text: WalletReview123!
- action: tap
identifier: auth-submit
ready: { identifier: home-balance }
-262
View File
@@ -1,262 +0,0 @@
{
"schemaVersion": "report-1",
"run": {
"id": "01a14c4a-51de-7ee0-bfc7-69e8c5353071",
"specVersion": "0.1",
"runner": {
"name": "e2e",
"version": "0.21.2"
},
"status": "passed",
"exitCode": 0,
"startedAt": "2026-10-17T23:55:01.510Z",
"finishedAt": "2026-10-17T23:55:01.530Z",
"project": {
"id": "e2e-probe",
"configDigest": "b61c15749f8acd2d3a2e2fe22cd35ef0b1c1496b94871dc26075448c0c47043a"
},
"environment": {
"ci": false,
"trustNoticeShown": false,
"os": "linux 6.8.0-1061-aws",
"arch": "x64",
"runtime": "node v24.12.0"
},
"targets": [
{
"id": "fake",
"index": 0,
"platform": "fake",
"environment": "test",
"engine": {
"name": "fake",
"version": "0.0.1",
"spiVersion": 1
},
"capabilities": [
"actions",
"artifacts",
"location",
"observation"
],
"artifactCapabilities": [
"screenshot"
],
"stateCapability": false
}
],
"serialGroups": [],
"results": [
{
"id": "eb3881d095c951b6922752e35a8485fa329ff482a49cc0bef3088675c1b34b35",
"testId": "tests/goal.e2e.ts::goal%20without%20model",
"kind": "test",
"declarationIndex": 0,
"titlePath": [
"goal without model"
],
"file": "tests/goal.e2e.ts",
"source": {
"file": "tests/goal.e2e.ts",
"line": 2,
"column": 1
},
"targetId": "fake",
"platform": "fake",
"agent": "default",
"repeat": 0,
"tags": [],
"selected": false,
"status": "skipped",
"skip": {
"cause": "filtered",
"reason": "file not selected by a positional argument"
},
"attempts": []
},
{
"id": "09af3c698e01af961caa47df553e9242887a9c799a28a1f39aa236cc85831150",
"testId": "tests/send.e2e.ts::send%20money%20reaches%20contacts",
"kind": "test",
"declarationIndex": 0,
"titlePath": [
"send money reaches contacts"
],
"file": "tests/send.e2e.ts",
"source": {
"file": "tests/send.e2e.ts",
"line": 2,
"column": 1
},
"targetId": "fake",
"platform": "fake",
"agent": "default",
"repeat": 0,
"tags": [],
"selected": true,
"status": "passed",
"attempts": [
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5",
"index": 0,
"status": "passed",
"startedAt": "2026-10-17T23:55:01.517Z",
"durationMs": 12,
"artifacts": [
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:artifact:0",
"kind": "screenshot",
"mediaType": "image/png",
"redaction": "complete",
"producer": {
"kind": "step",
"stepId": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:0"
},
"path": "send-money-reaches-contacts-09af3c698e01af96/attempt-1/screenshots/001.png",
"size": 70,
"sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581"
},
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:artifact:1",
"kind": "screenshot",
"mediaType": "image/png",
"redaction": "complete",
"producer": {
"kind": "step",
"stepId": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:3"
},
"path": "send-money-reaches-contacts-09af3c698e01af96/attempt-1/screenshots/002.png",
"size": 70,
"sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581"
}
],
"secondaryErrors": [],
"cleanup": "complete",
"steps": [
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:0",
"index": 0,
"kind": "app",
"api": "app.screenshot",
"label": "home",
"status": "passed",
"startedAt": "2026-10-17T23:55:01.520Z",
"durationMs": 1,
"events": [],
"artifacts": [
"01a14c4a-520d-76c6-9013-1d2dbc51ebc5:artifact:0"
],
"source": {
"file": "tests/send.e2e.ts",
"line": 3,
"column": 13
}
},
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:1",
"index": 1,
"kind": "locator",
"api": "locator.tap",
"label": "getByTestId(\"home-send\")",
"status": "passed",
"startedAt": "2026-10-17T23:55:01.521Z",
"durationMs": 1,
"events": [
{
"kind": "engine",
"name": "tap",
"startedAt": "2026-10-17T23:55:01.522Z",
"durationMs": 0,
"status": "passed",
"detail": "tap button \"Send\""
}
],
"artifacts": [],
"source": {
"file": "tests/send.e2e.ts",
"line": 4,
"column": 41
}
},
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:2",
"index": 2,
"kind": "assertion",
"api": "expect.toBeVisible",
"label": "getByRole(\"heading\", name: \"Your contacts\")",
"status": "passed",
"startedAt": "2026-10-17T23:55:01.523Z",
"durationMs": 0,
"events": [
{
"kind": "poll",
"name": "expect",
"startedAt": "2026-10-17T23:55:01.523Z",
"durationMs": 0,
"status": "passed",
"count": 1
}
],
"artifacts": [],
"source": {
"file": "tests/send.e2e.ts",
"line": 5,
"column": 62
}
},
{
"id": "01a14c4a-520d-76c6-9013-1d2dbc51ebc5:3",
"index": 3,
"kind": "app",
"api": "app.screenshot",
"label": "contacts",
"status": "passed",
"startedAt": "2026-10-17T23:55:01.523Z",
"durationMs": 0,
"events": [],
"artifacts": [
"01a14c4a-520d-76c6-9013-1d2dbc51ebc5:artifact:1"
],
"source": {
"file": "tests/send.e2e.ts",
"line": 6,
"column": 13
}
}
]
}
]
}
],
"errors": [],
"summary": {
"discovered": 2,
"selected": 1,
"executed": 1,
"passed": 1,
"failed": 0,
"interrupted": 0,
"flaky": 0,
"skipped": 0
},
"limits": {
"maxAgentContextBytes": 16384,
"maxLedgerBytes": 8192,
"maxObservationBytes": 262144,
"maxEventsPerStep": 1000,
"maxModelTokensPerCall": 64000
},
"usage": {
"discoveredResults": 2,
"maxAgentContextBytes": 0,
"maxLedgerBytes": 0,
"maxObservationBytes": 0,
"artifactBytes": 140,
"downloads": 0,
"events": 2,
"modelTokens": 0,
"maxModelCallsInStep": 0,
"maxActionStepsInStep": 0
}
}
}
-36
View File
@@ -1,36 +0,0 @@
// A two-screen app for the flows worker: Home (a Send button) and Contacts (a heading and one contact).
import { defineEngine, resolveExpression } from "e2e/engine";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";
const PNG = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "base64");
const screens = {
home: [{ ref: { id: "send", revision: "1" }, role: "button", name: "Send", testId: "home-send", rect: { x: 0, y: 0, width: 100, height: 40 } }],
contacts: [
{ ref: { id: "title", revision: "2" }, role: "heading", name: "Your contacts", rect: { x: 0, y: 0, width: 100, height: 40 } },
{ ref: { id: "alex", revision: "2" }, role: "button", name: "Alex Rivera", rect: { x: 0, y: 50, width: 100, height: 40 } },
],
};
export function engine() {
let screen = "home";
let attemptDir = "";
let shots = 0;
const root = () => ({ ref: { id: "root", revision: screen }, role: "window", children: screens[screen] });
return defineEngine({
name: "fake-device", version: "0.0.1", spiVersion: 1, platform: "fake",
async startAttempt(info) { attemptDir = info.artifactsDir; screen = "home"; shots = 0; },
async observe() { return { root: root(), viewport: { width: 100, height: 100 } }; },
async locate(expression) { return resolveExpression(expression, [root()]); },
actions: ["tap"],
async perform(ref) { if (ref.id === "send") screen = "contacts"; },
session: { async restart() { screen = "home"; } },
artifacts: { async screenshot() {
shots += 1;
const path = `screenshots/${String(shots).padStart(3, "0")}.png`;
mkdirSync(join(attemptDir, "screenshots"), { recursive: true });
writeFileSync(join(attemptDir, path), PNG);
return path;
} },
});
}
-223
View File
@@ -1,223 +0,0 @@
{
"id": "send-money/send-money-to-a-contact",
"title": "send money to a contact",
"file": "flows/send-money.e2e.ts",
"base": {
"status": "passed",
"durationMs": 3202,
"steps": [
{
"api": "device.openLink",
"label": "explore-example-wallet://send/contacts",
"status": "passed",
"durationMs": 812,
"line": 4
},
{
"api": "expect.toBeVisible",
"label": "getByTestId(\"contacts-list\")",
"status": "passed",
"durationMs": 140,
"line": 5
},
{
"api": "app.screenshot",
"label": "contacts",
"status": "passed",
"durationMs": 310,
"frame": "contacts",
"line": 6
},
{
"api": "locator.tap",
"label": "getByText(\"Alex Rivera\")",
"status": "passed",
"durationMs": 420,
"line": 7
},
{
"api": "locator.fill",
"label": "getByTestId(\"send-amount-input\")",
"status": "passed",
"durationMs": 380,
"line": 8
},
{
"api": "app.screenshot",
"label": "amount",
"status": "passed",
"durationMs": 290,
"frame": "amount",
"line": 9
},
{
"api": "locator.tap",
"label": "getByTestId(\"send-amount-continue\")",
"status": "passed",
"durationMs": 400,
"line": 10
},
{
"api": "expect.toBeVisible",
"label": "getByTestId(\"send-confirm\")",
"status": "passed",
"durationMs": 150,
"line": 11
},
{
"api": "app.screenshot",
"label": "review",
"status": "passed",
"durationMs": 300,
"frame": "review",
"line": 12
}
],
"frames": {
"contacts": {
"url": "https://embedded.expo-explore.invalid/f3f6e607859abb7e1ff343cdeed2e8939d243966e7aca90e023fb561266cdfcb.png",
"sha256": "f3f6e607859abb7e1ff343cdeed2e8939d243966e7aca90e023fb561266cdfcb",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:39:40.895Z"
},
"amount": {
"url": "https://embedded.expo-explore.invalid/c127fb80b3c6423998da6bc161aba372c6fcf76b664253822718672f33c7d238.png",
"sha256": "c127fb80b3c6423998da6bc161aba372c6fcf76b664253822718672f33c7d238",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:39:47.748Z"
},
"review": {
"url": "https://embedded.expo-explore.invalid/157d6714f158f3b430cd0522eb72c20861f4159339d85ff0fc0ad4515a70ba72.png",
"sha256": "157d6714f158f3b430cd0522eb72c20861f4159339d85ff0fc0ad4515a70ba72",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:39:54.038Z"
}
},
"line": 3
},
"head": {
"status": "failed",
"durationMs": 7754,
"error": {
"code": "ASSERTION_FAILED",
"message": "getByTestId(\"send-confirm\") was not visible within 5000 ms"
},
"steps": [
{
"api": "device.openLink",
"label": "explore-example-wallet://send/contacts",
"status": "passed",
"durationMs": 812,
"line": 4
},
{
"api": "expect.toBeVisible",
"label": "getByTestId(\"contacts-list\")",
"status": "passed",
"durationMs": 140,
"line": 5
},
{
"api": "app.screenshot",
"label": "contacts",
"status": "passed",
"durationMs": 310,
"frame": "contacts",
"line": 6
},
{
"api": "locator.tap",
"label": "getByText(\"Alex Rivera\")",
"status": "passed",
"durationMs": 420,
"line": 7
},
{
"api": "locator.fill",
"label": "getByTestId(\"send-amount-input\")",
"status": "passed",
"durationMs": 380,
"line": 8
},
{
"api": "app.screenshot",
"label": "amount",
"status": "passed",
"durationMs": 290,
"frame": "amount",
"line": 9
},
{
"api": "locator.tap",
"label": "getByTestId(\"send-amount-continue\")",
"status": "passed",
"durationMs": 400,
"line": 10
},
{
"api": "expect.toBeVisible",
"label": "getByTestId(\"send-confirm\")",
"status": "failed",
"durationMs": 5002,
"error": {
"code": "ASSERTION_FAILED",
"message": "getByTestId(\"send-confirm\") was not visible within 5000 ms"
},
"line": 11
}
],
"frames": {
"contacts": {
"url": "https://embedded.expo-explore.invalid/962bb0cd594c48b6c47ef6fd8a6ca6f2411128d812a93ab17854b74fc59e6892.png",
"sha256": "962bb0cd594c48b6c47ef6fd8a6ca6f2411128d812a93ab17854b74fc59e6892",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:31:18.054Z"
},
"amount": {
"url": "https://embedded.expo-explore.invalid/4b2cd242fcf5a38712a4f290561fb24e496dfeeeb7c78c4258f6c75f26608b9f.png",
"sha256": "4b2cd242fcf5a38712a4f290561fb24e496dfeeeb7c78c4258f6c75f26608b9f",
"width": 402,
"height": 874,
"capturedAt": "2026-09-22T11:31:33.692Z"
}
},
"line": 3
},
"frames": [
{
"key": "contacts",
"id": "flow:send-money/send-money-to-a-contact/contacts",
"label": "contacts",
"visual": {
"verdict": "unchanged",
"reason": "matched",
"mismatchPercentage": 0,
"threshold": 0.1,
"tool": "[email protected]",
"ignoredStatusBarRegions": 1
}
},
{
"key": "amount",
"id": "flow:send-money/send-money-to-a-contact/amount",
"label": "amount",
"visual": {
"verdict": "unchanged",
"reason": "matched",
"mismatchPercentage": 0,
"threshold": 0.1,
"tool": "[email protected]",
"ignoredStatusBarRegions": 1
}
},
{
"key": "review",
"id": "flow:send-money/send-money-to-a-contact/review",
"label": "review"
}
]
}
+1 -4
View File
@@ -22,7 +22,7 @@ function fail(args) {
test("explore:binary is in the short help with its archive kinds and --no-upload", () => {
const help = spawnSync(process.execPath, [cli, "help"], { cwd: root, encoding: "utf8" });
assert.equal(help.status, 0, help.stderr);
assert.match(help.stdout, /explore:binary <app\.apk \| app\.app \| app\.tar\.gz \| simulator \.ipa>.*--simulator eas\|local.*--no-upload/);
assert.match(help.stdout, /explore:binary <app\.apk \| app\.app \| app\.tar\.gz \| simulator \.ipa>.*--no-upload/);
});
test("explore:binary validates its arguments before touching EAS or a model", () => {
@@ -30,9 +30,6 @@ test("explore:binary validates its arguments before touching EAS or a model", ()
assert.match(fail(["./app.apk", "--upload", "--no-upload"]), /either --upload or --no-upload/);
assert.match(fail(["./app.apk", "--expires-in", "400d"]), /--expires-in must be 1d to 90d, or never/);
assert.match(fail(["./app.apk", "--platform", "web"]), /platform/);
assert.match(fail(["./app.apk", "--simulator", "cloud"]), /simulator/);
// A local run needs no EAS login, so the archive is the first thing it checks.
assert.match(fail(["./does-not-exist.apk", "--simulator", "local"]), /Archive not found: .*does-not-exist\.apk/);
assert.match(fail(["./does-not-exist.apk", "--no-upload"]), /Archive not found: .*does-not-exist\.apk/);
assert.match(fail(["./package.json", "--no-upload"]), /Unsupported archive: package\.json/);
const human = spawnSync(process.execPath, [cli, "explore:binary", "./does-not-exist.apk", "--no-upload"], { cwd: root, encoding: "utf8", env: { ...process.env, EXPO_TOKEN: "", EXPO_SESSION_SECRET: "" } });
-87
View File
@@ -1,87 +0,0 @@
import assert from "node:assert/strict";
import { writeFileSync } from "node:fs";
import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
import { tsImport } from "tsx/esm/api";
const { runBinaryExploration } = await tsImport("../../src/binary/run.ts", import.meta.url);
const { controllerVersion } = await tsImport("../../src/capture/simulator.ts", import.meta.url);
const { CONTROLLER_SESSION } = await tsImport("../../src/capture/common.ts", import.meta.url);
const UDID = "0A1B2C3D-4E5F-4A6B-8C7D-9E0F1A2B3C4D";
const PNG = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "base64");
const DEVICE_TYPE = "com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro";
async function simulatorApp(root) {
const app = join(root, "Example.app");
await mkdir(app, { recursive: true });
await writeFile(join(app, "Info.plist"), `<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0"><dict>
<key>CFBundleIdentifier</key><string>dev.example.app</string>
<key>CFBundleDisplayName</key><string>Example</string>
<key>DTPlatformName</key><string>iphonesimulator</string>
<key>CFBundleURLTypes</key><array><dict><key>CFBundleURLSchemes</key><array><string>example</string></array></dict></array>
</dict></plist>`);
await writeFile(join(app, "Example"), "binary");
return app;
}
/** simctl and agent-device on a Mac with one iPhone 17 Pro runtime; the app shows a single screen. */
function localRunner() {
const requests = [];
const ok = data => ({ stdout: JSON.stringify({ success: true, data }), stderr: "" });
const runner = request => {
requests.push(request);
const [first, second, third] = request.args;
if (request.command === "xcrun") {
if (second === "list" && third === "devicetypes") return { stdout: JSON.stringify({ devicetypes: [{ name: "iPhone 17 Pro", identifier: DEVICE_TYPE }] }), stderr: "" };
if (second === "list" && third === "runtimes") return { stdout: JSON.stringify({ runtimes: [{ isAvailable: true, platform: "iOS", identifier: "com.apple.CoreSimulator.SimRuntime.iOS-27-0",
version: "27.0", supportedDeviceTypes: [{ identifier: DEVICE_TYPE }] }] }), stderr: "" };
if (second === "create") return { stdout: `${UDID}\n`, stderr: "" };
return { stdout: "", stderr: "" };
}
if (first === "--version") return { stdout: `${controllerVersion("agent-device")}\n`, stderr: "" };
if (first === "open") return ok({ session: CONTROLLER_SESSION, appBundleId: "dev.example.app", device: { platform: "ios", target: "mobile", name: "Explore iPhone 17 Pro", id: UDID },
identifiers: { session: CONTROLLER_SESSION, appBundleId: "dev.example.app", deviceName: "Explore iPhone 17 Pro", deviceId: UDID } });
if (first === "snapshot") return ok({ nodes: [{ type: "StaticText", label: "Welcome" }, { type: "Button", label: "Settings" }] });
if (first === "appstate") return ok({ platform: "ios", appBundleId: "dev.example.app", state: "runningForeground", surface: "app" });
if (first === "screenshot") { writeFileSync(request.args[1], PNG); return ok({}); }
return ok({});
};
return { requests, runner };
}
test("explore:binary --simulator local runs on a simulator it creates, with no EAS login, and deletes it afterwards", async t => {
const root = await mkdtemp(join(tmpdir(), "explore-binary-local-"));
t.after(() => rm(root, { recursive: true, force: true }));
const { requests, runner } = localRunner();
const session = { provider: "anthropic", model: "test", async preflight() {}, async run() { return { stopReason: "done" }; } };
const result = await runBinaryExploration({ archive: await simulatorApp(root), output: join(root, "out"), simulator: "local", provider: "anthropic", runner,
createSession: () => session, environment: { PATH: process.env.PATH, HOME: root, ANTHROPIC_API_KEY: "key" } });
// No EAS: no login check, project, or session.
assert.equal(requests.some(request => request.args.some(arg => /^(whoami|init|simulator:)/.test(arg))), false);
const simctl = requests.filter(request => request.command === "xcrun").map(request => request.args.slice(1).join(" "));
assert.ok(simctl.some(command => command.startsWith(`create Explore iPhone 17 Pro (binary `)));
assert.ok(simctl.includes(`spawn ${UDID} defaults write com.apple.launchservices.schemeapproval com.apple.CoreSimulator.CoreSimulatorBridge-->example -string dev.example.app`),
"the app's own scheme opens without a prompt");
assert.ok(simctl.some(command => command.startsWith(`install ${UDID} `)), "simctl installs the app");
assert.equal(simctl.at(-1), `delete ${UDID}`, "and the simulator goes last");
// agent-device runs its own daemon in the run's directory and is pointed at the simulator by its UDID.
const controller = requests.filter(request => request.command !== "xcrun" && request.args[0] !== "--version" && request.args[0] !== "close");
assert.ok(controller.length > 0);
for (const request of controller) {
assert.deepEqual(request.args.slice(request.args.indexOf("--udid"), request.args.indexOf("--udid") + 2), ["--udid", UDID]);
assert.match(request.environment.AGENT_DEVICE_STATE_DIR, /agent-device-state$/);
assert.equal(request.environment.AGENT_DEVICE_DAEMON_BASE_URL, undefined);
}
assert.equal(controller.some(request => request.args[0] === "install"), false, "the controller does not install it again");
assert.equal(result.runtime.provider, "local-simulator");
assert.equal(result.runtime.osVersion, "27.0");
assert.equal(result.session.id, `local-${UDID}`);
assert.deepEqual(await readdir(join(root, ".cache", "expo-explore", "local-captures")), [], "nothing is left for a sweep");
});
+1 -1
View File
@@ -8,7 +8,7 @@ const transition = await tsImport(
);
test("canvas view direction follows the toolbar order", () => {
assert.deepEqual(transition.CANVAS_VIEW_ORDER, ["flows", "map", "screens", "compare"]);
assert.deepEqual(transition.CANVAS_VIEW_ORDER, ["map", "screens", "compare"]);
assert.equal(transition.canvasViewTransitionDirection("screens", "compare"), "forward");
assert.equal(transition.canvasViewTransitionDirection("map", "screens"), "forward");
assert.equal(transition.canvasViewTransitionDirection("compare", "screens"), "backward");
+5 -68
View File
@@ -1,7 +1,7 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { spawn, spawnSync } from 'node:child_process';
import { existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
import { mkdtemp, mkdir, readdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
import { join, relative, sep } from 'node:path';
@@ -103,16 +103,10 @@ async function fixture(t, settings = {}) {
await writeCaptureObserverPackages(project);
await writeFile(join(project, 'package.json'), '{"name":"example","main":"index.js"}\n');
await writeFile(join(project, 'app.json'), JSON.stringify({ expo: { name: 'Example', slug: 'example' } }));
if (settings.flowFiles) {
// The app resolves `e2e` from its own node_modules, as a real app does.
await mkdir(join(project, 'e2e')); await mkdir(join(project, 'node_modules'), { recursive: true });
symlinkSync(new URL('../../node_modules/e2e', import.meta.url).pathname, join(project, 'node_modules', 'e2e'), 'dir');
for (const [name, source] of Object.entries(settings.flowFiles)) await writeFile(join(project, 'e2e', name), source);
}
const routes = settings.routes ?? [route('home'), route('settings')];
const files = new Map(routes.map(item => [item.routeFile, 'export default function Screen(){return null;}']));
const plan = createSourceCapturePlan({ baseSha: SHA, headSha: HEAD, baseFiles: files, headFiles: files,
changedFiles: [], mode: 'all', provider: 'expo-router', ...(settings.flows?.only ? { captureRoutes: false } : {}) });
changedFiles: [], mode: 'all', provider: 'expo-router' });
const ids = Object.fromEntries(routes.map(item => [item.id, plan.surfaces.find(row => row.baseSurface.routeFile === item.routeFile).id]));
const planPath = join(root, 'plan.json'); await writeFile(planPath, JSON.stringify(plan));
const requests = [];
@@ -131,12 +125,6 @@ async function fixture(t, settings = {}) {
const runner = request => {
requests.push(request);
const command = request.args[0];
// The flows worker is a real child process: e2e runs the app's test files against the fake engine.
if (request.command === process.execPath) {
const child = spawnSync(request.command, request.args, { cwd: request.cwd, env: request.environment, encoding: 'utf8', timeout: request.timeoutMs });
if (child.status !== 0 && !request.allowFailure) throw new Error(`worker exited ${child.status}: ${child.stderr}`);
return { stdout: child.stdout ?? '', stderr: child.stderr ?? '' };
}
if (request.command === 'git') {
if (command === 'ls-files') return { stdout: readdirSync(project, { recursive: true, withFileTypes: true })
.filter(entry => entry.isFile() && !relative(project, entry.parentPath).split(sep).includes('node_modules'))
@@ -287,8 +275,6 @@ async function fixture(t, settings = {}) {
if (command === 'install') { assert.ok(existsSync(request.args[1]), 'the repacked app is on this machine'); return ok({ installed: true, appBundleId: 'com.example.app' }); }
// agent-device 0.21.15 cannot read Xcode 27.1's hinge angle back, so a local fold reports a failure after folding.
if (command === 'fold') return settings.local ? json({ success: false, error: { code: 'COMMAND_FAILED', message: "CoreDevice reported no hinge angle sample: Unknown option '--device'" } })
// EAS Simulator: the pose is dispatched, but agent-device cannot read the hinge back to confirm it.
: settings.foldUnverified ? json({ success: false, error: { code: 'COMMAND_FAILED', message: `fold: iPhone Duo received the ${request.args[1]} pose request, but the first hinge-angle read returned no sample to verify it` } })
: ok({ action: 'fold', pose: request.args[1] });
if (command === 'record' && settings.recording) {
if (request.args[1] === 'start') { recordingPath = request.args[2]; return ok({ path: recordingPath }); }
@@ -392,7 +378,7 @@ async function fixture(t, settings = {}) {
buildId: 'source-capture', buildVersion: '1', gitCommit: SHA, bundleId: 'com.example.app',
...(settings.noScheme ? {} : { scheme: 'sample' }), device: deviceName, easProfile: 'capture', expoToken: 'expo-private', ...(settings.android ? { platform: 'android' } : {}),
planPath, maxScreens: 120, maxActions: 500, maxDurationMinutes: 30, forceFreshBuild: false,
confirmExternalRun: true, confirmTrustedSource: true, easCommand: 'fake-eas', repackCommand: 'fake-repack', agentDeviceCommand: 'fake-controller', ...(settings.argent ? { controller: 'argent' } : {}), ...(settings.devicePose ? { devicePose: settings.devicePose } : {}), ...(settings.launch ? { launch: settings.launch, recordingTools: settings.recordingTools ?? null } : {}), ...(settings.repack ? { repack: settings.repack } : {}), ...(settings.local ? { simulator: 'local' } : {}), ...(settings.flows ? { flows: settings.flows } : {}),
confirmExternalRun: true, confirmTrustedSource: true, easCommand: 'fake-eas', repackCommand: 'fake-repack', agentDeviceCommand: 'fake-controller', ...(settings.argent ? { controller: 'argent' } : {}), ...(settings.devicePose ? { devicePose: settings.devicePose } : {}), ...(settings.launch ? { launch: settings.launch, recordingTools: settings.recordingTools ?? null } : {}), ...(settings.repack ? { repack: settings.repack } : {}), ...(settings.local ? { simulator: 'local' } : {}),
environment: { PATH: process.env.PATH, HOME: root, ...(settings.local && settings.android ? { ANDROID_HOME: sdk, TMPDIR: root } : {}), GITHUB_TOKEN: 'github-private', ANTHROPIC_API_KEY: 'must-not-be-used', AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'wrong-token', ...settings.environment },
// Every controller round trip advances the fixture clock by one poll interval, as a device snapshot would.
runner: request => { clockMs += 600; return runner(request); }, now: () => clockMs, sleep: milliseconds => { clockMs += milliseconds; }, fetch: catalog };
@@ -512,22 +498,13 @@ test('device.pose folds the device first, before the app is opened, read or capt
assert.equal(folds.length, 1);
assert.deepEqual(folds[0].args.slice(0, 2), ['fold', 'open']);
const foldAt = controller.indexOf(folds[0]);
// The fold comes first: the app is installed but not read or captured before it, so the controller starts on the lit panel.
// agent-device folds only inside a session, so one open (and nothing else) starts it; Argent folds without one.
assert.deepEqual(controller.slice(0, foldAt).map(request => request.args[0]).filter(command => command !== '--version' && command !== 'install'), argent ? [] : ['open']);
// The fold comes first: the app is installed but not opened, read or captured before it, so the controller starts on the lit panel.
assert.deepEqual(controller.slice(0, foldAt).map(request => request.args[0]).filter(command => command !== '--version' && command !== 'install'), []);
// Argent's bridge is told the pose, so it captures the opened panel's landscape UI upright.
if (argent) for (const request of controller) assert.equal(request.environment.EXPLORE_ARGENT_POSE, 'open');
}
});
test('on EAS Simulator a fold the controller cannot read back is confirmed by the lit display: portrait is closed, landscape is open', async t => {
const closed = await fixture(t, { devicePose: 'closed', foldUnverified: true });
assert.equal((await runCiMap(closed.options)).runStatus, 'complete');
assert.ok(closed.requests.some(request => request.args[0] === 'screenshot' && request.args[1].endsWith('pose.png')), 'the display is read after the unconfirmed fold');
const open = await fixture(t, { devicePose: 'open', foldUnverified: true });
await assert.rejects(runCiMap(open.options), error => error.code === 'CONTROLLER_FOLD_UNVERIFIED');
});
test('a local simulator capture creates its own iOS simulator, installs the repacked app there, and deletes the simulator', async t => {
for (const repack of ['local', 'eas']) {
const f = await fixture(t, { local: true, repack });
@@ -3375,43 +3352,3 @@ test('a verified label is located on the image\'s axes when the screenshot is th
// A 669 x 951 portrait panel captured upright as a 951 x 669 image: the button near its bottom-left is near the image's top-left.
assert.deepEqual(verifiedCaptureLabels(nodes, ['Done'], { height: 951 })[0].rect, { x: 11, y: 10, width: 40, height: 100 });
});
const FAKE_ENGINE = new URL('../fixtures/flows/fake-engine.mjs', import.meta.url).pathname;
const FLOW_FILE = `import { test, expect } from "e2e";
test("home shows the balance", async ({ app, screen }) => {
await app.screenshot("home");
await screen.getByTestId("home-send").tap();
await expect(screen.getByRole("heading", "Your contacts")).toBeVisible();
await app.screenshot("contacts");
});
`;
test('flows mode runs the app\'s e2e files after the routes, hands the device over, and exports their frames with the map', async t => {
const f = await fixture(t, { flows: { tests: ['e2e/*.e2e.ts'], only: true }, flowFiles: { 'home.e2e.ts': FLOW_FILE }, environment: { EXPLORE_FLOWS_ENGINE_MODULE: FAKE_ENGINE } });
const result = await runCiMap(f.options);
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
assert.equal(bundle.flowsFailure, undefined);
const flow = bundle.flows['home/home-shows-the-balance'];
assert.equal(flow.status, 'passed');
assert.deepEqual(Object.keys(flow.frames), ['home', 'contacts']);
for (const frame of Object.values(flow.frames)) {
const png = await readFile(join(f.options.outputDirectory, frame.path));
assert.equal(createHash('sha256').update(png).digest('hex'), frame.sha256, 'the exported frame is the one the flow took');
}
assert.deepEqual(Object.keys(bundle.images), [], 'flows mode captures no routes');
assert.deepEqual((await readdir(f.options.project)).filter(name => name.startsWith('.expo-explore')), [], "e2e's output leaves the app directory");
assert.ok(f.operations().lastIndexOf('close') < f.requests.findIndex(request => request.command === process.execPath), 'Explore closes its session before e2e opens the app');
assert.equal(result.runStatus, 'complete', 'no route was planned, so none is missing');
});
test('a flows worker that cannot start leaves a flows failure in the bundle instead of failing the capture', async t => {
const f = await fixture(t, { flows: { tests: ['e2e/*.e2e.ts'], only: true }, flowFiles: { 'home.e2e.ts': FLOW_FILE }, environment: { EXPLORE_FLOWS_ENGINE_MODULE: join(tmpdir(), 'missing-engine.mjs') } });
const lines = [];
await runCiMap({ ...f.options, progress: line => lines.push(line) });
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
assert.equal(bundle.flows, undefined);
assert.equal(bundle.flowsFailure.code, 'FLOWS_NOT_RUN');
assert.match(bundle.flowsFailure.message, /missing-engine/);
assert.ok(lines.some(line => /the flows did not run: .*missing-engine/.test(line)), 'the capture log names the reason the flows did not run');
assert.deepEqual((await readdir(f.options.project)).filter(name => name.startsWith('.expo-explore')), []);
});
+1 -6
View File
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { readFile, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { runCompareCi } from '../../dist/ci/pipeline.js';
import { writeCaptureOutputs } from '../../dist/ci/workflow-steps.js';
@@ -16,10 +16,6 @@ test('any two commits: a capture and report like a pull request\'s, with no pull
await writeFile(comparePath, JSON.stringify({ origin: 'compare', repositoryId: '123', repository: 'acme/example',
base: { ref: 'v1.0.0', sha: f.baseSha }, head: { ref: 'v1.1.0', sha: f.headSha } }));
const output = join(f.root, 'compare');
// Another target's flows may be running in the same checkout: Explore's scratch directory is not a source change.
const scratch = join(f.baseProject, '.expo-explore-flows');
await mkdir(join(scratch, 'android-abc'), { recursive: true });
await writeFile(join(scratch, 'android-abc', 'frame.png'), 'png');
const result = await runCompareCi({ baseProject: f.baseProject, headProject: f.headProject, comparePath, output, config: f.config,
environment: { ...f.environment, GITHUB_TOKEN: '' }, runner: f.runner, now: f.now, sleep: f.sleep });
@@ -70,7 +66,6 @@ test('any two commits: a capture and report like a pull request\'s, with no pull
assert.match(summary, new RegExp(`\\(https://github\\.com/acme/example/compare/${f.baseSha}\\.\\.${f.headSha}\\)`));
assert.match(summary, /^- iOS.*: \d+ changes?$/m);
await rm(scratch, { recursive: true, force: true });
assert.equal(git(f.baseProject, 'status', '--porcelain'), '');
assert.equal(git(f.headProject, 'status', '--porcelain'), '');
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length,
-20
View File
@@ -647,23 +647,3 @@ test("doctor checks each target where it runs: local tools for local targets, EA
assert.equal(check(forced, "eas-simulator")[0].status, "pass");
assert.deepEqual(check(forced, "controller"), []);
});
test("doctor checks that flows.tests names committed e2e files and that the app can import e2e", async (t) => {
const flows = { ...baseConfig, mode: "flows", flows: { tests: ["e2e/*.e2e.ts", "e2e/extra/checkout.e2e.ts"] } };
const root = await app(t, flows, { "e2e/home.e2e.ts": "import { test } from 'e2e';\ntest('home', async () => {});\n" });
const report = await runDoctor(offline(root));
const tests = check(report, "flows-tests")[0];
assert.equal(tests.status, "fail");
assert.equal(tests.code, "FLOWS_TESTS_MISSING");
assert.match(tests.message, /"e2e\/extra\/checkout\.e2e\.ts"/);
assert.doesNotMatch(tests.message, /e2e\/\*\.e2e\.ts/);
assert.equal(check(report, "flows-e2e")[0].code, "FLOWS_E2E_UNRESOLVED");
assert.equal(check(report, "flows-output").length, 0);
await write(root, { "e2e/extra/checkout.e2e.ts": "export {};\n", "node_modules/e2e/package.json": JSON.stringify({ name: "e2e", version: "0.21.2" }), ".expo-explore-flows/keep": "" });
const ready = await runDoctor(offline(root));
assert.equal(check(ready, "flows-tests")[0].status, "pass");
assert.match(check(ready, "flows-tests")[0].message, /2 e2e test files/);
assert.match(check(ready, "flows-e2e")[0].message, /e2e 0\.21\.2/);
assert.equal(check(ready, "flows-output")[0].code, "FLOWS_OUTPUT_EXISTS");
});
-41
View File
@@ -354,44 +354,3 @@ test("a target can choose its own controller and simulator over capture's", () =
assert.deepEqual(["duo", "android", "cloud"].map(id => captureRepack(resolveTargetConfig(config, { target: id }))), ["local", "local", "eas"]);
assert.throws(() => validateExploreConfig({ ...base(), targets: { duo: { platform: "ios", controller: "maestro" } } }), error => error.code === "CONFIG_INVALID");
});
test("flows: the app's e2e tests run in flows mode or beside deterministic routes, never with the agent", () => {
const flows = validateExploreConfig({ ...base(), mode: "flows", flows: { tests: ["flows/*.e2e.ts", "e2e/checkout.e2e.ts"] } });
assert.equal(flows.mode, "flows");
assert.deepEqual(flows.flows, { tests: ["flows/*.e2e.ts", "e2e/checkout.e2e.ts"] });
assert.deepEqual(validateExploreConfig({ ...base(), flows: { tests: "e2e/**/*.e2e.ts" } }).flows, { tests: ["e2e/**/*.e2e.ts"] });
assert.deepEqual(validateExploreConfig({ ...base(), flows: { tests: "e2e/a.e2e.ts", frames: "steps" } }).flows, { frames: "steps", tests: ["e2e/a.e2e.ts"] });
assert.deepEqual(validateExploreConfig({ ...base(), flows: { tests: "e2e/a.e2e.ts", frames: "checkpoints" } }).flows, { tests: ["e2e/a.e2e.ts"] }, "checkpoints is the default and is not kept");
assert.throws(() => validateExploreConfig({ ...base(), flows: { tests: "e2e/a.e2e.ts", frames: "all" } }), /flows\.frames must be "checkpoints"/);
assert.throws(() => validateExploreConfig({ ...base(), mode: "flows" }), /flows.tests is required in flows mode/);
assert.throws(() => validateExploreConfig({ ...base(), mode: "agent", agent: { provider: "openai", model: "m", instructions: "x.md" }, flows: { tests: ["a.e2e.ts"] } }), /cannot be combined with agent mode/);
assert.throws(() => validateExploreConfig({ ...base(), flows: { tests: ["../outside.e2e.ts"] } }), /inside the app directory/);
assert.throws(() => validateExploreConfig({ ...base(), flows: { tests: [], extra: 1 } }), /flows/);
});
test("--flows runs the named e2e files as the whole capture, in flows mode, and is validated", () => {
const plain = validateExploreConfig(base());
const flows = withRunOverrides(plain, { flows: ["e2e/checkout.e2e.ts", " e2e/sign-up/*.e2e.ts "] });
assert.equal(flows.mode, "flows");
assert.deepEqual(flows.flows, { tests: ["e2e/checkout.e2e.ts", "e2e/sign-up/*.e2e.ts"] });
assert.deepEqual(withRunOverrides(plain, {}), plain);
assert.throws(() => withRunOverrides(plain, { flows: [" "] }), error => error.code === "CONFIG_INVALID");
assert.throws(() => withRunOverrides(plain, { flows: ["../other/app.e2e.ts"] }), error => error.code === "CONFIG_INVALID");
assert.throws(() => withRunOverrides(validateExploreConfig({ ...base(), mode: "agent" }), { flows: ["e2e/a.e2e.ts"] }), error => error.code === "CONFIG_INVALID");
});
test("a target or platform runs its own flows over the top-level list; agent mode takes none", () => {
const shared = { tests: ["e2e/*.e2e.ts"] };
const targets = validateExploreConfig({ ...base(), flows: shared, targets: {
phone: { platform: "ios" },
fold: { platform: "ios", device: "iPhone Duo", flows: { tests: ["e2e/fold/*.e2e.ts"] } } } });
assert.deepEqual(resolveTargetConfig(targets, { target: "phone" }).flows, shared);
assert.deepEqual(resolveTargetConfig(targets, { target: "fold" }).flows, { tests: ["e2e/fold/*.e2e.ts"] });
const platforms = validateExploreConfig({ ...base(), mode: "flows", flows: shared, platforms: {
ios: {}, android: { bundleId: "com.example.app", easProfile: "explore", flows: { tests: ["e2e/android/*.e2e.ts"] } } } });
assert.deepEqual(resolvePlatformConfig(platforms, "ios").flows, shared);
assert.deepEqual(resolvePlatformConfig(platforms, "android").flows, { tests: ["e2e/android/*.e2e.ts"] });
assert.throws(() => validateExploreConfig({ ...base(), targets: { fold: { platform: "ios", flows: { tests: ["../e2e/x.e2e.ts"] } } } }), error => error.code === "CONFIG_INVALID");
assert.throws(() => validateExploreConfig({ ...base(), mode: "agent", agent: { provider: "openai", model: "gpt-5" }, targets: { fold: { platform: "ios", flows: shared } } }),
error => error.code === "CONFIG_INVALID" && /agent mode/.test(error.message));
});
-28
View File
@@ -1,28 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createRequire } from 'node:module';
import { contentSha256 } from '../../dist/shared/png-evidence.js';
const { PNG } = createRequire(import.meta.url)('pngjs');
function frame(width, height, paint) {
const png = new PNG({ width, height });
for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
const [r, g, b] = paint(x, y); const i = (y * width + x) * 4;
png.data[i] = r; png.data[i + 1] = g; png.data[i + 2] = b; png.data[i + 3] = 255;
}
return PNG.sync.write(png);
}
test('contentSha256 ignores the status-bar and home-indicator bands and sees everything between them', () => {
const bands = { top: 6.5, bottom: 3 };
const body = (x, y) => [x % 256, y % 256, 40];
const base = frame(60, 200, body);
const clockTicked = frame(60, 200, (x, y) => (y < 10 ? [255, 255, 255] : body(x, y)));
const indicatorInverted = frame(60, 200, (x, y) => (y >= 196 ? [0, 0, 0] : body(x, y)));
const contentChanged = frame(60, 200, (x, y) => (y === 100 && x === 30 ? [9, 9, 9] : body(x, y)));
assert.equal(contentSha256(clockTicked, bands), contentSha256(base, bands), 'a change inside the top band does not count');
assert.equal(contentSha256(indicatorInverted, bands), contentSha256(base, bands), 'a change inside the bottom band does not count');
assert.notEqual(contentSha256(contentChanged, bands), contentSha256(base, bands), 'one pixel between the bands does');
assert.notEqual(contentSha256(base, bands), contentSha256(base, { top: 0, bottom: 0 }), 'the hashed region is part of the hash');
assert.match(contentSha256(base, bands), /^[a-f0-9]{64}$/);
});
-38
View File
@@ -1,38 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { settledScreenshot } from '../../dist/capture/flows/worker.js';
function fakeDevice(frames) {
const shots = [];
return { shots, client: { capture: { async screenshot({ path }) { const frame = frames[Math.min(shots.length, frames.length - 1)]; shots.push(frame); await writeFile(path, frame); } } } };
}
test('a step frame is shot again until two shots agree, and the last shot is kept', async () => {
const dir = await mkdtemp(join(tmpdir(), 'explore-settled-'));
const pauses = [];
const sleep = async ms => { pauses.push(ms); };
const settling = fakeDevice(['easing-1', 'easing-2', 'settled', 'settled']);
const file = join(dir, 'a.png');
assert.deepEqual(await settledScreenshot(settling.client, file, { sleep, pauseMs: 150 }), { tries: 4, settled: true });
assert.equal(settling.shots.length, 4, 'three re-shots after the first');
assert.deepEqual(pauses, [150, 150, 150]);
assert.equal(await readFile(file, 'utf8'), 'settled');
const still = fakeDevice(['same']);
assert.deepEqual(await settledScreenshot(still.client, join(dir, 'b.png'), { sleep }), { tries: 2, settled: true }, 'a still screen costs one re-shot');
const restless = fakeDevice(['1', '2', '3', '4', '5', '6']);
const result = await settledScreenshot(restless.client, join(dir, 'c.png'), { sleep, tries: 3 });
assert.deepEqual(result, { tries: 3, settled: false }, 'bounded: an animating screen is kept after the last try');
assert.equal(await readFile(join(dir, 'c.png'), 'utf8'), '3');
const closing = fakeDevice(['x', 'y', 'z']);
let open = true;
const stopAfterFirstPause = async ms => { pauses.push(ms); open = false; };
assert.deepEqual(await settledScreenshot(closing.client, join(dir, 'd.png'), { sleep: stopAfterFirstPause, more: () => open }), { tries: 1, settled: false },
'once the device is going away the shot in hand is kept instead of asking for another');
assert.equal(closing.shots.length, 1);
});
-87
View File
@@ -1,87 +0,0 @@
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import test from "node:test";
import { tsImport } from "tsx/esm/api";
const { summarizeFlowReport, flowId, flowSlug } = await tsImport("../../src/capture/flows/report.ts", import.meta.url);
const report = JSON.parse(readFileSync(new URL("../fixtures/flows/e2e-report.json", import.meta.url), "utf8"));
test("summarizes the selected tests of an e2e report with their steps and screenshot frames", () => {
const tests = summarizeFlowReport(report);
assert.equal(tests.length, 1, "unselected files stay out");
const [flow] = tests;
assert.equal(flow.id, "send/send-money-reaches-contacts");
assert.equal(flow.status, "passed");
assert.equal(flow.file, "tests/send.e2e.ts");
assert.deepEqual(flow.steps.map(step => [step.api, step.label, step.status, step.frame]), [
["app.screenshot", "home", "passed", "home"],
["locator.tap", 'getByTestId("home-send")', "passed", undefined],
["expect.toBeVisible", 'getByRole("heading", name: "Your contacts")', "passed", undefined],
["app.screenshot", "contacts", "passed", "contacts"],
]);
assert.deepEqual(flow.frames.map(frame => [frame.key, frame.path, frame.stepIndex]), [
["home", "send-money-reaches-contacts-09af3c698e01af96/attempt-1/screenshots/001.png", 0],
["contacts", "send-money-reaches-contacts-09af3c698e01af96/attempt-1/screenshots/002.png", 3],
]);
assert.ok(Number.isFinite(Date.parse(flow.frames[0].capturedAt)));
});
test("flow ids and frame keys are stable path segments", () => {
assert.equal(flowId("tests/checkout/Pay now.e2e.ts", ["Checkout", "pays with the test card"]), "checkout-pay-now/checkout-pays-with-the-test-card");
assert.equal(flowId("e2e/onboarding.e2e.ts", ["signs up"]), "onboarding/signs-up");
assert.equal(flowSlug(" Review — step 2! "), "review-step-2");
assert.equal(flowSlug("***"), "flow");
});
test("a failed flow keeps the frames it took and names the failing step", () => {
const failed = structuredClone(report);
const result = failed.run.results.find(entry => entry.selected);
result.status = "failed";
const attempt = result.attempts[0];
attempt.status = "failed";
attempt.error = { code: "LOCATOR_NOT_FOUND", message: "no element matches getByText(\"Alex Rivera\")" };
attempt.steps = [...attempt.steps.slice(0, 2), { ...attempt.steps[1], index: 2, api: "locator.tap", label: 'getByText("Alex Rivera")', status: "failed", artifacts: [],
error: { code: "LOCATOR_NOT_FOUND", message: "no element matches" } }];
const [flow] = summarizeFlowReport(failed);
assert.equal(flow.status, "failed");
assert.equal(flow.error.code, "LOCATOR_NOT_FOUND");
assert.deepEqual(flow.frames.map(frame => frame.key), ["home"]);
assert.equal(flow.steps[2].status, "failed");
assert.equal(flow.steps[2].error.code, "LOCATOR_NOT_FOUND");
});
test("repeated screenshot labels get distinct frame keys", () => {
const twice = structuredClone(report);
const attempt = twice.run.results.find(entry => entry.selected).attempts[0];
attempt.steps[3] = { ...attempt.steps[3], label: "home" };
const [flow] = summarizeFlowReport(twice);
assert.deepEqual(flow.frames.map(frame => frame.key), ["home", "home-2"]);
});
test("steps and tests carry the e2e source line of the test file", async () => {
const summaries = summarizeFlowReport(JSON.parse(readFileSync(new URL("../fixtures/flows/e2e-report.json", import.meta.url), "utf8")));
const send = summaries.find(summary => summary.file === "tests/send.e2e.ts");
assert.equal(send.steps[0].line, 3);
assert.equal(send.steps[1].line, 4);
assert.ok(send.line === undefined || send.line > 0);
});
test("per-step frames fill the steps that took no frame of their own, keyed by step number", () => {
const selected = report.run.results.find(result => result.selected !== false);
const stepFrames = new Map([[selected.testId, [
{ stepIndex: 1, path: "explore-step-frames/a-1.png", capturedAt: "2026-01-01T00:00:01.000Z" },
{ stepIndex: 0, path: "explore-step-frames/a-0.png", capturedAt: "2026-01-01T00:00:00.000Z" },
{ stepIndex: 2, path: "explore-step-frames/a-2.png", capturedAt: "2026-01-01T00:00:02.000Z" },
{ stepIndex: 9, path: "explore-step-frames/a-9.png", capturedAt: "2026-01-01T00:00:09.000Z" },
]]]);
const [flow] = summarizeFlowReport(report, stepFrames);
assert.deepEqual(flow.steps.map(step => step.frame), ["home", "step-2", "step-3", "contacts"], "a screenshot step keeps its own frame; a step past the end is ignored");
assert.deepEqual(flow.frames.map(frame => [frame.key, frame.stepIndex, frame.path]), [
["home", 0, flow.frames[0].path],
["step-2", 1, "explore-step-frames/a-1.png"],
["step-3", 2, "explore-step-frames/a-2.png"],
["contacts", 3, flow.frames[3].path],
], "frames come out in step order");
assert.equal(flow.frames[1].label, '2. getByTestId("home-send")');
assert.deepEqual(summarizeFlowReport(report, new Map([["other-test", [{ stepIndex: 1, path: "x.png", capturedAt: "" }]]]))[0].frames.length, 2, "frames of another test are not attached");
});
-81
View File
@@ -1,81 +0,0 @@
import assert from "node:assert/strict";
import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import test from "node:test";
import { runFlows, flowFramePath } from "../../dist/capture/flows/run-flows.js";
import { defaultRunner } from "../../dist/capture/controller.js";
const engineModule = fileURLToPath(new URL("../fixtures/flows/fake-engine.mjs", import.meta.url));
const repo = fileURLToPath(new URL("../../", import.meta.url));
async function project(files) {
const root = await mkdtemp(join(tmpdir(), "explore-flows-"));
const app = join(root, "app");
await mkdir(join(app, "e2e"), { recursive: true });
// The app resolves `e2e` the way a real app does: from its own node_modules.
await mkdir(join(app, "node_modules"), { recursive: true });
const { symlink } = await import("node:fs/promises");
await symlink(join(repo, "node_modules", "e2e"), join(app, "node_modules", "e2e"), "dir");
for (const [name, source] of Object.entries(files)) await writeFile(join(app, "e2e", name), source);
return { root, app, work: join(root, "work"), output: join(root, "bundle") };
}
const run = async (files, options = {}) => {
const paths = await project(files);
await mkdir(paths.work, { recursive: true });
await mkdir(paths.output, { recursive: true });
const progress = [];
const result = await runFlows({ project: paths.app, tests: Object.keys(files).map(name => `e2e/${name}`), platform: "ios", bundleId: "com.example.app",
stateDir: join(paths.work, "state"), workDirectory: paths.work, outputDirectory: paths.output, runner: defaultRunner, environment: { ...process.env },
timeoutMs: 60_000, progress: message => progress.push(message), engineModule, ...options });
return { ...paths, result, progress };
};
test("runs e2e flows through the worker and keeps every app.screenshot as a bundle frame", async () => {
const { result, output, root } = await run({ "send.e2e.ts": `import { test, expect } from "e2e";
test("send money reaches contacts", async ({ app, screen }) => {
await app.screenshot("home");
await screen.getByTestId("home-send").tap();
await expect(screen.getByRole("heading", "Your contacts")).toBeVisible();
await app.screenshot("contacts");
});
` });
try {
assert.equal(result.failure, undefined);
assert.deepEqual((await readdir(join(root, "app"))).filter(name => name.startsWith(".expo-explore")), [], "e2e's output leaves the app directory");
const flow = result.flows["send/send-money-reaches-contacts"];
assert.ok(flow, Object.keys(result.flows).join(","));
assert.equal(flow.status, "passed");
assert.deepEqual(flow.steps.map(step => [step.api, step.status, step.frame]),
[["app.screenshot", "passed", "home"], ["locator.tap", "passed", undefined], ["expect.toBeVisible", "passed", undefined], ["app.screenshot", "passed", "contacts"]]);
assert.deepEqual(Object.keys(flow.frames), ["home", "contacts"]);
for (const [key, frame] of Object.entries(flow.frames)) {
assert.equal(frame.path, flowFramePath("send/send-money-reaches-contacts", key));
assert.deepEqual([frame.width, frame.height], [1, 1]);
const bytes = await readFile(join(output, frame.path));
assert.equal(bytes.length > 0, true);
assert.match(frame.sha256, /^[a-f0-9]{64}$/);
}
} finally { await rm(root, { recursive: true, force: true }); }
});
test("a failing flow keeps the frames before the failure and reports the failing step; the capture goes on", async () => {
const { result, root } = await run({ "broken.e2e.ts": `import { test, expect } from "e2e";
test("taps a contact that is not there", async ({ app, screen }) => {
await app.screenshot("home");
await screen.getByTestId("home-send").tap();
await screen.getByText("Nobody Here").tap();
await app.screenshot("never");
});
` });
try {
assert.equal(result.failure, undefined);
const flow = result.flows["broken/taps-a-contact-that-is-not-there"];
assert.equal(flow.status, "failed");
assert.deepEqual(Object.keys(flow.frames), ["home"]);
assert.equal(flow.steps[2].status, "failed");
assert.ok(flow.error?.code, JSON.stringify(flow));
} finally { await rm(root, { recursive: true, force: true }); }
});
+2 -3
View File
@@ -196,10 +196,9 @@ test("a screen without a route, or one the map does not know yet, travels as an
test("legacy hashes still parse", () => {
assert.deepEqual(parse("/#workspace"), base);
assert.deepEqual(parse("/#workspace/screens"), { ...base, canvas: "screens" });
// The hash-era Flows canvas was retired; its links land on the map. The path form is the
// current Flows view (the app sends it to the map when the review ran no flows).
// Flows was retired; its links land on the map.
assert.deepEqual(parse("/#workspace/flows"), base);
assert.deepEqual(parse("/flows?flow=derived-apps"), { ...base, canvas: "flows" });
assert.deepEqual(parse("/flows?flow=derived-apps"), base);
assert.deepEqual(parse("/#workspace/graph"), base);
assert.deepEqual(parse("/map?panel=workspace"), base);
assert.equal(nav.formatRoute(parse("/map?panel=workspace"), ctx), "/map");
+1 -15
View File
@@ -66,7 +66,7 @@ async function exportFixture(t, options) {
}
/** A fake EAS CLI plus a fake deployment: `deploy` captures the sealed report and .env, then serves them like the Worker would. */
function easFixture({ origin = "https://acme-explore--1lcbdcpwn3.expo.app", aliasOrigin = "https://acme-explore--bluesky.expo.app", accounts = ["brent-org"], failDeploy = false, aliasServes = true, aliasListing, existingComment } = {}) {
function easFixture({ origin = "https://acme-explore--1lcbdcpwn3.expo.app", aliasOrigin = "https://acme-explore--bluesky.expo.app", accounts = ["brent-org"], failDeploy = false, aliasServes = true, existingComment } = {}) {
let deploys = 0;
let latestComment = existingComment;
const calls = []; const captured = {};
@@ -107,8 +107,6 @@ function easFixture({ origin = "https://acme-explore--1lcbdcpwn3.expo.app", alia
? new Response("<!doctype html>", { status: 200, headers: { "content-type": "text/html; charset=utf-8" } })
: new Response("# Expo Explore report", { status: 200, headers: { "content-type": "text/markdown; charset=utf-8" } });
if (match[2] === "api/v1") return new Response(JSON.stringify({ kind: "pr-review" }), { status: 200, headers: { "content-type": "application/json; charset=utf-8" } });
// aliasListing: the alias still points at an earlier deployment of the same token and reports, listed the old way.
if (match[2] === "reports.json" && aliasListing && url.origin === aliasOrigin) return new Response(aliasListing, { status: 200, headers: { "content-type": "application/json; charset=utf-8" } });
if (match[2] === "reports.json") return new Response(JSON.stringify(captured.listing.map(({ path: _path, ...rest }) => rest)), { status: 200, headers: { "content-type": "application/json; charset=utf-8" } });
// Selection as the Worker does it: ?target= by id, ?platform= by id and then by platform, else the first.
const target = url.searchParams.get("target"), platform = url.searchParams.get("platform");
@@ -476,18 +474,6 @@ test("a fixture preview seals each platform's ZIP as is behind one alias and lis
assert.equal(logged.filter(line => /^::warning::The alias https:\/\/explore-viewer-pr--pr-12\.expo\.app still answers HTTP 404 \d+ s after eas deploy returned\. The pull request links the deployment https:\/\/acme-explore--1lcbdcpwn3\.expo\.app instead\./.test(line)).length, 1);
assert.ok(behind.requests.some(request => request.url.origin === "https://explore-viewer-pr--pr-12.expo.app"), "the alias was polled");
// The example report keeps one token and the same fixtures, so an alias still on the previous deployment serves the
// token page and the same report: only its listing (an older Viewer's) gives it away. That is an alias behind too.
const stale = easFixture({ aliasOrigin: "https://explore-viewer-pr--pr-12.expo.app", aliasListing: JSON.stringify([{ platform: "ios" }]) });
clock = now; logged.length = 0;
process.stderr.write = chunk => { logged.push(String(chunk)); return true; };
try {
linked = await deployFixturePreview({ reports: [{ platform: "ios", zipPath: join(root, "ios.zip") }], project: "explore-viewer-pr", owner: "brent-org", alias: "pr-12", token,
exportPath, environment: deployEnvironment, transport: stale.transport, run: stale.run, now: ticking, verifyTimeoutMs: 60_000 });
} finally { process.stderr.write = quiet; }
assert.equal(linked.previewUrl, `https://acme-explore--1lcbdcpwn3.expo.app/p/${token}`);
assert.equal(logged.filter(line => /^::warning::The alias https:\/\/explore-viewer-pr--pr-12\.expo\.app still serves an earlier deployment \d+ s after eas deploy returned\./.test(line)).length, 1);
await assert.rejects(deployFixturePreview({ reports: [{ platform: "ios", zipPath: join(root, "ios.zip") }, { platform: "ios", zipPath: join(root, "ios.zip") }],
project: "explore-viewer-pr", alias: "pr-12", exportPath, environment: deployEnvironment, transport: eas.transport, run: eas.run, verifyTimeoutMs: 1 }),
error => error.code === "PREVIEW_REPORTS_INVALID");
-41
View File
@@ -357,44 +357,3 @@ test('a head that gained a dark appearance reviews <id>@dark with its own digest
assert.equal(secondary.headOutcome.status, 'captured');
assert.equal(secondary.headImage.url, `https://embedded.expo-explore.invalid/${darkSha}.png`);
});
test('a flows failure is published per side and validated as a code and a bounded message', async t => {
const f = await captureFixture(t);
const result = await prepareCaptureReview({ ...f.options });
const failure = { code: 'FLOWS_NOT_RUN', message: 'The e2e worker wrote no result.' };
assertPublicReview({ ...result.review, flowsFailure: { head: failure } });
assertPublicReview({ ...result.review, flowsFailure: { base: failure, head: failure } });
for (const invalid of [{}, { head: {} }, { head: { code: 1, message: 'x' } }, { head: { ...failure, extra: true } }, { other: failure }, { head: { ...failure, message: 'x'.repeat(4_001) } }]) {
assert.throws(() => assertPublicReview({ ...result.review, flowsFailure: invalid }), /Public flows failure is invalid/);
}
});
test('flow frames are report assets: the review names them by hash and the local report carries their bytes', async t => {
const f = await captureFixture(t);
// A second PNG, distinct from the route frame.
const frameImage = new PNG({ width: 1, height: 1 }); frameImage.data = Buffer.from([12, 34, 56, 255]);
const framePng = PNG.sync.write(frameImage);
const frameSha = createHash('sha256').update(framePng).digest('hex');
const headDirectory = f.options.headDirectory;
await mkdir(join(headDirectory, 'flows', 'home', 'home-opens'), { recursive: true });
await writeFile(join(headDirectory, 'flows', 'home', 'home-opens', 'home.png'), framePng);
const darkImage = new PNG({ width: 1, height: 1 }); darkImage.data = Buffer.from([1, 2, 3, 255]);
const darkPng = PNG.sync.write(darkImage); const darkSha = createHash('sha256').update(darkPng).digest('hex');
await writeFile(join(headDirectory, 'flows', 'home', 'home-opens', '[email protected]'), darkPng);
const head = { ...f.bundles.head, runtimeProfile: { ...f.bundles.head.runtimeProfile, colorSchemes: 'light,dark' }, flows: { 'home/home-opens': { file: 'e2e/home.e2e.ts', title: 'home opens', status: 'passed', durationMs: 12,
steps: [{ api: 'app.screenshot', label: 'home', status: 'passed', durationMs: 3, frame: 'home' }],
frames: { home: { path: 'flows/home/home-opens/home.png', sha256: frameSha, width: 1, height: 1, capturedAt: '2026-09-08T00:00:01Z' },
'home@dark': { path: 'flows/home/home-opens/[email protected]', sha256: darkSha, width: 1, height: 1, capturedAt: '2026-09-08T00:00:02Z' } } } } };
await writeFile(join(headDirectory, 'bundle.json'), JSON.stringify(head));
const result = await prepareCaptureReview({ ...f.options });
assertPublicReview(result.review);
const flow = result.review.flows[0];
assert.equal(flow.id, 'home/home-opens');
assert.match(flow.head.frames.home.url, new RegExp(`${frameSha}\\.png$`));
assert.deepEqual(result.assets.filter(asset => asset.sha256 === frameSha).map(asset => asset.path), [join(headDirectory, 'flows', 'home', 'home-opens', 'home.png')]);
// A second appearance's frame is its own surface, `<key>@<scheme>`, carrying the scheme; the primary frame carries none.
assert.deepEqual(flow.frames.map(frame => [frame.key, frame.id, frame.colorScheme]),
[['home', 'flow:home/home-opens/home', undefined], ['home@dark', 'flow:home/home-opens/home@dark', 'dark']]);
assert.match(flow.head.frames['home@dark'].url, new RegExp(`${darkSha}\\.png$`));
assert.equal(result.assets.filter(asset => asset.sha256 === darkSha).length, 1);
});
-9
View File
@@ -588,12 +588,3 @@ test('a comment written by a per-platform version keeps parsing, and malformed t
const many = Array.from({ length: 10 }, (_, index) => line(`t${index}`, { ...valid, target: `t${index}` }));
assert.equal(parse(...many).length, 8, 'a comment holds at most one record per configurable target');
});
test('a side whose flows did not run is named with e2e\'s reason, ahead of the flow lines', () => {
const flowsFailure = { head: { code: 'FLOWS_NOT_RUN', message: 'Cannot find module "e2e/runner"' } };
const body = renderPublicComment(reviewOnlyState({ ...review([surface('home', 'unchanged')]), flowsFailure }));
assert.match(visible(body), /Flows did not run on head: Cannot find module "e2e\/runner"\./);
const both = renderPublicComment(reviewOnlyState({ ...review([surface('home', 'unchanged')]), flowsFailure: { ...flowsFailure, base: { code: 'FLOWS_NOT_RUN', message: 'timed out' } } }));
assert.match(visible(both), /Flows did not run on head: Cannot find module/);
assert.match(visible(both), /Flows did not run on base: timed out\./);
});
-15
View File
@@ -209,18 +209,3 @@ test("in a black-box tree, a screen with screens opened from it folds under its
assert.deepEqual(shape.screensUnder.get("screen:seq"), ["new"]);
assert.deepEqual(shape.ancestors.get("new"), ["screen:seq"]);
});
test("flow frames stay out of the Screens tree in both modes: the Flows view shows them, the Map draws their chain", () => {
const screens = [
screen("home", "Home", 0, { route: "/" }),
screen("flow:send-money/contacts", "Send money › contacts", 1, { route: "send-money", state: "contacts" }),
screen("removed:aaaaaaaa:screen:flow:send-money/review", "Send money › review", 2, { route: "send-money", state: "review" }),
];
const routeFiles = new Map([["home", "src/app/index.tsx"]]);
for (const tree of [screenTree(screens, indexMap(map({ screens })), routeFiles), screenTree(screens, indexMap(map({ screens })))]) {
const listed = tree.sections.flatMap((section) => section.screenIds);
assert.deepEqual(listed.filter((id) => id.includes("flow:")), []);
assert.deepEqual(treeScreenOrder(tree).filter((id) => id.includes("flow:")), []);
assert.ok(listed.includes("home"));
}
});
+1 -20
View File
@@ -17,7 +17,6 @@ import { MapView } from "./components/views/semantic-map";
import { RightPanel } from "./components/panels/right";
import { SearchCommand } from "./components/search-command";
import { ScreensView } from "./components/views/screens";
import { FlowsView } from "./components/views/flows";
import { publicReviewProjection, publicReviewToWorkspace } from "./public/public-workspace";
import type { PublicReview } from "../../src/contracts/capture";
import {
@@ -28,7 +27,7 @@ import {
type ViewerBuild,
type ViewerWorkspace,
} from "./utils/build-diff";
import { type ViewerPayload, artifactUrl, isFlowScreen } from "./utils/model";
import { type ViewerPayload, artifactUrl } from "./utils/model";
import {
canonicalRoute,
formatRoute,
@@ -1184,16 +1183,6 @@ function ViewerApp() {
? { ...presentedMap, run: { ...presentedMap.run, name: workspace.catalog.name } }
: presentedMap
), [presentedMap, workspace]);
const hasFlows = (Array.isArray(loadedPublicReview?.flows) && loadedPublicReview!.flows!.length > 0) || loadedPublicReview?.flowsFailure !== undefined;
// A flows-only review has no routes: the Map and Screens would be empty, so the Flows view is the home.
// A flows review: every screen is a flow frame, or the capture took no route frame on either side (flows mode lists the routes without capturing them).
const flowsOnly = hasFlows && ((map !== undefined && map.screens.length > 0 && map.screens.every((screen) => isFlowScreen(screen)))
|| (loadedPublicReview?.surfaces ?? []).every((surface) => isFlowScreen(surface) || (!surface.baseImage && !surface.headImage)));
useEffect(() => {
if (flowsOnly && (route.canvas === "map" || route.canvas === "screens")) navigate({ canvas: "flows" }, { replace: true });
// A Flows link into a review that ran none (or an old link to the retired canvas) lands on the map.
if (loadedPublicReview && !hasFlows && route.canvas === "flows") navigate({ canvas: "map" }, { replace: true });
}, [flowsOnly, hasFlows, loadedPublicReview, route.canvas, navigate]);
// Focus singles out diff states, so it means nothing without a baseline to diff against.
const focusFilter = diff ? route.focus : [];
const focusCounts = useMemo(() => countFocusStatuses(diff), [diff]);
@@ -1539,9 +1528,6 @@ function ViewerApp() {
<CanvasVisibleFrameProvider
layoutKey={`${rightCollapsed}:${route.canvas}:${route.inspect}`}>
<div className="canvas-view-content" data-canvas-view={route.canvas}>
{route.canvas === "flows" && loadedPublicReview ? (
<FlowsView review={loadedPublicReview} phone={phone} onOpenFrame={(id) => openChangedScreen(id)} />
) : null}
{route.canvas === "screens" ? (
<ScreensView
map={map}
@@ -1614,16 +1600,12 @@ function ViewerApp() {
<PhoneTabBar
canvas={route.canvas}
compareCount={compareOrder.length}
hasFlows={hasFlows}
flowsOnly={flowsOnly}
onSelectCanvas={selectCanvas}
/>
) : <CanvasToolbar
canvas={route.canvas}
searchOpen={searchOpen}
compareCount={compareOrder.length}
hasFlows={hasFlows}
flowsOnly={flowsOnly}
{...(handoffAction ? { actions: handoffAction } : {})}
onOpenShortcuts={() => setShortcutsOpen(true)}
onSelectCanvas={selectCanvas}
@@ -1660,7 +1642,6 @@ function ViewerApp() {
onSelectScreen={goToScreenKeepingView}
onOpenCompare={compareOrder.length > 0 ? () => selectCanvas("compare") : undefined}
review={compareOrder.length > 0 ? { order: compareOrder, onSelectScreen: openChangedScreen } : undefined}
flowReview={loadedPublicReview ?? undefined}
/>}
{error && payload && (
<button className="sync-warning" onClick={() => void load()}>
+2 -8
View File
@@ -1,4 +1,4 @@
import { GitCompareArrows, Keyboard, LayoutGrid, Map, Search, ListOrdered } from "lucide-react";
import { GitCompareArrows, Keyboard, LayoutGrid, Map, Search } from "lucide-react";
import { type CSSProperties } from "react";
import { Tooltip } from "../shared/tooltip";
import { useCanvasVisibleFrame } from "./visible-frame-provider";
@@ -14,16 +14,11 @@ const VIEW_ICONS: Record<CanvasView, React.ReactNode> = {
map: <Map />,
screens: <LayoutGrid />,
compare: <GitCompareArrows />,
flows: <ListOrdered />,
};
const TOOLBAR_MINIMUM_FRAME_WIDTH = 220;
type CanvasToolbarProps = {
/** True when the review ran flows: the Flows view is offered. */
hasFlows?: boolean;
/** True when the review captured flows and no routes: Map and Screens have nothing to show. */
flowsOnly?: boolean;
canvas: CanvasView;
searchOpen: boolean;
/** How many changed screens Compare holds, shown as a badge on its button. Compare's own header
@@ -46,8 +41,7 @@ export function CanvasToolbar(props: CanvasToolbarProps) {
const style = visibleFrame ? ({
"--canvas-visible-bottom-inset": `calc(100% - ${visibleFrame.y + visibleFrame.height}px)`,
} as CSSProperties) : undefined;
// The Flows view exists only for a review that ran flows.
const views = CANVAS_VIEW_ORDER.filter((id) => (id !== "flows" || props.hasFlows) && !(props.flowsOnly && (id === "map" || id === "screens")));
const views = CANVAS_VIEW_ORDER;
return (
<div className="canvas-toolbar" role="toolbar" aria-label="Canvas tools" style={style}>
@@ -412,9 +412,8 @@ export function compareNotes(screenDiff: ScreenDiff, factCount: number, statusBa
return [
...(factCount === 0 && screenDiff.status === "needs-review"
? ["The code for this screen changed. No visible difference was found."] : []),
// A capture note says why a side has no frame (a flow that stopped before it); without one the screen itself came or went.
...(screenDiff.status === "added" ? [screenDiff.captureNotes?.before ?? "This screen is new in this PR. There is no Before to compare."]
: screenDiff.status === "removed" ? [screenDiff.captureNotes?.after ?? "This screen was removed in this PR. There is no After to compare."] : []),
...(screenDiff.status === "added" ? ["This screen is new in this PR. There is no Before to compare."]
: screenDiff.status === "removed" ? ["This screen was removed in this PR. There is no After to compare."] : []),
...(statusBarIgnored
? ["The status bar (clock, signal, battery) differs between the captures. It is not counted as a change."] : []),
...(homeIndicatorIgnored
@@ -1,5 +1,3 @@
import type { PublicFlowEvidence, PublicReview } from "../../../../src/contracts/capture";
import { flowOfScreen, flowSourceHref } from "../../utils/flow-source";
import { useEffect, useMemo, useRef, useState, type CSSProperties } from "react";
import { LAUNCH_SURFACE_ID } from "../../../../src/contracts/capture";
import { isEmbeddedArtifactUrl, resolveEmbeddedArtifactUrl } from "../../utils/embedded-report";
@@ -417,8 +415,6 @@ type InspectorPanelProps = {
onOpenCompare?: (() => void) | undefined;
/** The changed screens in review order, and how to step to one, for the sidebar review. */
review?: { order: readonly ChangedScreen[]; onSelectScreen: (id: string) => void } | undefined;
/** The public review, for a flow frame's flow (its steps and e2e source). */
flowReview?: PublicReview | undefined;
};
/** The URL to show for an artifact, resolving an embedded (self-contained report) reference lazily. */
@@ -465,50 +461,6 @@ function LaunchSection({ screen, index, note }: { screen: Screen; index: MapInde
);
}
/** A flow frame's place in its flow: the step that took it, the steps around it, the outcome per side, and the e2e source. */
function FlowSection(props: { context: { flow: PublicFlowEvidence; key: string }; review: PublicReview | undefined; onSelectScreen: (id: string) => void }) {
const { flow, key } = props.context;
const side = flow.head ?? flow.base;
const steps = side?.steps ?? [];
// A secondary-appearance frame (`<key>@<scheme>`) belongs to the step that took the primary one.
const frameKey = key.replace(/@(?:light|dark)$/, "");
const stepIndex = steps.findIndex(step => step.frame === frameKey);
const fileHref = flowSourceHref(props.review, flow.file, side?.line);
const outcome = (name: "base" | "head") => {
const run = flow[name];
if (!run) return "not run";
const failed = run.steps.findIndex(step => step.status !== "passed");
return run.status === "passed" || failed < 0 ? run.status : `${run.status} at step ${failed + 1}`;
};
return (
<section className="inspector-section flow-section">
<div className="section-title"><h3>Flow</h3></div>
<p className="flow-section-title">{flow.title}</p>
<p className="flow-section-file">{fileHref ? <a href={fileHref} target="_blank" rel="noreferrer">{flow.file}</a> : flow.file}</p>
<dl className="flow-section-outcomes">
<div><dt>After</dt><dd>{outcome("head")}</dd></div>
<div><dt>Before</dt><dd>{outcome("base")}</dd></div>
</dl>
{stepIndex >= 0 ? <p className="flow-section-step">Frame from step {stepIndex + 1} of {steps.length}</p> : null}
<ol className="flow-section-steps">
{steps.map((step, index) => {
const href = flowSourceHref(props.review, flow.file, step.line);
const frame = step.frame ? flow.frames.find(entry => entry.key === step.frame) : undefined;
const text = <><span className="flow-section-step-api">{step.api}</span> <span className="flow-section-step-label">{step.label}</span></>;
return (
<li key={index} className={`flow-section-step-row${index === stepIndex ? " current" : ""}${step.status !== "passed" ? " failed" : ""}`}>
<span className="flow-section-step-number">{index + 1}</span>
{href ? <a href={href} target="_blank" rel="noreferrer" title={`${flow.file}:${step.line}`}>{text}</a> : text}
{frame && frame.key !== key ? <button type="button" className="flow-section-step-frame" onClick={() => props.onSelectScreen(frame.id)}>frame · {frame.label}</button> : null}
{step.status !== "passed" && step.error ? <span className="flow-section-step-error">{step.error.message}</span> : null}
</li>
);
})}
</ol>
</section>
);
}
export function InspectorPanel(props: InspectorPanelProps) {
const { direction, screen } = props;
const screenDiff = screen ? props.diff?.screens.get(screen.id) : undefined;
@@ -516,7 +468,6 @@ export function InspectorPanel(props: InspectorPanelProps) {
const { outgoing, incoming } = useMemo(
() => inspectorTransitions(screen?.id, props.index), [screen?.id, props.index],
);
const flowContext = useMemo(() => screen ? flowOfScreen(props.flowReview, screen.id) : undefined, [props.flowReview, screen]);
// Only a screen whose comparison actually differs earns the Before → After layout. A screen
// the review confirmed as unchanged reads like any other: one screenshot and its transitions.
const showDiff = Boolean(
@@ -590,7 +541,6 @@ export function InspectorPanel(props: InspectorPanelProps) {
{screen.id.startsWith(LAUNCH_SURFACE_ID) ? <LaunchSection screen={screen} index={props.index} note={screenDiff?.note} /> : null}
{flowContext ? <FlowSection context={flowContext} review={props.flowReview} onSelectScreen={props.onSelectScreen} /> : (
<section
className={`inspector-section transition-section${transitions.length === 0 ? " is-empty" : ""}`}>
<div className="section-title">
@@ -624,7 +574,6 @@ export function InspectorPanel(props: InspectorPanelProps) {
</div>
)}
</section>
)}
</div>
);
}
-4
View File
@@ -1,4 +1,3 @@
import type { PublicReview } from "../../../../src/contracts/capture";
import { useEffect, useRef } from "react";
import { GitCompareArrows, PanelRight, ScanSearch, X } from "lucide-react";
import { Tooltip } from "../shared/tooltip";
@@ -30,8 +29,6 @@ type RightPanelProps = {
onOpenCompare?: (() => void) | undefined;
/** The changed screens in review order, and how to step to one, for the sidebar review. */
review?: { order: readonly ChangedScreen[]; onSelectScreen: (id: string) => void } | undefined;
/** The public review, for a flow frame's flow (its steps and e2e source). */
flowReview?: PublicReview | undefined;
};
export function RightPanel(props: RightPanelProps) {
@@ -152,7 +149,6 @@ export function RightPanel(props: RightPanelProps) {
onSelectScreen={props.onSelectScreen}
onOpenCompare={props.onOpenCompare}
review={props.review}
flowReview={props.flowReview}
/>
</AutoHideScrollArea>
</aside>
+2 -5
View File
@@ -1,6 +1,6 @@
import { useEffect, useRef, type PointerEvent as ReactPointerEvent, type ReactNode } from "react";
import { createPortal } from "react-dom";
import { GitCompareArrows, LayoutGrid, Map as MapIcon, X, ListOrdered } from "lucide-react";
import { GitCompareArrows, LayoutGrid, Map as MapIcon, X } from "lucide-react";
import { CANVAS_LABELS, type CanvasView } from "../../utils/navigation";
import { CANVAS_VIEW_ORDER } from "../../utils/canvas-view-transition";
import "./phone.css";
@@ -9,7 +9,6 @@ const VIEW_ICONS: Record<CanvasView, ReactNode> = {
map: <MapIcon />,
screens: <LayoutGrid />,
compare: <GitCompareArrows />,
flows: <ListOrdered />,
};
/**
@@ -19,13 +18,11 @@ const VIEW_ICONS: Record<CanvasView, ReactNode> = {
export function PhoneTabBar(props: {
canvas: CanvasView;
compareCount: number;
hasFlows?: boolean;
flowsOnly?: boolean;
onSelectCanvas: (canvas: CanvasView) => void;
}) {
return (
<nav className="phone-tab-bar" aria-label="Views">
{CANVAS_VIEW_ORDER.filter((id) => (id !== "flows" || props.hasFlows) && !(props.flowsOnly && (id === "map" || id === "screens"))).map((id) => {
{CANVAS_VIEW_ORDER.map((id) => {
return (
<button key={id} type="button" className="phone-tab"
aria-current={props.canvas === id ? "page" : undefined}
-4
View File
@@ -380,10 +380,6 @@
.phone-layout .collapsed-pr,
.screens-page.phone .screens-cell .screen-path-text,
.phone-layout .inspector-screen-path { padding-top: 14px; padding-bottom: 14px; margin-top: -14px; margin-bottom: -14px; }
/* A long review title ("devin/flows-capture vs main") ends in an ellipsis instead of running under the search buttons. */
.phone-layout .collapsed-app-identity > .tooltip-anchor { flex: none; }
.phone-layout .collapsed-app-identity > .tooltip-anchor:has(> .collapsed-pr) { flex: 1 1 0; min-width: 0; }
.phone-layout .collapsed-pr { flex: 0 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
/* Before/After keep a 32px line; the hit area grows into the gap on each side. */
.phone-layout .compare-flip-side { min-height: 32px; padding: 6px 12px; margin: -6px 0; }
.phone-layout .right-panel .icon-button { width: 44px; height: 44px; }
-58
View File
@@ -1,58 +0,0 @@
.flows-page { padding: 72px 32px 120px; display: flex; flex-direction: column; gap: 24px; overflow: auto; height: 100%; box-sizing: border-box; }
.flows-page.phone { padding: 64px 12px 120px; gap: 16px; }
.flows-empty { color: var(--text-muted, #6b6b6b); }
.flow-card { border: 1px solid var(--border, #e5e5e5); border-radius: 14px; background: var(--surface, #fff); padding: 18px 20px; display: flex; flex-direction: column; gap: 14px; }
.flow-header { display: flex; justify-content: space-between; gap: 16px; align-items: flex-start; flex-wrap: wrap; }
.flow-header h2 { margin: 0; font-size: 17px; font-weight: 600; }
.flow-file { margin: 4px 0 0; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; color: var(--text-muted, #6b6b6b); }
.flow-outcomes { display: flex; gap: 16px; }
.flow-outcome { display: flex; flex-direction: column; gap: 4px; align-items: flex-start; }
.flow-outcome-side { font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--text-muted, #6b6b6b); }
.flow-status, .flow-verdict { display: inline-flex; align-items: center; padding: 2px 8px; border-radius: 999px; font-size: 12px; font-weight: 600; background: #f0f0f0; color: #444; }
.tone-passed.flow-status, .tone-unchanged.flow-verdict { background: #e6f4ea; color: #1e7a3b; }
.tone-failed.flow-status, .tone-removed.flow-verdict { background: #fdecec; color: #b42318; }
.tone-modified.flow-verdict, .tone-needs-review.flow-verdict { background: #fff1e0; color: #b45309; }
.tone-added.flow-verdict { background: #e6f4ea; color: #1e7a3b; }
.flow-failure { margin: 0; padding: 10px 12px; border-radius: 10px; background: #fdecec; color: #7a1c14; font-size: 13px; }
.flow-failure code { font-size: 12px; }
.flow-body { display: grid; grid-template-columns: minmax(0, 1fr) minmax(260px, 360px); gap: 20px; align-items: start; }
.flows-page.phone .flow-body { grid-template-columns: 1fr; }
.flow-filmstrip { list-style: none; margin: 0; padding: 4px 0 8px; display: flex; flex-wrap: wrap; gap: 16px; }
/* Phone: one horizontal strip, swiped frame by frame. Desktop wraps so a long flow is visible at a glance. */
.flows-page.phone .flow-filmstrip { flex-wrap: nowrap; overflow-x: auto; scroll-snap-type: x proximity; }
.flow-frame { flex: 0 0 auto; width: 140px; display: flex; flex-direction: column; gap: 8px; scroll-snap-align: start; }
.flows-page.phone .flow-frame { width: 150px; }
.flow-frame-face {
position: relative;
margin: 0;
display: flex;
flex-direction: column;
}
/* A folded run of unchanged step frames: the count sits after the label; the folded steps are the tooltip. */
.flow-frame-tags { display: flex; align-items: center; gap: 6px; }
.flow-frame-same { padding: 1px 6px; border-radius: 999px; background: var(--panel-hover, #f0f0f0); color: var(--text-muted, #6b6b6b); font-size: 10px; font-weight: 600; vertical-align: 1px; }
.flow-header-side { display: flex; flex-direction: column; align-items: flex-end; gap: 10px; }
.flow-side-toggle { font-size: 12px; }
.flow-frame-button { padding: 0; border: 0; background: none; cursor: pointer; border-radius: 10px; min-width: 44px; min-height: 44px; }
.flow-frame-button:focus-visible { outline: 2px solid #2f6fed; outline-offset: 2px; }
.flow-frame-image { display: block; width: 140px; height: auto; border-radius: 10px; border: 1px solid var(--border, #e5e5e5); background: #fafafa; }
.flows-page.phone .flow-frame-image { width: 150px; }
.flow-frame-missing { width: 140px; aspect-ratio: 402 / 874; border-radius: 10px; border: 1px dashed #d0d0d0; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 6px; text-align: center; padding: 12px; box-sizing: border-box; font-size: 12px; color: var(--text-muted, #6b6b6b); }
.flow-frame-missing small { font-size: 11px; }
.flow-frame-caption { display: flex; flex-direction: column; align-items: flex-start; gap: 4px; }
/* The label is the step that produced the frame; long locators clamp to two lines (full text on hover). */
.flow-frame-caption strong { font-size: 12px; font-weight: 600; line-height: 1.3; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; overflow-wrap: anywhere; }
.flow-steps { margin: 0; padding: 0; list-style: none; display: flex; flex-direction: column; gap: 6px; font-size: 13px; }
.flow-step { display: grid; grid-template-columns: 22px auto 1fr auto; column-gap: 8px; row-gap: 2px; align-items: baseline; padding: 6px 8px; border-radius: 8px; min-height: 44px; box-sizing: border-box; }
.flow-step.frame { background: #f6f8fb; }
.flow-step.failed { background: #fdecec; }
.flow-step.skipped { opacity: 0.45; }
.flow-step-number { color: var(--text-muted, #6b6b6b); font-variant-numeric: tabular-nums; }
.flow-step-api { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; color: #444; }
.flow-step-label { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; overflow-wrap: anywhere; }
.flow-step-duration { grid-column: 4; font-size: 11px; color: var(--text-muted, #6b6b6b); font-variant-numeric: tabular-nums; white-space: nowrap; }
.flow-meta { margin: 2px 0 0; font-size: 12px; color: var(--text-muted, #6b6b6b); font-variant-numeric: tabular-nums; }
.flow-step-frame { grid-column: 2 / -1; font-size: 11px; color: #2f6fed; }
.flow-step-error { grid-column: 2 / -1; font-size: 12px; color: #7a1c14; }
-221
View File
@@ -1,221 +0,0 @@
import { useState } from "react";
import type { PublicFlowEvidence, PublicFlowSide, PublicReview } from "../../../../src/contracts/capture";
import { artifactUrl, type Artifact } from "../../utils/model";
import { flowSourceHref } from "../../utils/flow-source";
import { ScreenshotImage } from "../shared/screenshot-image";
import { ToggleGroup } from "../shared/toggle-group";
import "./flows.css";
type Side = "base" | "head";
const SIDE_LABEL: Record<Side, string> = { base: "Before", head: "After" };
/** The step a side stopped at, when it did not pass. */
function stoppedAt(flow: PublicFlowSide): { index: number; step: PublicFlowSide["steps"][number] } | undefined {
if (flow.status === "passed") return undefined;
const index = flow.steps.findIndex(step => step.status !== "passed");
return index < 0 ? undefined : { index, step: flow.steps[index]! };
}
function formatDuration(ms: number): string {
if (!Number.isFinite(ms) || ms < 0) return "";
if (ms < 1000) return `${Math.round(ms)} ms`;
if (ms < 60_000) return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)} s`;
return `${Math.floor(ms / 60_000)}m ${String(Math.round((ms % 60_000) / 1000)).padStart(2, "0")}s`;
}
function sideSummary(entry: PublicFlowEvidence, side: Side): string {
const flow = entry[side];
if (!flow) return "not run";
const stop = stoppedAt(flow);
return stop ? `${flow.status} at step ${stop.index + 1}` : flow.status;
}
function verdictLabel(entry: PublicFlowEvidence["frames"][number], base: PublicFlowSide | undefined, head: PublicFlowSide | undefined): { text: string; tone: string } {
const inBase = Boolean(base?.frames[entry.key]); const inHead = Boolean(head?.frames[entry.key]);
if (inBase && inHead) {
if (!entry.visual) return { text: "Not compared", tone: "muted" };
return entry.visual.verdict === "unchanged" ? { text: "Unchanged", tone: "unchanged" }
: entry.visual.verdict === "modified" ? { text: entry.visual.mismatchPercentage !== undefined ? `Changed · ${entry.visual.mismatchPercentage.toFixed(1)}%` : "Changed", tone: "modified" }
: { text: "Needs review", tone: "needs-review" };
}
if (inHead) return { text: base ? "Not reached before" : "New", tone: "added" };
if (inBase) return { text: head ? "Not reached after" : "Removed", tone: "removed" };
return { text: "Not taken", tone: "muted" };
}
/** The same resolution the Screens grid uses: embedded bytes in a report, the published URL otherwise. */
function frameSrc(entry: PublicFlowEvidence, side: Side, key: string, taken: NonNullable<PublicFlowSide["frames"][string]>): string | undefined {
const artifact: Artifact = { id: `flow:${side}:${entry.id}/${key}`, kind: "screenshot", path: `${side}/flows/${entry.id}/${key}.png`,
publicUrl: taken.url, sha256: taken.sha256, mimeType: "image/png", width: taken.width, height: taken.height, createdAt: taken.capturedAt };
return artifactUrl(artifact);
}
function Frame(props: {
entry: PublicFlowEvidence;
frame: PublicFlowEvidence["frames"][number];
side: Side;
/** Labels of the step frames after this one that left the screen unchanged, folded into this frame. */
same: string[];
onOpen?: (surfaceId: string) => void;
}) {
const { entry, frame, side } = props;
const verdict = verdictLabel(frame, entry.base, entry.head);
const taken = entry[side]?.frames[frame.key];
const flow = entry[side];
const stop = flow && !taken ? stoppedAt(flow) : undefined;
const src = taken ? frameSrc(entry, side, frame.key, taken) : undefined;
return (
<li className={`flow-frame tone-${verdict.tone}`} data-side={side}>
<figure className="flow-frame-face">
{taken && src ? (
<button
type="button"
className="flow-frame-button"
onClick={props.onOpen ? () => props.onOpen!(frame.id) : undefined}
aria-label={`Open ${frame.label} (${SIDE_LABEL[side]}) in Compare`}
>
<ScreenshotImage
className="flow-frame-image"
src={src}
alt={`${entry.title} › ${frame.label}, ${SIDE_LABEL[side]}`}
width={taken.width}
height={taken.height}
/>
</button>
) : (
<div className="flow-frame-missing" role="note">
{!flow
? "Flow not run"
: stop
? (
<>
Not reached
<small>
the flow {flow.status} at step {stop.index + 1}
</small>
</>
)
: "Not taken"}
</div>
)}
</figure>
<div className="flow-frame-caption">
<strong title={frame.label}>{frame.label}</strong>
<span className="flow-frame-tags">
<span className={`flow-verdict tone-${verdict.tone}`}>
{verdict.text}
</span>
{props.same.length ? (
<small className="flow-frame-same" title={`Unchanged after:\n${props.same.join("\n")}`}>+{props.same.length}</small>
) : null}
</span>
</div>
</li>
);
}
/** A step frame whose picture (outside the system bands, when the capture hashed that) equals the previous shown frame's on every side that took both adds nothing: it folds into that frame. Checkpoints always show. */
function visibleFrames(entry: PublicFlowEvidence): { frame: PublicFlowEvidence["frames"][number]; same: string[] }[] {
const sameOnEverySide = (a: string, b: string) => (["head", "base"] as const).every(side => {
const frames = entry[side]?.frames;
if (!frames) return true;
const x = frames[a]; const y = frames[b];
return Boolean(x && y && (x.contentSha256 ?? x.sha256) === (y.contentSha256 ?? y.sha256));
});
const shown: { frame: PublicFlowEvidence["frames"][number]; same: string[] }[] = [];
for (const frame of entry.frames.filter(frame => !frame.colorScheme)) {
const previous = shown.at(-1);
if (previous && /^step-\d+$/.test(frame.key) && sameOnEverySide(previous.frame.key, frame.key)) { previous.same.push(frame.label); continue; }
shown.push({ frame, same: [] });
}
return shown;
}
function FlowCard(props: { entry: PublicFlowEvidence; review: PublicReview; onOpenFrame?: (surfaceId: string) => void }) {
const { entry, review } = props;
const head = entry.head; const base = entry.base;
const [side, setSide] = useState<Side>(head ? "head" : "base");
const shownSide: Side = head && base ? side : head ? "head" : "base";
const headStop = head ? stoppedAt(head) : undefined;
const tone = !head ? "muted" : head.status === "passed" ? "passed" : "failed";
const sourceHref = flowSourceHref(review, entry.file, entry.head?.line ?? entry.base?.line);
return (
<section className={`flow-card tone-${tone}`} aria-labelledby={`flow-${entry.id}`}>
<header className="flow-header">
<div>
<h2 id={`flow-${entry.id}`}>{entry.title}</h2>
<p className="flow-file">{sourceHref ? <a href={sourceHref} target="_blank" rel="noreferrer noopener">{entry.file}</a> : entry.file}</p>
{(head ?? base) ? <p className="flow-meta">{(head ?? base)!.steps.length} steps · {formatDuration((head ?? base)!.steps.reduce((sum, step) => sum + step.durationMs, 0))}</p> : null}
</div>
<div className="flow-header-side">
<div className="flow-outcomes">
<span className="flow-outcome"><span className="flow-outcome-side">After</span><span className={`flow-status tone-${tone}`}>{sideSummary(entry, "head")}</span></span>
<span className="flow-outcome"><span className="flow-outcome-side">Before</span><span className={`flow-status tone-${!base ? "muted" : base.status === "passed" ? "passed" : "failed"}`}>{sideSummary(entry, "base")}</span></span>
</div>
{head && base ? (
<div className="flow-side-toggle">
<ToggleGroup<Side> value={shownSide} onChange={setSide} ariaLabel="Frames shown" variant="flat"
options={[{ id: "head", label: "After" }, { id: "base", label: "Before" }]} />
</div>
) : null}
</div>
</header>
{headStop?.step.error ? (
<p className="flow-failure" role="note">
Stopped at step {headStop.index + 1} — <code>{headStop.step.api} {headStop.step.label}</code>: {headStop.step.error.message}
</p>
) : null}
<div className="flow-body">
<ol className="flow-filmstrip" aria-label={`Frames (${SIDE_LABEL[shownSide]})`}>
{visibleFrames(entry).map(({ frame, same }) => <Frame key={frame.key} entry={entry} frame={frame} side={shownSide} same={same} {...(props.onOpenFrame ? { onOpen: props.onOpenFrame } : {})} />)}
</ol>
<Steps entry={entry} review={review} />
</div>
</section>
);
}
function Steps(props: { entry: PublicFlowEvidence; review: PublicReview }) {
// The steps as head ran them; base's are shown when head did not run at all.
const side: Side = props.entry.head ? "head" : "base";
const flow = props.entry[side];
if (!flow) return null;
const stop = stoppedAt(flow);
return (
<ol className="flow-steps" aria-label={`Steps (${SIDE_LABEL[side]})`}>
{flow.steps.map((step, index) => {
const failed = stop?.index === index;
const after = stop !== undefined && index > stop.index;
return (
<li key={index} className={`flow-step${failed ? " failed" : ""}${after ? " skipped" : ""}${step.frame ? " frame" : ""}`}>
<span className="flow-step-number">{index + 1}</span>
{flowSourceHref(props.review, props.entry.file, step.line) ? (
<a className="flow-step-source" href={flowSourceHref(props.review, props.entry.file, step.line)} target="_blank" rel="noreferrer" title={`${props.entry.file}:${step.line}`}>
<span className="flow-step-api">{step.api}</span> <span className="flow-step-label">{step.label}</span>
</a>
) : <><span className="flow-step-api">{step.api}</span> <span className="flow-step-label">{step.label}</span></>}
<span className="flow-step-duration">{formatDuration(step.durationMs)}</span>
{step.frame ? <span className="flow-step-frame">frame · {step.frame}</span> : null}
{failed && step.error ? <span className="flow-step-error">{step.error.message}</span> : null}
</li>
);
})}
</ol>
);
}
export function FlowsView(props: { review: PublicReview; phone?: boolean; onOpenFrame?: (surfaceId: string) => void }) {
const flows = Array.isArray(props.review.flows) ? props.review.flows : [];
return (
<main className={`flows-page${props.phone ? " phone" : ""}`} aria-label="Flows">
{(["head", "base"] as const).filter(side => props.review.flowsFailure?.[side]).map(side => (
<section key={side} className="flow-card tone-failed flows-not-run" role="alert">
<header className="flow-header"><div><h2>The flows did not run</h2></div><div className="flow-outcomes"><span className="flow-outcome"><span className="flow-outcome-side">{SIDE_LABEL[side]}</span><span className="flow-status tone-failed">{props.review.flowsFailure![side]!.code}</span></span></div></header>
<p className="flow-failure">{props.review.flowsFailure![side]!.message}</p>
</section>
))}
{flows.length === 0 && !props.review.flowsFailure ? <p className="flows-empty">This review ran no flows.</p> : null}
{flows.map(entry => <FlowCard key={entry.id} entry={entry} review={props.review} {...(props.onOpenFrame ? { onOpenFrame: props.onOpenFrame } : {})} />)}
</main>
);
}
+3 -3
View File
@@ -1,6 +1,6 @@
import { useEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent, type ReactNode } from "react";
import { ChevronRight, ChevronsDownUp, ChevronsUpDown, ListTree } from "lucide-react";
import { artifactUrl, isFlowScreen, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
import { artifactUrl, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
import { primaryScreenshotForScreen, screenshotSize, typicalScreenshotSize, type ScreenshotSize } from "../../utils/screen-images";
import { diffClass, type BuildDiff, type DiffStatus } from "../../utils/build-diff";
import { focusStatusOf, isCapturedChange } from "../../utils/changed-screens";
@@ -129,7 +129,7 @@ function ScreenCell(props: {
className="screens-card"
ariaLabel={props.screen.title}
title={props.screen.title}
path={isFlowScreen(props.screen) ? props.screen.state ?? displayPathForScreen(props.screen) : displayPathForScreen(props.screen)}
path={displayPathForScreen(props.screen)}
{...(props.index.plainTitles ? { plainTitle: true } : {})}
{...(url ? { screenshot: url } : {})}
{...(size ? size : {})}
@@ -188,7 +188,7 @@ function TreeRows(props: {
if (!screen) return null;
const dot = dotClass(props.diff, props.elsewhere, screen.id);
const launch = isLaunchScreen(screen);
const label = launch ? "Cold start" : isFlowScreen(screen) ? screen.state ?? screenLabel(screen, props.index) : screenLabel(screen, props.index);
const label = launch ? "Cold start" : screenLabel(screen, props.index);
return (
<li key={node.screenId} className={key ? "screens-tree-parent" : undefined}>
<button type="button" style={style}
+1 -83
View File
@@ -1,4 +1,4 @@
import { flowSurfaceId, type CapturedImage, type PublicLaunchEvidence, type PublicReview } from "../../../src/contracts/capture";
import type { CapturedImage, PublicLaunchEvidence, PublicReview } from "../../../src/contracts/capture";
import type {
Artifact,
BuildComparisonEntry,
@@ -7,7 +7,6 @@ import type {
Coverage,
ExploreMap,
RunTarget,
Transition,
} from "../../../src/types";
import {
captureNotes,
@@ -411,58 +410,6 @@ function sidePayload(review: PublicReview, side: Side): { map: ExploreMap; cover
: "No splash screen was observed in screenshots; a launch recording (ffmpeg on the runner) is needed to see short splashes. Shown is the first settled frame.", createdAt: review.createdAt });
}
}
// The app's flows sit outside the route graph too: each frame a flow took is a screen, and the flow is a journey
// through them in step order. A side that failed before a frame has a gap there naming the step that failed.
for (const entry of Array.isArray(review.flows) ? review.flows : []) {
const flow = entry[side];
const screenIds: string[] = [];
for (const frame of entry.frames) {
const taken = flow?.frames[frame.key];
if (!taken) {
if (flow) {
const failed = flow.steps.find(step => step.status !== "passed");
map.gaps.push({ id: `flow:${side}:${frame.id}`, screenId: frame.id, kind: "coverage", status: "open",
message: failed ? `Not reached: the flow ${flow.status} at step ${flow.steps.indexOf(failed) + 1} (${failed.api} ${failed.label})${failed.error ? `: ${failed.error.message}` : ""}`
: `Not taken: the flow ${flow.status} without this frame`, createdAt: review.createdAt });
}
continue;
}
const artifact: Artifact = { id: `image:${side}:${frame.id}`, kind: "screenshot", path: `${side}/${frame.id.replace(/[:/]/g, "-")}.png`,
publicUrl: taken.url, sha256: taken.sha256, mimeType: "image/png", width: taken.width, height: taken.height, createdAt: taken.capturedAt };
map.artifacts.push(artifact);
map.screens.push({
id: frame.id, title: `${entry.title} › ${frame.label}`, route: `flow:${entry.id}`, state: frame.label,
start: false, terminal: false, depth: screenIds.length, firstSeenAt: taken.capturedAt, lastSeenAt: taken.capturedAt, visits: 1,
variantIds: [variantId(frame.id)], observationIds: [observationId(side, frame.id)], elementIds: [],
});
map.variants.push({ id: variantId(frame.id), screenId: frame.id, key: frame.key, name: frame.label, firstSeenAt: taken.capturedAt, lastSeenAt: taken.capturedAt, observationIds: [observationId(side, frame.id)] });
map.observations.push({
id: observationId(side, frame.id), screenId: frame.id, variantId: variantId(frame.id),
fingerprints: { combined: taken.sha256 }, capturedAt: taken.capturedAt, surfaceScope: "app",
elementIds: [], elements: [], screenshotArtifactId: artifact.id,
});
screenIds.push(frame.id);
}
// The Map draws the flow as a chain: one edge per pair of consecutive frames, labelled with the step that led on.
const transitionIds: string[] = [];
if (flow) {
const kindOf = (api: string): Transition["actionKind"] => api.endsWith(".tap") || api.endsWith(".press") ? "press" : api.endsWith(".fill") || api.endsWith(".type") ? "fill"
: api.endsWith(".swipe") || api.endsWith(".scroll") ? "swipe" : api === "device.openLink" || api === "app.open" ? "deep-link" : "other";
const frameSteps = flow.steps.map((step, index) => ({ step, index })).filter(({ step }) => step.frame && screenIds.includes(flowSurfaceId(entry.id, step.frame)));
for (let i = 1; i < frameSteps.length; i += 1) {
const from = frameSteps[i - 1]!; const to = frameSteps[i]!;
const between = flow.steps.slice(from.index + 1, to.index).filter(step => !step.api.startsWith("expect.") && step.api !== "app.screenshot");
const action = between.find(step => kindOf(step.api) !== "other") ?? between[0];
const fromId = flowSurfaceId(entry.id, from.step.frame!); const toId = flowSurfaceId(entry.id, to.step.frame!);
const at = flow.frames[to.step.frame!]!.capturedAt;
const id = `flow:${side}:${toId}`;
map.transitions.push({ id, fromScreenId: fromId, toScreenId: toId, actionKind: action ? kindOf(action.api) : "other",
...(action ? { selector: action.label } : {}), firstObservedAt: at, lastObservedAt: at, attemptIds: [] });
transitionIds.push(id);
}
}
if (screenIds.length) map.journeys.push({ id: `flow:${entry.id}`, title: entry.title, screenIds, transitionIds, attemptIds: [] });
}
const openGaps = map.gaps.filter((gap) => gap.status === "open");
if (openGaps.length > 0) map.run.status = "partial";
return {
@@ -696,35 +643,6 @@ export function publicReviewProjection(review: PublicReview): ViewerReviewProjec
reviewerChanges: [], runtimeEvidenceRefs: [ref], noVisibleChange: entry.visual?.verdict === "unchanged" };
evidence[ref] = {};
}
for (const entry of Array.isArray(review.flows) ? review.flows : []) {
for (const frame of entry.frames) {
const ref = `public:${frame.id}`;
const visual = frame.visual && frame.visual.verdict !== "unchanged"
? visualDiff({
...(frame.visual.mismatchPercentage !== undefined ? { mismatchPercentage: frame.visual.mismatchPercentage } : {}),
...(frame.visual.ignoredStatusBarRegions ? { ignoredStatusBarRegions: frame.visual.ignoredStatusBarRegions } : {}),
...(frame.visual.ignoredHomeIndicatorRegions ? { ignoredHomeIndicatorRegions: frame.visual.ignoredHomeIndicatorRegions } : {}),
regions: (frame.visual.regions ?? []).map((region) => ({ ...region.normalizedRect, share: region.shareOfDiffPercentage })),
})
: undefined;
const missing = (side: Side) => {
const flow = entry[side];
if (!flow || flow.frames[frame.key]) return undefined;
const failed = flow.steps.find(step => step.status !== "passed");
return failed ? `Not reached: the flow ${flow.status} at step ${flow.steps.indexOf(failed) + 1} (${failed.api} ${failed.label}).` : `Not taken: the flow ${flow.status} without this frame.`;
};
const notes = captureNotes({ before: missing("base"), after: missing("head") });
const status = (side: Side) => {
const flow = entry[side];
if (!flow) return `not run on ${side}`;
const failed = flow.status === "passed" ? undefined : flow.steps.find(step => step.status !== "passed");
return `${flow.status} on ${side}${failed ? ` at step ${flow.steps.indexOf(failed) + 1} (${failed.api} ${failed.label})` : ""}`;
};
surfaces[frame.id] = { note: `Flow ${entry.title}: ${status("head")}${entry.base ? `, ${status("base")}` : ""}`, ...(visual ? { visual } : {}), ...(notes ? { captureNotes: notes } : {}),
reviewerChanges: [], runtimeEvidenceRefs: [ref], noVisibleChange: frame.visual?.verdict === "unchanged" };
evidence[ref] = {};
}
}
return {
pullRequest: {
...(review.pullRequest.origin === "local" || review.pullRequest.origin === "compare" ? { origin: review.pullRequest.origin } : {}),
-20
View File
@@ -2406,23 +2406,3 @@ html [data-sonner-toaster][data-sonner-theme] {
text-align: center;
opacity: 0.75;
}
/* A flow frame's flow in the inspector: the steps around the frame, each a link to its e2e line when the review names the repository. */
.flow-section-title { margin: 0 0 2px; font-weight: 600; font-size: 13px; }
.flow-section-file { margin: 0 0 8px; font-size: 12px; color: var(--muted, #6b6b6b); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
.flow-section-file a { color: inherit; }
.flow-section-outcomes { display: flex; gap: 16px; margin: 0 0 8px; font-size: 12px; }
.flow-section-outcomes div { display: flex; gap: 6px; }
.flow-section-outcomes dt { color: var(--muted, #6b6b6b); text-transform: uppercase; font-size: 10px; letter-spacing: 0.04em; align-self: center; }
.flow-section-outcomes dd { margin: 0; font-weight: 600; }
.flow-section-step { margin: 0 0 6px; font-size: 12px; color: var(--muted, #6b6b6b); }
.flow-section-steps { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; font-size: 12px; }
.flow-section-step-row { display: grid; grid-template-columns: 20px 1fr; gap: 4px 8px; padding: 4px 6px; border-radius: 6px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
.flow-section-step-row.current { background: var(--accent-soft, #eef2ff); }
.flow-section-step-row.failed { background: #fdecec; color: #7a1c14; }
.flow-section-step-row a { color: inherit; text-decoration: none; }
.flow-section-step-row a:hover { text-decoration: underline; }
.flow-section-step-number { color: var(--muted, #6b6b6b); text-align: right; }
.flow-section-step-api { color: var(--muted, #6b6b6b); }
.flow-section-step-frame { grid-column: 2; justify-self: start; background: none; border: 0; padding: 0; min-height: 24px; color: #2f5fd0; font: inherit; cursor: pointer; }
.flow-section-step-error { grid-column: 2; }
+1 -1
View File
@@ -1,7 +1,7 @@
import type { CanvasView } from "./navigation";
/** Matches the left-to-right order of the persistent canvas toolbar. */
export const CANVAS_VIEW_ORDER = ["flows", "map", "screens", "compare"] as const satisfies readonly CanvasView[];
export const CANVAS_VIEW_ORDER = ["map", "screens", "compare"] as const satisfies readonly CanvasView[];
export type CanvasViewTransitionDirection = "forward" | "backward";
-17
View File
@@ -1,17 +0,0 @@
import type { PublicFlowEvidence, PublicReview } from "../../../src/contracts/capture";
/** The flow a flow-frame screen belongs to, and the frame's key, from `flow:<flowId>/<key>` (with any side prefix). */
export function flowOfScreen(review: PublicReview | undefined, screenId: string): { flow: PublicFlowEvidence; key: string } | undefined {
const match = /flow:([a-z0-9-]+\/[a-z0-9-]+)\/([a-z0-9-]+(?:@[a-z]+)?)$/.exec(screenId);
if (!match || !Array.isArray(review?.flows)) return undefined;
const flow = review.flows.find(entry => entry.id === match[1]);
return flow ? { flow, key: match[2]! } : undefined;
}
/** The e2e file at the head commit on GitHub, at a line when known; undefined when the review names no GitHub repository. */
export function flowSourceHref(review: Pick<PublicReview, "pullRequest"> | undefined, file: string, line?: number): string | undefined {
const presentation = review?.pullRequest as { repository?: string; head?: { sha?: string } } | undefined;
const repository = presentation?.repository; const sha = presentation?.head?.sha;
if (!repository || !/^[\w.-]+\/[\w.-]+$/.test(repository) || !sha || !/^[0-9a-f]{40}$/i.test(sha)) return undefined;
return `https://github.com/${repository}/blob/${sha}/${file.split("/").map(encodeURIComponent).join("/")}${line ? `#L${line}` : ""}`;
}
-5
View File
@@ -136,11 +136,6 @@ export function isLaunchScreen(screen: Pick<Screen, "id">): boolean {
return screen.id === LAUNCH_SURFACE_ID || screen.id.startsWith(`${LAUNCH_SURFACE_ID}@`);
}
/** A frame an e2e flow took (`flow:<flow id>/<key>`): shown with the screens, grouped by flow, outside the route graph. */
export function isFlowScreen(screen: Pick<Screen, "id">): boolean {
return /^(?:(?:removed|baseline-context):.+?:screen:)?flow:/.test(screen.id);
}
/** The order of the Screens canvas and list: the launch first, then by depth, then by title. */
export function screensInListOrder<T extends Pick<Screen, "id" | "depth" | "title">>(screens: readonly T[]): T[] {
return [...screens].sort(
+4 -8
View File
@@ -3,7 +3,7 @@
// and the URL is that route written out, Figma-style: a path for the place and a query for the
// selection. This module is DOM-free on purpose so the grammar can be tested in plain node.
/** Map and Screens are canvases; Compare is the Before/After review of one changed screen. */
export type CanvasView = "map" | "screens" | "compare" | "flows";
export type CanvasView = "map" | "screens" | "compare";
export type ThemePreference = "light" | "dark" | "system";
export type MapDirection = "TB" | "LR";
/** The explicitly selected amount of Map hierarchy, independent from camera zoom. */
@@ -81,7 +81,7 @@ export type FocusRequest = {
preserveMapContent?: boolean;
};
const CANVASES: CanvasView[] = ["map", "screens", "compare", "flows"];
const CANVASES: CanvasView[] = ["map", "screens", "compare"];
const INSPECTS: InspectView[] = ["session", "diff"];
const DIRECTIONS: TransitionDirection[] = ["in", "out"];
const FOCUSES: FocusStatus[] = ["added", "modified", "accessibility-only", "removed", "needs-review", "source-affected"];
@@ -162,15 +162,13 @@ function routeFitsPath(route: string | undefined): route is string {
return route !== undefined && route !== "/";
}
/** `#workspace/<canvas>` and the bare `#screens` predate path routing and are still linked; an unknown canvas lands on the map. */
/** `#workspace/<canvas>` and the bare `#screens` predate path routing and are still linked; a retired canvas (flows) lands on the map. */
function parseLegacyHash(hash: string): CanvasView | undefined {
const [first, second] = hash.replace(/^#/, "").split("/");
if (first === "screens" && !second) return "screens";
// "workspace" was the original name of the Changes panel, which once named the hash's panel.
if (first !== "workspace" && first !== "changes") return undefined;
// The hash era had a "flows" canvas that was retired; those links land on the map.
if (second === "graph" || second === "flows") return "map";
return isCanvas(second) ? second : "map";
return second === "graph" ? "map" : isCanvas(second) ? second : "map";
}
/** Settles the states the URL cannot express together, and drops what the context does not know. */
@@ -317,7 +315,6 @@ export const CANVAS_LABELS: Record<CanvasView, string> = {
map: "Map",
screens: "Screens",
compare: "Compare",
flows: "Flows",
};
/** One line each, shown under the canvas name on hover, so the views are easy to tell apart. */
@@ -325,7 +322,6 @@ export const CANVAS_DESCRIPTIONS: Record<CanvasView, string> = {
map: "How screens connect",
screens: "Every screen in one grid",
compare: "Before and After of each changed screen",
flows: "Each e2e flow: its steps and the frames it took, Before and After",
};
export const FOCUS_LABELS: Record<FocusStatus, string> = {
-2
View File
@@ -26,8 +26,6 @@ export function screenLabel(screen: Pick<Screen, "route" | "title">, index: Pick
export function displayPathForScreen(screen: Pick<Screen, "route" | "title">): string {
const route = screen.route?.trim();
// A flow frame has no path: its route names the flow, and its title (`<flow> › <frame>`) is what to show.
if (route?.startsWith("flow:")) return screen.title;
if (route && !MOBBIN_CAPTURE_ROUTE.test(route)) {
return route.startsWith("/") ? route : `/${route}`;
}
+3 -4
View File
@@ -1,5 +1,5 @@
import { sourceScreenId } from "./build-diff";
import { cleanControlLabel, isFlowScreen, isLaunchScreen, screensInListOrder, transitionLabel, type MapIndex, type Screen, type Transition } from "./model";
import { cleanControlLabel, isLaunchScreen, screensInListOrder, transitionLabel, type MapIndex, type Screen, type Transition } from "./model";
/** One row of the Screens tree: a screen, or a folder of route files (source mode only). */
export type ScreenTreeNode =
@@ -64,13 +64,12 @@ function routeFileOf(routeFiles: ReadonlyMap<string, string>, id: string): strin
return routeFiles.get(id) ?? routeFiles.get(sourceScreenId(id));
}
// Flow frames are not screens of the app: the Flows view shows them, the Map draws their chain; the Screens tree leaves them out.
function sourceTree(screens: Screen[], routeFiles: ReadonlyMap<string, string>): ScreenTree {
const launch = screens.filter(isLaunchScreen);
const byFolder = new Map<string, string[]>();
const other: string[] = [];
for (const screen of screens) {
if (isLaunchScreen(screen) || isFlowScreen(screen)) continue;
if (isLaunchScreen(screen)) continue;
const file = routeFileOf(routeFiles, screen.id);
if (!file) { other.push(screen.id); continue; }
const folder = routeFolder(file);
@@ -127,7 +126,7 @@ function viaLabel(transition: Transition, index: MapIndex): string | undefined {
function observedTree(screens: Screen[], index: MapIndex): ScreenTree {
const launch = screens.filter(isLaunchScreen);
const routes = screens.filter(screen => !isLaunchScreen(screen) && !isFlowScreen(screen));
const routes = screens.filter(screen => !isLaunchScreen(screen));
const order = new Map(routes.map((screen, position) => [screen.id, position]));
// A tab is a screen the explorer reached by pressing a tab-bar control.
const tabs = new Set<string>();
-2
View File
@@ -79,14 +79,12 @@ export const SHORTCUTS = {
map: plain("KeyM", "M"),
screens: plain("KeyS", "S"),
compare: plain("KeyC", "C"),
flows: plain("KeyF", "F"),
},
/** The canvases by their place in the toolbar, as tabs are numbered elsewhere. Apple keyboards only (CANVAS_NUMBER_KEYS). */
canvasByNumber: {
map: ctrl("Digit1", "1"),
screens: ctrl("Digit2", "2"),
compare: ctrl("Digit3", "3"),
flows: ctrl("Digit4", "4"),
},
/** Compare only. The arrows walk changed screens; J and K walk the changed areas of one. */
compare: {