feat: enable Playwright tests in CI with proper browser and viewer setup

- Add 'Install Playwright browsers' step (chromium --with-deps) to CI workflow
- Add 'Start viewer for Playwright tests' step with health-check wait loop
- Remove Playwright exclusion from vitest.config.ci.ts — tests run in CI now
- Expand Playwright docs guide with comprehensive CI setup (3-step walkthrough,
  complete GitHub Actions example, headed vs headless tip)
- Add Playwright troubleshooting row to CI/CD guide

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dotnetprofessional

.github/workflows/ci.yml

@@ -34,6 +34,17 @@ jobs:
       - name: Build all packages
         run: pnpm build
 
+      - name: Install Playwright browsers
+        run: npx playwright install chromium --with-deps
+
+      - name: Start viewer for Playwright tests
+        run: |
+          cd packages/viewer
+          PORT=3100 node dist/server/index.js &
+          echo "Waiting for viewer on port 3100..."
+          timeout 30 bash -c 'until curl -sf http://localhost:3100 > /dev/null 2>&1; do sleep 1; done'
+          echo "Viewer is ready"
+
       - name: Test vitest package
         run: npx vitest run --config vitest.config.ci.ts
         working-directory: packages/vitest

docs/docs/vitest/guides/ci-cd.mdx

@@ -274,6 +274,7 @@ These are generated using exactly the pipeline described above — JSON export,
 | `--config` ignored via pnpm | Double `--config` argument | Use `npx vitest run --config ...` directly |
 | Tests pass locally, fail in CI | Environment differences | Check Node.js version, use CI-specific config |
 | No output in CI logs | `detailLevel: 'silent'` | Use `'spec+summary+headers'` for visible output |
+| Playwright tests pending in CI | Missing browsers or no app running | See [Playwright CI setup](./playwright.mdx#ci-configuration) |
 
 ## Related
 

docs/docs/vitest/guides/playwright.mdx

@@ -161,20 +161,81 @@ export default defineConfig({
 
 ## CI Configuration
 
-Playwright in CI requires browser binaries. Add a caching step for speed:
+Playwright tests in CI need two things the local environment already has:
+**browser binaries** and a **running application to test against**.
+
+### Step 1 — Install Browsers
+
+```yaml
+- name: Install Playwright browsers
+  run: npx playwright install chromium --with-deps
+```
+
+The `--with-deps` flag installs system-level libraries (fonts, codecs) that
+headless Chromium needs on Linux runners. Only install the browsers you actually
+test against — `chromium` alone is usually sufficient.
+
+### Step 2 — Start Your Application
+
+Playwright tests navigate to a running web app. Start it in the background
+before running tests:
 
 ```yaml
-# .github/workflows/ci.yml (excerpt)
-- name: Install Playwright
-  run: npx playwright install --with-deps chromium
+- name: Start application
+  run: |
+    npm run start &
+    # Wait until the server responds (up to 30 seconds)
+    timeout 30 bash -c 'until curl -sf http://localhost:3000 > /dev/null 2>&1; do sleep 1; done'
+    echo "Application is ready"
+```
+
+:::caution Don't forget the wait
+Without the health-check loop, tests may start before the server is ready —
+leading to flaky connection-refused failures.
+:::
+
+### Step 3 — Run Tests
 
-- name: Run E2E tests
+```yaml
+- name: Run tests (including Playwright)
   run: npx vitest run --config vitest.config.ci.ts
 ```
 
-:::tip
-Only install the browsers you actually test against. `chromium` alone is usually
-sufficient — add `firefox` or `webkit` only if you need cross-browser coverage.
+### Complete GitHub Actions Example
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-node@v4
+    with:
+      node-version: 22
+
+  - run: npm ci
+
+  - name: Build
+    run: npm run build
+
+  - name: Install Playwright browsers
+    run: npx playwright install chromium --with-deps
+
+  - name: Start application
+    run: |
+      npm run start &
+      timeout 30 bash -c 'until curl -sf http://localhost:3000 > /dev/null 2>&1; do sleep 1; done'
+
+  - name: Run tests
+    run: npx vitest run --config vitest.config.ci.ts
+```
+
+:::tip Headed vs headless
+Use the `CI` environment variable to toggle headed mode:
+```typescript
+const { page } = useBrowser({
+    launch: { headless: process.env.CI === 'true' },
+});
+```
+GitHub Actions sets `CI=true` automatically, so tests run headless in CI and
+can optionally run headed locally for visual debugging.
 :::
 
 ## Troubleshooting

packages/vitest/vitest.config.ci.ts

@@ -9,7 +9,6 @@ export default defineConfig({
     globals: true,
     environment: 'node',
     include: ['_src/test/**/*.Spec.ts'],
-    exclude: ['_src/test/Playwright/**'],  // Playwright tests need a running viewer + browsers — run locally or in dedicated e2e job
     setupFiles: ['./_src/app/setup.ts'],
     pool: 'forks',
     fileParallelism: false,