Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

ci(android): run the canary on real phones, not only on SwiftShader

yhh5687035c252c
diff --git a/.github/workflows/android-canary-apk.yml b/.github/workflows/android-canary-apk.yml
new file mode 100644
index 000000000..6e5d78be3
--- /dev/null
+++ b/.github/workflows/android-canary-apk.yml
@@ -0,0 +1,189 @@
+name: Package the canary example(s)
+
+# ONE packaged APK, for whoever wants to run it somewhere.
+#
+# Extracted from android-compat.yml when a second consumer appeared: the device
+# farm run (android-device.yml) installs the same binary on real hardware that
+# the emulator matrix installs on emulators. Two copies of a 35-minute build
+# recipe would drift, and the first symptom would be an emulator row and a device
+# row disagreeing for a reason that is not the device.
+#
+# It stays a job rather than a script because most of it IS workflow: caching the
+# Dawn build, choosing a template source from what the PR touched, and the NDK.
+
+on:
+ workflow_call:
+ inputs:
+ examples:
+ description: 'Comma-separated example names to package.'
+ required: false
+ default: 'space-shooter'
+ type: string
+ template-source:
+ description: 'Which runtime template to wrap: release, head, or auto (decide from what the PR touches).'
+ required: false
+ default: auto
+ type: string
+ outputs:
+ template-from:
+ description: 'Which template the APKs were wrapped in — "release" or "head".'
+ value: ${{ jobs.apk.outputs.template-from }}
+
+permissions:
+ contents: read
+
+jobs:
+ apk:
+ name: Package the canary example(s)
+ runs-on: ubuntu-latest
+ timeout-minutes: 120
+ permissions:
+ contents: read
+ pull-requests: read # to see which files the PR touches
+ outputs:
+ # Reported alongside the numbers: "the shipped binary" and "a build of this
+ # branch" are different claims, and a table that does not say which it made
+ # is a table nobody can act on.
+ template-from: ${{ steps.src.outputs.from }}
+ steps:
+ # Submodules only matter to a from-source build; the released template
+ # carries its libraries already. Fetched unconditionally because a
+ # conditional checkout is a second way for the two paths to diverge.
+ - uses: actions/checkout@v7
+ with:
+ submodules: recursive
+
+ - uses: ./.github/actions/setup
+
+ # The SDK bundle is compiled INTO the host binary, so a template built here
+ # needs it — and the export bundles the game against it either way.
+ - name: Build SDK
+ run: pnpm --filter ./sdk build
+
+ # Building the host takes ~35 minutes (Dawn, once per ABI) and produces
+ # something byte-for-byte irrelevant unless the host source actually changed.
+ # A released template was already built, on a machine that did nothing else,
+ # and it has the stronger claim besides: it is the binary users installed, so
+ # a crash reproduced against it is THE crash rather than a rebuild of it.
+ #
+ # So: from source only when this PR touches the host, and from the release
+ # otherwise. Getting this backwards is silent — a native fix "verified"
+ # against a template that predates it — hence the decision is logged.
+ - name: Decide where the template comes from
+ id: src
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ set -euo pipefail
+ WANT='${{ inputs.template-source }}'
+ if [ -z "$WANT" ] || [ "$WANT" = 'auto' ]; then
+ if [ "$GITHUB_EVENT_NAME" = 'pull_request' ]; then
+ CHANGED=$(gh pr diff '${{ github.event.pull_request.number }}' --name-only)
+ # build-tools/ counts: the API level the host compiles against is a
+ # DEFAULT in build-tools, not a value in native/. The change that fixed
+ # the Android 10 crash touched nothing under native/, so a rule that
+ # watched only native/ would have tested the old released binary and
+ # reported the fix as not working.
+ if echo "$CHANGED" | grep -qE '^(native/|build-tools/|toolchain\.manifest\.json)'; then
+ WANT=head
+ echo "this PR touches the native host — the template must be built from it"
+ else
+ WANT=release
+ echo "this PR touches no native host source — using the released template"
+ fi
+ else
+ WANT=release
+ fi
+ fi
+ echo "from=$WANT" >> "$GITHUB_OUTPUT"
+
+ - name: Take the template from the latest release
+ if: steps.src.outputs.from == 'release'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ set -euo pipefail
+ TAG=$(gh release view --repo "$GITHUB_REPOSITORY" --json tagName -q .tagName)
+ echo "template from $TAG"
+ mkdir -p artifacts
+ gh release download "$TAG" --repo "$GITHUB_REPOSITORY" \
+ -p 'estella-native-android-*.zip' -D artifacts
+
+ - name: Read the native dependency pins
+ if: steps.src.outputs.from == 'head'
+ id: pins
+ run: |
+ node -e "const p=require('./toolchain.manifest.json').native;\
+ console.log('dawn='+p.dawn.commit);console.log('quickjs='+p.quickjs.commit)" >> "$GITHUB_OUTPUT"
+
+ # restore-keys without the pins, because a Dawn build for a DIFFERENT pin is
+ # still most of this one's object files. Note the release pipeline's own cache
+ # is written from a tag ref and is therefore unreachable from any branch —
+ # see the PR discussion; warming this from master is separate work.
+ - name: Cache the pinned checkouts + Dawn builds
+ if: steps.src.outputs.from == 'head'
+ uses: actions/cache@v4
+ with:
+ path: build/native-deps
+ key: native-deps-android-${{ steps.pins.outputs.dawn }}-${{ steps.pins.outputs.quickjs }}
+ restore-keys: native-deps-android-
+
+ - name: Set up the Android NDK
+ if: steps.src.outputs.from == 'head'
+ uses: nttld/setup-ndk@v1
+ id: ndk
+ with:
+ ndk-version: r28
+
+ - name: Fetch Dawn + QuickJS at their pinned commits
+ if: steps.src.outputs.from == 'head'
+ run: node build-tools/cli.js native --fetch-deps
+
+ # BOTH ABIs, even though every emulator here is x86_64: ANDROID_ABIS names
+ # arm64-v8a and x86_64 as what a template must carry, and the emitter refuses
+ # an incomplete one. An x86_64-only build fails at the emit step, not at the
+ # compile — which is exactly how this was found.
+ - name: Build the Android runtime template from this branch
+ if: steps.src.outputs.from == 'head'
+ env:
+ ANDROID_NDK_HOME: ${{ steps.ndk.outputs.ndk-path }}
+ run: |
+ node build-tools/cli.js native --abi arm64-v8a
+ node build-tools/cli.js native --abi x86_64 --template-out artifacts
+
+ - name: Unpack the template
+ run: |
+ node build-tools/cli.js verify-template artifacts/*.zip
+ mkdir -p template
+ unzip -q artifacts/*.zip -d template
+
+ # Packaged the way the editor's Package dialog does it, once: every version
+ # in the matrix installs the identical file, so a difference between two rows
+ # cannot be a difference between two builds.
+ - name: Package the canary example(s)
+ run: |
+ set -euo pipefail
+ mkdir -p apks
+ IFS=',' read -ra NAMES <<< "${{ inputs.examples }}"
+ for name in "${NAMES[@]}"; do
+ name=$(echo "$name" | xargs)
+ [ -z "$name" ] && continue
+ echo "::group::packaging $name"
+ node desktop/scripts/export-project.mjs "examples/$name" \
+ --platform android --template template \
+ --out "build/pkg/$name" --json "build/pkg/$name.json"
+ APK=$(node -e "process.stdout.write(require('./build/pkg/$name.json').apkFile || '')")
+ if [ -z "$APK" ]; then
+ echo "::error::the export of $name wrote no APK"
+ exit 1
+ fi
+ cp "$APK" "apks/$name.apk"
+ echo "::endgroup::"
+ done
+ ls -la apks
+
+ - uses: actions/upload-artifact@v7
+ with:
+ name: compat-apks
+ path: apks/*.apk
+ retention-days: 3
diff --git a/.github/workflows/android-compat.yml b/.github/workflows/android-compat.yml
index 70f652df2..866751e8c 100644
--- a/.github/workflows/android-compat.yml
+++ b/.github/workflows/android-compat.yml
@@ -73,7 +73,6 @@ env:
# stated once, in one place, rather than implied by a matrix.
ANDROID_API_FLOOR: ${{ inputs.api-floor || '29' }}
ANDROID_PROFILE: pixel_6
- CANARY_EXAMPLES: ${{ inputs.examples || 'space-shooter' }}
jobs:
# ---------------------------------------------------------------------------
@@ -121,160 +120,17 @@ jobs:
echo "Testing API levels: $(echo $LEVELS | tr '\n' ' ')"
# ---------------------------------------------------------------------------
+ # The APKs come from the shared packaging workflow, so the emulator matrix and
+ # the device farm run install a byte-identical binary. See android-canary-apk.yml.
apk:
- name: Package the canary example(s)
- runs-on: ubuntu-latest
- timeout-minutes: 120
+ uses: ./.github/workflows/android-canary-apk.yml
permissions:
contents: read
pull-requests: read # to see which files the PR touches
- outputs:
- # Reported alongside the numbers: "the shipped binary" and "a build of this
- # branch" are different claims, and a table that does not say which it made
- # is a table nobody can act on.
- template-from: ${{ steps.src.outputs.from }}
- steps:
- # Submodules only matter to a from-source build; the released template
- # carries its libraries already. Fetched unconditionally because a
- # conditional checkout is a second way for the two paths to diverge.
- - uses: actions/checkout@v7
- with:
- submodules: recursive
+ with:
+ examples: ${{ inputs.examples || 'space-shooter' }}
+ template-source: ${{ inputs.template-source || 'auto' }}
- - uses: ./.github/actions/setup
-
- # The SDK bundle is compiled INTO the host binary, so a template built here
- # needs it — and the export bundles the game against it either way.
- - name: Build SDK
- run: pnpm --filter ./sdk build
-
- # Building the host takes ~35 minutes (Dawn, once per ABI) and produces
- # something byte-for-byte irrelevant unless the host source actually changed.
- # A released template was already built, on a machine that did nothing else,
- # and it has the stronger claim besides: it is the binary users installed, so
- # a crash reproduced against it is THE crash rather than a rebuild of it.
- #
- # So: from source only when this PR touches the host, and from the release
- # otherwise. Getting this backwards is silent — a native fix "verified"
- # against a template that predates it — hence the decision is logged.
- - name: Decide where the template comes from
- id: src
- env:
- GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: |
- set -euo pipefail
- WANT='${{ inputs.template-source }}'
- if [ -z "$WANT" ] || [ "$WANT" = 'auto' ]; then
- if [ "$GITHUB_EVENT_NAME" = 'pull_request' ]; then
- CHANGED=$(gh pr diff '${{ github.event.pull_request.number }}' --name-only)
- # build-tools/ counts: the API level the host compiles against is a
- # DEFAULT in build-tools, not a value in native/. The change that fixed
- # the Android 10 crash touched nothing under native/, so a rule that
- # watched only native/ would have tested the old released binary and
- # reported the fix as not working.
- if echo "$CHANGED" | grep -qE '^(native/|build-tools/|toolchain\.manifest\.json)'; then
- WANT=head
- echo "this PR touches the native host — the template must be built from it"
- else
- WANT=release
- echo "this PR touches no native host source — using the released template"
- fi
- else
- WANT=release
- fi
- fi
- echo "from=$WANT" >> "$GITHUB_OUTPUT"
-
- - name: Take the template from the latest release
- if: steps.src.outputs.from == 'release'
- env:
- GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: |
- set -euo pipefail
- TAG=$(gh release view --repo "$GITHUB_REPOSITORY" --json tagName -q .tagName)
- echo "template from $TAG"
- mkdir -p artifacts
- gh release download "$TAG" --repo "$GITHUB_REPOSITORY" \
- -p 'estella-native-android-*.zip' -D artifacts
-
- - name: Read the native dependency pins
- if: steps.src.outputs.from == 'head'
- id: pins
- run: |
- node -e "const p=require('./toolchain.manifest.json').native;\
- console.log('dawn='+p.dawn.commit);console.log('quickjs='+p.quickjs.commit)" >> "$GITHUB_OUTPUT"
-
- # restore-keys without the pins, because a Dawn build for a DIFFERENT pin is
- # still most of this one's object files. Note the release pipeline's own cache
- # is written from a tag ref and is therefore unreachable from any branch —
- # see the PR discussion; warming this from master is separate work.
- - name: Cache the pinned checkouts + Dawn builds
- if: steps.src.outputs.from == 'head'
- uses: actions/cache@v4
- with:
- path: build/native-deps
- key: native-deps-android-${{ steps.pins.outputs.dawn }}-${{ steps.pins.outputs.quickjs }}
- restore-keys: native-deps-android-
-
- - name: Set up the Android NDK
- if: steps.src.outputs.from == 'head'
- uses: nttld/setup-ndk@v1
- id: ndk
- with:
- ndk-version: r28
-
- - name: Fetch Dawn + QuickJS at their pinned commits
- if: steps.src.outputs.from == 'head'
- run: node build-tools/cli.js native --fetch-deps
-
- # BOTH ABIs, even though every emulator here is x86_64: ANDROID_ABIS names
- # arm64-v8a and x86_64 as what a template must carry, and the emitter refuses
- # an incomplete one. An x86_64-only build fails at the emit step, not at the
- # compile — which is exactly how this was found.
- - name: Build the Android runtime template from this branch
- if: steps.src.outputs.from == 'head'
- env:
- ANDROID_NDK_HOME: ${{ steps.ndk.outputs.ndk-path }}
- run: |
- node build-tools/cli.js native --abi arm64-v8a
- node build-tools/cli.js native --abi x86_64 --template-out artifacts
-
- - name: Unpack the template
- run: |
- node build-tools/cli.js verify-template artifacts/*.zip
- mkdir -p template
- unzip -q artifacts/*.zip -d template
-
- # Packaged the way the editor's Package dialog does it, once: every version
- # in the matrix installs the identical file, so a difference between two rows
- # cannot be a difference between two builds.
- - name: Package the canary example(s)
- run: |
- set -euo pipefail
- mkdir -p apks
- IFS=',' read -ra NAMES <<< "$CANARY_EXAMPLES"
- for name in "${NAMES[@]}"; do
- name=$(echo "$name" | xargs)
- [ -z "$name" ] && continue
- echo "::group::packaging $name"
- node desktop/scripts/export-project.mjs "examples/$name" \
- --platform android --template template \
- --out "build/pkg/$name" --json "build/pkg/$name.json"
- APK=$(node -e "process.stdout.write(require('./build/pkg/$name.json').apkFile || '')")
- if [ -z "$APK" ]; then
- echo "::error::the export of $name wrote no APK"
- exit 1
- fi
- cp "$APK" "apks/$name.apk"
- echo "::endgroup::"
- done
- ls -la apks
-
- - uses: actions/upload-artifact@v7
- with:
- name: compat-apks
- path: apks/*.apk
- retention-days: 3
# ---------------------------------------------------------------------------
compat:
diff --git a/.github/workflows/android-device.yml b/.github/workflows/android-device.yml
new file mode 100644
index 000000000..bb383a70f
--- /dev/null
+++ b/.github/workflows/android-device.yml
@@ -0,0 +1,144 @@
+name: Android real devices
+
+# The same canary, on real phones.
+#
+# android-compat.yml answers "does this Android VERSION work" across a dozen
+# emulators. It cannot answer "does this DRIVER work", and for this engine that
+# is the question that matters: the host renders through Dawn → Vulkan, and an
+# emulator's Vulkan is SwiftShader — a CPU rasteriser. Adreno, Mali and Xclipse
+# are where a renderer actually breaks, and none of them exist in CI's emulators.
+#
+# So this runs the SAME APK, through the SAME verifier, on AWS Device Farm's real
+# hardware. Not per PR: it costs device minutes and a driver break is not the
+# thing that lands ten times a day. Before a release, and whenever someone wants
+# to know.
+#
+# Wiring it up needs three repository secrets, all created in the AWS console
+# (us-west-2 — Device Farm has no other region):
+# AWS_DEVICEFARM_ROLE_ARN an IAM role trusting this repo via GitHub OIDC
+# DEVICEFARM_PROJECT_ARN the Device Farm project
+# DEVICEFARM_DEVICE_POOL_ARN the pool of models to run on
+#
+# Pick the pool by GPU vendor rather than by popularity: a Pixel (Mali/Tensor), a
+# Snapdragon Galaxy (Adreno) and an Exynos Galaxy (Xclipse) cover the three
+# drivers between them, and a fourth phone from the same vendor as one of those
+# is a device minute spent on a question already answered.
+
+on:
+ workflow_dispatch:
+ inputs:
+ examples:
+ description: 'Comma-separated example names to package and run.'
+ required: false
+ default: 'space-shooter'
+ type: string
+ template-source:
+ description: 'Which runtime template to wrap: the latest release, or a build of this branch (~35 min).'
+ required: false
+ default: release
+ type: choice
+ options: [release, head]
+ push:
+ tags:
+ - 'v*'
+
+permissions:
+ contents: read
+
+concurrency:
+ group: android-device-${{ github.ref }}
+ cancel-in-progress: false # a device farm run costs money; do not abandon one mid-flight
+
+jobs:
+ # The same packaging the emulator matrix uses, so a device row and an emulator
+ # row that disagree disagree about the DEVICE.
+ apk:
+ uses: ./.github/workflows/android-canary-apk.yml
+ permissions:
+ contents: read
+ pull-requests: read
+ with:
+ examples: ${{ inputs.examples || 'space-shooter' }}
+ template-source: ${{ inputs.template-source || 'release' }}
+
+ devices:
+ name: Real devices (AWS Device Farm)
+ needs: apk
+ runs-on: ubuntu-latest
+ timeout-minutes: 90
+ permissions:
+ contents: read
+ id-token: write # OIDC, so no long-lived AWS keys live in this repo
+ steps:
+ - uses: actions/checkout@v7
+
+ # Where the toolchain versions live. The bundle script has no dependencies,
+ # but "which Node" is not a thing to leave to whatever the runner shipped.
+ - uses: ./.github/actions/setup
+
+ - uses: actions/download-artifact@v8
+ with:
+ name: compat-apks
+ path: apks
+
+ - name: Build the test bundle
+ run: node tools/devicefarm/pack-test-bundle.mjs
+
+ # Fails early and by name when the account side was never wired up, rather
+ # than as an opaque AWS error three steps later.
+ - name: Check the run is configured
+ env:
+ ROLE: ${{ secrets.AWS_DEVICEFARM_ROLE_ARN }}
+ PROJECT: ${{ secrets.DEVICEFARM_PROJECT_ARN }}
+ POOL: ${{ secrets.DEVICEFARM_DEVICE_POOL_ARN }}
+ run: |
+ set -euo pipefail
+ missing=
+ [ -z "$ROLE" ] && missing="$missing AWS_DEVICEFARM_ROLE_ARN"
+ [ -z "$PROJECT" ] && missing="$missing DEVICEFARM_PROJECT_ARN"
+ [ -z "$POOL" ] && missing="$missing DEVICEFARM_DEVICE_POOL_ARN"
+ if [ -n "$missing" ]; then
+ echo "::error::missing repository secret(s):$missing — see the header of .github/workflows/android-device.yml"
+ exit 1
+ fi
+ ls -la apks
+
+ - uses: aws-actions/configure-aws-credentials@v4
+ with:
+ role-to-assume: ${{ secrets.AWS_DEVICEFARM_ROLE_ARN }}
+ aws-region: us-west-2
+
+ - name: Install and measure on real devices
+ id: farm
+ uses: aws-actions/aws-devicefarm-mobile-device-testing@v3
+ with:
+ # File paths (rather than ARNs) tell the action to upload them first.
+ run-settings-json: |
+ {
+ "name": "estella canary ${{ github.ref_name }} ${{ github.sha }}",
+ "projectArn": "${{ secrets.DEVICEFARM_PROJECT_ARN }}",
+ "devicePoolArn": "${{ secrets.DEVICEFARM_DEVICE_POOL_ARN }}",
+ "appArn": "apks/${{ inputs.examples || 'space-shooter' }}.apk",
+ "test": {
+ "type": "APPIUM_NODE",
+ "testPackageArn": "build/devicefarm/tests.zip",
+ "testSpecArn": "tools/devicefarm/testspec.yml"
+ }
+ }
+ artifact-types: CUSTOMER_ARTIFACT,VIDEO,SCREENSHOT
+
+ # Always: a failed run's artifacts are the ones worth having, and the device
+ # is gone by the time anyone reads the red X.
+ - name: Keep what the devices produced
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: device-farm-artifacts
+ path: ${{ steps.farm.outputs.artifact-folder }}
+ if-no-files-found: warn
+
+ - name: Where to look
+ if: always()
+ run: |
+ echo "result: ${{ steps.farm.outputs.result }}"
+ echo "console: ${{ steps.farm.outputs.console-url }}"
diff --git a/tools/devicefarm/pack-test-bundle.mjs b/tools/devicefarm/pack-test-bundle.mjs
new file mode 100644
index 000000000..08c6b1d78
--- /dev/null
+++ b/tools/devicefarm/pack-test-bundle.mjs
@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// Build the zip Device Farm unpacks onto its test host.
+//
+// node tools/devicefarm/pack-test-bundle.mjs [out.zip]
+//
+// The bundle is small on purpose: the verifier and what it imports, nothing
+// else. It is NOT the repository — a device farm run should carry the thing that
+// decides "did it boot", not a checkout, or the next person to add a dependency
+// somewhere unrelated breaks a run they cannot see.
+//
+// It is uploaded as an APPIUM_NODE package, which is Device Farm's vocabulary for
+// "a Node test bundle" rather than a claim that Appium is involved: the test spec
+// replaces every command, and no Appium server is started. That type validates
+// the presence of `node_modules`, so one is written even though the verifier has
+// no dependencies — an empty directory does not survive a zip.
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, rmSync, copyFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const OUT = path.resolve(process.argv[2] ?? path.join(ROOT, 'build/devicefarm/tests.zip'));
+const STAGE = path.join(ROOT, 'build/devicefarm/bundle');
+
+/** What the test spec invokes, plus anything it reaches. Kept explicit: a glob
+ * would quietly start shipping whatever lands in tools/ next. */
+const FILES = ['tools/verify-native-boot.mjs'];
+
+rmSync(STAGE, { recursive: true, force: true });
+mkdirSync(path.join(STAGE, 'tools'), { recursive: true });
+
+for (const rel of FILES) {
+ const src = path.join(ROOT, rel);
+ if (!existsSync(src)) {
+ console.error(`::error::${rel} is missing — the bundle would ship without the verifier`);
+ process.exit(1);
+ }
+ copyFileSync(src, path.join(STAGE, rel));
+}
+
+// The type's package validation wants these; the run does not.
+writeFileSync(path.join(STAGE, 'package.json'), `${JSON.stringify({
+ name: 'estella-devicefarm-bundle',
+ version: '0.0.0',
+ private: true,
+ description: 'Drives tools/verify-native-boot.mjs against a Device Farm device. See tools/devicefarm/testspec.yml.',
+}, null, 2)}\n`);
+mkdirSync(path.join(STAGE, 'node_modules'), { recursive: true });
+writeFileSync(path.join(STAGE, 'node_modules', '.keep'), 'The verifier has no dependencies; this exists so the directory survives the zip.\n');
+
+mkdirSync(path.dirname(OUT), { recursive: true });
+rmSync(OUT, { force: true });
+
+// Zipped from INSIDE the stage, so the archive has no wrapper directory — the
+// test spec cd's to $DEVICEFARM_TEST_PACKAGE_PATH and runs `node tools/...`
+// from there.
+//
+// `zip` on the runner, PowerShell where there is none: this is meant to be
+// runnable by hand while working out a test spec, and on the machine most of
+// that happens on there is no `zip`.
+function archive() {
+ try {
+ execFileSync('zip', ['-r', '-q', OUT, '.'], { cwd: STAGE, stdio: 'inherit' });
+ return 'zip';
+ } catch (err) {
+ if (err?.code !== 'ENOENT') throw err;
+ }
+ execFileSync('powershell.exe', [
+ '-NoProfile', '-NonInteractive', '-Command',
+ `Compress-Archive -Path '${STAGE.replace(/'/g, "''")}\\*' -DestinationPath '${OUT.replace(/'/g, "''")}' -Force`,
+ ], { stdio: 'inherit' });
+ return 'Compress-Archive';
+}
+const tool = archive();
+
+// Compress-Archive writes Windows separators into the entry names, which Linux
+// unzips into one flat directory of files literally called `tools\verify-...`.
+// Fine for looking at what went in; not fine for a run. The bundle a device farm
+// consumes is built on the runner, where `zip` exists.
+if (tool !== 'zip') {
+ console.warn('warning: built with Compress-Archive — entry paths use backslashes, so this archive is for LOCAL inspection only');
+}
+
+console.log(`${path.relative(ROOT, OUT)} — ${(statSync(OUT).size / 1024).toFixed(1)} KB (via ${tool})`);
diff --git a/tools/devicefarm/testspec.yml b/tools/devicefarm/testspec.yml
new file mode 100644
index 000000000..8895abda0
--- /dev/null
+++ b/tools/devicefarm/testspec.yml
@@ -0,0 +1,77 @@
+version: 0.1
+
+# Run the canary on a REAL phone, with the same verifier the emulators use.
+#
+# Device Farm's custom test environment hands you a shell on the test HOST with
+# the device attached over adb, which is the only reason this platform was picked:
+# tools/verify-native-boot.mjs drives adb directly (install, `am start -W`,
+# logcat, dumpsys, /proc/<pid>/stat), and a farm that only runs Espresso or
+# Appium would have meant rewriting the thing that decides whether the engine
+# booted — and then having two answers to that question.
+#
+# Two variables make it fit with no code change at all:
+# $ANDROID_HOME — the verifier already builds its adb path from this
+# $DEVICEFARM_DEVICE_UDID → ANDROID_SERIAL, which the adb CLIENT honours, so
+# nothing downstream needs to learn a -s flag
+#
+# What this covers that no emulator can: the real GPU driver. The host renders
+# through Dawn → Vulkan, and on an emulator that is SwiftShader, a CPU
+# rasteriser — so the emulator matrix answers "does this Android VERSION work"
+# and this answers "does this DRIVER work". They are different questions and
+# this file exists because only one of them was being asked.
+
+android_test_host: amazon_linux_2
+
+phases:
+ install:
+ commands:
+ # The verifier is plain Node with no dependencies; it just needs a runtime.
+ - devicefarm-cli use node 20
+ - node --version
+ # Every later command re-exports this: a phase's commands share a shell,
+ # but relying on that across phases is a footgun this file cannot test.
+ - export ANDROID_SERIAL=$DEVICEFARM_DEVICE_UDID
+ - adb devices -l
+
+ pre_test:
+ commands:
+ - export ANDROID_SERIAL=$DEVICEFARM_DEVICE_UDID
+ # Named in the artifact and in the metrics, because "it failed on Android 14"
+ # is not actionable when the two Android 14 devices in the pool are a Pixel
+ # and a Galaxy with different GPUs. The model is the interesting axis here.
+ - echo "device=$DEVICEFARM_DEVICE_NAME os=$DEVICEFARM_DEVICE_OS_VERSION udid=$DEVICEFARM_DEVICE_UDID"
+ - adb shell getprop ro.product.model
+ - adb shell getprop ro.hardware
+ # The GPU this run actually exercised, recorded before anything can crash:
+ # it is the one fact that explains a driver-shaped failure, and it is gone
+ # once the device is released back to the pool.
+ - adb shell dumpsys SurfaceFlinger 2>/dev/null | grep -iE "GLES|Vulkan" | head -5 > $DEVICEFARM_LOG_DIR/gpu.txt || true
+ - cat $DEVICEFARM_LOG_DIR/gpu.txt || true
+
+ test:
+ commands:
+ - export ANDROID_SERIAL=$DEVICEFARM_DEVICE_UDID
+ - cd $DEVICEFARM_TEST_PACKAGE_PATH
+ # --no-frame-judge for the same reason the emulator matrix passes it: a
+ # scene that is legitimately dark and a renderer that died produce the same
+ # dark PNG. The frame is collected for a human; the gate is install +
+ # `ready` + no recorded error.
+ - |-
+ node tools/verify-native-boot.mjs \
+ --platform android \
+ --apk "$DEVICEFARM_APP_PATH" \
+ --label "device-$DEVICEFARM_DEVICE_OS_VERSION" \
+ --no-frame-judge \
+ --out "$DEVICEFARM_LOG_DIR" \
+ --metrics-out "$DEVICEFARM_LOG_DIR/metrics.json"
+
+ post_test:
+ commands:
+ # The logcat tail ships whether or not the verifier was happy: a run that
+ # passed and a run that failed are read the same way, and asking for the log
+ # only on failure is how you find out you needed it after the device is gone.
+ - export ANDROID_SERIAL=$DEVICEFARM_DEVICE_UDID
+ - adb logcat -d -t 2000 > $DEVICEFARM_LOG_DIR/logcat.txt 2>&1 || true
+
+artifacts:
+ - $DEVICEFARM_LOG_DIR