feat: add comprehensive test coverage (unit + E2E) with mock SDK client (#834)

## Summary

Adds comprehensive test coverage for the frontend and runner, going from
**0% → 74% unit test coverage** with a mock SDK client for E2E tests
that doesn't require a real Anthropic API key.

## What's included

### Mock SDK Client
- `MockClaudeSDKClient` in the runner — activated by
`ANTHROPIC_API_KEY=mock-replay-key`
- Replays pre-recorded SDK messages from JSONL fixtures through the real
`ClaudeAgentAdapter`
- Tests the full AG-UI translation pipeline without calling the
Anthropic API
- Capture script (`scripts/capture-fixtures.py`) to record new fixtures
from real sessions

### Frontend Unit Tests (466 tests, ~74% coverage)
- **26 test files** using Vitest + React Testing Library
- Covers: event-handlers, export-chat, tool-message, ChatInputBox,
FeedbackModal, stream-message, normalize-snapshot, status-colors,
file-tree, input-with-history, theme-toggle, use-session-queue,
use-agui-stream, use-autocomplete, use-workspace, use-projects,
use-sessions, and more

### E2E Tests (58 tests)
- **One comprehensive test file** (`sessions.cy.ts`) covering the full
user journey
- Workspace CRUD, session lifecycle, agent interaction, chat features,
workspace admin, modals, feedback
- Always uses `mock-replay-key` — no real API key needed
- Runs in Chrome (Electron has SSE issues)

### CI Updates
- `unit-tests.yml`: Added frontend vitest job alongside
backend/runner/CLI tests
- `e2e.yml`: Removed `ANTHROPIC_API_KEY` dependency, uses mock SDK mode
- `run-tests.sh`: Uses Chrome instead of Electron

### Documentation
- `CLAUDE.md`: Testing section with quick reference
- `e2e/README.md`: Full E2E guide (mock SDK, test structure, writing
tests)
- `components/frontend/README.md`: Unit test guide (vitest patterns,
mocking)

### Cleanup
- Removed outdated test files: `chatbox-demo.cy.ts`,
`jira-integration-demo.cy.ts`, `public-api.cy.ts`, `vteam.cy.ts`
- Removed deleted admin/runtimes page
- Added `data-testid` attributes to key frontend components
- Added `.gitignore` for coverage output

## How to run

```bash
# Unit tests (fast, ~2s)
cd components/frontend && npx vitest run --coverage

# E2E tests (~3min, needs running cluster)
cd e2e
TEST_TOKEN=$(kubectl get secret test-user-token -n ambient-code -o jsonpath='{.data.token}' | base64 -d) \
CYPRESS_BASE_URL=http://localhost:3000 \
npx cypress run --browser chrome --spec cypress/e2e/sessions.cy.ts
```

---------

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

Author: Gkrumbach07

.github/workflows/e2e.yml

@@ -1,41 +1,24 @@
 name: E2E Tests
 
-# ONLY runs when maintainer adds "safe-to-test" label to a PR
-# Has access to secrets (including ANTHROPIC_API_KEY)
-# Maintainers: Review PR code before adding label!
+# Runs automatically on PRs. Uses mock SDK (no real API key needed).
 
 on:
   pull_request:
-    types: [labeled]
     branches: [ main, master ]
 
+  push:
+    branches: [ main ]
+
 concurrency:
-  group: e2e-tests-${{ github.event.pull_request.number }}
+  group: e2e-tests-${{ github.event.pull_request.number || github.sha }}
   cancel-in-progress: true
 
 jobs:
-  # Security check - only proceed if safe-to-test label was added
-  check-label:
-    if: github.event.pull_request.head.repo.full_name == github.repository
-    runs-on: ubuntu-latest
-    outputs:
-      should-run: ${{ steps.check.outputs.should-run }}
-    steps:
-      - name: Check if safe-to-test label was added
-        id: check
-        run: |
-          if [ "${{ github.event.label.name }}" = "safe-to-test" ]; then
-            echo "should-run=true" >> $GITHUB_OUTPUT
-            echo "✅ safe-to-test label added - proceeding with tests"
-          else
-            echo "should-run=false" >> $GITHUB_OUTPUT
-            echo "⏭️  Label '${{ github.event.label.name }}' is not safe-to-test - skipping"
-          fi
-
   detect-changes:
+    # Only run for same-repo PRs (not forks) and pushes to main.
+    # Fork PRs build and execute untrusted code in the CI runner environment.
+    if: github.event.pull_request.head.repo.full_name == github.repository || github.event_name == 'push'
     runs-on: ubuntu-latest
-    needs: check-label
-    if: needs.check-label.outputs.should-run == 'true'
     outputs:
       frontend: ${{ steps.filter.outputs.frontend }}
       backend: ${{ steps.filter.outputs.backend }}
@@ -64,8 +47,9 @@ jobs:
   e2e:
     name: End-to-End Tests
     runs-on: ubuntu-latest
-    needs: [check-label, detect-changes]
-    if: needs.check-label.outputs.should-run == 'true'
+    needs: [detect-changes]
+    if: github.event.pull_request.head.repo.full_name == github.repository || github.event_name == 'push'
+    
     timeout-minutes: 25
 
     steps:
@@ -165,7 +149,7 @@ jobs:
 
     - name: Install kind
       run: |
-        curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
+        curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.27.0/kind-linux-amd64
         chmod +x ./kind
         sudo mv ./kind /usr/local/bin/kind
         kind version
@@ -187,15 +171,13 @@ jobs:
         kind load docker-image quay.io/ambient_code/vteam_claude_runner:e2e-test --name ambient-local
         echo "✅ All images loaded into kind cluster"
 
-    - name: Update kustomization to use e2e-test images
-      run: |
-        sed -i 's/newTag: latest/newTag: e2e-test/g' components/manifests/overlays/e2e/kustomization.yaml
-        echo "Updated kustomization.yaml to use e2e-test tag"
-
-    - name: Deploy vTeam (with ANTHROPIC_API_KEY)
+    - name: Deploy vTeam (mock SDK mode)
       working-directory: e2e
       env:
-        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        IMAGE_FRONTEND: quay.io/ambient_code/vteam_frontend:e2e-test
+        IMAGE_BACKEND: quay.io/ambient_code/vteam_backend:e2e-test
+        IMAGE_OPERATOR: quay.io/ambient_code/vteam_operator:e2e-test
+        IMAGE_RUNNER: quay.io/ambient_code/vteam_claude_runner:e2e-test
       run: ./scripts/deploy.sh
 
     - name: Verify deployment
@@ -206,12 +188,11 @@ jobs:
         echo "Checking services..."
         kubectl get svc -n ambient-code
 
-    - name: Run Cypress tests (with ANTHROPIC_API_KEY)
+    - name: Run Cypress E2E tests
       working-directory: e2e
-      env:
-        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
       run: ./scripts/run-tests.sh
 
+
     - name: Upload test results
       if: failure()
       uses: actions/upload-artifact@v6

.github/workflows/unit-tests.yml

@@ -9,6 +9,7 @@ on:
       - 'components/runners/ambient-runner/**'
       - 'components/ambient-cli/**'
       - 'components/ambient-sdk/go-sdk/**'
+      - 'components/frontend/**'
       - '.github/workflows/unit-tests.yml'
       - '!**/*.md'
 
@@ -19,6 +20,7 @@ on:
       - 'components/runners/ambient-runner/**'
       - 'components/ambient-cli/**'
       - 'components/ambient-sdk/go-sdk/**'
+      - 'components/frontend/**'
       - '.github/workflows/unit-tests.yml'
       - '!**/*.md'
 
@@ -47,6 +49,7 @@ jobs:
       api-server: ${{ steps.filter.outputs.api-server }}
       runner: ${{ steps.filter.outputs.runner }}
       cli: ${{ steps.filter.outputs.cli }}
+      frontend: ${{ steps.filter.outputs.frontend }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -65,6 +68,8 @@ jobs:
             cli:
               - 'components/ambient-cli/**'
               - 'components/ambient-sdk/go-sdk/**'
+            frontend:
+              - 'components/frontend/**'
 
   backend:
     runs-on: ubuntu-latest
@@ -221,24 +226,13 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
-          pip install pytest pytest-asyncio pytest-cov
+          pip install -e '.[claude]'
+          pip install pytest pytest-asyncio pytest-cov httpx
 
-      - name: Run unit tests
+      - name: Run unit tests with coverage
         run: |
-          pytest tests/ -v --tb=short --color=yes -x
+          pytest tests/ -v --tb=short --color=yes -x --cov=ambient_runner --cov-report=term-missing --cov-report=xml
 
-      - name: Run tests with coverage
-        run: |
-          pytest tests/ --cov=ambient_runner --cov-report=term-missing --cov-report=xml
-
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
-        with:
-          files: ./components/runners/ambient-runner/coverage.xml
-          flags: runner
-          name: ambient-runner
-          fail_ci_if_error: false
 
   cli:
     runs-on: ubuntu-latest
@@ -280,9 +274,35 @@ jobs:
           path: components/ambient-cli/coverage.out
           retention-days: 7
 
+  frontend:
+    runs-on: ubuntu-latest
+    needs: detect-changes
+    if: needs.detect-changes.outputs.frontend == 'true' || github.event_name == 'workflow_dispatch'
+    name: Frontend Unit Tests (Vitest)
+    defaults:
+      run:
+        working-directory: components/frontend
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: 'components/frontend/package.json'
+          cache: 'npm'
+          cache-dependency-path: 'components/frontend/package-lock.json'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests with coverage
+        run: npx vitest run --coverage
+
   summary:
     runs-on: ubuntu-latest
-    needs: [detect-changes, backend, api-server, runner, cli]
+    needs: [detect-changes, backend, api-server, runner, cli, frontend]
     if: always()
     steps:
       - name: Check overall status
@@ -292,7 +312,8 @@ jobs:
             "${{ needs.backend.result }}" \
             "${{ needs.api-server.result }}" \
             "${{ needs.runner.result }}" \
-            "${{ needs.cli.result }}"; do
+            "${{ needs.cli.result }}" \
+            "${{ needs.frontend.result }}"; do
             if [ "$result" == "failure" ] || [ "$result" == "cancelled" ]; then
               failed=true
             fi
@@ -303,6 +324,7 @@ jobs:
             echo "  api-server: ${{ needs.api-server.result }}"
             echo "  runner: ${{ needs.runner.result }}"
             echo "  cli: ${{ needs.cli.result }}"
+            echo "  frontend: ${{ needs.frontend.result }}"
             exit 1
           fi
           echo "All unit tests passed!"

CLAUDE.md

@@ -118,6 +118,13 @@ git push --no-verify      # Skip pre-push hooks
 - `tsc --noEmit` and `npm run build` are **not** included (slow; CI gates on them)
 - Branch/push protection scripts remain in `scripts/git-hooks/` and are invoked by pre-commit
 
+## Testing
+
+- **Frontend unit tests**: `cd components/frontend && npx vitest run --coverage` (466 tests, ~74% coverage). See `components/frontend/README.md`.
+- **E2E tests**: `cd e2e && npx cypress run --browser chrome` (58 tests, mock SDK). See `e2e/README.md`.
+- **Runner tests**: `cd components/runners/ambient-runner && python -m pytest tests/`
+- **Backend tests**: `cd components/backend && make test`. See `components/backend/TEST_GUIDE.md`.
+
 ## More Info
 
 See [BOOKMARKS.md](BOOKMARKS.md) for architecture decisions, development context, code patterns, and component-specific guides.

components/frontend/.gitignore

@@ -64,3 +64,6 @@ next-env.d.ts
 
 # Previous frontend
 previous-frontend/
+
+# Coverage
+coverage/

components/frontend/README.md

@@ -191,3 +191,108 @@ curl -i http://localhost:3000/api/projects/my-project/agentic-sessions \
 - **Error Handling**: Comprehensive error states with recovery actions
 
 The frontend provides a complete user interface for the RFE (Request For Enhancement) workflow system, integrating GitHub repositories, AI runners, and real-time collaboration features.
+
+## Testing
+
+### Unit Tests (Vitest)
+
+466 tests across 26 files. Primary coverage metric (~74%).
+
+```bash
+# Run all tests
+npx vitest run
+
+# With coverage report
+npx vitest run --coverage
+open coverage/index.html
+
+# Watch mode
+npx vitest
+
+# Single file
+npx vitest run src/utils/__tests__/export-chat.test.ts
+```
+
+**Config**: `vitest.config.ts` — uses jsdom, Istanbul coverage, `@/` path alias.
+
+### Writing Unit Tests
+
+Place tests in `__tests__/` next to the source:
+
+```
+src/
+  components/
+    chat/
+      ChatInputBox.tsx
+      __tests__/
+        ChatInputBox.test.tsx    ← test file here
+  hooks/
+    use-session-queue.ts
+    __tests__/
+      use-session-queue.test.ts  ← test file here
+```
+
+**Pure function test:**
+```typescript
+import { describe, it, expect } from 'vitest';
+import { convertEventsToMarkdown } from '../export-chat';
+
+describe('convertEventsToMarkdown', () => {
+  it('renders text messages', () => {
+    const events = [
+      { type: 'TEXT_MESSAGE_START', role: 'user' },
+      { type: 'TEXT_MESSAGE_CONTENT', delta: 'Hello' },
+      { type: 'TEXT_MESSAGE_END' },
+    ];
+    const md = convertEventsToMarkdown(makeExport(events), makeSession());
+    expect(md).toContain('Hello');
+  });
+});
+```
+
+**Component test:**
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { MyComponent } from '../MyComponent';
+
+it('handles click', () => {
+  const onClick = vi.fn();
+  render(<MyComponent onClick={onClick} />);
+  fireEvent.click(screen.getByText('Click me'));
+  expect(onClick).toHaveBeenCalled();
+});
+```
+
+**Hook test:**
+```typescript
+import { renderHook, act } from '@testing-library/react';
+
+it('updates state', () => {
+  const { result } = renderHook(() => useMyHook());
+  act(() => result.current.setValue('new'));
+  expect(result.current.value).toBe('new');
+});
+```
+
+**Mocking:**
+```typescript
+// Module mock
+vi.mock('@/services/api/sessions', () => ({
+  createSession: vi.fn().mockResolvedValue({ name: 'test' }),
+}));
+
+// Function stub
+const onSend = vi.fn();
+
+// DOM API spy
+vi.spyOn(document, 'createElement').mockReturnValue(mockEl);
+
+// React Query wrapper
+const wrapper = ({ children }) => (
+  <QueryClientProvider client={new QueryClient()}>
+    {children}
+  </QueryClientProvider>
+);
+const { result } = renderHook(() => useMyQuery(), { wrapper });
+```

components/frontend/next.config.js

@@ -1,12 +1,34 @@
 /** @type {import('next').NextConfig} */
+const isCoverage = process.env.CYPRESS_COVERAGE === 'true'
+
 const nextConfig = {
   output: 'standalone',
   turbopack: {
-    root: __dirname, // Silence "inferred workspace root" warning in monorepo
+    root: __dirname,
   },
   experimental: {
     instrumentationHook: true,
-  }
+    // Force all static pages into a single worker to prevent QEMU SIGILL
+    // crashes during cross-architecture Docker builds (arm64 emulation).
+    staticGenerationMinPagesPerWorker: 100,
+  },
+  webpack(config) {
+    if (isCoverage) {
+      config.module.rules.push({
+        test: /\.(js|ts|jsx|tsx)$/,
+        exclude: /node_modules/,
+        enforce: 'post',
+        use: {
+          loader: 'babel-loader',
+          options: {
+            presets: ['next/babel'],
+            plugins: ['istanbul'],
+          },
+        },
+      })
+    }
+    return config
+  },
 }
 
 module.exports = nextConfig