E2E Behavior Validation for Frontend Modifications

Core Principle: Test Product Behavior, Not UI States

CRITICAL: Tests must verify that product features WORK correctly, not just that UI elements render.

What NOT to test (UI States):

• ❌ "Dropdown opens when clicked"
• ❌ "Modal appears after button click"
• ❌ "Loading spinner shows during request"
• ❌ "Form fields are visible"
• ❌ "Sidebar collapses"

What TO test (Product Behavior):

• ✅ "Selecting an LLM provider configures the agent to use that provider"
• ✅ "Creating a new agent persists it and shows in the agents list"
• ✅ "Running a tool with parameters returns the expected output"
• ✅ "Chat messages stream correctly and maintain conversation context"
• ✅ "Workflow execution triggers tools in the correct order"

BDD Structure (REQUIRED)

Every E2E spec MUST follow the same BDD shape as the MSW tests. In packages/playground, e2e-bdd/test-needs-when-describe enforces this shape.

The structure has exactly three levels:

1. Outer test.describe = the unit under test (one page or feature per file).
2. Inner test.describe('when …') = exactly ONE precondition. The title MUST start with when.
3. Each test = exactly ONE observable outcome.

import { test, expect } from '@playwright/test';
import { resetStorage } from '../__utils__/reset-storage';

test.describe('Tools list page', () => {
  // the unit
  test.afterEach(async () => {
    await resetStorage();
  });

  test.describe('when a registered tool is clicked', () => {
    // ONE precondition (starts with "when")
    test('navigates to that tool detail page', async ({ page }) => {
      // ONE outcome
      await page.goto('/tools');
      await page.locator('text=Get current weather for a location').click();
      await expect(page).toHaveURL(/\/tools\/weatherInfo$/);
    });