test(mobile): run the generated apps on a simulator and an emulator

.github/workflows/README.mdmodified+57-9

Changes to .github/workflows/README.md

		@@ -1,13 +1,61 @@
1	1	# GitHub Actions
2	2
3		-This folder contains the following GitHub Actions:
	3	+| Workflow | What it proves |
	4	+|---|---|
	5	+| [CI](./ci.yml) | Lint, typecheck, the Zig and TypeScript suites, and that the generated iOS, Watch, Live Activity and Android projects still **compile** |
	6	+| [Mobile E2E Testing](./mobile-e2e.yml) | That a generated app **runs**: a call from JavaScript reaches native code and comes back, on a real simulator and a real emulator |
	7	+| [Native Package Lifecycle](./native-lifecycle.yml) | Install, update, rollback and uninstall of the packaged app on macOS, Linux and Windows |
	8	+| [Benchmark](./benchmarks.yml) | Startup and runtime numbers, tracked over time |
	9	+| [Binary Size](./binary-size.yml) | The shipped binary has not grown unexpectedly |
	10	+| [SBOM](./sbom.yml) | A software bill of materials for each build |
	11	+| [Release](./release.yml) | Tagging, changelog, pantry publish and npm publish |
4	12
5		-- [CI][CI] - all CI jobs for the project
6		- - lints the code
7		- - `typecheck`s the code
8		- - runs test suite
9		- - runs on `ubuntu-latest`
10		-- [Release][Release] - automates the release process & changelog generation
	13	+## Running the mobile E2E locally
11	14
12		-[CI]: ./workflows/ci.yml
13		-[Release]: ./workflows/release.yml
	15	+The harness generates an app, drops a self-driving page into its web assets,
	16	+builds it, installs it on a device and reads the page's report back off the
	17	+console. It asserts a required list of cases per platform — at least one
	18	+success path and one rejection path — and nothing in it skips: a missing
	19	+toolchain or an app that printed nothing is a failure with a named cause.
	20	+
	21	+iOS needs Xcode, `xcodegen` (`brew install xcodegen`), and the Zig archives,
	22	+because the suite runs twice — once with the Zig runtime linked and once
	23	+without. `build-ios-all` rather than `build-ios-simulator`: the generated
	24	+project links a device slice too, and project generation refuses a runtime
	25	+directory that has none.
	26	+
	27	+```bash
	28	+cd packages/zig && zig build build-ios-all -Doptimize=ReleaseSafe && cd -
	29	+bun run test:mobile-e2e:ios
	30	+```
	31	+
	32	+```
	33	+ok ios-shim — 4/4 cases, no zig
	34	+ok ios-runtime — 4/4 cases, zig served clipboardRead, clipboardWrite, getCurrentPosition, getDeviceInfo, log
	35	+```
	36	+
	37	+Android needs JDK 17, Gradle 8.11.1, an Android SDK with `platforms;android-36`
	38	+and `build-tools;36.0.0`, a booted emulator or attached device, and the Zig
	39	+Android libraries — it runs twice as well, once with `libcraft.so` packaged
	40	+into the APK and once without:
	41	+
	42	+The Zig Android library links bionic, so building it needs the NDK —
	43	+`sdkmanager --install "ndk;26.1.10909125"`. Without it `build-android` refuses
	44	+rather than producing a library that installs and then fails to load.
	45	+
	46	+```bash
	47	+cd packages/zig && zig build build-android-all -Doptimize=ReleaseSafe -Dandroid-ndk="$ANDROID_NDK_HOME" && cd -
	48	+bun run test:mobile-e2e:android
	49	+```
	50	+
	51	+```
	52	+ok android-shim — 4/4 cases, no zig
	53	+ok android-runtime — 4/4 cases, zig served registered:59
	54	+```
	55	+
	56	+Both write everything they saw — console logs, build logs, a screenshot, the
	57	+exact page that ran and a `report.json` — to
	58	+`artifacts/mobile-e2e/<label>/`, which is what CI uploads.
	59	+
	60	+The cases themselves are in [`scripts/mobile-e2e/driver.html`](../../scripts/mobile-e2e/driver.html);
	61	+which of them are mandatory is in [`scripts/mobile-e2e/protocol.ts`](../../scripts/mobile-e2e/protocol.ts).