Run PR E2E (CI APK)

This skill covers ONLY what's different from /run-e2e. For pre-flight (sim/emu booted, devices.json drift, port-4723 cleanup), reports, and failure-mode lookup — read /run-e2e. Do not duplicate.

When to use this vs /run-e2e

This skill is Android only. iOS is out of scope at the CI-artifact level.

What's different from /run-e2e

Four things. Everything else is the same and lives in /run-e2e.

1. Where the APK comes from

• Default (prod APK from ci.yml). tools/run-pr-e2e.sh calls tools/fetch-pr-apk.sh, which finds the newest completed ci.yml pull_request run for the PR, downloads android-release-apk, and drops it at <worktree>/android/app/build/outputs/apk/release/app-release.apk. This APK is bridge-stripped — specs that drive the src/__automation__/ bridge (memory-snapshot, bench-runner) silently no-op.
• --e2e flag (bridge-enabled APK from e2e-tests.yml). Required for bridge-driven specs. Dropped at <worktree>/android/app/build/outputs/apk/e2e/releaseE2e/app-e2e-releaseE2e.apk. e2e-tests.yml is workflow_dispatch-only and matched by head branch — it must have been dispatched for this PR's branch first (tools/ghb workflow run e2e-tests.yml --repo a-ghorbani/pocketpal-ai --ref <head-branch>), otherwise fetch fails with "no completed workflow_dispatch run found for branch".
• appPath. The wrapper rewrites every Android appPath in e2e/devices.json to the path of the APK it fetched (or would fetch, with --no-fetch).

2. Worktree contract

Always a fresh ./worktrees/PR-<N>-e2e on detached origin/<head-branch> — the exact commit CI built. Rules:

• Never reuse an in-flight PR-<N> fix worktree (APK-vs-specs drift — the fix worktree may have uncommitted changes the CI APK doesn't know about).
• If PR-<N>-e2e already exists from a prior run, fast-forward it to current origin/<branch>; don't create a parallel one.
• ./tools/create-worktree.sh PR-<N>-e2e --detach --ref origin/<branch> already syncs e2e/devices.json, .env, keystores. For an existing worktree refresh via ./tools/sync-worktree-config.sh "$WORKTREE".

3. Spec selection

Default is every *.spec.ts minus visual-capture, diagnostic, memory-profile, tts-memory-profile, benchmark-matrix:

• visual-capture — screenshot generation driven by story files, not a regression.
• diagnostic — device-state inspector, not a regression.
• memory-profile, tts-memory-profile — have their own pipeline (/memory-profile); need device-specific baselines to be meaningful.
• benchmark-matrix — has its own pipeline (/bench).

Enumerate dynamically so new specs on the PR are picked up:

EXCLUDE='^(visual-capture|diagnostic|memory-profile|tts-memory-profile|benchmark-matrix)$'
SPECS=$(find "$WORKTREE/e2e/specs" -type f -name '*.spec.ts' \
  | sed -E 's#.*/##; s#\.spec\.ts$##' | grep -vE "$EXCLUDE" \
  | sort -u | paste -sd, -)

4. The entry point is tools/run-pr-e2e.sh, not the runner directly

It's a thin wrapper around scripts/run-e2e.ts --skip-build. It handles APK fetch + placement, then loops --specs invocations against the runner. Don't replicate its work by calling the runner directly — you'll re-download the APK or fight the wrapper.

Run

From the dev-team repo root:

ROOT="$PWD"
PR=<number>
PR_REF="refs/remotes/pr/$PR"

# Fetch the PR head into the submodule (read-only use; no cd into it; works for fork PRs)
git -C "$ROOT/repos/pocketpal-ai" fetch origin "+pull/$PR/head:$PR_REF"

# Create or fast-forward the e2e worktree (reset targets the worktree only)
if [ -d "./worktrees/PR-${PR}-e2e" ]; then
  git -C "./worktrees/PR-${PR}-e2e" reset --hard "$PR_REF"
  ./tools/sync-worktree-config.sh "./worktrees/PR-${PR}-e2e"
else
  ./tools/create-worktree.sh "PR-${PR}-e2e" --detach --ref "$PR_REF"
fi

WORKTREE="./worktrees/PR-${PR}-e2e"
cd "$WORKTREE" && yarn install && (cd e2e && yarn install) && cd -

# Pre-flight: see /run-e2e Step 1 (phone claimed through agistry, emu/device attached, port 4723).

SPECS=$(find "$WORKTREE/e2e/specs" -type f -name '*.spec.ts' \
  | sed -E 's#.*/##; s#\.spec\.ts$##' \
  | grep -vE '^(visual-capture|diagnostic|memory-profile|tts-memory-profile|benchmark-matrix)$' \
  | sort -u | paste -sd, -)

POCKETPAL_REPO="$(realpath "$WORKTREE")" \
  bash ./tools/run-pr-e2e.sh "$PR" [--e2e] --specs "$SPECS" -- --devices connected

Add --e2e if any spec in the list drives the automation bridge (memory-snapshot / bench-runner / AUTOMATION_BRIDGE).

Inputs that ONLY exist here (not in /run-e2e)

Everything after -- is passed verbatim to scripts/run-e2e.ts (devices filter, dry-run, etc.).

PR-specific failure modes (everything else: see /run-e2e)

Required env

• GITHUB_TOKEN or GH_TOKEN (for artifact download)
• ANDROID_HOME or ANDROID_SDK_ROOT