e2e-frontend-validation（e2e 前端验证）

E2E Validation for Frontend Modifications

Prerequisites

Requires Playwright MCP server. If the browser_navigate tool is unavailable, instruct the user to add it:

claude mcp add playwright -- npx @playwright/mcp@latest

Validation Steps

After completing frontend changes:

1. Build the CLI

pnpm build:cli

1. Start the dev server

cd packages/playground/e2e/kitchen-sink && pnpm dev

1. Verify server is running

- URL: http://localhost:4111 - Wait for the server to be ready before proceeding

1. Identify impacted routes

- Routes are defined in packages/playground/src/App.tsx - Browse them ALL to verify behavior

1. Test with Playwright MCP

- Use browser_navigate to visit each impacted route - Visually verify the changes render correctly - Test any interactive elements modified - Use browser_screenshot to capture results for the user

1. Write E2E Tests Write Playwright tests covering the validated behavior. Follow the conventions below. File Placement Map validated routes to test file paths under packages/playground/e2e/tests/: Route pattern Test file /agents agents/page.spec.ts /agents/:id/... agents/$agentId/page.spec.ts /agents/:id/chat/:chatId agents/$agentId/stream.spec.ts (if streaming) /tools tools/page.spec.ts /tools/:id tools/$toolId/page.spec.ts /workflows workflows/page.spec.ts /workflows/:id workflows/$workflowId/page.spec.ts /mcps mcps/page.spec.ts /mcps/:id/tools/:toolId mcps/$serverId/tools/$toolId/page.spec.ts New File vs Extend Existing Fixture Decision Tree Test Conventions // Imports import {test, expect} from '@playwright/test'; import {resetStorage} from '../__utils__/reset-storage'; // Only for streaming tests: import {selectFixture} from '../__utils__/select-fixture'; import {nanoid} from 'nanoid'; Kitchen-Sink Extension When the feature under test requires new fixtures or entities:

- Layout/navigation tests → page.spec.ts - Streaming/chat tests → stream.spec.ts - If the spec file already exists, add new test() blocks to it. - If it doesn't exist, create a new file with the full boilerplate (imports, afterEach hook, etc.). - AI streaming responses (text-delta, tool calls, workflow execution) → use selectFixture() + nanoid() for deterministic, isolated tests - Static UI, navigation, forms, deterministic tool execution → no fixture needed - Always call resetStorage() in test.afterEach - For streaming tests, create a fresh browser context in test.beforeEach: let page: Page; test.beforeEach(async ({browser}) => {const context = await browser.newContext(); page = await context.newPage();}); - Locator priority: getByTestId > getByRole > getByLabel > locator('text=...') - Use {timeout: 20000} for async/streaming content assertions - Use nanoid() for unique chat session IDs in URLs - Verify memory persistence with page.reload() where applicable - Use toMatchAriaSnapshot() for stable layout assertions - New fixtures: Add to e2e/kitchen-sink/fixtures/, create a <name>.fixture.ts file, and register it in fixtures/index.ts - Update types: Add the fixture name to the Fixtures union in e2e/kitchen-sink/types.ts and e2e/tests/__utils__/select-fixture.ts - New tools/agents/workflows: Add to the corresponding files in e2e/kitchen-sink/src/mastra/

1. Verify Tests Pass cd packages/playground && pnpm test:e2e If tests fail, fix them and re-run until green.

Quick Reference