weaver-frontend-test

name	weaver-frontend-test
description	Run and write frontend tests for Weaver. Use when implementing frontend features, fixing UI bugs, or when asked to test frontend code. Covers Vitest unit tests and Playwright E2E browser tests with screenshots.

Weaver Frontend Testing

Announce at start: "Running weaver-frontend-test skill."

Decision Tree

What are you doing?
│
├─ Writing NEW UI code → Go to TDD Flow
├─ Fixing a UI bug → Go to Bug Fix Flow
├─ Running existing tests → Go to Run Tests
├─ Need browser screenshot → Go to Playwright Screenshot
└─ Investigating a test failure → Go to Debug Flow

TDD Flow

Iron rule: No implementation without a failing test first.

Step 1: Document

cp docs/testing/test-plan-template.md docs/testing/plans/<feature>-test-plan.md

Fill in the Frontend Test Cases section — both unit (Vitest) and E2E (Playwright).

Step 2: Decide Test Type

Is it pure logic (store, hook, utility, parser)?
  → Vitest unit test

Is it a component's render output or interaction?
  → Vitest + @testing-library/react

Is it a user-facing flow across pages?
  → Playwright E2E test

Does the change affect visual appearance?
  → Playwright E2E with screenshot

Step 3: Write Failing Test

Vitest unit test — for stores, hooks, utils:

Location: app/frontend/src/<path>/__tests__/<module>.test.ts

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

describe('FeatureName', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('should do expected behavior', () => {
    // GIVEN
    const input = ...;

    // WHEN
    const result = functionUnderTest(input);

    // THEN
    expect(result).toBe(expected);
  });

  it('should handle error case', () => {
    expect(() => functionUnderTest(badInput)).toThrow();
  });
});

Vitest component test — for React components:

Location: app/frontend/src/components/<path>/__tests__/<Component>.test.tsx

import { describe, it, expect, vi } from 'vitest';
import { render, screen, fireEvent } from '@testing-library/react';
import { ComponentUnderTest } from '../ComponentUnderTest';

// Mock Chakra UI provider if needed
vi.mock('@chakra-ui/react', async () => {
  const actual = await vi.importActual('@chakra-ui/react');
  return { ...actual };
});

describe('ComponentUnderTest', () => {
  it('renders with correct content', () => {
    render(<ComponentUnderTest prop="value" />);
    expect(screen.getByText('expected text')).toBeInTheDocument();
  });

  it('handles click interaction', async () => {
    const onAction = vi.fn();
    render(<ComponentUnderTest onAction={onAction} />);

    fireEvent.click(screen.getByRole('button', { name: 'Action' }));
    expect(onAction).toHaveBeenCalledOnce();
  });
});

Playwright E2E test — for full user flows:

Location: app/frontend/e2e/<feature>.spec.ts

import { test, expect } from '@playwright/test';

test.describe('Feature Name', () => {
  test.beforeEach(async ({ page }) => {
    // Navigate to the page under test
    await page.goto('/dashboard');
    await page.waitForLoadState('networkidle');
  });

  test('user can perform action', async ({ page }) => {
    // ACT
    await page.click('[data-testid="action-button"]');
    await page.waitForSelector('[data-testid="result"]');

    // ASSERT
    await expect(page.locator('[data-testid="result"]')).toBeVisible();

    // SCREENSHOT (optional — for visual verification)
    await page.screenshot({
      path: 'e2e/__screenshots__/feature-action-result.png',
      fullPage: false,
    });
  });

  test('handles error state', async ({ page }) => {
    // Trigger error condition
    await page.route('**/api/v1/**', (route) =>
      route.fulfill({ status: 500, body: 'Server error' })
    );

    await page.click('[data-testid="action-button"]');
    await expect(page.locator('[data-testid="error-message"]')).toBeVisible();
  });
});

Step 4: Confirm RED

# Vitest
cd app/frontend && npx vitest run src/<path>/__tests__/<module>.test.ts
# MUST see FAILED

# Playwright
cd app/frontend && npx playwright test e2e/<feature>.spec.ts
# MUST see FAILED

Step 5: Implement (minimal)

Write the minimum code to make the test pass.

Step 6: Confirm GREEN

# Vitest
cd app/frontend && npx vitest run src/<path>/__tests__/<module>.test.ts
# MUST see PASSED

# Playwright
cd app/frontend && npx playwright test e2e/<feature>.spec.ts
# MUST see PASSED

Step 7: Full Suite + Register

make test-frontend-unit    # All vitest tests pass?
make test-frontend-e2e     # All Playwright tests pass? (needs servers running)

Add test IDs to docs/testing/test-registry.md.

Bug Fix Flow

1. Write Playwright test or Vitest test reproducing the bug
2. Confirm it fails
3. Fix the bug
4. Confirm test passes
5. Run full suite

Run Tests

# ─── Vitest (unit/component) ─────────────────────

# All unit tests (single run)
make test-frontend-unit

# Watch mode (interactive)
cd app/frontend && npx vitest

# Single file
cd app/frontend && npx vitest run src/stores/__tests__/chatStore.test.ts

# Single test by name
cd app/frontend && npx vitest run -t "should handle error"

# With coverage
cd app/frontend && npm run test:coverage

# ─── Playwright (E2E browser) ────────────────────

# Prerequisites: backend on :8000, frontend on :3000
# Start them first:
#   Terminal 1: make run-backend
#   Terminal 2: make run-frontend

# All E2E tests
make test-frontend-e2e

# Single file
cd app/frontend && npx playwright test e2e/user-journey.spec.ts

# Interactive UI mode (great for debugging)
cd app/frontend && npx playwright test --ui

# Headed mode (see the browser)
cd app/frontend && npx playwright test --headed

# Update screenshot baselines
cd app/frontend && npx playwright test --update-snapshots

# Generate test code by recording actions
cd app/frontend && npx playwright codegen http://localhost:3000

Playwright Screenshot Workflow

When a frontend change affects visual appearance:

# 1. Run tests to capture screenshots
cd app/frontend && npx playwright test e2e/<feature>.spec.ts

# 2. Screenshots saved to:
#    app/frontend/e2e/__screenshots__/

# 3. Review screenshots visually
open app/frontend/e2e/__screenshots__/<name>.png

# 4. If screenshots look correct, update baselines
cd app/frontend && npx playwright test --update-snapshots

In your E2E test, capture screenshots at key points:

// After important UI state changes
await page.screenshot({
  path: 'e2e/__screenshots__/feature-state-name.png',
  fullPage: false,
});

// For visual comparison tests
await expect(page).toHaveScreenshot('expected-state.png', {
  maxDiffPixelRatio: 0.01,
});

Debug Flow

# Vitest: verbose output
cd app/frontend && npx vitest run src/<path>.test.ts --reporter=verbose

# Playwright: headed browser + slow motion
cd app/frontend && npx playwright test e2e/<test>.spec.ts --headed --slow-mo=500

# Playwright: trace viewer (captures timeline of all actions)
cd app/frontend && npx playwright test e2e/<test>.spec.ts --trace on
# View trace:
cd app/frontend && npx playwright show-trace test-results/<test>/trace.zip

# Playwright: debug mode (opens inspector)
cd app/frontend && PWDEBUG=1 npx playwright test e2e/<test>.spec.ts

Project-Specific Patterns

Vitest Config

• Environment: jsdom (browser APIs simulated)
• Globals: true (describe/it/expect available without import)
• Setup: src/test/setup.ts (imports @testing-library/jest-dom)
• Path alias: @ → src/

Playwright Config

• Browser: Chromium only
• Base URL: http://localhost:3000
• Timeout: 30s per test
• Screenshots: only on failure
• Traces: on first retry

Mocking API Calls

// Vitest: mock fetch
vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
  ok: true,
  json: () => Promise.resolve({ data: 'mocked' }),
}));

// Playwright: intercept network requests
await page.route('**/api/v1/projects', (route) =>
  route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify({ projects: [] }),
  })
);

Testing Zustand Stores

import { useCanvasStore } from '@/stores/canvasStore';

// Reset store between tests
beforeEach(() => {
  useCanvasStore.setState(useCanvasStore.getInitialState());
});

it('should update nodes', () => {
  const { addNode } = useCanvasStore.getState();
  addNode({ id: '1', type: 'card', title: 'Test' });

  const { nodes } = useCanvasStore.getState();
  expect(nodes).toHaveLength(1);
});

Testing with Konva Canvas

Konva doesn't render in jsdom. For canvas logic:

• Test the data/state layer with Vitest (store operations, layout algorithms)
• Test the visual layer with Playwright (actual rendering in browser)

Auth in E2E Tests

Auth is bypassed in dev mode (AUTH_BYPASS_ENABLED=true). Playwright tests hit localhost directly — no login required.

If testing auth flows specifically:

// Test guest login
await page.goto('/login');
await page.click('[data-testid="guest-login"]');
await page.waitForURL('/dashboard');

Checklist Before Done

• Test plan documented in docs/testing/plans/
• Tests written BEFORE implementation
• Test saw RED before GREEN
• Vitest tests pass: make test-frontend-unit
• Playwright tests pass: make test-frontend-e2e (if E2E added)
• Screenshots captured and reviewed (if visual change)
• Test IDs registered in docs/testing/test-registry.md
• Lint passes: cd app/frontend && npx eslint src/ --max-warnings=0