feat(e2e): move CI to Linux by default, keep macOS optional

Move desktop E2E from macOS-only (Appium Mac2) to Linux-default
(tauri-driver) in CI, reducing cost and improving scalability.
macOS E2E remains available for local dev and manual CI dispatch.

- Add platform detection layer (platform.ts) for tauri-driver vs Mac2
- Make all E2E helpers cross-platform (element, app, deep-link)
- Extract shared clickNativeButton/clickToggle/hasAppChrome helpers
- Replace inline XCUIElementType selectors in specs with helpers
- Update wdio.conf.ts with conditional capabilities per platform
- Update build/run scripts for Linux (tauri-driver) and macOS (Appium)
- Add e2e-linux CI job on ubuntu-22.04 (default, every push/PR)
- Convert e2e-macos to workflow_dispatch (manual opt-in)
- Add Docker support for running Linux E2E on macOS locally
- Add docs/E2E-TESTING.md contributor guide

Closes tinyhumansai#81

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: CodeGhost21

.github/workflows/test.yml

@@ -3,6 +3,16 @@ name: Test
 on:
   push:
   pull_request:
+  workflow_dispatch:
+    inputs:
+      run_macos_e2e:
+        description: 'Run macOS E2E tests (Appium Mac2)'
+        required: false
+        default: 'false'
+        type: choice
+        options:
+          - 'false'
+          - 'true'
 
 permissions:
   contents: read
@@ -113,41 +123,110 @@ jobs:
       - name: Test Tauri shell (OpenHuman)
         run: cargo test --manifest-path app/src-tauri/Cargo.toml
 
-  # e2e-macos:
-  #   name: E2E (macOS / Appium)
-  #   runs-on: macos-latest
-  #   timeout-minutes: 90
-  #   steps:
-  #     - name: Checkout code
-  #       uses: actions/checkout@v4
-  #       with:
-  #         fetch-depth: 1
-  #         submodules: recursive
-
-  #     - name: Setup Node.js 24.x
-  #       uses: actions/setup-node@v4
-  #       with:
-  #         node-version: 24.x
-  #         cache: "yarn"
-
-  #     - name: Install Rust (rust-toolchain.toml)
-  #       uses: dtolnay/rust-toolchain@1.93.0
-
-  #     - name: Install dependencies
-  #       run: yarn install --frozen-lockfile
-
-  #     - name: Ensure .env exists for E2E build
-  #       run: |
-  #         touch .env
-  #         touch app/.env
-
-  #     - name: Install Appium and mac2 driver
-  #       run: |
-  #         npm install -g appium
-  #         appium driver install mac2
-
-  #     - name: Build E2E app bundle
-  #       run: yarn workspace openhuman-app test:e2e:build
-
-  #     - name: Run all E2E flows
-  #       run: yarn workspace openhuman-app test:e2e:all:flows
+  e2e-linux:
+    name: E2E (Linux / tauri-driver)
+    runs-on: ubuntu-22.04
+    timeout-minutes: 60
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          submodules: recursive
+
+      - name: Setup Node.js 24.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: "yarn"
+
+      - name: Install Rust (rust-toolchain.toml)
+        uses: dtolnay/rust-toolchain@1.93.0
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev \
+            librsvg2-dev patchelf \
+            xvfb at-spi2-core dbus-x11
+
+      - name: Cargo.lock fingerprint (deps only)
+        id: cargo-lock-fingerprint
+        shell: bash
+        run: |
+          echo "hash=$(tail -n +8 Cargo.lock | openssl dgst -sha256 | awk '{print $2}')" >> "$GITHUB_OUTPUT"
+
+      - name: Cache Cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-e2e-cargo-${{ steps.cargo-lock-fingerprint.outputs.hash }}
+          restore-keys: |
+            ${{ runner.os }}-e2e-cargo-
+
+      - name: Install tauri-driver
+        run: cargo install tauri-driver
+
+      - name: Install JS dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Ensure .env exists for E2E build
+        run: |
+          touch .env
+          touch app/.env
+
+      - name: Build E2E app
+        run: yarn workspace openhuman-app test:e2e:build
+
+      - name: Run E2E tests under Xvfb
+        run: |
+          export DISPLAY=:99
+          Xvfb :99 -screen 0 1280x1024x24 &
+          sleep 2
+          # dbus session is required by webkit2gtk
+          eval $(dbus-launch --sh-syntax)
+          yarn workspace openhuman-app test:e2e:all:flows
+
+  e2e-macos:
+    name: E2E (macOS / Appium)
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.run_macos_e2e == 'true'
+    runs-on: macos-latest
+    timeout-minutes: 90
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          submodules: recursive
+
+      - name: Setup Node.js 24.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: "yarn"
+
+      - name: Install Rust (rust-toolchain.toml)
+        uses: dtolnay/rust-toolchain@1.93.0
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Ensure .env exists for E2E build
+        run: |
+          touch .env
+          touch app/.env
+
+      - name: Install Appium and mac2 driver
+        run: |
+          npm install -g appium
+          appium driver install mac2
+
+      - name: Build E2E app bundle
+        run: yarn workspace openhuman-app test:e2e:build
+
+      - name: Run all E2E flows
+        run: yarn workspace openhuman-app test:e2e:all:flows

CLAUDE.md

@@ -114,32 +114,45 @@ yarn mock:api
 curl -s http://127.0.0.1:18473/__admin/health
 ```
 
-### E2E tests (WDIO + Appium mac2)
+### E2E tests (WDIO — dual platform)
+
+Full guide: [`docs/E2E-TESTING.md`](docs/E2E-TESTING.md).
+
+Two automation backends:
+- **Linux (CI default)**: `tauri-driver` (WebDriver, port 4444) — drives the debug binary directly
+- **macOS (local dev)**: Appium Mac2 (XCUITest, port 4723) — drives the `.app` bundle
 
 - **Where specs live**: `app/test/e2e/specs/*.spec.ts`
 - **Shared harness**:
-  - Helpers: `app/test/e2e/helpers/*`
+  - Platform detection: `app/test/e2e/helpers/platform.ts`
+  - Element helpers: `app/test/e2e/helpers/element-helpers.ts`
+  - Deep link helpers: `app/test/e2e/helpers/deep-link-helpers.ts`
+  - App lifecycle: `app/test/e2e/helpers/app-helpers.ts`
   - Mock backend: `app/test/e2e/mock-server.ts`
-  - WDIO config: `app/test/wdio.conf.ts`
+  - WDIO config: `app/test/wdio.conf.ts` (auto-detects platform)
 
 - **Build + run**:
 
 ```bash
-# Build desktop app bundle + stage core sidecar
+# Build app + stage core sidecar (detects macOS vs Linux automatically)
 yarn test:e2e:build
 
 # Run one spec
 bash app/scripts/e2e-run-spec.sh test/e2e/specs/smoke.spec.ts smoke
 
 # Run all flow specs
 yarn test:e2e:all:flows
+
+# Docker on macOS (run Linux E2E locally)
+docker compose -f e2e/docker-compose.yml run --rm e2e
 ```
 
 - **Authoring rules**:
   - Ensure each spec is runnable in isolation.
-  - Use helper waits (`waitForAppReady`, `waitForWebView`, etc.) instead of ad hoc long sleeps.
+  - Use helpers from `element-helpers.ts` — never use raw `XCUIElementType*` selectors in specs.
+  - Use `clickNativeButton()`, `hasAppChrome()`, `waitForWebView()`, `clickToggle()` for cross-platform element interaction.
   - Assert both UI outcomes and backend/mock effects when relevant.
-  - Add failure diagnostics (request logs, accessibility tree dump) for faster debugging by agents.
+  - Add failure diagnostics (request logs, `dumpAccessibilityTree()`) for faster debugging by agents.
 
 ### Deterministic core-sidecar reset
 

app/scripts/e2e-build.sh

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 #
-# Build the .app bundle for E2E tests with the mock server URL baked in.
+# Build the app for E2E tests with the mock server URL baked in.
+#
+# - macOS: builds a .app bundle (Appium Mac2)
+# - Linux: builds a debug binary (tauri-driver)
+#
 # Cargo incremental builds are used by default for faster iteration.
 #
 set -euo pipefail
@@ -14,7 +18,7 @@ cd "$APP_DIR"
 
 export VITE_BACKEND_URL="http://127.0.0.1:${E2E_MOCK_PORT:-18473}"
 
-echo "Building E2E app bundle with VITE_BACKEND_URL=$VITE_BACKEND_URL"
+echo "Building E2E app with VITE_BACKEND_URL=$VITE_BACKEND_URL"
 
 if [ -n "${E2E_FORCE_CARGO_CLEAN:-}" ]; then
   echo "Forcing cargo clean (E2E_FORCE_CARGO_CLEAN is set)."
@@ -39,6 +43,16 @@ node "$REPO_ROOT/scripts/stage-core-sidecar.mjs"
 TAURI_CONFIG_OVERRIDE='{"bundle":{"createUpdaterArtifacts":false}}'
 # Tauri CLI maps env CI to --ci and only accepts true|false; some runners set CI=1.
 case "${CI:-}" in 1) export CI=true ;; 0) export CI=false ;; esac
-npx tauri build -c "$TAURI_CONFIG_OVERRIDE" --bundles app --debug
+
+OS="$(uname)"
+if [ "$OS" = "Linux" ]; then
+  # Linux: build debug binary only (no bundle needed for tauri-driver)
+  echo "Building for Linux (debug binary, no bundle)..."
+  npx tauri build -c "$TAURI_CONFIG_OVERRIDE" --debug
+else
+  # macOS: build .app bundle for Appium Mac2
+  echo "Building for macOS (.app bundle)..."
+  npx tauri build -c "$TAURI_CONFIG_OVERRIDE" --bundles app --debug
+fi
 
 echo "E2E build complete."