test: add agent-browser QA workflow

.agents/skills/browser-qa/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: browser-qa
+description: Reproduce and verify DevSpace issues or PRs through the real MCP Apps UI with Agent Browser, capturing screenshots, video, console output, and exact repro steps. Use for issue triage, PR verification, UI changes, dogfooding, or end-to-end browser QA.
+---
+
+# DevSpace browser QA
+
+Use browser QA to verify behavior at the host/UI seam. Do not replace a focused MCP, process, Git, or filesystem acceptance test with a browser test when the browser adds no signal.
+
+## Deterministic MCP Apps smoke
+
+Run:
+
+```bash
+pnpm qa:browser
+```
+
+This builds the current DevSpace app, starts an isolated DevSpace server and OAuth-authenticated proxy, runs the pinned official MCP Apps `basic-host`, and drives `open_workspace` followed by `show_changes` with Agent Browser. The run records screenshots, a WebM video/contact sheet, browser console/errors, a snapshot, and a Markdown report under:
+
+```text
+.devspace-dev/browser-qa/artifacts/<timestamp>/
+```
+
+The fixture and all downloaded host dependencies live under ignored `.devspace-dev/browser-qa/` state. The runner refuses to replace an existing process on one of its required ports.
+
+## Exploratory issue or PR QA
+
+Start the same authenticated reference host without running the built-in smoke:
+
+```bash
+pnpm qa:browser -- --serve
+```
+
+Keep that process running and use a worktree-scoped Agent Browser session for the investigation:
+
+```bash
+export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix devspace-qa)"
+agent-browser open http://127.0.0.1:8080
+```
+
+Before using Agent Browser, load its installed version-matched guidance:
+
+```bash
+agent-browser skills get core
+agent-browser skills get dogfood
+```
+
+For a bug report, reproduce the claim once before collecting evidence. If it reproduces, start a clean video before the second reproduction and take screenshots at meaningful steps. For a fix, run the same acceptance scenario against the base revision and the PR revision when practical; report `reproduces on base`, `fixed on PR`, or `not reproduced` rather than inferring correctness from the diff.
+
+Prefer the reference host for deterministic MCP App behavior. Use the existing `setup-qa` flow plus the real ChatGPT host only when the claim is specifically about ChatGPT behavior, reconnect/auth state, host capabilities, or rendering differences that the reference host cannot establish.
+
+## Evidence standard
+
+Interactive failures need a short reproduction video and step screenshots. Static visual issues need an annotated screenshot. Capture console/errors when relevant. Keep the report focused on observable behavior and distinguish confirmed failures from untested risks.

.github/workflows/ci.yml

@@ -62,3 +62,42 @@ jobs:
 
       - name: Doctor
         run: node dist/cli.js doctor
+
+  browser-qa:
+    name: Browser QA
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm and Node
+        uses: pnpm/setup@84cb39b217b10273981911c288cd62326dc7c6d2 # v2
+        with:
+          runtime: node@24
+          cache: true
+          install: false
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install browser QA dependencies
+        run: |
+          npm install --prefix "$RUNNER_TEMP/agent-browser" agent-browser@0.38.1
+          echo "$RUNNER_TEMP/agent-browser/node_modules/.bin" >> "$GITHUB_PATH"
+          "$RUNNER_TEMP/agent-browser/node_modules/.bin/agent-browser" install --with-deps
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg
+
+      - name: Run browser QA
+        run: pnpm qa:browser
+
+      - name: Upload browser QA evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: browser-qa-${{ github.run_id }}
+          path: .devspace-dev/browser-qa/artifacts/
+          if-no-files-found: ignore
+          retention-days: 7

docs/development.md

@@ -96,6 +96,37 @@ pnpm test
 pnpm build
 ```
 
+## Browser QA
+
+For MCP App changes and browser-visible issue reproduction, run the browser QA
+smoke:
+
+```bash
+pnpm qa:browser
+```
+
+It runs the current checkout through the official MCP Apps reference host and
+uses Agent Browser to exercise `open_workspace` and `show_changes` against an
+isolated dirty Git fixture. Evidence is written under the ignored
+`.devspace-dev/browser-qa/artifacts/` directory, including screenshots, a short
+video, browser console/errors, and a report.
+
+The first run downloads a pinned revision of the MCP Apps repository into the
+checkout-local QA directory and installs the `basic-host` dependencies there.
+It requires `agent-browser`, Chrome for Agent Browser, and `ffmpeg`; run
+`agent-browser doctor` to verify those prerequisites.
+
+For exploratory issue or PR QA, keep the reference host running instead:
+
+```bash
+pnpm qa:browser -- --serve
+```
+
+Then drive `http://127.0.0.1:8080` with a worktree-scoped Agent Browser session.
+Use this reference-host path for deterministic MCP App behavior. Use the seeded
+`pnpm dev` flow with the real ChatGPT host only when the behavior being checked
+is specifically host-dependent.
+
 ## Releases
 
 Releases are published by the manual `Release` GitHub Actions workflow. Do not

package.json

@@ -36,6 +36,7 @@
     "dev": "tsx scripts/dev.ts",
     "dev:seed": "tsx scripts/dev-state.ts seed",
     "dev:reset": "tsx scripts/dev-state.ts reset",
+    "qa:browser": "tsx scripts/browser-qa.ts",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "prepack": "pnpm build",
     "schema:config": "tsx scripts/generate-config-schema.ts",