version: "1.0.0" name: dev-testing-frontend description: Testing the Capsem frontend (Astro 5 + Svelte 5 + Tailwind v4 + Preline). Use when writing frontend tests, running type checks, debugging UI issues, or doing visual verification with Chrome DevTools MCP. Covers vitest, svelte-check, astro check, mock mode, and systematic visual verification workflow.

Frontend Testing

Stack

Astro 5 + Svelte 5 (runes only) + Tailwind v4 + Preline + LayerChart v2.

Running tests

cd frontend
pnpm run check              # astro check + svelte-check (type errors)
npx vitest run --coverage   # Unit tests with coverage
pnpm run build              # Production build (catches bundling issues dev misses)

All three run as part of just test. The production build is important -- Tailwind v4's Vite plugin can miss client:only components in the SSR module graph, so @source directives in global.css must explicitly include .svelte and .ts files.

Test files

Tests live in frontend/src/lib/__tests__/. Use vitest with standard patterns:

import { describe, it, expect } from 'vitest';

Mock mode

When window.__TAURI_INTERNALS__ is absent (browser via just ui), api.ts auto-switches all IPC calls to return fake data from mock.ts. Settings data comes from mock-settings.generated.ts (auto-generated from config/defaults.json by the builder). Other mock data (MCP servers, VM state, logs) lives in mock.ts.

This means you can test the full UI without a VM by running just ui.

Generated mock data: mock-settings.generated.ts is produced by scripts/generate_schema.py from the TOML configs in guest/config/. It runs as part of just run and just test via the _generate-settings recipe. Never hand-edit this file.

Visual verification with Chrome DevTools MCP

Every UI change requires visual verification via Chrome DevTools MCP. No exceptions. Type checks and unit tests pass on broken UIs all the time. The only way to know the UI actually works is to look at it.

Workflow for every UI change

1. Start just ui (if not already running)
2. navigate_page to http://localhost:5173
3. list_console_messages types=["error","warn"] -- expect zero
4. Navigate to the view(s) affected by your change
5. take_screenshot each affected view -- visually confirm it renders correctly
6. If the change affects multiple views or layout, screenshot all views (Terminal, Sessions, Network, Settings)
7. Check console again after navigation for new errors

Settings view

Click through every section (AI Providers, Repositories, Security, VM, Appearance). Verify:

• All settings from defaults.json are present (currently 68 leaf settings)
• Provider toggle enables/disables child settings visually
• API key reveal button works (password <-> text)
• Snapshots section shows auto_max, manual_max, auto_interval
• VM Resources section shows all resource settings including min_content_sessions
• Theme toggle switches live
• Lint warnings display inline

After changing TOML configs or generated mock data

When modifying guest/config/*.toml or regenerating mock-settings.generated.ts:

1. Run just _generate-settings (or let just run/just test do it)
2. Start just ui
3. Navigate to Settings view
4. Screenshot and verify new/changed settings appear correctly
5. Check that setting counts match (grep mockSettings.find in generated file)

Color rules (firm)

• Blue (info) = positive (allowed, running, ok). No green in UI chrome.
• Purple (secondary) = negative (denied, stopped, error). No red in UI chrome.
• Terminal emulation colors (xterm green) are fine -- that's xterm, not UI.

Svelte 5 reference

Read references/svelte5.md for Svelte 5 patterns and the @sveltejs/mcp CLI for doc lookups.

Gotchas

• vm-state-changed payload is { state, trigger } (object), not a plain string
• Dynamic Svelte components: use <svelte:component this={item.icon} />, not <item.icon />
• Tailwind v4 + client:only: needs @source directives to scan Svelte files
• Preline is CSS-only -- no JS plugins, no data-hs-* attributes, no HSStaticMethods