Skip to content

Commit 711b7ea

Browse files
mikepitreclaude
andcommitted
docs(expo): say that CI runs the verify-clerk-expo device specs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent f8d9dcf commit 711b7ea

3 files changed

Lines changed: 6 additions & 3 deletions

File tree

‎.claude/skills/verify-clerk-expo/SKILL.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ No change to `@clerk/expo` UI or auth behavior is done until a `run` on the real
1111

1212
Run every command from the repo root. In the prose below, `doctor`, `up`, `run`, `screen`, `attach`, and `down` are verbs of that CLI. Paths that begin `specs/`, `features/`, `references/`, `src/`, `test/`, or `.verify/` are inside `.claude/skills/verify-clerk-expo/`. Every verb but `attach` takes `--platform ios|android`, and iOS is the default. Every verb takes `--json` and then prints one `{ "ok": ... }` object. Exit codes are 0 for success, 1 for a failing spec, 2 for a usage error, and 3 for a failed precondition. Every error prints a `fix` line.
1313

14-
CI runs none of these specs. The `Verify Skill Tests` job in `.github/workflows/ci.yml` runs the skill's unit tests and `tsc`. The device tests that gate a pull request are `integration/tests/expo-native/*.e2e.ts`, which `.github/workflows/expo-native-build.yml` runs against a Release build of the same fixture with the same `e2e` engine. This skill is the development loop, and a regression test that must run on every pull request belongs in `integration/tests/expo-native/`.
14+
CI runs the golden specs, the `form-entry` ones included, and leaves out only a spec tagged `known-bug`, as `run --all` does. The `Verify device specs` workflow, `.github/workflows/verify-device-specs.yml`, has one job for iOS and one for Android, and each job has its own device and its own Clerk application. It starts on a pull request to `main` that changes the skill's code, the fixture, or one of the three packages the fixture links, and it can be started by hand. It skips with a notice on a pull request from a fork, which has no access to the repository secret. The `Verify Skill Tests` job in `.github/workflows/ci.yml` runs the skill's unit tests and `tsc`. The device tests that gate a pull request are `integration/tests/expo-native/*.e2e.ts`, which `.github/workflows/expo-native-build.yml` runs against a Release build of the same fixture with the same `e2e` engine. This skill is the development loop, and a regression test that must gate every pull request belongs in `integration/tests/expo-native/`.
1515

1616
The fixture links `@clerk/expo`, `@clerk/expo-biometrics`, and `@clerk/expo-google-signin` from the workspace. It does not install `@clerk/expo-passkeys`, so the skill cannot verify passkeys.
1717

@@ -85,7 +85,7 @@ The `backend` line says which backend the CLI chose and why. This transcript is
8585

8686
A remote session has no Metro and no watch build. A worktree's iOS session and its Android session share the worktree's application, so run their specs one after the other too. After an edit to the app or to a package, commit, push, and `run` again, and the same session builds the new commit and installs it. Specs run from your working tree, so an edit to a spec needs no commit. The session is billed by the minute. It stops itself after 15 minutes without a call from the CLI and always after 60, and `down` stops it at once, so run `down` as soon as you are done. After a change under `src/`, commit, push, `down`, then `up`. [Remote devices](references/remote.md) has what the machine needs, the runner labels, the limits, what the session builds, and what the runner and the tunnel can see.
8787

88-
The fixture is built locally on macOS only. On a Linux machine that can run the emulator, the CLI picks the local backend for Android, and the build then fails with `UNSUPPORTED` and the fix `rerun with --backend remote`.
88+
On a Linux machine that can run the emulator, the CLI picks the local backend for Android and builds the fixture on that machine, as the `Verify device specs` workflow does on its Linux runner.
8989

9090
## Doctor
9191

@@ -251,6 +251,7 @@ For a remote device, `down` ends the runner job and waits for it to finish, and
251251
- `npm test --prefix .claude/skills/verify-clerk-expo` runs the CLI's unit tests, with no network, key, or device. `npm run typecheck --prefix .claude/skills/verify-clerk-expo` runs `tsc`. The `Verify Skill Tests` job in `.github/workflows/ci.yml` runs both on Linux when a pull request changes the skill, the fixture, or a package the fixture links.
252252
- `src/core/`, `src/platform/ios/`, `src/platform/android/`, `specs/fixtures.ts`, `testing/`, and every test but `test/host.test.ts`, `test/remote-host.test.ts`, and `test/freshness.test.ts` are shared with the clerk-ios and clerk-android verification skills. Change them there first, then copy them here, and never edit them here. `doctor`'s `core-drift` check fails when a file under `src/core/` differs from `src/core/MANIFEST`. Do not rewrite the manifest here to make it pass.
253253
- `src/host.ts`, `src/fixture.ts`, and `src/freshness.ts` are this repository's own: the screens, the build of the fixture, the Metro ports, and the check that Metro serves current JS. `specs/native.ts` holds the per-platform locators for the native views.
254+
- `.github/workflows/verify-device-specs.yml` runs `up --backend local`, `run --all`, and `down` on a runner for each platform, so the device is on the runner itself and no remote session starts. It sets `VERIFY_LOCAL_BUILD=standalone`, which makes a local lease build the Release app with the JS embedded and start no Metro. The Platform API key comes from the `MOBILE_VERIFICATION_PLATFORM_API_KEY` repository secret, and the repository variables `VERIFY_CI_RUNNER_IOS` and `VERIFY_CI_RUNNER_ANDROID` name other runner labels. It uploads each run's `run.json`, video, screenshots, and `e2e` summary and failure pages for three days, and only when the run is sealed with no secret found in it.
254255
- `src/platform/session-device.ts` holds the steps that a remote session runs on its device, `.github/workflows/verify-remote.yml` is the workflow that the session runs in, and `src/core/remote/` is the code on both ends of it. The runner installs this skill with `npm ci` and uses the same `node_modules/.bin/agent-device` as a Mac does.
255256
- To call `agent-device` yourself, use `node_modules/.bin/agent-device` in the skill directory with `AGENT_DEVICE_STATE_DIR=.claude/skills/verify-clerk-expo/.verify/agent-device`. Each worktree runs its own daemon from there, and `down` stops it. Never print `.verify/agent-device/daemon.json`, because it holds the daemon's auth token.
256257
- `features/` is the feature map. Start with `features/README.md`, and update a feature file in the same PR as a change to the behavior it maps.

‎.claude/skills/verify-clerk-expo/features/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# @clerk/expo verification map
22

3-
This directory is the maintained source for verifying the user-facing behavior of `@clerk/expo` through the `expo-native` fixture app in `integration/templates/expo-native`. On a local device the fixture runs as a Debug dev client that loads its JS, and `packages/expo` with it, from a local Metro server. On a remote device it runs as a standalone Release build of a pushed commit, with the JS embedded. Read this index before driving the app, then use the matching feature file as the recipe. Every recipe runs through `.claude/skills/verify-clerk-expo/bin/control-clerk-expo` and the golden specs under `specs/golden/<feature>/`.
3+
This directory is the maintained source for verifying the user-facing behavior of `@clerk/expo` through the `expo-native` fixture app in `integration/templates/expo-native`. On a local device the fixture runs as a Debug dev client that loads its JS, and `packages/expo` with it, from a local Metro server. On a remote device it runs as a standalone Release build of a pushed commit, with the JS embedded. `VERIFY_LOCAL_BUILD=standalone` gives a local device that standalone build too, which is how CI runs the specs. Read this index before driving the app, then use the matching feature file as the recipe. Every recipe runs through `.claude/skills/verify-clerk-expo/bin/control-clerk-expo` and the golden specs under `specs/golden/<feature>/`.
44

55
## Baseline preconditions
66

‎.claude/skills/verify-clerk-expo/references/freshness.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ The check dates a Metro revision it has not seen before by the second it was bui
3737

3838
A remote lease runs a standalone Release build with the JS embedded, so there is no watch build, no Metro, and none of the three checks. Its build key also covers the JS inputs, and a JS edit reaches the app by commit, push, `run`. See [remote.md](remote.md).
3939

40+
`VERIFY_LOCAL_BUILD=standalone` makes a local lease build that same standalone app in the working tree. `up` and `run` then start no watch build and no Metro, and the build key covers the JS inputs. Every JS edit then changes the key, so the next `up` or `run` generates the native project again and rebuilds the app, and that build stops this worktree's Metro and watch build if a dev client left them running. The `Verify device specs` workflow sets it, so its runners build the same kind of app as a remote session and serve no JS. Unset, or set to `dev-client`, a local lease gets the dev client.
41+
4042
## Troubleshooting
4143

4244
- A machine behind an HTTPS debugging proxy such as Proxyman needs the proxy's CA trusted by `Clerk Verify Template iOS` before lanes are cloned from it. `doctor` reports it as `proxy-trust` and prints the fix.

0 commit comments

Comments
 (0)