test(e2e): Playwright harness and main-process hooks for migration stack

.github/actions/install-os-dependencies/action.yaml

@@ -62,6 +62,9 @@ runs:
       if: inputs.os == 'macOS'
       shell: bash
       run: |
+        # GitHub-hosted macOS runners ship aws/tap and azure/bicep pre-tapped.
+        # Trust them so Homebrew does not warn on every brew invocation.
+        brew trust aws/tap azure/bicep 2>/dev/null || true
         brew install nss
 
     - name: Install Windows Dependencies

.github/workflows/cmt-provisioner.yml

@@ -1,20 +1,16 @@
 name: CMT Provisioner
 
-# Trigger workflow for Compatibility Matrix Testing (CMT).
-# When this workflow runs, GitHub fires a workflow_run webhook to matterwick.
-# Matterwick provisions one cloud server per version and dispatches
-# compatibility-matrix-testing.yml automatically.
+# Lightweight signal workflow for Compatibility Matrix Testing (CMT).
+# When this runs, matterwick detects the workflow_run:requested event, provisions one
+# cloud server per version in its CMT set, and dispatches compatibility-matrix-testing.yml.
+# Triggers: RC tag pushes (e.g. v6.2.2-rc.1) and manual workflow_dispatch.
 
 on:
-  # Fire on each RC tag cut (v6.2.0-rc.1, v6.2.0-rc.2, …).
   push:
     tags:
-      - "v*-rc*"
-  # Manual runs from the Actions tab (any ref).
+      - "v[0-9]+.[0-9]+.[0-9]+-rc.[0-9]+"
   workflow_dispatch: {}
 
-# This workflow does not use GITHUB_TOKEN. Its only purpose is to emit a
-# workflow_run event that matterwick reacts to.
 permissions: {}
 
 jobs:

.github/workflows/e2e-functional-template.yml

@@ -188,7 +188,9 @@ jobs:
         run: |
           RUNNER_OS=$(echo "${{ runner.os }}" | tr '[:upper:]' '[:lower:]')
           echo "RUNNER_OS=${RUNNER_OS}" >> $GITHUB_ENV
-          echo "CI_ENVIRONMENT_NAME=@${RUNNER_OS}" >> $GITHUB_ENV
+          # Report-only tag for Playwright blob/HTML output (@ci-* avoids colliding with
+          # platform selection grep tokens @linux/@darwin/@win32 in playwright.config.ts).
+          echo "CI_ENVIRONMENT_NAME=@ci-${RUNNER_OS}" >> $GITHUB_ENV
 
           # Define build type and suffix
           # inputs.TYPE takes precedence when provided by the caller (e.g. RELEASE, MASTER, PR).
@@ -235,26 +237,48 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: '22.x'
-          cache: "npm"
-          cache-dependency-path: package-lock.json
+          package-manager-cache: false
+          # node_modules is cached in e2e/cache-node-modules; disable setup-node's
+          # npm cache so actions/cache v5 does not hit legacy entries.
+
+      - name: e2e/use-gnu-tar-macos
+        if: runner.os == 'macOS'
+        run: echo "/opt/homebrew/opt/gnu-tar/libexec/gnubin" >> $GITHUB_PATH
 
       - name: e2e/cache-node-modules
         id: cache-node-modules
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: |
             node_modules
-            C:\Users\runneradmin\.electron-gyp
-          key: ${{ runner.os }}-build-node-modules-${{ hashFiles('**/package-lock.json') }}
+            e2e/node_modules
+          enableCrossOsArchive: false
+          # v7: exact restore only — avoids probing legacy v6 blobs that warn on macOS
+          key: ${{ runner.os }}-build-node-modules-v7-${{ hashFiles('**/package-lock.json') }}
+
+      - name: e2e/cache-electron-gyp-windows
+        if: runner.os == 'Windows'
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: C:\Users\runneradmin\.electron-gyp
+          enableCrossOsArchive: false
+          key: ${{ runner.os }}-electron-gyp-v7-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
-            ${{ runner.os }}-build-node-modules
-            ${{ runner.os }}-build-
-            ${{ runner.os }}-
+            ${{ runner.os }}-electron-gyp-v7-${{ hashFiles('**/package-lock.json') }}
 
       - name: e2e/setup-python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        env:
+          # Bypass pip's on-disk HTTP cache entirely so a stale/corrupt entry on the
+          # runner image cannot trigger deserialization warnings (actions/setup-python#1317).
+          PIP_NO_CACHE_DIR: "1"
         with:
-          python-version: "3.10"
+          # Use a version pre-installed on macOS-26 (3.13 is in its toolcache), so
+          # setup-python doesn't install a mismatched interpreter whose pip can't
+          # deserialize the image's pre-baked cache. PIP_NO_CACHE_DIR above is the
+          # remaining guard for non-macOS runners.
+          python-version: "3.13"
+          # Omit `cache` — setup-python only accepts pip/pipenv/poetry, not `false`.
 
       - name: e2e/install-os-dependencies
         uses: ./.github/actions/install-os-dependencies
@@ -287,7 +311,7 @@ jobs:
           cd e2e
           export PW_CHROMIUM_ARGS="--disable-gpu --no-sandbox --disable-dev-shm-usage"
           set +e
-          xvfb-run --auto-servernum --server-args='-screen 0 1024x768x24' npm test
+          xvfb-run --auto-servernum --server-args='-screen 0 1024x768x24' npm test -- --project=linux
           echo "PLAYWRIGHT_EXIT_CODE=$?" >> $GITHUB_ENV
         env:
           SERVER_VERSION: ${{ inputs.MM_SERVER_VERSION }}
@@ -303,7 +327,7 @@ jobs:
           echo "Running E2E tests…"
           cd e2e
           set +e
-          npm test
+          npm test -- --project=darwin
           echo "PLAYWRIGHT_EXIT_CODE=$?" >> $GITHUB_ENV
         env:
           SERVER_VERSION: ${{ inputs.MM_SERVER_VERSION }}
@@ -316,7 +340,7 @@ jobs:
           npm run build-test
           cd e2e
           set +e
-          npm test
+          npm test -- --project=win32
           echo "PLAYWRIGHT_EXIT_CODE=$?" >> $GITHUB_ENV
         env:
           SERVER_VERSION: ${{ inputs.MM_SERVER_VERSION }}
@@ -368,10 +392,9 @@ jobs:
           script: |
             process.chdir('./e2e');
             const { analyzeFlakyTests } = require('./utils/analyze-flaky-test.js');
-            const { failureCount, passCount, skipCount, totalCount, os } = analyzeFlakyTests();
+            const { failureCount, passCount, skipCount, totalCount, os, testStatus } = analyzeFlakyTests();
             const runUrl = `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
             const reportUrl = process.env.PER_OS_REPORT_URL || runUrl;
-            const testStatus = failureCount > 0 || Number(process.env.PLAYWRIGHT_EXIT_CODE || 0) !== 0 ? 'failure' : 'success';
             const setOSOutputs = (suffix) => {
               core.setOutput(`NEW_FAILURES_${suffix}`, String(failureCount));
               core.setOutput(`REPORT_LINK_${suffix}`, reportUrl);

.github/workflows/e2e-functional.yml

@@ -239,26 +239,54 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: '22.x'
-          cache: "npm"
-          cache-dependency-path: package-lock.json
+          package-manager-cache: false
+          # node_modules is cached in e2e/cache-node-modules; disable setup-node's
+          # npm cache so actions/cache v5 does not hit legacy entries.
+
+      - name: e2e/use-gnu-tar-macos
+        if: runner.os == 'macOS'
+        run: |
+          # BSD tar on macOS can corrupt actions/cache v5 archives; prefer GNU tar when present.
+          # All current macOS runners are arm64 (Homebrew under /opt/homebrew); keep the
+          # -x guard so a future non-arm64 matrix entry falls back to BSD tar safely.
+          if [ -x /opt/homebrew/opt/gnu-tar/libexec/gnubin/gtar ]; then
+            echo "/opt/homebrew/opt/gnu-tar/libexec/gnubin" >> $GITHUB_PATH
+          fi
 
       - name: e2e/cache-node-modules
         id: cache-node-modules
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: |
             node_modules
-            C:\Users\runneradmin\.electron-gyp
-          key: ${{ runner.os }}-build-node-modules-${{ hashFiles('**/package-lock.json') }}
+            e2e/node_modules
+          enableCrossOsArchive: false
+          # v7: exact restore only — avoids probing legacy v6 blobs that warn on macOS
+          key: ${{ runner.os }}-build-node-modules-v7-${{ hashFiles('**/package-lock.json') }}
+
+      - name: e2e/cache-electron-gyp-windows
+        if: runner.os == 'Windows'
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: C:\Users\runneradmin\.electron-gyp
+          enableCrossOsArchive: false
+          key: ${{ runner.os }}-electron-gyp-v7-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
-            ${{ runner.os }}-build-node-modules
-            ${{ runner.os }}-build-
-            ${{ runner.os }}-
+            ${{ runner.os }}-electron-gyp-v7-${{ hashFiles('**/package-lock.json') }}
 
       - name: e2e/setup-python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        env:
+          # Bypass pip's on-disk HTTP cache entirely so a stale/corrupt entry on the
+          # runner image cannot trigger deserialization warnings (actions/setup-python#1317).
+          PIP_NO_CACHE_DIR: "1"
         with:
-          python-version: "3.10"
+          # Use a version pre-installed on macOS-26 (3.13 is in its toolcache), so
+          # setup-python doesn't install a mismatched interpreter whose pip can't
+          # deserialize the image's pre-baked cache. PIP_NO_CACHE_DIR above is the
+          # remaining guard for non-macOS runners.
+          python-version: "3.13"
+          # Omit `cache` — setup-python only accepts pip/pipenv/poetry, not `false`.
 
       - name: e2e/install-os-dependencies
         uses: ./.github/actions/install-os-dependencies

e2e/AGENTS.md

@@ -44,6 +44,26 @@ await exampleServer.waitForSelector('#sidebarItem_town-square');
 - Reuse helpers from `e2e/helpers` before creating new launch, login, or server-discovery logic.
 - Do not add new `electron-mocha`, `robotjs`, or Mochawesome-based code.
 
+## Declarative platform tags
+
+Platform selection is handled by Playwright **projects** in `e2e/playwright.config.ts`, not runtime `test.skip()` guards.
+
+Every test must declare:
+
+- **Priority:** `@P0`, `@P1`, or `@P2`
+- **Platform:** `@all` (runs on every OS) or one or more of `@linux`, `@darwin`, `@win32`
+
+Special tags:
+
+- `@wayland` — Wayland-only coverage (`linux/wayland_launch.test.ts`). Runs only when `E2E_WAYLAND=true` on Linux via the `wayland` project; excluded from normal Linux CI.
+- Policy specs under `specs/policy/` — excluded from the main CI run unless `RUN_POLICY_E2E=true`.
+
+Do **not** add `test.skip()` for platform gating when tags already express the intended OS. Keep runtime skips only for conditional cases (missing server URL, license/feature unavailable on the test instance).
+
+CI report labels (`@ci-linux`, `@ci-macos`, `@ci-windows`) come from `CI_ENVIRONMENT_NAME` and must not be used as test tags — they would collide with platform grep.
+
+Local/CI runs use `--project=<linux|darwin|win32>` to match the host OS (set automatically in GitHub Actions).
+
 ## Version Compatibility
 
 Treat dependency upgrades as infrastructure changes, not routine edits.
@@ -138,6 +158,8 @@ Many server-backed specs require:
 
 Do not remove skips or platform guards unless the test can actually run in the current environment.
 
+Platform guards belong in test **tags** (`@linux`, `@darwin`, `@win32`, `@all`, `@wayland`), not `test.skip()` — see [Declarative platform tags](#declarative-platform-tags).
+
 Examples:
 - Tests tagged for Windows or Linux are not truthfully verified on macOS.
 - Tests requiring a live Mattermost server should not be treated as fixed unless those env vars are set and the spec was rerun.