REQUIRED when modifying any file in packages/playground-ui or packages/playground. Triggers on: React component creation/modification/refactoring, UI changes, new playground features, bug fixes affecting studio UI. Generates Playwright E2E tests that validate PRODUCT BEHAVIOR, not just UI states.

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. Rules: One outer test.describe per file naming the unit. Every leaf test lives inside a test.describe('when …') precondition group. No top level flat test() . Split a multi assertion test() only where assertions represent distinct outcomes ; keep tightly coupled assertions that prove a single outcome together. Never drop an assertion. Place beforeEach / afterEach in the narrowest describe scope that needs them. Prerequisites Requires Playwright MCP server. If the browser navigate tool is unavailable, instruct the user to add it: Step 1: Understand the Feature Intent Before writing ANY test, answer these questions: 1. What user problem does this feature solve? 2. What is the expected outcome when the feature works correctly? 3. What data flows through the system? (user input → API → state → UI) 4. What should persist after page reload? 5. What downstream effects should this action have? Document these answers as comments in your test file. Step 2: Build and Start Verify server at http://localhost:4111 Step 3: Map Feature to Behavior Tests Feature to Test Mapping Guide Feature Category What to Test Example Assertion Agent Configuration Config changes affect agent behavior Send message → verify response uses selected model LLM Provider Selection Selected provider is used in requests Intercept API call → verify provider in request payload Tool Execution Tool runs with correct params & returns result Execute tool → verify output matches expected transformation Workflow Execution Steps execute in order, data flows between steps Run workflow → verify each step's output feeds next step Chat/Streaming Messages persist, context maintained across turns Multi turn conversation → verify context awareness MCP Server Tools Server tools are callable and return data Call MCP tool → verify response structure and content Memory/Persistence Data survives page reload Create item → reload → verify item exists Error Handling Errors surface correctly to user Trigger error condition → verify error message + recovery Step 4: Write Behavior Focused Tests Test Structure Template Behavior Test Patterns Pattern 1: Configuration Affects Behavior Pattern 2: Data Persistence Pattern 3: Tool Execution Produces Correct Output Pattern 4: Workflow Step Chaining Pattern 5: Streaming Chat with Context Pattern 6: Error Recovery Step 5: Update Existing Tests When a test file already exists: 1. Read the existing tests to understand current coverage 2. Identify if tests are UI focused or behavior focused 3. Refactor UI focused tests to verify behavior instead: Refactoring Example BEFORE (UI focused): AFTER (Behavior focused + BDD nesting): Step 6: Kitchen Sink Fixtures for Behavior Testing Fixtures should represent realistic scenarios , not just mock data: Fixture Naming Convention Fixture Content Requirements Each fixture must define: 1. Scenario description (what behavior it enables testing) 2. Expected outcomes (what assertions should pass) 3. Edge cases covered (error states, empty states, etc.) Step 7: Run and Validate Test Quality Checklist Before considering tests complete, verify: [ ] Each test has a clear user story comment [ ] One outer test.describe names the unit under test [ ] Every test is nested in a test.describe('when …') precondition block (no flat top level test() ) [ ] Each test asserts exactly ONE observable outcome [ ] Tests verify OUTCOMES, not intermediate UI states [ ] Tests would FAIL if the feature broke (not just if UI changed) [ ] Persistence is verified via page.reload() where applicable [ ] Error scenarios are covered [ ] Tests use appropriate timeouts for async operations [ ] Fixtures represent realistic usage scenarios Quick Reference Step Command/Action Build pnpm build:cli Start cd packages/playground/e2e/kitchen sink && pnpm dev App URL http://localhost:4111 Routes @packages/playground/src/App.tsx Run tests cd packages/playground && pnpm test:e2e Test dir packages/playground/e2e/tests/ Fixtures packages/playground/e2e/kitchen sink/fixtures/ Anti Patterns to Avoid ❌ Don't ✅ Do Instead Test that modal opens Test that modal action completes and persists Test that button is clickable Test that clicking button produces expected result Test loading spinner appears Test that loaded data is correct Test form validation message shows Test that invalid form cannot submit AND valid form succeeds Test dropdown has options Test that selecting option changes system behavior Test sidebar navigation works Test that navigated page has correct data/functionality Assert element is visible Assert element contains expected data/state Top level flat test() with no precondition describe Nest every test in a test.describe('when …') block One test() asserting several unrelated outcomes One test() per observable outcome

e2e-tests-studio