test: add X11/Preedit browser E2E foundation with Playwright and xdotool

.github/dependabot.yml

@@ -10,3 +10,8 @@ updates:
     schedule:
       interval: "weekly"
     target-branch: "dev"
+  - package-ecosystem: "npm" # Playwright pins its browser builds; keep that pin from aging silently
+    directory: "/test/browser"
+    schedule:
+      interval: "weekly"
+    target-branch: "dev"

.github/workflows/browser-e2e.yml

@@ -0,0 +1,175 @@
+# Browser-level E2E for the X11/Preedit key-to-DOM plumbing (canary), not a
+# general regression net: engine logic is guarded by the headless ctest suite.
+# Gate rule: PRs run only when the harness itself changes; engine PRs see
+# this lane via nightly + dev pushes. Promotion to a blocking gate on src/**
+# requires >=20 consecutive clean nightlies with >=5 of them unbroken by any
+# src/**/bamboo/** change (so the streak can't accrue against 20 different
+# engines); demotion back to workflow_dispatch-only at 3 consecutive reds
+# without a linked triage issue OR >1 failure per rolling 10 — 20-clean
+# alone would still promote a 10%-flake suite ~12% of the time.
+name: Browser E2E
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '23 3 * * *'
+  push:
+    paths:
+      - 'test/browser/**'
+      - '.github/workflows/browser-e2e.yml'
+      - 'src/**'
+      - 'bamboo/**'
+      - 'data/**'
+      - 'server/**'
+      - '**/CMakeLists.txt'
+  pull_request:
+    paths:
+      - 'test/browser/**'
+      - '.github/workflows/browser-e2e.yml'
+
+# INVARIANT: this job executes PR-authored code (scripts, lockfile, and this
+# file itself) and must stay secret-free — no repository/environment secrets,
+# ever; that plus `contents: read` and ephemeral hosted runners (the X11 -ac /
+# XTEST / --no-sandbox trust model) is what makes fork-PR execution safe.
+permissions:
+  contents: read
+
+concurrency:
+  group: browser-e2e-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' && !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  browser-e2e:
+    name: Browser E2E (X11 / Xvfb)
+    runs-on: ubuntu-24.04
+    env:
+      GTK_IM_MODULE: fcitx
+      QT_IM_MODULE: fcitx
+      XMODIFIERS: '@im=fcitx'
+      CI: "true"
+      PLAYWRIGHT_BROWSERS_PATH: /home/runner/.cache/ms-playwright
+    steps:
+      - name: Setup test environment
+        run: echo "TEST_HOME=$(mktemp -d -t fcitx5-browser-e2e-XXXXXX)" >> "$GITHUB_ENV"
+
+      - name: Checkout fcitx5-lotus
+        uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Setup Go
+        uses: actions/setup-go@v7
+        with:
+          go-version: '1.18'
+          cache: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: 22
+      - name: Install system dependencies
+        run: |
+          sudo apt update
+          sudo apt install -y --no-install-recommends \
+            xvfb \
+            x11-utils \
+            openbox \
+            xdotool \
+            dbus-x11 \
+            fcitx5 \
+            fcitx5-frontend-all \
+            fcitx5-frontend-gtk3 \
+            fcitx5-frontend-gtk4 \
+            libfcitx5core-dev \
+            libfcitx5config-dev \
+            libfcitx5utils-dev \
+            fcitx5-modules-dev \
+            extra-cmake-modules \
+            cmake \
+            ninja-build \
+            gettext \
+            libfmt-dev \
+            librsvg2-bin \
+            libinput-dev \
+            libudev-dev
+
+      - name: Build and install fcitx5-lotus
+        run: |
+          cmake -B build -S . -GNinja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
+          sudo ninja -C build install
+
+      - name: Install test dependencies and Playwright browsers
+        working-directory: test/browser
+        run: |
+          npm ci
+          npx playwright install --with-deps chromium firefox
+
+      - name: Typecheck browser test suite
+        working-directory: test/browser
+        run: npm run typecheck
+      - name: Setup Fcitx configuration
+        run: |
+          chmod +x test/browser/scripts/setup-fcitx.sh test/browser/scripts/run-xvfb.sh
+          ./test/browser/scripts/setup-fcitx.sh
+
+      - name: Start X11 Desktop environment and Fcitx5
+        run: |
+          # Record which distro fcitx5 this run validated — green suites
+          # must be attributable when noble SRUs move the 5.1.x series.
+          fcitx5 --version
+          ./test/browser/scripts/run-xvfb.sh
+
+      - name: Run Chromium E2E tests
+        working-directory: test/browser
+        env:
+          E2E_JSON_OUTPUT: reports/results-chromium.json
+        run: npm run test:chromium
+
+      - name: Run Firefox E2E tests
+        working-directory: test/browser
+        env:
+          E2E_JSON_OUTPUT: reports/results-firefox.json
+        run: npm run test:firefox
+
+      # Timing data is the flake-rate experiment's raw material; the dot
+      # reporter alone can't tell a 50ms poll from a 1.9s one.
+      - name: Upload timing results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: browser-e2e-timing
+          path: test/browser/reports/*.json
+          if-no-files-found: error
+
+      - name: Collect diagnostics on failure
+        if: failure()
+        run: |
+          fcitx5-diagnose > /tmp/fcitx5-diagnose.log 2>&1 || true
+          # Runner stall vs engine bug, decided from the artifact: a red run
+          # next to high cpu pressure is a runner-statistics event, not a
+          # Lotus regression.
+          cat /proc/pressure/* > /tmp/pressure.txt 2>/dev/null || true
+          # Copy logs from isolated TEST_HOME to /tmp for artifact upload
+          cp "${TEST_HOME}/fcitx5.log" /tmp/fcitx5.log 2>/dev/null || true
+          cp "${TEST_HOME}/xvfb.log" /tmp/xvfb.log 2>/dev/null || true
+          cp "${TEST_HOME}/openbox.log" /tmp/openbox.log 2>/dev/null || true
+
+      - name: Upload diagnostics on failure
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: browser-e2e-failure-artifacts
+          path: |
+            test/browser/playwright-report/
+            test/browser/test-results/
+            /tmp/fcitx5.log
+            /tmp/fcitx5-diagnose.log
+            /tmp/xvfb.log
+            /tmp/openbox.log
+            /tmp/pressure.txt
+          if-no-files-found: ignore
+
+      - name: Stop X11 and Fcitx5
+        if: always()
+        run: |
+          ./test/browser/scripts/run-xvfb.sh --stop || true

test/browser/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+playwright-report/
+test-results/
+reports/
+.playwright/
+bun.lock

test/browser/README.md

@@ -0,0 +1,55 @@
+# Browser E2E harness
+
+Real `fcitx5` session under Xvfb; keys injected via `xdotool` (XTEST); results
+asserted in Chromium/Firefox DOM via Playwright. What this lane guards is the
+key-to-DOM plumbing in `Mode=Preedit` (XTEST → fcitx5 → XIM/GTK path → browser
+→ committed text). Engine logic (Telex/VNI rules, macro, per-app mode rules,
+surrounding text) is guarded by the headless ctest suite in `test/` —
+deliberately NOT here, and the workflow header records the same scope.
+
+## Invariants (violating any of these produces green-but-meaningless runs)
+
+- The harness owns its X display: `DISPLAY` is never inherited, the run aborts
+  if the display is occupied (live server or stale socket), and readiness polls
+  `xdpyinfo` (hard dependency — no silent socket-only fallback).
+- `HOME`/`XDG_*` are exported BEFORE openbox starts, and openbox readiness
+  waits for `_NET_SUPPORTING_WM_CHECK` — the focus/raise policy in `rc.xml` is
+  load-bearing for `ensureActive()`; without the ordering, tests pass on
+  stock-default luck.
+- D-Bus is a private bus from `dbus-session.conf` (no
+  `standard_session_servicedirs`) — fcitx5 name ownership (`-r`) is scoped to
+  it, so the harness can coexist with a developer's running desktop.
+- `workers=1`/`fullyParallel=false`: one display, one focused window. Parallel
+  keystroke injection into the same X server is undefined behavior, not speed.
+- `retries=0`: red runs are data. Do not add retries; open a triage issue.
+- `fcitx5` comes from apt and its version is printed per run — a green run
+  only attests to the (addon SHA × fcitx5 version × runner image) triple it
+  actually executed.
+
+Known fidelity caveats: `ShareInputState=All` + `resetStateWhenFocusIn=No`
+are set so `fcitx5-remote` switching works without focus games — real users
+mostly run per-window state, so cross-field isolation bugs are NOT covered
+here by design; and the corpus pins one Telex configuration (hats/DD/tones),
+not VNI or spellcheck edges. Widen both in the phase-2 issue, not ad hoc.
+
+## CI gate contract
+
+Lives in `.github/workflows/browser-e2e.yml` header; summary: PRs are gated on
+harness changes only; nightlies + dev pushes carry the engine-facing signal.
+Promotion to a blocking `src/**` gate needs ≥20 consecutive clean nightlies
+with ≥5 uncontaminated by `src/**`/`bamboo/**` changes; demotion on 3 reds
+without a linked triage issue, or >1 failure per rolling 10.
+
+## Local use (Linux/X11 only)
+
+```bash
+scripts/run-browser-e2e.sh          # creates TEST_HOME, starts stack, runs both browsers
+BROWSER_E2E_DISPLAY=:98 scripts/run-browser-e2e.sh   # if :99 is taken
+```
+
+Triage on red: the failure artifact carries `input-events.json` (DOM-side),
+`fcitx5.log` at `*=4` (inter-event timing), xvfb/openbox logs, and
+`/proc/pressure` — high cpu pressure + failed poll ⇒ runner statistics event,
+not a Lotus regression. The json reporter timing artifact (`*.json`) is
+uploaded on green runs too; compare p95 poll margins against the 2 s
+`expect.poll` deadlines before blaming the engine.