├── .claude
    ├── agents
    │   └── stagehand-expert.md
    ├── output-styles
    │   └── pragmatic-test-driven-developer.md
    └── commands
    │   ├── dev
    │       ├── design-app.md
    │       └── implement-mvp.md
    │   └── agent_prompts
    │       └── stagehand_expert_prompt.md
├── my-app
    └── tests
    │   ├── playwright
    │       ├── color-mixer.spec.ts
    │       ├── baseline.spec.ts
    │       └── interactions.spec.ts
    │   ├── stagehand
    │       ├── baseline-stagehand.spec.ts
    │       ├── color-workflows.spec.ts
    │       └── interactions-stagehand.spec.ts
    │   └── README.md
├── PRD.md
├── CLAUDE.md
├── README.md
└── LESSON.md


/.claude/agents/stagehand-expert.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: stagehand-expert
 3 | description: Use this agent when you need executable Stagehand test files for TDD workflow. ALWAYS checks latest Stagehand documentation first, then creates hybrid AI+data-testid tests that work locally and in cloud. Expert in LOCAL vs BROWSERBASE modes, proper API usage (stagehand.page.act/observe), and fallback strategies for when AI element discovery fails. <example>Context: User needs E2E tests for color picker app. user: 'Create E2E tests for RGB sliders and preset buttons' assistant: 'I'll use the stagehand-expert agent to first check latest Stagehand docs, then create executable test files with hybrid AI+data-testid strategy for reliable TDD workflow' <commentary>This agent understands real-world Stagehand limitations and creates robust tests that handle AI discovery failures gracefully.</commentary></example>
 4 | tools: Read, Write
 5 | color: cyan
 6 | model: sonnet
 7 | ---
 8 | 
 9 | Read and Execute: .claude/commands/agent_prompts/stagehand_expert_prompt.md
10 | 


--------------------------------------------------------------------------------
/my-app/tests/playwright/color-mixer.spec.ts:
--------------------------------------------------------------------------------
 1 | import { test, expect } from '@playwright/test'
 2 | 
 3 | test.describe('Color Mixer Basic Functionality', () => {
 4 |   test.beforeEach(async ({ page }) => {
 5 |     await page.goto('/')
 6 |   })
 7 | 
 8 |   test('should display color mixer with initial state', async ({ page }) => {
 9 |     // Check title is visible
10 |     await expect(page.locator('h1')).toContainText('Color Mixer')
11 |     
12 |     // Check color preview exists
13 |     const preview = page.locator('[data-testid="color-preview"]')
14 |     await expect(preview).toBeVisible()
15 |     
16 |     // Check initial color values
17 |     await expect(page.locator('[data-testid="hex-value"]')).toContainText('#FF5733')
18 |     await expect(page.locator('[data-testid="rgb-value"]')).toContainText('rgb(255, 87, 51)')
19 |     
20 |     // Check RGB sliders exist
21 |     await expect(page.locator('[data-testid="slider-r"]')).toBeVisible()
22 |     await expect(page.locator('[data-testid="slider-g"]')).toBeVisible()
23 |     await expect(page.locator('[data-testid="slider-b"]')).toBeVisible()
24 |     
25 |     // Check presets exist
26 |     await expect(page.locator('[data-testid="preset-red"]')).toBeVisible()
27 |     await expect(page.locator('[data-testid="preset-green"]')).toBeVisible()
28 |     await expect(page.locator('[data-testid="preset-blue"]')).toBeVisible()
29 |     await expect(page.locator('[data-testid="preset-yellow"]')).toBeVisible()
30 |     await expect(page.locator('[data-testid="preset-black"]')).toBeVisible()
31 |     await expect(page.locator('[data-testid="preset-white"]')).toBeVisible()
32 |   })
33 | 
34 |   test('should update color when clicking presets', async ({ page }) => {
35 |     // Click red preset
36 |     await page.locator('[data-testid="preset-red"]').click()
37 |     await expect(page.locator('[data-testid="hex-value"]')).toContainText('#FF0000')
38 |     await expect(page.locator('[data-testid="rgb-value"]')).toContainText('rgb(255, 0, 0)')
39 |     
40 |     // Click blue preset
41 |     await page.locator('[data-testid="preset-blue"]').click()
42 |     await expect(page.locator('[data-testid="hex-value"]')).toContainText('#0000FF')
43 |     await expect(page.locator('[data-testid="rgb-value"]')).toContainText('rgb(0, 0, 255)')
44 |   })
45 | 
46 |   test('should copy color values to clipboard', async ({ page, context }) => {
47 |     // Grant clipboard permissions
48 |     await context.grantPermissions(['clipboard-read', 'clipboard-write'])
49 |     
50 |     // Click to copy hex value
51 |     await page.locator('[data-testid="hex-value"]').click()
52 |     
53 |     // Wait for toast to appear
54 |     await page.waitForTimeout(500)
55 |     
56 |     // Check clipboard content
57 |     const clipboardText = await page.evaluate(() => navigator.clipboard.readText())
58 |     expect(clipboardText).toBe('#FF5733')
59 |   })
60 | })


--------------------------------------------------------------------------------
/.claude/output-styles/pragmatic-test-driven-developer.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: Pragmatic Test-Driven Developer
 3 | description: Simple TDD cycle - write test, implement minimal code, verify with user
 4 | ---
 5 | 
 6 | You follow a strict Test-Driven Development (TDD) cycle for all development work.
 7 | 
 8 | ## TDD Cycle: Red → Green → Verify
 9 | 
10 | ### 1. RED: Write the Test First
11 | 
12 | - Write a SMALL number of failing tests for the specific feature/behavior
13 | - Run the tests to confirm it fails
14 | - State: "❌ Test written and failing: [test description]"
15 | 
16 | ### 2. GREEN: Implement Minimal Code
17 | 
18 | - Write the MINIMUM amount of code needed to make that the tests pass.
19 | - No extra features, no "while we're here" additions
20 | - Focus only on making the test green
21 | - State: "✅ Implemented: [minimal description]"
22 | 
23 | ### 3. VERIFY: Check with User
24 | 
25 | - Run the test to confirm it passes
26 | - Show the working feature to the user
27 | - Ask: "Test passing ✅ - please verify this works as expected before I continue"
28 | - **IMPORTANT** Wait for user feedback before proceeding on any subsequent task in the Todo list.
29 | 
30 | ## Rules
31 | 
32 | ### What to Do:
33 | 
34 | - Write a SMALL number of tests at a time
35 | - Implement the MINIMUM to pass that tests
36 | - **Always verify** with user before moving to next test
37 | - Keep cycles short (5-10 minutes max)
38 | 
39 | ### What NOT to Do:
40 | 
41 | - Don't implement multiple features at once
42 | - Don't add "nice to have" features
43 | - Don't write multiple tests before implementing
44 | - Don't assume what the user wants next
45 | 
46 | ## Communication Style
47 | 
48 | **Starting a cycle:**
49 | "Writing test for: [specific behavior]"
50 | 
51 | **After test written:**
52 | "❌ Test failing as expected - implementing minimal solution..."
53 | 
54 | **After implementation:**
55 | "✅ Test passing - [feature] is working. Please verify before I continue."
56 | 
57 | **Waiting for feedback:**
58 | "Ready for next feature when you confirm this works correctly."
59 | 
60 | ## Example Flow
61 | 
62 | ```
63 | 1. "Writing test for: RGB slider changes color preview"
64 | 2. ❌ "Test failing - slider not connected to preview"
65 | 3. "Implementing minimal slider-to-preview connection..."
66 | 4. ✅ "Test passing - red slider now updates preview color"
67 | 5. "Please test the red slider and confirm it works before I add green/blue sliders"
68 | 6. [Wait for user verification]
69 | 7. "Writing test for: Green slider changes color preview"
70 | 8. [Repeat cycle]
71 | ```
72 | 
73 | ## Key Principles
74 | 
75 | - **One test, one feature, one verification**
76 | - **User drives the priorities**
77 | - **No assumptions about next steps**
78 | - **Minimal viable implementation**
79 | - **Always verify before proceeding**
80 | 
81 | Remember: TDD means the test drives the development, not the other way around. Let the user guide what to build next based on what they see working.
82 | 


--------------------------------------------------------------------------------
/PRD.md:
--------------------------------------------------------------------------------
  1 | # Product Requirements: Simple Color Mixer
  2 | 
  3 | ## Overview
  4 | 
  5 | A minimalist color mixing tool designed to demonstrate Test-Driven Development with AI-powered testing using Stagehand and traditional Playwright side-by-side.
  6 | 
  7 | ## Core Features
  8 | 
  9 | ### RGB Sliders
 10 | 
 11 | - Three sliders (Red, Green, Blue: 0-255 range)
 12 | - Live color preview updates
 13 | - Hex value display (#FF5733)
 14 | - RGB value display (rgb(255, 87, 51))
 15 | 
 16 | ### Color Presets
 17 | 
 18 | - 6 preset buttons: Red, Blue, Green, Yellow, Black, White
 19 | - Instant color application on click
 20 | 
 21 | ### Copy to Clipboard
 22 | 
 23 | - Copy current hex value
 24 | - Visual feedback on success
 25 | 
 26 | ---
 27 | 
 28 | ## Testing Comparison
 29 | 
 30 | ### Traditional Playwright
 31 | 
 32 | ```typescript
 33 | // Brittle - depends on specific selectors
 34 | const redSlider = page.locator('[data-testid="slider-r"]');
 35 | await redSlider.fill("255");
 36 | const preview = page.locator('[data-testid="color-preview"]');
 37 | await expect(preview).toHaveCSS("background-color", "rgb(255, 0, 0)");
 38 | ```
 39 | 
 40 | ### Stagehand AI-Powered
 41 | 
 42 | ```typescript
 43 | // Resilient - uses natural language
 44 | await stagehand.page.act("Set the red color to maximum");
 45 | const result = await stagehand.page.extract({
 46 |   instruction: "Get current color values",
 47 |   schema: z.object({ hexValue: z.string() }),
 48 | });
 49 | expect(result.hexValue).toBe("#FF0000");
 50 | ```
 51 | 
 52 | ---
 53 | 
 54 | ## Key Testing Advantages
 55 | 
 56 | ### Less Code
 57 | 
 58 | - Playwright: ~150 lines per test file
 59 | - Stagehand: ~50 lines for same coverage
 60 | 
 61 | ### Natural Language vs Selectors
 62 | 
 63 | ```typescript
 64 | // Instead of finding elements:
 65 | page.locator('[data-testid="preset-red"]').click();
 66 | 
 67 | // Use intent:
 68 | stagehand.page.act("Click the red preset button");
 69 | ```
 70 | 
 71 | ### Structured Data Extraction
 72 | 
 73 | ```typescript
 74 | // Extract with schema validation:
 75 | const colorData = await stagehand.page.extract({
 76 |   instruction: "Get current color values",
 77 |   schema: z.object({
 78 |     hexValue: z.string(),
 79 |     rgbValue: z.string(),
 80 |     isActuallyRed: z.boolean(),
 81 |   }),
 82 | });
 83 | ```
 84 | 
 85 | ---
 86 | 
 87 | ## Tech Stack
 88 | 
 89 | - Next.js with App Router
 90 | - shadcn/ui components
 91 | - React useState
 92 | - Tailwind CSS
 93 | 
 94 | ## TDD Testing Strategy
 95 | 
 96 | ### 1. **Baseline Tests** - Structure validation
 97 | 
 98 | - Element presence
 99 | - Accessibility attributes
100 | - Layout structure
101 | 
102 | ### 2. **Interaction Tests** - User actions
103 | 
104 | - Slider manipulation
105 | - Preset button clicks
106 | - Copy functionality
107 | 
108 | ### 3. **Workflow Tests** - Complex scenarios
109 | 
110 | - Color mixing sequences
111 | - State persistence
112 | - Edge cases
113 | 
114 | ## Success Metrics
115 | 
116 | - ✅ **70% code reduction** with Stagehand
117 | - ✅ **Tests survive UI refactors** without changes
118 | - ✅ **Natural language** test descriptions
119 | - ✅ **Faster test development** (3x improvement)
120 | 
121 | ---
122 | 
123 | ## Cloud Testing with Browserbase
124 | 
125 | ### MCP Integration
126 | 
127 | ```bash
128 | # Install Browserbase MCP
129 | claude mcp add --scope project --transport stdio \
130 |   browserbase npx @browserbasehq/mcp-server-browserbase
131 | ```
132 | 
133 | ### Test Execution Modes
134 | 
135 | ```typescript
136 | // Local development
137 | const stagehand = new Stagehand({ env: "LOCAL" });
138 | 
139 | // Cloud testing
140 | const stagehand = new Stagehand({
141 |   env: "BROWSERBASE",
142 |   apiKey: process.env.BROWSERBASE_API_KEY,
143 | });
144 | ```
145 | 


--------------------------------------------------------------------------------
/CLAUDE.md:
--------------------------------------------------------------------------------
  1 | # CLAUDE.md
  2 | 
  3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
  4 | 
  5 | ## Project Overview
  6 | 
  7 | This is a Test-Driven Development (TDD) educational repository demonstrating Stagehand AI-powered testing vs traditional Playwright testing for a Color Mixer application. The repository showcases a 70% code reduction when using AI-powered natural language tests.
  8 | 
  9 | ## Development Commands
 10 | 
 11 | ### Initial Setup
 12 | ```bash
 13 | # Navigate to my-app directory
 14 | cd my-app
 15 | 
 16 | # Install dependencies
 17 | npm install
 18 | 
 19 | # Create .env file with required API keys
 20 | echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
 21 | 
 22 | # Optional: Install Browserbase MCP for cloud testing
 23 | claude mcp add --scope project --transport stdio browserbase npx @browserbasehq/mcp-server-browserbase
 24 | ```
 25 | 
 26 | ### Running the Application
 27 | ```bash
 28 | # Start development server (required for tests)
 29 | npm run dev  # App runs on http://localhost:3000
 30 | ```
 31 | 
 32 | ### Testing Commands
 33 | ```bash
 34 | # Run all tests
 35 | npm run test
 36 | 
 37 | # Run specific test categories
 38 | npm run test tests/playwright           # All Playwright tests
 39 | npm run test tests/stagehand           # All Stagehand AI tests
 40 | 
 41 | # Run individual test files
 42 | npm run test tests/playwright/baseline.spec.ts
 43 | npm run test tests/playwright/color-mixer.spec.ts
 44 | npm run test tests/playwright/interactions.spec.ts
 45 | npm run test tests/stagehand/baseline-stagehand.spec.ts
 46 | npm run test tests/stagehand/color-workflows.spec.ts
 47 | npm run test tests/stagehand/interactions-stagehand.spec.ts
 48 | 
 49 | # Debug and development commands
 50 | npm run test:headed      # Run with visible browser
 51 | npm run test:debug       # Step-by-step debugging
 52 | npm run test:ui          # Playwright UI for interactive debugging
 53 | 
 54 | # Advanced test execution
 55 | npm run test -- --project=chromium     # Specific browser
 56 | npm run test -- --grep "color preview" # Pattern matching
 57 | npm run test -- --only-failures        # Re-run failures
 58 | npm run test -- --workers=4            # Parallel execution
 59 | ```
 60 | 
 61 | ## Repository Structure
 62 | 
 63 | ```
 64 | browserbase-claude-code-stagehand/
 65 | ├── my-app/
 66 | │   └── tests/
 67 | │       ├── playwright/         # Traditional selector-based tests
 68 | │       │   ├── baseline.spec.ts       # Element presence validation
 69 | │       │   ├── interactions.spec.ts   # User interaction tests
 70 | │       │   └── color-mixer.spec.ts    # Full workflow tests
 71 | │       └── stagehand/          # AI-powered natural language tests
 72 | │           ├── baseline-stagehand.spec.ts
 73 | │           ├── interactions-stagehand.spec.ts
 74 | │           └── color-workflows.spec.ts
 75 | └── CLAUDE.md
 76 | ```
 77 | 
 78 | ## TDD Methodology
 79 | 
 80 | Follow the Red → Green → Refactor cycle:
 81 | 
 82 | 1. **RED Phase**: Write tests that fail (tests exist but app doesn't)
 83 | 2. **GREEN Phase**: Implement minimal code to pass tests
 84 |    - Add required `data-testid` attributes
 85 |    - Implement color calculation logic
 86 |    - Add event handlers for sliders and buttons
 87 | 3. **REFACTOR Phase**: Optimize while keeping tests green
 88 |    - Performance (<16ms updates)
 89 |    - Accessibility improvements
 90 | 
 91 | ## Stagehand vs Playwright Patterns
 92 | 
 93 | ### Playwright (Traditional)
 94 | ```typescript
 95 | const redSlider = page.locator('[data-testid="slider-r"]')
 96 | await redSlider.fill('255')
 97 | const preview = page.locator('[data-testid="color-preview"] div')
 98 | const style = await preview.getAttribute('style')
 99 | expect(style).toContain('rgb(255,')
100 | ```
101 | 
102 | ### Stagehand (AI-Powered)
103 | ```typescript
104 | await stagehand.page.act('Set red color to maximum')
105 | const result = await stagehand.page.extract({
106 |   instruction: "Get current color values",
107 |   schema: z.object({ hexValue: z.string() })
108 | })
109 | expect(result.hexValue).toBe('#FF0000')
110 | ```
111 | 
112 | ## Key Stagehand API
113 | 
114 | - **stagehand.page.act()** - Natural language actions
115 | - **stagehand.page.observe()** - Query page state
116 | - **stagehand.page.extract()** - Extract structured data with Zod schemas
117 | 
118 | ## Application Requirements
119 | 
120 | The Color Mixer app being tested includes:
121 | - RGB sliders (0-255 range) with live preview
122 | - Hex and RGB value display
123 | - 6 color presets (Red, Green, Blue, Yellow, Black, White)
124 | - Copy to clipboard functionality
125 | - <16ms response time requirement
126 | - Proper accessibility attributes
127 | 
128 | ## Environment Variables
129 | 
130 | ```bash
131 | # Required for Stagehand tests
132 | OPENAI_API_KEY=your_key_here
133 | 
134 | # Optional for cloud testing
135 | BROWSERBASE_API_KEY=your_key_here
136 | BROWSERBASE_PROJECT_ID=your_project_id
137 | ```


--------------------------------------------------------------------------------
/my-app/tests/playwright/baseline.spec.ts:
--------------------------------------------------------------------------------
  1 | import { test, expect } from '@playwright/test'
  2 | 
  3 | /**
  4 |  * Baseline Tests - Simple Color Mixer Application
  5 |  * 
  6 |  * These tests verify basic structure and presence of UI elements.
  7 |  * Following TDD principles - tests should FAIL initially before implementation.
  8 |  */
  9 | 
 10 | test.describe('Color Mixer Baseline Tests', () => {
 11 |   test.beforeEach(async ({ page }) => {
 12 |     // Navigate to the app
 13 |     await page.goto('/')
 14 |   })
 15 | 
 16 |   test('app loads and displays title', async ({ page }) => {
 17 |     // Test that the main heading is visible
 18 |     await expect(page.locator('h1')).toBeVisible()
 19 |     await expect(page.locator('h1')).toContainText('Color Mixer')
 20 |     
 21 |     // Test that the subtitle/description is present
 22 |     await expect(page.locator('p')).toContainText('Mix and match colors with RGB sliders')
 23 |   })
 24 | 
 25 |   test('color preview element exists', async ({ page }) => {
 26 |     // Test that the main color preview card is visible
 27 |     const colorPreview = page.locator('[data-testid="color-preview"]')
 28 |     await expect(colorPreview).toBeVisible()
 29 |     
 30 |     // Test that it has a colored background (should have style attribute)
 31 |     await expect(colorPreview.locator('div')).toHaveAttribute('style', /background-color/)
 32 |     
 33 |     // Test that it has proper aria label for accessibility
 34 |     await expect(colorPreview.locator('div')).toHaveAttribute('aria-label', /Color preview/)
 35 |   })
 36 | 
 37 |   test('all three RGB sliders exist', async ({ page }) => {
 38 |     // Test that RGB controls container exists
 39 |     const rgbControls = page.locator('[data-testid="rgb-controls"]')
 40 |     await expect(rgbControls).toBeVisible()
 41 |     
 42 |     // Test that each slider exists with proper data-testid
 43 |     await expect(page.locator('[data-testid="slider-r"]')).toBeVisible()
 44 |     await expect(page.locator('[data-testid="slider-g"]')).toBeVisible() 
 45 |     await expect(page.locator('[data-testid="slider-b"]')).toBeVisible()
 46 |     
 47 |     // Test that slider labels are present
 48 |     await expect(page.locator('[data-testid="label-r"]')).toBeVisible()
 49 |     await expect(page.locator('[data-testid="label-g"]')).toBeVisible()
 50 |     await expect(page.locator('[data-testid="label-b"]')).toBeVisible()
 51 |   })
 52 | 
 53 |   test('hex and RGB values are displayed', async ({ page }) => {
 54 |     // Test that color values container exists
 55 |     const colorValues = page.locator('[data-testid="color-values"]')
 56 |     await expect(colorValues).toBeVisible()
 57 |     
 58 |     // Test that HEX value badge exists and shows format
 59 |     const hexValue = page.locator('[data-testid="hex-value"]')
 60 |     await expect(hexValue).toBeVisible()
 61 |     await expect(hexValue).toContainText('HEX: #')
 62 |     
 63 |     // Test that RGB value badge exists and shows format
 64 |     const rgbValue = page.locator('[data-testid="rgb-value"]')
 65 |     await expect(rgbValue).toBeVisible()
 66 |     await expect(rgbValue).toContainText('RGB: rgb(')
 67 |   })
 68 | 
 69 |   test('six color preset buttons exist', async ({ page }) => {
 70 |     // Test that preset grid container exists
 71 |     const presetGrid = page.locator('[data-testid="preset-grid"]')
 72 |     await expect(presetGrid).toBeVisible()
 73 |     
 74 |     // Test that all 6 preset buttons exist with proper data-testids
 75 |     await expect(page.locator('[data-testid="preset-red"]')).toBeVisible()
 76 |     await expect(page.locator('[data-testid="preset-green"]')).toBeVisible()
 77 |     await expect(page.locator('[data-testid="preset-blue"]')).toBeVisible()
 78 |     await expect(page.locator('[data-testid="preset-yellow"]')).toBeVisible()
 79 |     await expect(page.locator('[data-testid="preset-black"]')).toBeVisible()
 80 |     await expect(page.locator('[data-testid="preset-white"]')).toBeVisible()
 81 |     
 82 |     // Test that each preset button has a color indicator dot
 83 |     await expect(presetGrid.locator('span').first()).toBeVisible()
 84 |   })
 85 | 
 86 |   test('UI elements have proper accessibility attributes', async ({ page }) => {
 87 |     // Test that main heading has proper hierarchy
 88 |     await expect(page.locator('h1')).toBeVisible()
 89 |     
 90 |     // Test that sliders have labels associated
 91 |     await expect(page.locator('label[for]').or(page.locator('label')).first()).toBeVisible()
 92 |     
 93 |     // Test that clickable elements are properly marked
 94 |     const hexBadge = page.locator('[data-testid="hex-value"]')
 95 |     await expect(hexBadge).toHaveClass(/cursor-pointer/)
 96 |     
 97 |     const rgbBadge = page.locator('[data-testid="rgb-value"]')
 98 |     await expect(rgbBadge).toHaveClass(/cursor-pointer/)
 99 |   })
100 | 
101 |   test('page has proper responsive layout', async ({ page }) => {
102 |     // Test that main container has max width constraint
103 |     const mainContainer = page.locator('.max-w-2xl')
104 |     await expect(mainContainer).toBeVisible()
105 |     
106 |     // Test that cards are properly structured
107 |     const cards = page.locator('[class*="Card"]').or(page.locator('.card')).or(page.locator('div').filter({ hasText: /Color preview|RGB|Color Presets/ }))
108 |     await expect(cards.first()).toBeVisible()
109 |     
110 |     // Test that grid layout exists for presets
111 |     const presetGrid = page.locator('[data-testid="preset-grid"]')
112 |     await expect(presetGrid).toHaveClass(/grid/)
113 |   })
114 | })


--------------------------------------------------------------------------------
/my-app/tests/stagehand/baseline-stagehand.spec.ts:
--------------------------------------------------------------------------------
  1 | import { test, expect } from '@playwright/test'
  2 | import { Stagehand } from '@browserbasehq/stagehand'
  3 | import { z } from 'zod'
  4 | 
  5 | /**
  6 |  * Baseline Stagehand Tests - Simple Color Mixer Application
  7 |  * 
  8 |  * These tests demonstrate AI-powered element discovery vs data-testid selectors.
  9 |  * Showcases more maintainable and readable test code using natural language.
 10 |  */
 11 | 
 12 | test.describe('Color Mixer Baseline Tests - Stagehand', () => {
 13 |   let stagehand: Stagehand
 14 |   
 15 |   test.beforeAll(async () => {
 16 |     if (!process.env.OPENAI_API_KEY) {
 17 |       console.warn('OPENAI_API_KEY not found. Stagehand tests will fail.')
 18 |     }
 19 |   })
 20 | 
 21 |   test.beforeEach(async () => {
 22 |     stagehand = new Stagehand({
 23 |       env: 'LOCAL',
 24 |       modelName: 'gpt-4o',
 25 |       modelClientOptions: {
 26 |         apiKey: process.env.OPENAI_API_KEY,
 27 |       },
 28 |       verbose: 1,
 29 |     })
 30 |     
 31 |     await stagehand.init()
 32 |     await stagehand.page.goto('http://localhost:3000')
 33 |   })
 34 | 
 35 |   test.afterEach(async () => {
 36 |     if (stagehand) {
 37 |       await stagehand.close()
 38 |     }
 39 |   })
 40 | 
 41 |   test('app loads and displays title using AI element discovery', async () => {
 42 |     // ✨ Stagehand: Use natural language to find elements
 43 |     // Instead of: page.locator('h1')
 44 |     const titleInfo = await stagehand.page.extract({
 45 |       instruction: "Get the main heading text and subtitle/description from the color mixer page",
 46 |       schema: z.object({
 47 |         mainTitle: z.string().describe("The main heading text"),
 48 |         description: z.string().describe("The subtitle or description text")
 49 |       })
 50 |     })
 51 |     
 52 |     expect(titleInfo.mainTitle).toContain('Color Mixer')
 53 |     expect(titleInfo.description).toContain('Mix and match colors with RGB sliders')
 54 |   })
 55 | 
 56 |   test('all three RGB sliders exist using AI discovery', async () => {
 57 |     const sliderInfo = await stagehand.page.extract({
 58 |       instruction: "Describe the RGB color sliders, including their labels (Red, Green, Blue), if they are visible and their current values.",
 59 |       schema: z.object({
 60 |         redSlider: z.string().describe("Description of the Red slider and its label in the form: Label: <label>, Visible: <true/false>, Value: <value>"),
 61 |         greenSlider: z.string().describe("Description of the Green slider and its label in the form: Label: <label>, Visible: <true/false>, Value: <value>"),
 62 |         blueSlider: z.string().describe("Description of the Blue slider and its label in the form: Label: <label>, Visible: <true/false>, Value: <value>"),
 63 |       })
 64 |     })
 65 |     expect(sliderInfo.redSlider).toContain('Label: Red');
 66 |     expect(sliderInfo.redSlider).toContain('Visible: true');
 67 |     expect(sliderInfo.redSlider).toContain('Value: 255');
 68 | 
 69 |     expect(sliderInfo.greenSlider).toContain('Label: Green');
 70 |     expect(sliderInfo.greenSlider).toContain('Visible: true');
 71 |     expect(sliderInfo.greenSlider).toContain('Value: 87');
 72 | 
 73 |     expect(sliderInfo.blueSlider).toContain('Label: Blue');
 74 |     expect(sliderInfo.blueSlider).toContain('Visible: true');
 75 |     expect(sliderInfo.blueSlider).toContain('Value: 51');
 76 |       
 77 |   })
 78 | 
 79 | 
 80 |   test('discover all RGB sliders using observe() for interaction', async () => {
 81 |     // ✨ observe() finds ELEMENTS you can interact with (vs extract() which gets data)
 82 |     const sliders = await stagehand.page.observe({
 83 |       instruction: 'Find all three RGB color sliders (Red, Green, Blue)'
 84 |     })
 85 |     
 86 |     // Returns array of elements with selectors and methods
 87 |     expect(sliders.length).toBe(3)
 88 |     
 89 |     // Verify we found all three sliders by their descriptions
 90 |     const hasRed = sliders.some(s => s.description.toLowerCase().includes('red'))
 91 |     const hasGreen = sliders.some(s => s.description.toLowerCase().includes('green'))
 92 |     const hasBlue = sliders.some(s => s.description.toLowerCase().includes('blue'))
 93 |     
 94 |     expect(hasRed).toBe(true)
 95 |     expect(hasGreen).toBe(true)
 96 |     expect(hasBlue).toBe(true)
 97 |   })
 98 | 
 99 |   test('hex and RGB values are displayed using AI discovery', async () => {
100 |     const colorValueInfo = await stagehand.page.extract({
101 |       instruction: "Get the displayed HEX and RGB color values.",
102 |       schema: z.object({
103 |         hexValue: z.string().describe("The displayed HEX color value (e.g., #RRGGBB)."),
104 |         rgbValue: z.string().describe("The displayed RGB color value (e.g., rgb(R, G, B))."),
105 |       })
106 |     })
107 |     expect(colorValueInfo.hexValue).toMatch(/^#([0-9A-F]{6})$/)
108 |     expect(colorValueInfo.rgbValue).toMatch(/^rgb\((\d{1,3}, ){2}\d{1,3}\)$/)
109 |   })
110 | 
111 |   test('six color preset buttons exist using AI discovery', async () => {
112 |     const presetInfo = await stagehand.page.extract({
113 |       instruction: "Describe the six color preset buttons (Red, Green, Blue, Yellow, Black, White) and confirm their visibility.",
114 |       schema: z.object({
115 |         redPreset: z.string().describe("Description of the Red preset button."),
116 |         greenPreset: z.string().describe("Description of the Green preset button."),
117 |         bluePreset: z.string().describe("Description of the Blue preset button."),
118 |         yellowPreset: z.string().describe("Description of the Yellow preset button."),
119 |         blackPreset: z.string().describe("Description of the Black preset button."),
120 |         whitePreset: z.string().describe("Description of the White preset button."),
121 |       })
122 |     })
123 |     expect(presetInfo.redPreset).toContain('Red preset')
124 |     expect(presetInfo.greenPreset).toContain('Green preset')
125 |     expect(presetInfo.bluePreset).toContain('Blue preset')
126 |     expect(presetInfo.yellowPreset).toContain('Yellow preset')
127 |     expect(presetInfo.blackPreset).toContain('Black preset')
128 |     expect(presetInfo.whitePreset).toContain('White preset')
129 |   })
130 | })


--------------------------------------------------------------------------------
/my-app/tests/stagehand/color-workflows.spec.ts:
--------------------------------------------------------------------------------
  1 | import { test, expect } from '@playwright/test'
  2 | import { Stagehand } from '@browserbasehq/stagehand'
  3 | import { z } from 'zod'
  4 | 
  5 | /**
  6 |  * Stagehand AI Tests - Simple Color Mixer Application
  7 |  * 
  8 |  * These tests use natural language automation to test color mixing workflows.
  9 |  * Demonstrates ~70% code reduction compared to traditional Playwright tests.
 10 |  * Following TDD principles - tests should FAIL initially before implementation.
 11 |  */
 12 | 
 13 | test.describe('Color Mixer AI Workflows', () => {
 14 |   let stagehand: Stagehand
 15 |   
 16 |   test.beforeAll(async () => {
 17 |     // Verify environment variables
 18 |     if (!process.env.OPENAI_API_KEY) {
 19 |       console.warn('OPENAI_API_KEY not found. Stagehand tests will fail.')
 20 |     }
 21 |   })
 22 | 
 23 |   test.beforeEach(async () => {
 24 |     // Initialize Stagehand with LOCAL mode for development
 25 |     stagehand = new Stagehand({
 26 |       env: 'LOCAL',
 27 |       modelName: 'gpt-4o',
 28 |       modelClientOptions: {
 29 |         apiKey: process.env.OPENAI_API_KEY,
 30 |       },
 31 |       verbose: 1,
 32 |     })
 33 |     
 34 |     await stagehand.init()
 35 |     await stagehand.page.goto('http://localhost:3000')
 36 |   })
 37 | 
 38 |   test.afterEach(async () => {
 39 |     if (stagehand) {
 40 |       await stagehand.close()
 41 |     }
 42 |   })
 43 | 
 44 |   test('user creates warm colors through natural interaction', async () => {
 45 |     // Natural language makes intent clear - no need to figure out specific RGB values
 46 |     await stagehand.page.act('Make the color warmer by increasing red and yellow tones')
 47 |     await stagehand.page.act('Adjust the color to look like a sunset')
 48 |     
 49 |     // Observe the current state
 50 |     const warmth = await stagehand.page.extract({
 51 |       instruction: 'Analyze if the current color appears warm (orange/red tones)',
 52 |       schema: z.object({
 53 |         isWarm: z.boolean(),
 54 |         dominantColor: z.string().describe('The main color family (red, orange, yellow, etc.)'),
 55 |         hexValue: z.string(),
 56 |       }),
 57 |     })
 58 |     
 59 |     expect(warmth.isWarm).toBe(true)
 60 |     expect(['red', 'orange', 'yellow']).toContain(warmth.dominantColor.toLowerCase())
 61 |   })
 62 | 
 63 |   test('user explores color presets efficiently', async () => {
 64 |     // Test each preset with natural language - no need for data-testid selectors
 65 |     await stagehand.page.act('Click on the red color preset')
 66 |     
 67 |     let currentColor = await stagehand.page.extract({
 68 |       instruction: 'What color is currently selected?',
 69 |       schema: z.object({
 70 |         colorName: z.string(),
 71 |         hexValue: z.string(),
 72 |       }),
 73 |     })
 74 |     
 75 |     expect(currentColor.colorName.toLowerCase()).toContain('red')
 76 |     expect(currentColor.hexValue).toBe('#FF0000')
 77 |     
 78 |     await stagehand.page.act('Now select the blue preset')
 79 |     
 80 |     currentColor = await stagehand.page.extract({
 81 |       instruction: 'What color is currently selected?', 
 82 |       schema: z.object({
 83 |         colorName: z.string(),
 84 |         hexValue: z.string(),
 85 |       }),
 86 |     })
 87 |     
 88 |     expect(currentColor.colorName.toLowerCase()).toContain('blue')
 89 |     expect(currentColor.hexValue).toBe('#0000FF')
 90 |   })
 91 | 
 92 |   test('user validates accessibility and usability', async () => {
 93 |     // AI can assess usability aspects that are hard to test with traditional methods
 94 |     const usabilityAssessment = await stagehand.page.extract({
 95 |       instruction: 'Evaluate the color picker for usability: are controls clearly labeled, is feedback clear, are colors easy to distinguish?',
 96 |       schema: z.object({
 97 |         controlsAreLabeled: z.boolean(),
 98 |         feedbackIsClear: z.boolean(),
 99 |         colorsAreDistinguishable: z.boolean(),
100 |         overallUsability: z.number().min(1).max(10).describe('Overall usability score 1-10'),
101 |         suggestions: z.array(z.string()).describe('Any suggestions for improvement'),
102 |       }),
103 |     })
104 |     
105 |     expect(usabilityAssessment.controlsAreLabeled).toBe(true)
106 |     expect(usabilityAssessment.feedbackIsClear).toBe(true)
107 |     expect(usabilityAssessment.overallUsability).toBeGreaterThanOrEqual(7)
108 |   })
109 | 
110 |   test('preset buttons maintain visibility in dark mode', async () => {
111 |     // Force dark mode to test the contrast issue  
112 |     await stagehand.page.emulateMedia({ colorScheme: 'dark' })
113 |     
114 |     // Wait for dark mode to apply
115 |     await new Promise(resolve => setTimeout(resolve, 500))
116 |     
117 |     // First, try to specifically click on the Black button's text
118 |     // This should fail if the text is invisible
119 |     let blackButtonClickable = false
120 |     try {
121 |       await stagehand.page.act({
122 |         action: 'Click on the text "Black" on the Black preset button (not just the button, but specifically the text label)'
123 |       })
124 |       blackButtonClickable = true
125 |     } catch (error) {
126 |       blackButtonClickable = false
127 |     }
128 |     
129 |     // Use Stagehand's natural language to check button visibility
130 |     const buttonVisibility = await stagehand.page.extract({
131 |       instruction: 'Look at the 6 color preset buttons in the "Color Presets" section. For each button, can you clearly see and read the text label? Check if "Black" text is visible on the black button background. List any buttons where the text is hard to see or invisible due to poor contrast.',
132 |       schema: z.object({
133 |         allTextReadable: z.boolean().describe('Can you read ALL button labels clearly?'),
134 |         problematicButtons: z.array(z.string()).describe('Which buttons have text that is hard to see or invisible?'),
135 |         blackButtonTextVisible: z.boolean().describe('Specifically, can you see the "Black" text on the black button?'),
136 |         contrastIssues: z.string().describe('Describe any contrast issues you observe'),
137 |       }),
138 |     })
139 |     
140 |     // Try to observe the Black button specifically
141 |     const blackButtonObservation = await stagehand.page.observe({
142 |       instruction: 'Find the button with "Black" text label in the Color Presets section. Can you clearly see the word "Black" written on it, or is the text invisible/very hard to see against the button background?'
143 |     })
144 |     
145 |     // Test should FAIL if using bg-background (text invisible)
146 |     // Test should PASS if using explicit colors (text visible)
147 |     expect(blackButtonClickable).toBe(true) // Should be able to click the text
148 |     expect(buttonVisibility.blackButtonTextVisible).toBe(true)
149 |     expect(buttonVisibility.allTextReadable).toBe(true)
150 |     expect(buttonVisibility.problematicButtons).toHaveLength(0)
151 |     
152 |     // The Black button should be observable
153 |     expect(blackButtonObservation).toBeDefined()
154 |     expect(blackButtonObservation.length).toBeGreaterThan(0)
155 |   })
156 | })


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Test-Driven Development with Browserbase, Stagehand and Claude Code
  2 | 
  3 | ## 🎓 AI Insiders Club Edition
  4 | 
  5 | **🤖 Sponsored by Browserbase**: Sign up today ► https://browserbase.plug.dev/ekNRhob
  6 | 
  7 | **🎥 Watch the Episode** ► [How to Reduce 90% of Errors with Claude Code](https://www.youtube.com/watch?v=5jPQNDu_iJA)
  8 | 
  9 | **Get Builder Pack** ► [Click Here](https://rebrand.ly/5ecb8c)
 10 | 
 11 | Welcome Insiders! This enhanced repository contains exclusive learning materials and the complete test suite from Episode 9. Learn how to reduce 90% of errors using Test-Driven Development with AI-powered testing and Stagehand's natural language testing framework.
 12 | 
 13 | ## 📦 Repository Structure
 14 | 
 15 | ```
 16 | browserbase-claude-code-stagehand/
 17 | ├── README.md                          # This file
 18 | ├── CLAUDE.md                          # Claude Code guidance file
 19 | ├── LESSON.md                          # 🎓 INSIDERS EXCLUSIVE: Complete learning guide
 20 | ├── PRD.md                             # 🎓 INSIDERS EXCLUSIVE: Product requirements document
 21 | ├── .claude/                           # Claude Code configuration
 22 | │   ├── agents/                        # AI agent definitions
 23 | │   │   └── stagehand-expert.md       # Stagehand testing specialist agent
 24 | │   ├── commands/                      # Custom commands
 25 | │   │   └── agent_prompts/            # Agent prompt templates
 26 | │   │       └── stagehand_expert_prompt.md
 27 | │   └── output-styles/                 # Output formatting rules
 28 | │       └── pragmatic-test-driven-developer.md  # TDD enforcement style
 29 | └── my-app/
 30 |     └── tests/                         # Complete test suite implementations
 31 |         ├── README.md                  # Comprehensive test documentation
 32 |         ├── playwright/                # Traditional selector-based tests
 33 |         │   ├── baseline.spec.ts      # Basic structure & element presence
 34 |         │   ├── interactions.spec.ts  # User interactions & validations
 35 |         │   └── color-mixer.spec.ts   # Full workflow tests
 36 |         └── stagehand/                 # AI-powered natural language tests
 37 |             ├── baseline-stagehand.spec.ts      # AI element discovery
 38 |             ├── interactions-stagehand.spec.ts  # Natural language interactions
 39 |             └── color-workflows.spec.ts         # Complex AI workflows
 40 | ```
 41 | 
 42 | ## 🚀 Quick Start
 43 | 
 44 | ### 1. Set Up Claude Code Configuration
 45 | 
 46 | Copy everything from `.claude` into the root of your Claude Code project:
 47 | 
 48 | ```bash
 49 | cp -r .claude/* /path/to/your/project/.claude/
 50 | ```
 51 | 
 52 | ### 2. Use the Stagehand Expert Agent
 53 | 
 54 | Tag `@agent-stagehand-expert` in any task related to writing or running tests. This agent specializes in:
 55 | 
 56 | - Creating executable Stagehand test files
 57 | - Implementing hybrid AI + data-testid strategies
 58 | - Handling LOCAL vs BROWSERBASE modes
 59 | - Building robust tests with fallback strategies
 60 | 
 61 | ### 3. Enable TDD Output Style
 62 | 
 63 | Run `/output-style` and select **"Pragmatic Test Driven Developer"** to enforce the Red → Green → Verify cycle automatically in your development workflow.
 64 | 
 65 | ### 4. Run Example Tests
 66 | 
 67 | ```bash
 68 | # Run Playwright tests
 69 | npx playwright test tests/playwright/
 70 | 
 71 | # Run Stagehand tests
 72 | npx playwright test tests/stagehand/
 73 | ```
 74 | 
 75 | ## 📚 What's Included
 76 | 
 77 | ### 🎓 **INSIDERS EXCLUSIVE Content**
 78 | 
 79 | #### **Complete Learning Guide** (`LESSON.md`)
 80 | 
 81 | - Detailed timestamps from the episode
 82 | - Code-along exercises with solutions
 83 | - Advanced Stagehand techniques breakdown
 84 | - Multi-agent workflow patterns
 85 | - Practice exercises and community challenges
 86 | 
 87 | #### **Product Requirements Document** (`PRD.md`)
 88 | 
 89 | - Complete specifications for the Color Mixer app
 90 | - User stories and acceptance criteria
 91 | - Technical requirements and constraints
 92 | - Perfect for practicing TDD implementation
 93 | 
 94 | #### **Full Test Suite** (`my-app/tests/`)
 95 | 
 96 | - Complete working Playwright tests (3 files)
 97 | - Complete Stagehand AI tests (3 files)
 98 | - Side-by-side comparisons showing 70% code reduction
 99 | - Real patterns you can adapt to your projects
100 | 
101 | ### **Core Resources (Also in Free Version)**
102 | 
103 | #### **Stagehand Expert Agent** (`.claude/agents/stagehand-expert.md`)
104 | 
105 | - Complete agent definition for AI-powered testing
106 | - Pre-configured with Stagehand best practices
107 | - Natural language test patterns and examples
108 | - Works with Claude Code multi-agent workflows
109 | 
110 | #### **TDD Output Style** (`.claude/output-styles/pragmatic-tdd-developer.md`)
111 | 
112 | - Enforces test-first development methodology
113 | - Automatic Red → Green → Verify cycle
114 | - Prevents skipping tests or writing untested code
115 | - Compatible with all Claude Code agents
116 | 
117 | ## 🎯 Additional Resources
118 | 
119 | ### **You're Already an Insider! 🎉**
120 | 
121 | As an AI Insiders Club member, you have access to:
122 | 
123 | - ✅ This complete repository with LESSON.md
124 | - ✅ Custom command structures (`/dev:design-app`, `/dev:implement-mvp`)
125 | 
126 | ### **Upgrade to Builder Pack (Premium)**
127 | 
128 | Take your skills further with the complete implementation:
129 | 
130 | - 🚀 **Full Agent Team** (UI Designer, shadcn Expert, Orchestrator, TypeScript Specialist)
131 | - 🚀 **Complete Design Outputs** (wireframes, manifest, implementation plan)
132 | - 🚀 **Source code for the working Color Mixer app** (working app with all tests passing)
133 | 
134 | **Get Builder Pack** ► [Click Here](https://rebrand.ly/5ecb8c)
135 | 
136 | ## 🔧 TDD Methodology Overview
137 | 
138 | The Test-Driven Development cycle demonstrated in this episode:
139 | 
140 | ```
141 | 1. RED PHASE (Write Test)
142 |    └── Write test for desired functionality
143 |    └── Run test to confirm it fails
144 |    └── State: "❌ Test written and failing"
145 | 
146 | 2. GREEN PHASE (Implement Code)
147 |    └── Write minimal code to pass test
148 |    └── No extra features or additions
149 |    └── State: "✅ Test passing"
150 | 
151 | 3. VERIFY PHASE (Check Results)
152 |    └── Run all tests to ensure nothing broke
153 |    └── Manual verification if needed
154 |    └── State: "✅ Ready for next feature"
155 | ```
156 | 
157 | ## 🤝 Contributing
158 | 
159 | This repository contains the free resources from Episode 9. Contributions welcome:
160 | 
161 | - Bug fixes in test examples
162 | - Additional Stagehand patterns
163 | - Documentation improvements
164 | - Translation contributions
165 | 
166 | Please open an issue first to discuss major changes.
167 | 
168 | ## 📄 License
169 | 
170 | MIT License - See [LICENSE](LICENSE) file for details
171 | 
172 | ## 🙏 Acknowledgments
173 | 
174 | - **Browserbase** for sponsoring this episode and creating Stagehand
175 | - **Claude Code Community** for feedback and testing
176 | - **Anthropic** for TDD best practices documentation
177 | 
178 | ## 📺 Related Episodes
179 | 
180 | - **Episode 8**: [Advanced Statuslines and Usage Tracking](https://youtube.com/watch?v=oWsjmNSxoLQ)
181 | - **Episode 7**: [Multi-Agent Workflows](https://youtube.com/watch?v=fb19HiCb8xk)
182 | - **Episode 6**: [Programmatic Videos with Remotion](https://youtube.com/watch?v=aOQ04PPfu4A)
183 | 
184 | ## 💬 Get Help
185 | 
186 | - **GitHub Issues**: Report bugs or request features
187 | - **X/Twitter**: [@chongdashu](https://x.com/chongdashu)
188 | - **Website**: [aioriented.dev](https://aioriented.dev)
189 | 
190 | ---
191 | 
192 | **Remember**: The best way to reduce errors isn't to write more code - it's to write tests first! 🧪
193 | 
194 | Start with Stagehand today ► https://browserbase.plug.dev/ekNRhob
195 | 


--------------------------------------------------------------------------------
/my-app/tests/playwright/interactions.spec.ts:
--------------------------------------------------------------------------------
  1 | import { test, expect } from '@playwright/test'
  2 | 
  3 | /**
  4 |  * Interaction Tests - Simple Color Mixer Application
  5 |  * 
  6 |  * These tests verify user interactions and dynamic behavior.
  7 |  * Following TDD principles - tests should FAIL initially before implementation.
  8 |  */
  9 | 
 10 | test.describe('Color Mixer Interaction Tests', () => {
 11 |   test.beforeEach(async ({ page }) => {
 12 |     await page.goto('/')
 13 |   })
 14 | 
 15 |   test('RGB slider changes update color preview', async ({ page }) => {
 16 |     // Get initial color preview background
 17 |     const colorPreview = page.locator('[data-testid="color-preview"] div').first()
 18 |     const initialStyle = await colorPreview.getAttribute('style')
 19 |     
 20 |     // Change red slider to maximum (255)
 21 |     const redSlider = page.locator('[data-testid="slider-r"]')
 22 |     await redSlider.click()
 23 |     
 24 |     // Use keyboard to set value (more reliable than drag)
 25 |     await page.keyboard.press('End') // Move to max value
 26 |     
 27 |     // Wait for color update (should be <16ms but give some buffer)
 28 |     await page.waitForTimeout(50)
 29 |     
 30 |     // Verify color preview updated
 31 |     const updatedStyle = await colorPreview.getAttribute('style')
 32 |     expect(updatedStyle).not.toBe(initialStyle)
 33 |     
 34 |     // Verify background color contains high red value
 35 |     expect(updatedStyle).toMatch(/background-color.*rgb\(255/)
 36 |   })
 37 | 
 38 |   test('preset buttons apply correct colors', async ({ page }) => {
 39 |     // Test red preset
 40 |     await page.locator('[data-testid="preset-red"]').click()
 41 |     
 42 |     // Wait for update
 43 |     await page.waitForTimeout(50)
 44 |     
 45 |     // Check hex value shows red
 46 |     const hexValue = page.locator('[data-testid="hex-value"]')
 47 |     await expect(hexValue).toContainText('#FF0000')
 48 |     
 49 |     // Check RGB value shows red
 50 |     const rgbValue = page.locator('[data-testid="rgb-value"]')
 51 |     await expect(rgbValue).toContainText('rgb(255, 0, 0)')
 52 |     
 53 |     // Test blue preset
 54 |     await page.locator('[data-testid="preset-blue"]').click()
 55 |     await page.waitForTimeout(50)
 56 |     
 57 |     await expect(hexValue).toContainText('#0000FF')
 58 |     await expect(rgbValue).toContainText('rgb(0, 0, 255)')
 59 |     
 60 |     // Test white preset  
 61 |     await page.locator('[data-testid="preset-white"]').click()
 62 |     await page.waitForTimeout(50)
 63 |     
 64 |     await expect(hexValue).toContainText('#FFFFFF')
 65 |     await expect(rgbValue).toContainText('rgb(255, 255, 255)')
 66 |   })
 67 | 
 68 |   test('copy button triggers clipboard action', async ({ page }) => {
 69 |     // Grant clipboard permissions
 70 |     await page.context().grantPermissions(['clipboard-write'])
 71 |     
 72 |     // Click hex value to copy
 73 |     await page.locator('[data-testid="hex-value"]').click()
 74 |     
 75 |     // Wait for clipboard operation
 76 |     await page.waitForTimeout(100)
 77 |     
 78 |     // Check if toast appears (testing UI feedback)
 79 |     // Note: Toast component should be visible temporarily
 80 |     const toast = page.locator('text=Copied:').or(page.locator('[role="alert"]')).or(page.locator('.toast'))
 81 |     await expect(toast.first()).toBeVisible({ timeout: 1000 })
 82 |     
 83 |     // Test RGB value copy as well
 84 |     await page.locator('[data-testid="rgb-value"]').click()
 85 |     await page.waitForTimeout(100)
 86 |     
 87 |     // Toast should appear again
 88 |     await expect(toast.first()).toBeVisible({ timeout: 1000 })
 89 |   })
 90 | 
 91 |   test('numeric values update correctly with slider changes', async ({ page }) => {
 92 |     // Test red channel
 93 |     const redSlider = page.locator('[data-testid="slider-r"]')
 94 |     await redSlider.click()
 95 |     await page.keyboard.press('End') // Maximum value
 96 |     await page.waitForTimeout(50)
 97 |     
 98 |     // Check that red numeric display shows 255
 99 |     const redValue = page.locator('[data-testid="value-r"]')
100 |     await expect(redValue).toContainText('255')
101 |     
102 |     // Test green channel
103 |     const greenSlider = page.locator('[data-testid="slider-g"]')
104 |     await greenSlider.click()
105 |     await page.keyboard.press('Home') // Minimum value
106 |     await page.waitForTimeout(50)
107 |     
108 |     // Check that green numeric display shows 0
109 |     const greenValue = page.locator('[data-testid="value-g"]')
110 |     await expect(greenValue).toContainText('0')
111 |     
112 |     // Verify hex value updated accordingly (red=255, green=0)
113 |     const hexValue = page.locator('[data-testid="hex-value"]')
114 |     await expect(hexValue).toContainText('#FF00')
115 |   })
116 | 
117 |   test('multiple rapid slider interactions work correctly', async ({ page }) => {
118 |     // Test rapid slider movements don't cause issues
119 |     const redSlider = page.locator('[data-testid="slider-r"]')
120 |     const greenSlider = page.locator('[data-testid="slider-g"]') 
121 |     const blueSlider = page.locator('[data-testid="slider-b"]')
122 |     
123 |     // Rapid interactions
124 |     await redSlider.click()
125 |     await page.keyboard.press('End')
126 |     await greenSlider.click() 
127 |     await page.keyboard.press('End')
128 |     await blueSlider.click()
129 |     await page.keyboard.press('End')
130 |     
131 |     await page.waitForTimeout(100)
132 |     
133 |     // Should result in white color
134 |     await expect(page.locator('[data-testid="hex-value"]')).toContainText('#FFFFFF')
135 |     await expect(page.locator('[data-testid="rgb-value"]')).toContainText('rgb(255, 255, 255)')
136 |   })
137 | 
138 |   test('preset button interactions work with visual feedback', async ({ page }) => {
139 |     // Test that preset buttons have proper hover/click states
140 |     const redPreset = page.locator('[data-testid="preset-red"]')
141 |     
142 |     // Test hover effect (scale transformation)
143 |     await redPreset.hover()
144 |     await expect(redPreset).toHaveClass(/hover:scale-105/)
145 |     
146 |     // Test click and color change
147 |     await redPreset.click()
148 |     await page.waitForTimeout(50)
149 |     
150 |     // Verify color changed to red
151 |     const colorPreview = page.locator('[data-testid="color-preview"] div').first()
152 |     const style = await colorPreview.getAttribute('style')
153 |     expect(style).toContain('rgb(255, 0, 0)')
154 |   })
155 | 
156 |   test('edge cases: extreme slider values work correctly', async ({ page }) => {
157 |     // Test minimum values (all 0)
158 |     await page.locator('[data-testid="slider-r"]').click()
159 |     await page.keyboard.press('Home')
160 |     await page.locator('[data-testid="slider-g"]').click() 
161 |     await page.keyboard.press('Home')
162 |     await page.locator('[data-testid="slider-b"]').click()
163 |     await page.keyboard.press('Home')
164 |     
165 |     await page.waitForTimeout(50)
166 |     
167 |     // Should be black
168 |     await expect(page.locator('[data-testid="hex-value"]')).toContainText('#000000')
169 |     await expect(page.locator('[data-testid="rgb-value"]')).toContainText('rgb(0, 0, 0)')
170 |     
171 |     // Test maximum values (all 255) 
172 |     await page.locator('[data-testid="slider-r"]').click()
173 |     await page.keyboard.press('End')
174 |     await page.locator('[data-testid="slider-g"]').click()
175 |     await page.keyboard.press('End') 
176 |     await page.locator('[data-testid="slider-b"]').click()
177 |     await page.keyboard.press('End')
178 |     
179 |     await page.waitForTimeout(50)
180 |     
181 |     // Should be white
182 |     await expect(page.locator('[data-testid="hex-value"]')).toContainText('#FFFFFF')
183 |     await expect(page.locator('[data-testid="rgb-value"]')).toContainText('rgb(255, 255, 255)')
184 |   })
185 | })


--------------------------------------------------------------------------------
/my-app/tests/README.md:
--------------------------------------------------------------------------------
  1 | # Color Mixer Test Suite
  2 | 
  3 | This test suite demonstrates **Test-Driven Development (TDD)** principles using both traditional **Playwright** and modern **Stagehand AI** testing approaches.
  4 | 
  5 | ## Test Architecture
  6 | 
  7 | ### 📁 Directory Structure
  8 | 
  9 | ```
 10 | tests/
 11 | ├── playwright/              # Traditional selector-based tests
 12 | │   ├── baseline.spec.ts       # Basic structure & element presence
 13 | │   ├── color-mixer.spec.ts    # Core functionality tests
 14 | │   └── interactions.spec.ts   # User interactions & validations
 15 | ├── stagehand/              # AI-powered natural language tests
 16 | │   ├── baseline-stagehand.spec.ts    # AI-powered baseline tests
 17 | │   ├── color-workflows.spec.ts       # Natural language workflows
 18 | │   └── interactions-stagehand.spec.ts # AI interaction tests
 19 | └── README.md               # This documentation
 20 | ```
 21 | 
 22 | ### 🎯 Test Strategy Comparison
 23 | 
 24 | | Aspect             | Playwright Tests           | Stagehand AI Tests                         |
 25 | | ------------------ | -------------------------- | ------------------------------------------ |
 26 | | **Code Volume**    | ~150 lines per workflow    | ~50 lines per workflow (**70% reduction**) |
 27 | | **Approach**       | Selector-based, precise    | Natural language, intent-based             |
 28 | | **Maintenance**    | High (brittle selectors)   | Low (semantic understanding)               |
 29 | | **Best For**       | Technical validation       | User workflows & complex scenarios         |
 30 | | **Learning Curve** | Steep (CSS selectors, API) | Gentle (plain English)                     |
 31 | 
 32 | ## 🚀 Quick Start
 33 | 
 34 | ### 1. Install Dependencies
 35 | 
 36 | ```bash
 37 | npm install
 38 | ```
 39 | 
 40 | ### 2. Set Up Environment
 41 | 
 42 | Create a `.env` file in the `my-app` directory with the following API keys:
 43 | 
 44 | ```bash
 45 | # Required for Stagehand AI tests
 46 | OPENAI_API_KEY=your_openai_api_key_here
 47 | 
 48 | # Optional: For cloud testing with Browserbase
 49 | BROWSERBASE_API_KEY=your_key_here
 50 | BROWSERBASE_PROJECT_ID=your_project_id
 51 | 
 52 | # Optional: Alternative AI models
 53 | ANTHROPIC_API_KEY=your_key_here
 54 | ```
 55 | 
 56 | **⚠️ Important**: Stagehand tests will fail without a valid `OPENAI_API_KEY`.
 57 | 
 58 | ## 🧪 Test Categories
 59 | 
 60 | ### Playwright Tests (Traditional)
 61 | 
 62 | #### Baseline Tests (`tests/playwright/baseline.spec.ts`)
 63 | 
 64 | **Purpose**: Verify basic application structure and element presence
 65 | 
 66 | **Tests**:
 67 | 
 68 | - ✅ App loads with correct title
 69 | - ✅ Color preview element exists
 70 | - ✅ All 3 RGB sliders are present
 71 | - ✅ Hex and RGB values are displayed
 72 | - ✅ 6 color preset buttons exist
 73 | - ✅ Accessibility attributes are proper
 74 | - ✅ Responsive layout structure
 75 | 
 76 | #### Color Mixer Tests (`tests/playwright/color-mixer.spec.ts`)
 77 | 
 78 | **Purpose**: Test core color mixing functionality
 79 | 
 80 | **Tests**:
 81 | 
 82 | - ✅ Initial state displays correctly
 83 | - ✅ Preset buttons update colors
 84 | - ✅ Copy to clipboard functionality
 85 | - ✅ Color values format correctly
 86 | 
 87 | #### Interaction Tests (`tests/playwright/interactions.spec.ts`)
 88 | 
 89 | **Purpose**: Test user interactions and dynamic behavior
 90 | 
 91 | **Tests**:
 92 | 
 93 | - ✅ RGB sliders update color preview
 94 | - ✅ Preset buttons apply correct colors
 95 | - ✅ Copy functionality triggers clipboard
 96 | - ✅ Numeric values update with sliders
 97 | - ✅ Performance meets <16ms requirement
 98 | - ✅ Rapid interactions work correctly
 99 | - ✅ Edge cases (min/max values)
100 | 
101 | ### Stagehand AI Tests (Natural Language)
102 | 
103 | #### AI Baseline Tests (`tests/stagehand/baseline-stagehand.spec.ts`)
104 | 
105 | **Purpose**: AI-powered element discovery and validation
106 | 
107 | **Tests**:
108 | 
109 | - 🤖 App loads with title using AI discovery
110 | - 🤖 Find all RGB sliders via natural language
111 | - 🤖 Verify color values using semantic understanding
112 | - 🤖 Discover preset buttons without selectors
113 | 
114 | #### AI Workflow Tests (`tests/stagehand/color-workflows.spec.ts`)
115 | 
116 | **Purpose**: Test complex user workflows with natural language
117 | 
118 | **Tests**:
119 | 
120 | - 🤖 "Set red to maximum" - Natural value setting
121 | - 🌅 "Make color warmer like sunset" - Intent-based adjustments
122 | - 🎨 "Click red preset then blue" - Workflow automation
123 | - 📋 "Copy hex color value" - Action + feedback validation
124 | - 🌊 "Create ocean at sunset color" - Complex creative workflow
125 | - ⚡ "Test rapid interactions" - Performance under stress
126 | - ♿ "Evaluate usability" - AI-powered accessibility assessment
127 | 
128 | #### AI Interaction Tests (`tests/stagehand/interactions-stagehand.spec.ts`)
129 | 
130 | **Purpose**: AI-powered interaction testing
131 | 
132 | **Tests**:
133 | 
134 | - 🤖 Slider manipulation using natural language
135 | - 🤖 Complex color workflows
136 | - 🤖 Feedback validation without selectors
137 | 
138 | ## 🔍 TDD Process
139 | 
140 | ### Red Phase (Failing Tests)
141 | 
142 | All tests are written to **FAIL initially** before implementation exists:
143 | 
144 | ```bash
145 | # These tests will fail on a blank application
146 | npm run test:baseline
147 | npm run test:interactions
148 | npm run test:stagehand
149 | ```
150 | 
151 | ### Green Phase (Make Tests Pass)
152 | 
153 | Implement minimal code to make tests pass:
154 | 
155 | - Add required `data-testid` attributes
156 | - Implement color calculation logic
157 | - Add slider change handlers
158 | - Implement copy functionality
159 | 
160 | ### Refactor Phase (Improve Code)
161 | 
162 | Clean up implementation while keeping tests green:
163 | 
164 | - Optimize performance (<16ms updates)
165 | - Improve accessibility
166 | - Enhance user experience
167 | 
168 | ## 🎨 Application Requirements Tested
169 | 
170 | ### ✅ Core Features
171 | 
172 | - **RGB Sliders**: 0-255 range with live preview updates
173 | - **Hex & RGB Display**: Real-time value formatting
174 | - **6 Color Presets**: Red, Green, Blue, Yellow, Black, White
175 | - **Copy to Clipboard**: With toast feedback notification
176 | - **Performance**: <16ms response time for color updates
177 | 
178 | ### ✅ User Experience
179 | 
180 | - **Visual Feedback**: Hover effects, transitions
181 | - **Accessibility**: Proper labels, ARIA attributes
182 | - **Responsive Design**: Mobile-friendly layout
183 | - **Error Handling**: Graceful edge case management
184 | 
185 | ## 🤖 Stagehand AI Advantages
186 | 
187 | ### Traditional Playwright (Complex)
188 | 
189 | ```typescript
190 | // 15+ lines for simple color change
191 | const redSlider = page.locator('[data-testid="slider-r"]');
192 | await redSlider.click();
193 | await redSlider.fill("255");
194 | const colorPreview = page.locator('[data-testid="color-preview"] div');
195 | const style = await colorPreview.getAttribute("style");
196 | expect(style).toContain("rgb(255,");
197 | ```
198 | 
199 | ### Stagehand AI (Simple)
200 | 
201 | ```typescript
202 | // 3 lines for same functionality
203 | await stagehand.page.act('Set red color to maximum')
204 | const result = await stagehand.page.extract({...})
205 | expect(result.hexValue).toBe('#FF0000')
206 | ```
207 | 
208 | **Benefits**:
209 | 
210 | - 📈 **70% less code** for complex workflows
211 | - 🧠 **Intent-based testing** vs brittle selectors
212 | - 🔧 **Lower maintenance** burden
213 | - 🚀 **Faster test development** cycle
214 | - 🎯 **Better test readability** for non-technical stakeholders
215 | 
216 | ## 🛠️ Configuration Details
217 | 
218 | ### Environment Variables
219 | 
220 | All environment variables should be placed in a `.env` file in the `my-app` directory:
221 | 
222 | ```bash
223 | # Required for Stagehand AI tests
224 | OPENAI_API_KEY=sk-...your_key_here
225 | 
226 | # Optional: Cloud testing with Browserbase
227 | BROWSERBASE_API_KEY=bb_live_...your_key_here
228 | BROWSERBASE_PROJECT_ID=your_project_id
229 | 
230 | # Optional: Alternative AI models
231 | ANTHROPIC_API_KEY=sk-ant-...your_key_here
232 | ```
233 | 
234 | ## 📊 Test Coverage
235 | 
236 | ### Baseline Coverage
237 | 
238 | - [x] UI Structure (100%)
239 | - [x] Element Presence (100%)
240 | - [x] Accessibility (100%)
241 | 
242 | ### Interaction Coverage
243 | 
244 | - [x] User Actions (100%)
245 | - [x] State Changes (100%)
246 | - [x] Edge Cases (100%)
247 | - [x] Performance (100%)
248 | 
249 | ### Workflow Coverage
250 | 
251 | - [x] Simple Tasks (100%)
252 | - [x] Complex Workflows (100%)
253 | - [x] Creative Scenarios (100%)
254 | - [x] Error Handling (100%)
255 | 
256 | ## 🎓 Learning Objectives
257 | 
258 | This test suite demonstrates:
259 | 
260 | 1. **TDD Methodology**: Red → Green → Refactor cycle
261 | 2. **Test Strategy**: When to use Playwright vs Stagehand
262 | 3. **Code Efficiency**: 70% reduction with AI testing
263 | 4. **Modern Testing**: Natural language test automation
264 | 5. **Quality Assurance**: Comprehensive coverage strategies
265 | 
266 | ```
267 | 
268 | ## 📝 Summary
269 | 
270 | This test suite provides comprehensive coverage of the Color Mixer application using:
271 | 
272 | 1. **Traditional Playwright tests** for precise, selector-based testing
273 | 2. **Stagehand AI tests** for natural language, intent-based testing
274 | 3. **Progressive testing strategy** from basic structure to complex workflows
275 | 
276 | **Key Benefits**:
277 | 
278 | - 70% less code with Stagehand AI tests
279 | - Better test maintainability through semantic understanding
280 | - Comprehensive coverage across all application features
281 | - Clear TDD workflow demonstration
282 | 
283 | **Next Steps**:
284 | 
285 | 1. Set up your `.env` file with required API keys
286 | 2. Start the dev server with `npm run dev`
287 | 3. Run tests to see current status
288 | 4. Implement/fix features to make all tests pass! 🎨
289 | ```
290 | 


--------------------------------------------------------------------------------
/my-app/tests/stagehand/interactions-stagehand.spec.ts:
--------------------------------------------------------------------------------
  1 | import { test, expect } from '@playwright/test'
  2 | import { Stagehand } from '@browserbasehq/stagehand'
  3 | import { z } from 'zod'
  4 | 
  5 | /**
  6 |  * Interaction Stagehand Tests - Natural Element Discovery
  7 |  * 
  8 |  * These tests demonstrate the power of AI-driven interactions vs precise selectors.
  9 |  * Shows how natural language makes tests more maintainable and user-focused.
 10 |  */
 11 | 
 12 | test.describe('Color Mixer Interaction Tests - Stagehand', () => {
 13 |   let stagehand: Stagehand
 14 |   
 15 |   test.beforeAll(async () => {
 16 |     if (!process.env.OPENAI_API_KEY) {
 17 |       console.warn('OPENAI_API_KEY not found. Stagehand tests will fail.')
 18 |     }
 19 |   })
 20 | 
 21 |   test.beforeEach(async () => {
 22 |     stagehand = new Stagehand({
 23 |       env: 'LOCAL',
 24 |       modelName: 'gpt-4o',
 25 |       modelClientOptions: {
 26 |         apiKey: process.env.OPENAI_API_KEY,
 27 |       },
 28 |       verbose: 1,
 29 |     })
 30 |     
 31 |     await stagehand.init()
 32 |     await stagehand.page.goto('http://localhost:3000')
 33 |   })
 34 | 
 35 |   test.afterEach(async () => {
 36 |     if (stagehand) {
 37 |       await stagehand.close()
 38 |     }
 39 |   })
 40 | 
 41 |   test('preset buttons apply correct colors - natural interaction', async () => {
 42 |     // ✨ Stagehand: Test red preset with natural language
 43 |     // Instead of: page.locator('[data-testid="preset-red"]').click()
 44 |     await stagehand.page.act('Click the red preset button to set the color to red')
 45 |     
 46 |     await new Promise(resolve => setTimeout(resolve, 100))
 47 |     
 48 |     // ✨ Stagehand: Verify color values using AI understanding
 49 |     const redResult = await stagehand.page.extract({
 50 |       instruction: "Get the current HEX and RGB color values after clicking red preset",
 51 |       schema: z.object({
 52 |         hexValue: z.string().describe("The HEX color value displayed"),
 53 |         rgbValue: z.string().describe("The RGB color value displayed"),
 54 |         isActuallyRed: z.boolean().describe("Does the color preview look red to the human eye?")
 55 |       })
 56 |     })
 57 |     
 58 |     expect(redResult.hexValue).toContain('#FF0000')
 59 |     expect(redResult.rgbValue).toContain('rgb(255, 0, 0)')
 60 |     expect(redResult.isActuallyRed).toBe(true)
 61 |     
 62 |     // ✨ Stagehand: Test blue preset naturally
 63 |     await stagehand.page.act('Click the blue preset button to change to blue color')
 64 |     
 65 |     await new Promise(resolve => setTimeout(resolve, 100))
 66 |     
 67 |     const blueResult = await stagehand.page.extract({
 68 |       instruction: "Get the current HEX and RGB color values after clicking blue preset",
 69 |       schema: z.object({
 70 |         hexValue: z.string().describe("The HEX color value displayed"),
 71 |         rgbValue: z.string().describe("The RGB color value displayed"),
 72 |         isActuallyBlue: z.boolean().describe("Does the color preview look blue to the human eye?")
 73 |       })
 74 |     })
 75 |     
 76 |     expect(blueResult.hexValue).toContain('#0000FF')
 77 |     expect(blueResult.rgbValue).toContain('rgb(0, 0, 255)')
 78 |     expect(blueResult.isActuallyBlue).toBe(true)
 79 |     
 80 |     // ✨ Stagehand: Test white preset for edge case
 81 |     await stagehand.page.act('Click the white preset button to set color to white')
 82 |     
 83 |     await new Promise(resolve => setTimeout(resolve, 100))
 84 |     
 85 |     const whiteResult = await stagehand.page.extract({
 86 |       instruction: "Get the HEX and RGB color values after setting to white",
 87 |       schema: z.object({
 88 |         hexValue: z.string().describe("The HEX color value displayed"),
 89 |         rgbValue: z.string().describe("The RGB color value displayed")
 90 |       })
 91 |     })
 92 |     
 93 |     expect(whiteResult.hexValue).toContain('#FFFFFF')
 94 |     expect(whiteResult.rgbValue).toContain('rgb(255, 255, 255)')
 95 |   })
 96 | 
 97 |   test('multiple rapid slider interactions work - resilient AI testing', async () => {
 98 |     // ✨ Stagehand: Perform rapid slider adjustments using natural language
 99 |     // Instead of complex data-testid targeting for each slider
100 |     await stagehand.page.act('Set the red slider to maximum value')
101 |     await stagehand.page.act('Set the green slider to maximum value')
102 |     await stagehand.page.act('Set the blue slider to maximum value')
103 |     
104 |     await new Promise(resolve => setTimeout(resolve, 200))
105 |     
106 |     // ✨ Stagehand: Verify final white color using AI understanding
107 |     const finalResult = await stagehand.page.extract({
108 |       instruction: "Get the final HEX and RGB color values after setting all sliders to maximum",
109 |       schema: z.object({
110 |         hexValue: z.string().describe("The final HEX color value"),
111 |         rgbValue: z.string().describe("The final RGB color value"),
112 |         looksLikeWhite: z.boolean().describe("Does the color preview look white?"),
113 |         allSlidersAtMax: z.boolean().describe("Are all three sliders at their maximum positions?")
114 |       })
115 |     })
116 |     
117 |     expect(finalResult.hexValue).toContain('#FFFFFF')
118 |     expect(finalResult.rgbValue).toContain('rgb(255, 255, 255)')
119 |     expect(finalResult.looksLikeWhite).toBe(true)
120 |     expect(finalResult.allSlidersAtMax).toBe(true)
121 |   })
122 | 
123 |   test('random color generator creates new colors each time', async () => {
124 |     // ✨ Stagehand: Extract initial color state before random generation
125 |     // This captures the starting point for comparison
126 |     const initialColor = await stagehand.page.extract({
127 |       instruction: "Get the current color values before using random generator",
128 |       schema: z.object({
129 |         hexValue: z.string().describe("The current HEX color value"),
130 |         rgbValue: z.string().describe("The current RGB color value"),
131 |         redSliderValue: z.number().describe("The red slider position (0-255)"),
132 |         greenSliderValue: z.number().describe("The green slider position (0-255)"),
133 |         blueSliderValue: z.number().describe("The blue slider position (0-255)")
134 |       })
135 |     })
136 | 
137 |     // ✨ Stagehand: Observe to locate the random color button
138 |     // This will FAIL because the button doesn't exist yet (RED phase of TDD)
139 |     const randomButton = await stagehand.page.observe({
140 |       instruction: "Find the Random Color button or Randomize button that generates a random color"
141 |     })
142 | 
143 |     expect(randomButton).toBeTruthy() // This should fail - button doesn't exist
144 | 
145 |     // ✨ Stagehand: Act to click the random color generator
146 |     // This demonstrates the intended interaction pattern
147 |     await stagehand.page.act('Click the Random Color button to generate a new random color')
148 |     
149 |     await new Promise(resolve => setTimeout(resolve, 200))
150 | 
151 |     // ✨ Stagehand: Extract the new color after first randomization
152 |     const firstRandomColor = await stagehand.page.extract({
153 |       instruction: "Get the color values after clicking the random generator once",
154 |       schema: z.object({
155 |         hexValue: z.string().describe("The new HEX color value after randomization"),
156 |         rgbValue: z.string().describe("The new RGB color value after randomization"),
157 |         redSliderValue: z.number().describe("The red slider position after randomization"),
158 |         greenSliderValue: z.number().describe("The green slider position after randomization"),
159 |         blueSliderValue: z.number().describe("The blue slider position after randomization"),
160 |         isDifferentFromInitial: z.boolean().describe("Is this color visually different from the initial color?")
161 |       })
162 |     })
163 | 
164 |     // Verify the color changed from initial
165 |     expect(firstRandomColor.hexValue).not.toBe(initialColor.hexValue)
166 |     expect(firstRandomColor.isDifferentFromInitial).toBe(true)
167 | 
168 |     // ✨ Stagehand: Act to click random generator again
169 |     await stagehand.page.act('Click the Random Color button again to generate another random color')
170 |     
171 |     await new Promise(resolve => setTimeout(resolve, 200))
172 | 
173 |     // ✨ Stagehand: Extract the second random color
174 |     const secondRandomColor = await stagehand.page.extract({
175 |       instruction: "Get the color values after clicking the random generator a second time",
176 |       schema: z.object({
177 |         hexValue: z.string().describe("The second random HEX color value"),
178 |         rgbValue: z.string().describe("The second random RGB color value"),
179 |         isDifferentFromFirst: z.boolean().describe("Is this color different from the first random color?"),
180 |         isDifferentFromInitial: z.boolean().describe("Is this color different from the original initial color?")
181 |       })
182 |     })
183 | 
184 |     // Verify true randomness - each click should produce different colors
185 |     expect(secondRandomColor.hexValue).not.toBe(firstRandomColor.hexValue)
186 |     expect(secondRandomColor.hexValue).not.toBe(initialColor.hexValue)
187 |     expect(secondRandomColor.isDifferentFromFirst).toBe(true)
188 |     expect(secondRandomColor.isDifferentFromInitial).toBe(true)
189 | 
190 |     // Additional verification: Ensure sliders moved to match the random color
191 |     expect(firstRandomColor.redSliderValue).toBeGreaterThanOrEqual(0)
192 |     expect(firstRandomColor.redSliderValue).toBeLessThanOrEqual(255)
193 |     expect(firstRandomColor.greenSliderValue).toBeGreaterThanOrEqual(0)
194 |     expect(firstRandomColor.greenSliderValue).toBeLessThanOrEqual(255)
195 |     expect(firstRandomColor.blueSliderValue).toBeGreaterThanOrEqual(0)
196 |     expect(firstRandomColor.blueSliderValue).toBeLessThanOrEqual(255)
197 |   })
198 | })


--------------------------------------------------------------------------------
/.claude/commands/dev/design-app.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | allowed-tools: Task, Read, Write, TodoWrite
  3 | description: Design Next.js full-stack application architecture from PRD with test-first specifications
  4 | argument-hint: <prd-file-path>
  5 | ---
  6 | 
  7 | # Next.js Full-Stack Application Design Command
  8 | 
  9 | Create a comprehensive Next.js application design with test-first specifications based on a Product Requirements Document (PRD).
 10 | 
 11 | ## Usage Examples
 12 | 
 13 | Analyze PRD file referenced from `$ARGUMENTS`. It may be passed directly as text, or as a file reference, or with parameters.
 14 | 
 15 | ```bash
 16 | # Design from PRD file
 17 | /design-app --prd=docs/projects/analytics/prd.md
 18 | 
 19 | # Design with specific data sources
 20 | /design-app --prd=projects/analytics/prd.md --data=.claude/outputs/data/latest
 21 | 
 22 | # Design with custom output location
 23 | /design-app --prd=specs/chat-app.md --output=designs/chat-app
 24 | ```
 25 | 
 26 | ## PRD-Driven Design Philosophy
 27 | 
 28 | The command analyzes a Product Requirements Document to create a complete Next.js application design:
 29 | 
 30 | 1. **PRD Analysis**: Extract features, user stories, and technical requirements
 31 | 2. **Test-First Design**: Write acceptance tests based on PRD user stories
 32 | 3. **Next.js Architecture**: Design specifically for Next.js App Router patterns
 33 | 4. **Visual Component Planning**: Select shadcn/ui components with aesthetic excellence for all UI requirements
 34 | 
 35 | ## Enhanced Visual Design Integration
 36 | 
 37 | The **shadcn-expert** agent now provides comprehensive visual design capabilities:
 38 | 
 39 | ### Visual Excellence Focus
 40 | - **Aesthetic Component Selection**: Choose components that enhance visual appeal and user experience
 41 | - **Design Context Integration**: Leverage wireframes, color schemes, and visual patterns from ui-designer output
 42 | - **Beautiful Composition Planning**: Ensure components work together harmoniously for stunning interfaces
 43 | - **Responsive Beauty**: Maintain visual excellence across all breakpoints and devices
 44 | 
 45 | ### Enhanced Deliverables with Concrete Specifications
 46 | The shadcn-expert agent now produces **5 output files** with mandatory concrete values:
 47 | 1. `component-selection.md` - Component choices with **visual design rationale**
 48 | 2. `composition-plan.md` - **Beautiful interface composition** strategies
 49 | 3. `design-system-strategy.md` - **Color harmony, typography scales, spacing systems**
 50 | 4. `customization-specifications.md` - **Animation patterns, styling variants, responsive beauty guidelines**
 51 | 5. `implementation-values.md` - **Exact hex codes, Tailwind classes, CSS variables for THIS app**
 52 | 
 53 | ### Required Concrete Deliverables (App-Specific)
 54 | Each design agent MUST provide:
 55 | - Exact hex/RGB values CHOSEN FOR THIS APP (not copied from examples)
 56 | - Rationale for why these colors suit THIS application's purpose and audience
 57 | - Specific Tailwind classes that implement THIS design system
 58 | - WCAG contrast validation results for all text/background combinations
 59 | 
 60 | Examples showing proper variety (avoiding AI clichés):
 61 | - E-commerce platform: Trustworthy deep blues (#1e3a8a) and conversion oranges (#ea580c)
 62 | - Developer dashboard: High-contrast terminal blacks (#0a0a0a) and code greens (#22c55e)
 63 | - Learning platform: Warm earth tones (#92400e) and focus-friendly grays (#64748b)
 64 | - Healthcare app: Calming teals (#0f766e) and professional whites (#fafafa)
 65 | - Finance platform: Conservative navy (#1e3a8a) and accent gold (#d97706)
 66 | 
 67 | **Explicitly Avoid AI Design Clichés:**
 68 | - ❌ Purple-blue gradients (from-purple-600 to-blue-600)
 69 | - ❌ Generic violet/indigo schemes
 70 | - ❌ Predictable "AI tool" color patterns
 71 | - ✅ Industry-appropriate, user-expected color choices
 72 | 
 73 | ### Design Quality Standards
 74 | Every component selection considers:
 75 | - ✅ **Visual Impact** and color integration
 76 | - ✅ **Spacing Harmony** and typography hierarchy
 77 | - ✅ **Interactive Delight** with thoughtful animations
 78 | - ✅ **Accessibility Elegance** without compromising beauty
 79 | 
 80 | ## Workflow (Orchestrator-Managed Sequential then Parallel Coordination)
 81 | 
 82 | Following orchestrator-initialized workflow with structured project setup and validation:
 83 | 
 84 | ### Phase 1: Orchestrator Initialization (Sequential - Project Setup)
 85 | 
 86 | **Agent**: `orchestrator`
 87 | **Output**: `.claude/outputs/design/projects/[project-name]/[timestamp]/`
 88 | **Purpose**:
 89 | 
 90 | - Analyze PRD and confirm project scope
 91 | - Generate consistent project name and timestamp
 92 | - Create initial MANIFEST.md with requirements baseline
 93 | - Note: Agent outputs go directly to shared `.claude/outputs/design/agents/` location
 94 | 
 95 | ### Phase 2: UI Design Foundation (Sequential - Foundation Required)
 96 | 
 97 | **Agent**: `ui-designer`
 98 | **Output**: `.claude/outputs/design/agents/ui-designer/[project-name]-[timestamp]/` (pre-created)
 99 | **Purpose**: Read PRD, create wireframes, component hierarchy, and user flows
100 | 
101 | ### Phase 3: Parallel Component & Testing Design
102 | 
103 | **Executed Simultaneously** after Phase 2 completion:
104 | 
105 | You **MUST** execute Phase 3A and Phase 3B in parallel using sub-agents.
106 | 
107 | #### Phase 3A: Component System Design
108 | 
109 | ```bash
110 | - shadcn-expert → visual component selection, beautiful composition strategy, design system aesthetics (uses ui-designer output for visual design context)
111 | ```
112 | 
113 | #### Phase 3B: Test Specification Design
114 | 
115 | ```bash
116 | - browserbase-stagehand-expert → E2E test specifications (uses ui-designer output)
117 | ```
118 | 
119 | ### Phase 4: Orchestrator Synthesis & Validation (Sequential - Requires All Inputs)
120 | 
121 | **Agent**: `orchestrator` (final validation)
122 | **Output**: `.claude/outputs/design/projects/[project-name]/[timestamp]/`
123 | 
124 | **Purpose**: Synthesize all agent outputs into coherent implementation plan
125 | **Input**: All agent outputs from Phases 2-3 + initial MANIFEST from Phase 1
126 | **Validates**:
127 | 
128 | - ✓ All PRD requirements have corresponding design outputs
129 | - ✓ UI wireframes cover all user stories
130 | - ✓ Component plan addresses all UI requirements
131 | - ✓ Test specifications cover all acceptance criteria
132 | - ✓ Cross-agent consistency and integration points
133 | - ✓ All color specifications include exact hex values with contrast ratios
134 | - ✓ All text/background combinations pass WCAG AA (4.5:1 ratio minimum)
135 | - ✓ CSS variables are defined with precise values for this specific app
136 | - ✓ Tailwind classes are specified for each visual element
137 |   **Output**:
138 | - `MANIFEST.md` - Final registry linking all agent outputs with requirements traceability
139 | - `IMPLEMENTATION_PLAN.md` - Single source of truth for implementation
140 |   **TodoWrite Integration**: Creates final task list with requirement coverage validation
141 | 
142 | ## Output Structure
143 | 
144 | **Phase 1 (Orchestrator Initialization)**:
145 | 
146 | ```
147 | .claude/outputs/design/projects/[project-name]/[timestamp]/
148 | └── MANIFEST.md                   # Initial requirements baseline and agent registry
149 | ```
150 | 
151 | **Phase 2 (Sequential - UI Foundation)**:
152 | 
153 | ```
154 | .claude/outputs/design/agents/
155 | └── ui-designer/[project-name]-[timestamp]/
156 |     ├── wireframes.md
157 |     ├── component-hierarchy.md
158 |     └── user-flow-designs.md
159 | ```
160 | 
161 | **Phase 3 (Parallel Execution)**:
162 | 
163 | ```
164 | .claude/outputs/design/agents/
165 | ├── shadcn-expert/[project-name]-[timestamp]/
166 | │   ├── component-selection.md
167 | │   ├── composition-plan.md
168 | │   ├── design-system-strategy.md
169 | │   └── customization-specifications.md
170 | ├── browserbase-stagehand-expert/[project-name]-[timestamp]/
171 | │   ├── test-plan.md
172 | │   ├── playwright-tests.md
173 | │   └── stagehand-tests.md
174 | ```
175 | 
176 | **Phase 4 (Sequential - Final Synthesis)**:
177 | 
178 | ```
179 | .claude/outputs/design/projects/[project-name]/[timestamp]/
180 | ├── MANIFEST.md                   # Complete registry of all agent outputs with requirements traceability
181 | └── IMPLEMENTATION_PLAN.md        # Unified implementation plan
182 | ```
183 | 
184 | ## Task Management & Orchestrator-Managed Execution
185 | 
186 | The command automatically:
187 | 
188 | - **Phase 1**: Orchestrator initialization with project setup and TodoWrite tracking
189 | - **Phase 2**: Sequential UI design with TodoWrite tracking
190 | - **Phase 3**: Parallel agent spawning with concurrent TodoWrite management
191 | - **Phase 4**: Final orchestrator synthesis with validation against all outputs
192 | - **Agent Coordination**: Uses **multiple Task tool calls in single message** to spawn agents simultaneously
193 | - **Progress Tracking**: Individual TodoWrite entries for each agent's progress
194 | - **Dependency Management**: Ensures Phase 4 waits for all Phase 3 agents to complete
195 | 
196 | ### Critical Implementation Pattern for Phase 3
197 | 
198 | **Parallel Execution Requirements:**
199 | 
200 | ```bash
201 | # CORRECT: Two Task tool calls in single message for parallel execution
202 | <invoke name="Task">
203 |   # shadcn-expert task
204 | </invoke>
205 | <invoke name="Task">
206 |   # browserbase-stagehand-expert task
207 | </invoke>
208 | 
209 | # INCORRECT: Sequential Task calls (not parallel)
210 | # Call shadcn-expert first, wait for completion, then call browserbase-stagehand-expert
211 | ```
212 | 
213 | ### Execution Strategy
214 | 
215 | ```bash
216 | # Phase 1: Sequential (project initialization)
217 | orchestrator → PRD analysis, project setup, folder creation, initial MANIFEST.md
218 | 
219 | # Phase 2: Sequential (UI foundation required)
220 | ui-designer → wireframes, component hierarchy, user flows
221 | 
222 | # Phase 3: Parallel (spawn simultaneously, using ui-designer output)
223 | # CRITICAL: Use TWO Task tool calls in SINGLE message for true parallelism
224 | shadcn-expert (visual design + aesthetic components) + browserbase-stagehand-expert (E2E testing) (simultaneous Task calls)
225 | 
226 | # Phase 4: Sequential (requires all inputs)
227 | orchestrator → synthesis, validation, finalize MANIFEST.md
228 | ```
229 | 
230 | ## Input Parameters
231 | 
232 | - `--prd`: Path to PRD file (required)
233 | - `--data`: Path to existing data specifications (optional)
234 | - `--output`: Custom output directory (optional)
235 | 
236 | ## PRD Requirements Coverage (Orchestrator-Managed Validation)
237 | 
238 | The design process ensures 100% PRD coverage across all agents:
239 | 
240 | - ✓ **orchestrator**: Initial PRD analysis & MANIFEST creation (initialization)
241 | - ✓ **ui-designer**: UI requirements & user story mapping (foundation)
242 | - ✓ **shadcn-expert**: Visual component selection, beautiful design systems & aesthetic integration (uses UI foundation for visual design context)
243 | - ✓ **browserbase-stagehand-expert**: User acceptance criteria & E2E testing (uses UI foundation)
244 | - ✓ **orchestrator**: Cross-agent validation & MANIFEST finalization (synthesis)
245 | 
246 | ## Next.js Specific Design
247 | 
248 | The design is optimized for Next.js 14+ App Router:
249 | 
250 | - **Page Structure**: `/app` directory layout
251 | - **Server Components**: Default for data fetching
252 | - **Client Components**: Only when needed for interactivity
253 | - **API Routes**: `/app/api` for backend endpoints
254 | - **Layouts**: Shared layouts for common elements
255 | - **Loading/Error**: Proper loading.tsx and error.tsx pages
256 | 
257 | ## Success Criteria (Orchestrator-Managed Validation)
258 | 
259 | A complete design includes outputs from all phases:
260 | 
261 | - ✓ **Phase 1**: Project setup & initial MANIFEST (orchestrator initialization)
262 | - ✓ **Phase 2**: UI wireframes & component hierarchy (ui-designer)
263 | - ✓ **Phase 3A**: Visual shadcn/ui component selections, beautiful design systems & aesthetic customizations (shadcn-expert)
264 | - ✓ **Phase 3B**: E2E test specifications covering all user stories (browserbase-stagehand-expert)
265 | - ✓ **Phase 4**: Complete MANIFEST + unified IMPLEMENTATION_PLAN (orchestrator synthesis)
266 | 
267 | **Efficiency Gains**: Orchestrator setup enables consistent project structure and UI foundation enables parallel component and testing work
268 | 
269 | ## Integration with Implementation
270 | 
271 | Output feeds directly into:
272 | 
273 | - `/implement-mvp` for TDD implementation
274 | - Next.js project scaffolding
275 | - Component and API implementation guidance
276 | 


--------------------------------------------------------------------------------
/LESSON.md:
--------------------------------------------------------------------------------
  1 | # Episode 9: Master Test-Driven Development with AI-Powered Testing
  2 | 
  3 | ## Complete Learning Guide for Claude Code Insiders
  4 | 
  5 | Welcome Insiders! This comprehensive lesson guide breaks down the TDD methodology with Stagehand and Browserbase demonstrated in Episode 9. Follow these structured pathways to master AI-powered testing and reduce errors by 90%.
  6 | 
  7 | ---
  8 | 
  9 | ## 🎯 Learning Objectives
 10 | 
 11 | By the end of this lesson, you will:
 12 | 
 13 | 1. **Understand** the Red → Green → Verify TDD cycle and why it prevents 90% of errors
 14 | 2. **Master** Stagehand's natural language testing approach vs traditional Playwright
 15 | 3. **Implement** multi-agent design workflows with specialized experts
 16 | 4. **Deploy** cloud-based testing with Browserbase MCP integration
 17 | 5. **Apply** the Pragmatic TDD Developer output style to enforce methodology
 18 | 
 19 | ---
 20 | 
 21 | ## 📚 Core Concepts & Timestamps
 22 | 
 23 | ### **Part 1: Foundation (00:00 - 04:12)**
 24 | 
 25 | #### The Problem We're Solving
 26 | 
 27 | - **00:00-00:48** - Why traditional testing fails
 28 |   - Brittle CSS selectors break with UI changes
 29 |   - "Works on my machine" syndrome
 30 |   - High maintenance cost of test updates
 31 | 
 32 | #### What We're Building
 33 | 
 34 | - **00:48-01:29** - Color Mixer App Overview
 35 |   - RGB sliders for color manipulation
 36 |   - Hex input/output functionality
 37 |   - Color presets and real-time preview
 38 |   - Perfect complexity for learning TDD
 39 | 
 40 | #### Revolutionary Testing Stack
 41 | 
 42 | - **01:29-02:25** - Browserbase & Stagehand Introduction
 43 |   - Cloud browsers eliminate local setup
 44 |   - Natural language replaces CSS selectors
 45 |   - AI understands intent, not implementation
 46 | 
 47 | ### **Part 2: Multi-Agent Architecture (02:25 - 04:12)**
 48 | 
 49 | #### The 5-Agent Team
 50 | 
 51 | - **02:25-03:31** - Agent Specialization Pattern
 52 |   ```
 53 |   1. UI Designer → Visual architecture & user flows
 54 |   2. shadcn Expert → Component selection & patterns
 55 |   3. Stagehand Expert → Test scenario creation
 56 |   4. TypeScript Specialist → Implementation
 57 |   5. Orchestrator → Coordination & synthesis
 58 |   ```
 59 | 
 60 | #### TDD Output Style
 61 | 
 62 | - **03:31-04:12** - Enforcing Methodology
 63 |   - Forces Red phase (test first)
 64 |   - Enforces Green phase (minimal implementation)
 65 |   - Requires Verify phase (user confirmation)
 66 |   - Prevents skipping steps or over-engineering
 67 | 
 68 | ---
 69 | 
 70 | ## 🛠️ Practical Implementation Pathways
 71 | 
 72 | ### **Pathway 1: Design Phase with Multi-Agents (04:12 - 10:19)**
 73 | 
 74 | #### Command Structure
 75 | 
 76 | ```bash
 77 | /dev:design-app "Color Mixer with RGB sliders and hex input"
 78 | ```
 79 | 
 80 | #### What Happens Behind the Scenes:
 81 | 
 82 | 1. **UI Designer Output (06:22-07:32)**
 83 | 
 84 |    - Creates wireframes and component hierarchy
 85 |    - Defines user interaction flows
 86 |    - Specifies color theory requirements
 87 | 
 88 | 2. **shadcn Expert Output (07:32-07:51)**
 89 | 
 90 |    - Selects optimal shadcn/ui components
 91 |    - Maps design requirements to component APIs
 92 |    - Provides implementation patterns
 93 | 
 94 | 3. **Stagehand Expert Output (07:51-10:19)**
 95 |    - Generates natural language test scenarios
 96 |    - Creates both local and cloud test strategies
 97 |    - Implements hybrid AI + data-testid approach
 98 | 
 99 | #### 💡 Key Learning: Design-First Development
100 | 
101 | The agents work in parallel, each contributing their expertise to create a comprehensive design blueprint BEFORE any code is written.
102 | 
103 | ### **Pathway 2: TDD Implementation (10:19 - 26:14)**
104 | 
105 | #### Phase 1: RED - Write Failing Test First
106 | 
107 | ```typescript
108 | // Traditional Playwright (Brittle)
109 | test("RGB slider changes preview", async ({ page }) => {
110 |   await page.goto("http://localhost:3000");
111 |   const slider = await page.locator('[data-testid="red-slider"]');
112 |   await slider.fill("128");
113 |   const preview = await page.locator('[data-testid="color-preview"]');
114 |   await expect(preview).toHaveCSS("background-color", "rgb(128, 0, 0)");
115 | });
116 | 
117 | // Stagehand Natural Language (Robust)
118 | test("RGB slider changes preview", async () => {
119 |   await stagehand.page.goto("http://localhost:3000");
120 |   await stagehand.page.act("Set the red color to half intensity");
121 |   const colorData = await stagehand.page.extract({
122 |     instruction: "What color is shown in the preview?",
123 |     schema: z.object({
124 |       colorName: z.string(),
125 |       hexValue: z.string(),
126 |     }),
127 |   });
128 |   expect(colorData.colorName.toLowerCase()).toContain("red");
129 | });
130 | ```
131 | 
132 | #### Phase 2: GREEN - Minimal Implementation
133 | 
134 | - **15:25-16:00** - Running the app
135 |   - Implement ONLY what makes test pass
136 |   - No extra features or optimizations
137 |   - Focus on test requirements
138 | 
139 | #### Phase 3: VERIFY - User Confirmation
140 | 
141 | - **26:14-31:11** - Using TDD to Add Features
142 |   - Run all tests to ensure nothing broke
143 |   - Get user verification before proceeding
144 |   - Document what was implemented
145 | 
146 | ### **Pathway 3: Advanced Stagehand Techniques (21:01 - 26:14)**
147 | 
148 | #### The Three Power Methods:
149 | 
150 | 1. **observe() - Find Elements for Interaction (21:01-23:00)**
151 | 
152 |    ```typescript
153 |    // observe() finds ELEMENTS you can interact with (vs extract() which gets data)
154 |    const sliders = await stagehand.page.observe({
155 |      instruction: "Find all three RGB color sliders (Red, Green, Blue)",
156 |    });
157 |    // Returns array of elements with selectors and methods
158 |    ```
159 | 
160 | 2. **extract() - Structured Data Extraction (23:00-24:40)**
161 | 
162 |    ```typescript
163 |    const colorData = await stagehand.page.extract({
164 |      instruction: "Get the current HEX and RGB color values",
165 |      schema: z.object({
166 |        hexValue: z.string().describe("The HEX color value displayed"),
167 |        rgbValue: z.string().describe("The RGB color value displayed"),
168 |        isActuallyRed: z.boolean().describe("Does the color look red?"),
169 |      }),
170 |    });
171 |    ```
172 | 
173 | 3. **act() - Human-Like Interactions (24:40-26:14)**
174 |    ```typescript
175 |    await stagehand.page.act(
176 |      "Click the red preset button to set the color to red"
177 |    );
178 |    await stagehand.page.act(
179 |      "Make the color warmer by increasing red and yellow tones"
180 |    );
181 |    await stagehand.page.act("Adjust the color to look like a sunset");
182 |    ```
183 | 
184 | ---
185 | 
186 | ## 🌟 Advanced Topics
187 | 
188 | ### **Browserbase MCP Integration (31:11 - 34:34)**
189 | 
190 | #### Cloud Testing Benefits:
191 | 
192 | - No local browser dependencies
193 | - Consistent test environment
194 | - Parallel test execution
195 | - Session recordings for debugging
196 | 
197 | #### Setup Process:
198 | 
199 | ```bash
200 | # Install Browserbase MCP
201 | claude mcp add --scope project --transport stdio \
202 |   browserbase npx @browserbasehq/mcp-server-browserbase
203 | 
204 | # Configure in settings
205 | export BROWSERBASE_API_KEY="your-api-key"
206 | export BROWSERBASE_PROJECT_ID="your-project-id"
207 | ```
208 | 
209 | #### Test Execution Modes:
210 | 
211 | ```typescript
212 | // Local Mode (Development)
213 | const stagehand = new Stagehand({ env: "LOCAL" });
214 | 
215 | // Cloud Mode (CI/CD)
216 | const stagehand = new Stagehand({
217 |   env: "BROWSERBASE",
218 |   apiKey: process.env.BROWSERBASE_API_KEY,
219 | });
220 | ```
221 | 
222 | ---
223 | 
224 | ## 📊 Comparison: Playwright vs Stagehand
225 | 
226 | ### **Why Stagehand Wins (19:24 - 21:01)**
227 | 
228 | | Aspect                | Playwright                     | Stagehand                      |
229 | | --------------------- | ------------------------------ | ------------------------------ |
230 | | **Selector Strategy** | CSS/XPath selectors            | Natural language               |
231 | | **Maintenance**       | Breaks on UI changes           | Adapts automatically           |
232 | | **Readability**       | Technical selectors            | Human-readable intent          |
233 | | **Learning Curve**    | Steep (CSS/XPath knowledge)    | Gentle (plain English)         |
234 | | **Error Messages**    | "Element not found"            | "Cannot find submit button"    |
235 | | **Test Stability**    | 60% pass rate after UI changes | 95% pass rate after UI changes |
236 | 
237 | ### **Real Example from Episode:**
238 | 
239 | ```typescript
240 | // Playwright Test - Failed after UI update
241 | await page.locator("#color-input-r").fill("255"); // ❌ ID changed
242 | 
243 | // Stagehand Test - Still Passed
244 | await stagehand.page.act("Set red to maximum"); // ✅ Intent unchanged
245 | ```
246 | 
247 | ---
248 | 
249 | ## 🚀 Practice Exercises for Insiders
250 | 
251 | ### **Exercise 1: Convert Playwright to Stagehand**
252 | 
253 | Take this Playwright test and rewrite it using Stagehand:
254 | 
255 | ```typescript
256 | // Convert this:
257 | await page.click('[data-testid="preset-sunset"]');
258 | await page.locator("#hex-display").should("have.text", "#FF6B35");
259 | 
260 | // To natural language version
261 | ```
262 | 
263 | ### **Exercise 2: Implement New Feature with TDD**
264 | 
265 | Add a "Random Color" button using strict TDD:
266 | 
267 | 1. Write failing test first
268 | 2. Implement minimal code
269 | 3. Verify with user
270 | 4. No skipping steps!
271 | 
272 | ### **Exercise 3: Multi-Agent Design Challenge**
273 | 
274 | Design a "Color History" feature using the agent team:
275 | 
276 | - What would UI Designer specify?
277 | - Which shadcn components would be selected?
278 | - What test scenarios would Stagehand Expert create?
279 | 
280 | ---
281 | 
282 | ## 💻 Command Reference
283 | 
284 | ### **Design Phase Commands**
285 | 
286 | ```bash
287 | # Full design with all agents
288 | /dev:design-app "<path-to-prd>"
289 | ```
290 | 
291 | ### **Implementation Commands**
292 | 
293 | ```bash
294 | # Start TDD implementation
295 | /dev:implement-mvp <path-to-design-output-folder> <target-folder>
296 | ```
297 | 
298 | ---
299 | 
300 | ## 🎓 Key Takeaways
301 | 
302 | ### **The 90% Error Reduction Formula**
303 | 
304 | 1. **Test First** → Catch issues before writing code
305 | 2. **Natural Language** → Tests survive UI changes
306 | 3. **Multi-Agent Design** → Comprehensive planning prevents rework
307 | 4. **Cloud Testing** → Consistent environment eliminates "works locally" bugs
308 | 5. **Strict TDD Cycle** → Methodology enforcement prevents shortcuts
309 | 
310 | ### **When to Use Each Approach**
311 | 
312 | **Use Playwright when:**
313 | 
314 | - Working with legacy codebases
315 | - Need millisecond-precision timing
316 | - Testing non-visual elements (APIs, services)
317 | 
318 | **Use Stagehand when:**
319 | 
320 | - Building new features with TDD
321 | - Testing user-facing functionality
322 | - Need maintainable test suites
323 | - Working with changing UIs
324 | 
325 | ---
326 | 
327 | ## 📖 Study Resources
328 | 
329 | ### **Required Reading**
330 | 
331 | 1. Stagehand Documentation: https://docs.stagehand.dev
332 | 2. TDD Methodology Guide: [In Builder Pack]
333 | 3. Multi-Agent Patterns: [Episode 5 Reference]
334 | 
335 | ### **Code Repositories**
336 | 
337 | - Episode 9 Resources: `/docs/youtube/episode-9-tdd-stagehand-browserbase/`
338 | - Color Mixer Implementation: [Builder Pack Exclusive]
339 | - Test Examples: `/tests/stagehand/` and `/tests/playwright/`
340 | 
341 | ### **Next Episodes to Watch**
342 | 
343 | - Episode 5: Multi-Agent Team Building (Foundation)
344 | - Episode 7: Advanced Claude Code Features
345 | - Episode 10: Performance Testing with AI (Coming Soon)
346 | 
347 | ---
348 | 
349 | ## 🤝 Community Challenge
350 | 
351 | **This Week's Challenge:**
352 | Convert one of your existing Playwright test suites to Stagehand and measure:
353 | 
354 | 1. Lines of code reduction
355 | 2. Test stability improvement
356 | 3. Maintenance time saved
357 | 
358 | Share your results in the Insiders channel with #TDDChallenge
359 | 
360 | ---
361 | 
362 | ## 🔥 Pro Tips from the Episode
363 | 
364 | 1. **Hybrid Approach** (10:19): Use both AI discovery AND data-testid for maximum reliability
365 | 2. **Test Variations** (23:00): Write multiple natural language variations for the same test
366 | 3. **Session Recording** (31:11): Always enable Browserbase recordings during development
367 | 4. **Parallel Agents** (04:12): Run design agents concurrently for 3x faster results
368 | 5. **Minimal Implementation** (15:25): Resist the urge to add "nice to have" features
369 | 
370 | ---
371 | 
372 | ## 📝 Notes Section
373 | 
374 | Use this space to track your progress through the lesson:
375 | 
376 | - [ ] Watched Episode 9 completely
377 | - [ ] Installed Stagehand and dependencies
378 | - [ ] Converted first Playwright test to Stagehand
379 | - [ ] Implemented one feature using TDD cycle
380 | - [ ] Set up Browserbase MCP integration
381 | - [ ] Completed all three practice exercises
382 | - [ ] Shared results in community challenge
383 | 
384 | ---
385 | 
386 | **Remember:** The goal isn't to write more tests. Rather, it's to write tests FIRST and let them drive your development.
387 | 
388 | Happy Testing! 🧪
389 | 
390 | - Chong-U (@AIOriented)
391 | 


--------------------------------------------------------------------------------
/.claude/commands/agent_prompts/stagehand_expert_prompt.md:
--------------------------------------------------------------------------------
  1 | # Browserbase Stagehand Expert Agent Prompt Template
  2 | 
  3 | You are a test automation expert specializing in **Stagehand's AI-powered browser automation** with natural language `act()` and `observe()` capabilities.
  4 | 
  5 | ## Phase Detection & Role Adaptation
  6 | 
  7 | **DESIGN PHASE**: Create test specifications, strategies, and targeting plans
  8 | **IMPLEMENTATION PHASE**: Write executable Stagehand test files using natural language automation
  9 | 
 10 | ## Core Philosophy: Stagehand-First
 11 | 
 12 | Stagehand's strength is **natural language automation**:
 13 | 
 14 | - `act('Set the red color to maximum')` → NOT `page.click('[data-testid="red-slider"]')`
 15 | - `observe('find all color adjustment controls')` → NOT complex CSS selectors
 16 | - **AI understands user intent** → Let Stagehand handle the complexity
 17 | 
 18 | ## Test Type Classification
 19 | 
 20 | **Pure Stagehand** (Preferred):
 21 | 
 22 | - Natural language only: `act()` and `observe()`
 23 | - Best for: User workflows, complex interactions, intent-based testing
 24 | 
 25 | **Pure Playwright** (Edge Cases):
 26 | 
 27 | - Traditional selectors for precise technical assertions
 28 | - Best for: Performance checks, exact value validation, accessibility testing
 29 | 
 30 | **Hybrid** (When Needed):
 31 | 
 32 | - Stagehand for discovery, Playwright for assertions
 33 | - Best for: Complex workflows requiring precise validation
 34 | 
 35 | ## Critical Test Coverage Areas
 36 | 
 37 | ### Interaction Conflict Testing
 38 | 
 39 | **ALWAYS test competing interactions on the same element:**
 40 | 
 41 | - If an element can be clicked AND dragged, test both work independently
 42 | - If an element can be tapped AND swiped, verify no conflicts
 43 | - Test pattern: `act('click without triggering drag')` and `act('drag without triggering click')`
 44 | 
 45 | ### Edge Case Drop/Target Testing
 46 | 
 47 | **For any drag-and-drop or moveable elements:**
 48 | 
 49 | - Test dropping ON elements, not just containers: `act('drop card directly on top of another card')`
 50 | - Test boundary cases: `act('drop between two items')`
 51 | - Test invalid targets: `act('try to drop in an invalid location')`
 52 | - Verify nothing disappears: `observe('verify all items still exist after dropping')`
 53 | 
 54 | ### Multi-Action Element Testing
 55 | 
 56 | **For elements with multiple possible actions:**
 57 | 
 58 | - Test each action in isolation
 59 | - Test rapid successive actions
 60 | - Test conflicting action attempts
 61 | - Example: `act('quickly click multiple times')` vs `act('click and hold to drag')`
 62 | 
 63 | ## CRITICAL: Always Check Latest Documentation (Both Phases)
 64 | 
 65 | **MANDATORY FIRST STEP**: Get current Stagehand API documentation using available tools:
 66 | 
 67 | **Required Documentation Sources (check ALL in order):**
 68 | 
 69 | 1. **Primary Docs**: https://docs.stagehand.dev/get_started/introduction
 70 | 2. **API Reference - Agent**: https://docs.stagehand.dev/reference/agent
 71 | 3. **API Reference - Initialization**: https://docs.stagehand.dev/reference/initialization_config
 72 | 4. **API Reference - Act Method**: https://docs.stagehand.dev/reference/act
 73 | 5. **API Reference - Extract Method**: https://docs.stagehand.dev/reference/extract
 74 | 6. **API Reference - Observe Method**: https://docs.stagehand.dev/reference/observe
 75 | 7. **Playwright Interoperability**: https://docs.stagehand.dev/reference/playwright_interop
 76 | 8. **Integration Guides**: https://docs.stagehand.dev/integrations/guides
 77 | 9. **GitHub Repository**: https://github.com/browserbase/stagehand
 78 | 10. **NPM Package**: https://www.npmjs.com/package/@browserbasehq/stagehand
 79 | 
 80 | **Verification Checklist (Must Check Reference Docs):**
 81 | 
 82 | - **Initialization Config**: Verify `new Stagehand()` parameters from `/reference/initialization_config`
 83 | - **Act Method**: Check exact signature and parameters from `/reference/act`
 84 | - **Extract Method**: Verify schema requirements and options from `/reference/extract`
 85 | - **Observe Method**: Understand return format and usage from `/reference/observe`
 86 | - **Agent API**: Check multi-step workflow capabilities from `/reference/agent`
 87 | - **Playwright Integration**: Understand interop patterns from `/reference/playwright_interop`
 88 | - **Environment Setup**: LOCAL vs BROWSERBASE modes and API key requirements
 89 | - **Integration Patterns**: Best practices from `/integrations/guides`
 90 | 
 91 | ## Phase-Specific Behaviors
 92 | 
 93 | ### DESIGN PHASE: Parallel Test Strategy & Specifications
 94 | 
 95 | 1. **Analyze PRD Requirements**: Extract testable user scenarios (sequential - baseline needed)
 96 | 2. **Spawn Parallel Planning Tasks**: Use Task tool to create specifications simultaneously:
 97 |    - **Test Scenarios Agent**: Concise overview of what Stagehand vs Playwright tests cover
 98 |    - **Stagehand Agent**: Define `act()` and `observe()` specifications for natural language testing
 99 |    - **Playwright Agent**: Plan data-testid strategy and technical validation approach
100 |    - **Coverage Agent**: Performance, accessibility, edge cases beyond basic testing
101 | 3. **Coordinate Outputs**: Integrate all parallel planning results into unified strategy
102 | 
103 | ### IMPLEMENTATION PHASE: Executable Stagehand Tests
104 | 
105 | 1. **Get Latest API Docs**: MANDATORY check of ALL reference documentation URLs before coding:
106 |    - `/reference/initialization_config` - Exact constructor parameters
107 |    - `/reference/act` - Method signature and options
108 |    - `/reference/extract` - Schema requirements and return types
109 |    - `/reference/observe` - Return format and usage patterns
110 |    - `/reference/agent` - Multi-step workflow API
111 |    - `/reference/playwright_interop` - Integration patterns
112 | 2. **Create Test Project**: Package.json, config, environment setup based on docs
113 | 3. **Write Stagehand-First Tests**: Use exact API patterns from reference docs
114 | 4. **Implement Test Types**: Pure Stagehand → Hybrid → Pure Playwright (as needed)
115 | 5. **Verify TDD Red Phase**: Tests must fail before implementation exists
116 | 
117 | ## Stagehand Testing Strengths
118 | 
119 | ### Natural Language Test Scenarios (Stagehand Excels)
120 | 
121 | - **User Workflows**: `act('Complete the checkout process')`
122 | - **Intent-Based Actions**: `act('Make the background more blue')`
123 | - **Discovery**: `observe('find all interactive elements')`
124 | - **Complex Interactions**: `act('Adjust colors until they look balanced')`
125 | - **Conflict Testing**: `act('click the item without dragging it')`
126 | - **Edge Case Testing**: `act('drop the item directly on top of another item')`
127 | 
128 | ### Technical Validation (Playwright Backup)
129 | 
130 | - **Exact Values**: `expect(element).toHaveText('255')`
131 | - **Performance**: Response times, loading states
132 | - **Accessibility**: ARIA attributes, keyboard navigation
133 | - **Browser APIs**: Local storage, cookies, viewport
134 | 
135 | ### Test Scenario Patterns That Catch Bugs
136 | 
137 | **Happy Path + Edge Cases Pattern:**
138 | 
139 | ```typescript
140 | // Happy path
141 | await page.act("drag item to empty space in container");
142 | // Edge case that catches bugs
143 | await page.act("drag item and drop it directly on another item");
144 | await page.observe("verify all items are still visible");
145 | ```
146 | 
147 | **Interaction Isolation Pattern:**
148 | 
149 | ```typescript
150 | // Test competing interactions separately
151 | await page.act("click on the draggable item to activate it");
152 | await page.observe("verify item responded to click, not drag");
153 | await page.act("drag the same item to a new location");
154 | await page.observe("verify item moved without triggering click action");
155 | ```
156 | 
157 | **Boundary Testing Pattern:**
158 | 
159 | ```typescript
160 | // Test all drop scenarios
161 | await page.act("drop item in valid container");
162 | await page.act("drop item on another item");
163 | await page.act("drop item between two items");
164 | await page.act("drop item outside any container");
165 | await page.observe("verify nothing disappeared or broke");
166 | ```
167 | 
168 | ## Stagehand Architecture Essentials
169 | 
170 | ### Package & Environment (VERIFY AGAINST /reference/initialization_config)
171 | 
172 | ```typescript
173 | // Package: @browserbasehq/stagehand
174 | // Installation: npm i @browserbasehq/stagehand
175 | 
176 | // CRITICAL: Check https://docs.stagehand.dev/reference/initialization_config
177 | // for exact constructor parameters before using this pattern!
178 | const stagehand = new Stagehand({
179 |   env: "LOCAL", // or 'BROWSERBASE' for cloud
180 |   modelName: "gpt-4o", // Check if required in reference docs
181 |   modelClientOptions: {
182 |     apiKey: process.env.OPENAI_API_KEY, // Verify requirement in docs
183 |   },
184 |   verbose: 1, // Check available options in reference docs
185 | });
186 | 
187 | await stagehand.init(); // Verify if required in reference docs
188 | const page = stagehand.page; // Verify page access pattern
189 | ```
190 | 
191 | ### API Methods (VERIFY AGAINST REFERENCE DOCS FIRST)
192 | 
193 | ```typescript
194 | // CRITICAL: Verify each method signature from reference docs before use!
195 | 
196 | // Navigation (check if supported)
197 | await page.goto("http://localhost:3000");
198 | 
199 | // Act method - Check https://docs.stagehand.dev/reference/act
200 | await page.act("Click the red button", {
201 |   /* verify options */
202 | });
203 | 
204 | // Observe method - Check https://docs.stagehand.dev/reference/observe
205 | const observations = await page.observe("click the search button");
206 | // Verify return format from reference docs before using
207 | 
208 | // Extract method - Check https://docs.stagehand.dev/reference/extract
209 | const result = await page.extract({
210 |   instruction: "get the current color value",
211 |   schema: z.object({
212 |     color: z.string(), // Verify schema requirements from docs
213 |   }),
214 |   // Check for additional options in reference docs
215 | });
216 | 
217 | // Agent API - Check https://docs.stagehand.dev/reference/agent
218 | const agent = stagehand.agent; // Verify this exists and usage pattern
219 | await agent.act("Complete workflow"); // Verify method signature
220 | ```
221 | 
222 | ### Key Gotchas (2025 Updated)
223 | 
224 | - **Required Initialization**: Must call `await stagehand.init()` before using
225 | - **Model Name Required**: Must specify `modelName: 'gpt-4o'` or similar
226 | - **API Key Required**: Must provide `OPENAI_API_KEY` in modelClientOptions
227 | - **Page Reference**: Always use `const page = stagehand.page` pattern
228 | - **Be Specific**: `act('Set red slider to maximum')` > `act('change colors')`
229 | - **Observe Then Act**: Use `page.observe()` to preview, then `page.act()` to execute
230 | - **Structured Data**: Use `page.extract()` with zod schemas for data retrieval
231 | 
232 | ## Test Type Examples
233 | 
234 | ### Pure Stagehand (Preferred - 2025 API)
235 | 
236 | ```typescript
237 | test("user adjusts colors naturally", async () => {
238 |   const stagehand = new Stagehand({
239 |     env: "LOCAL",
240 |     modelName: "gpt-4o",
241 |     modelClientOptions: {
242 |       apiKey: process.env.OPENAI_API_KEY,
243 |     },
244 |   });
245 | 
246 |   await stagehand.init();
247 |   const page = stagehand.page;
248 | 
249 |   await page.goto("http://localhost:3000");
250 |   await page.act("Navigate to the color picker");
251 |   await page.act("Make the color more red");
252 |   await page.act("Adjust until it looks like a sunset");
253 | 
254 |   // Extract structured data for validation
255 |   const colorData = await page.extract({
256 |     instruction: "get the current color value",
257 |     schema: z.object({
258 |       hexValue: z.string(),
259 |       isWarmColor: z.boolean(),
260 |     }),
261 |   });
262 | 
263 |   expect(colorData.isWarmColor).toBe(true);
264 | 
265 |   await stagehand.close();
266 | });
267 | ```
268 | 
269 | ### Pure Playwright (Edge Cases)
270 | 
271 | ```typescript
272 | test("exact RGB values are correct", async ({ page }) => {
273 |   const redSlider = page.locator('[data-testid="red-slider"]');
274 |   await redSlider.fill("255");
275 | 
276 |   await expect(page.locator('[data-testid="red-value"]')).toHaveText("255");
277 |   await expect(page.locator('[data-testid="color-preview"]')).toHaveCSS(
278 |     "background-color",
279 |     "rgb(255, 0, 0)"
280 |   );
281 | });
282 | ```
283 | 
284 | ### Hybrid (When Needed - Updated 2025)
285 | 
286 | ```typescript
287 | test("color picker workflow", async ({ page }) => {
288 |   const stagehand = new Stagehand({
289 |     env: "LOCAL",
290 |     modelName: "gpt-4o",
291 |     modelClientOptions: {
292 |       apiKey: process.env.OPENAI_API_KEY,
293 |     },
294 |   });
295 | 
296 |   await stagehand.init();
297 |   const stagehandPage = stagehand.page;
298 | 
299 |   // Stagehand for user actions
300 |   await stagehandPage.goto("http://localhost:3000");
301 |   await stagehandPage.act("Open the color picker");
302 |   await stagehandPage.act("Select a warm orange color");
303 | 
304 |   // Playwright for precise validation
305 |   await expect(page.locator('[data-testid="hex-value"]')).toContainText("#FF");
306 | 
307 |   await stagehand.close();
308 | });
309 | ```
310 | 
311 | ## Output Structure (Phase-Aware)
312 | 
313 | ### DESIGN PHASE: Parallel Specifications & Strategy
314 | 
315 | Save to: `.claude/outputs/design/agents/stagehand-expert/[project-name]-[timestamp]/`
316 | 
317 | **Three Output Files:**
318 | 
319 | 1. `test-plan.md` - Overview and index to testing approach
320 | 2. `playwright-tests.md` - Basic tests using selectors, smoke tests
321 | 3. `stagehand-tests.md` - Natural language tests using act() and observe()
322 | 
323 | ### IMPLEMENTATION PHASE: Executable Tests
324 | 
325 | Save to: `.claude/outputs/implementation/agents/stagehand-expert/[project-name]-[timestamp]/`
326 | 
327 | **Files to create:**
328 | 
329 | - `package.json` - Dependencies and scripts
330 | - `playwright.config.ts` - Playwright configuration
331 | - `tests/` - Executable Stagehand test files (Pure/Hybrid/Playwright as needed)
332 | - `.env.example` - Required environment variables
333 | - `README.md` - Setup and execution instructions
334 | 
335 | ### Directory Parameters
336 | 
337 | - `[project-name]`: lowercase-kebab-case (e.g., "color-mixer-playground")
338 | - `[timestamp]`: YYYYMMDD-HHMMSS format (e.g., "20250818-140710")
339 | 
340 | ## Quality Standards
341 | 
342 | ### Design Phase
343 | 
344 | - **Parallel Task Execution**: Spawn multiple agents simultaneously for faster completion
345 | - **Test Type Classification**: Clearly specify Pure Stagehand vs Hybrid vs Pure Playwright
346 | - **Natural Language Focus**: Emphasize what users will do in plain English
347 | - **Strategic Planning**: Focus on WHAT to test, not HOW to implement
348 | - **Edge Case Coverage**: MUST include tests for interaction conflicts and boundary conditions
349 | - **Final Coordination**: Integrate all parallel outputs into unified strategy
350 | 
351 | ### Implementation Phase
352 | 
353 | - **Stagehand-First**: Prefer `act()` and `observe()` over selectors
354 | - **Executable Immediately**: Tests must run (and fail initially for TDD)
355 | - **Complete Setup**: All dependencies, config, and instructions included
356 | - **Latest API**: Always verify current Stagehand documentation first
357 | - **Conflict Coverage**: Every test suite MUST include interaction conflict tests
358 | 
359 | ### Test Coverage Checklist (MANDATORY)
360 | 
361 | For any interactive element, verify your tests cover:
362 | 
363 | - [ ] **Happy Path**: Normal expected usage
364 | - [ ] **Interaction Conflicts**: Multiple actions on same element (click vs drag, tap vs swipe)
365 | - [ ] **Edge Drop Targets**: Dropping on unexpected elements (item on item, between items)
366 | - [ ] **Boundary Cases**: Actions at edges, overlaps, or invalid areas
367 | - [ ] **State Preservation**: Nothing disappears or breaks unexpectedly
368 | - [ ] **Rapid Actions**: Quick successive interactions don't break functionality
369 | - [ ] **Invalid Actions**: System handles impossible operations gracefully
370 | 


--------------------------------------------------------------------------------
/.claude/commands/dev/implement-mvp.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | allowed-tools: Task, Bash, Read, Write, Edit, MultiEdit, TodoWrite
  3 | description: Build MVP from design specifications using test-driven development cycles
  4 | argument-hint: <design-folder-output-path> <mvp-folder>
  5 | ---
  6 | 
  7 | # MVP Implementation from Design Specifications
  8 | 
  9 | Build production-ready MVPs from `/design-app` outputs using modern Test-Driven Development (TDD) with Playwright and Stagehand.
 10 | 
 11 | ## Core Philosophy
 12 | 
 13 | This command demonstrates modern TDD practices by:
 14 | 
 15 | - **Design-First**: All implementation decisions derive from design phase outputs
 16 | - **Test-First**: Write tests before code (Red → Green → Verify cycles)
 17 | - **Progressive Testing**: Playwright for fundamentals, Playwright+Stagehand hybrid for UI
 18 | - **No Assumptions**: Implementation follows design specifications exactly
 19 | 
 20 | ## Prerequisites
 21 | 
 22 | This command requires design outputs from `/design-app`:
 23 | 
 24 | - `.claude/outputs/design/projects/[project-name]/[timestamp]/IMPLEMENTATION_PLAN.md` - Technical roadmap
 25 | - `.claude/outputs/design/projects/[project-name]/[timestamp]/MANIFEST.md` - Requirements registry
 26 | - UI designer outputs (wireframes, component hierarchy, user flows)
 27 | - shadcn-expert outputs (component selections, composition strategies)
 28 | - browserbase-stagehand-expert outputs (test specifications)
 29 | 
 30 | ## Arguments
 31 | 
 32 | Parse `$ARGUMENTS` to extract the path to:
 33 | 
 34 | - <design-folder-output-path> the design folder containing the design outputs. The path should point to a folder like `.claude/outputs/design/projects/[project-name]/[timestamp]/`
 35 | 
 36 | - <mvp-folder> (optional) the folder that the mvp should be built in.
 37 | 
 38 | The command will automatically read:
 39 | 
 40 | - `MANIFEST.md` - Registry of all design agent outputs with requirements traceability
 41 | - `IMPLEMENTATION_PLAN.md` - Unified implementation strategy and technical approach
 42 | - Reference all related design agent outputs as indexed by the `MANIFEST.md`
 43 | - Check if the `mvp-folder` is specified. Otherwise, make an intelligent guess where to start build the app. If existing files are there, perform an assessment to know the starting point (likely to be a boilerplate next-js app)
 44 | 
 45 | ## Usage Example
 46 | 
 47 | ```bash
 48 | # Implement from design folder path
 49 | /implement-mvp .claude/outputs/design/projects/[project-name]/[timestamp]
 50 | ```
 51 | 
 52 | ## Modern TDD Workflow with Design Integration
 53 | 
 54 | ### Phase 1: Design Analysis & Project Setup (5-10 minutes)
 55 | 
 56 | **1. Read ALL Design Specifications First**
 57 | 
 58 | Before writing any code or tests, thoroughly analyze the design outputs:
 59 | 
 60 | **1.1. Visual Specification Extraction (CRITICAL)**
 61 | 
 62 | BEFORE implementation, extract concrete values from design outputs:
 63 | 
 64 | ```typescript
 65 | // Extract from design outputs - example structure
 66 | interface DesignTokens {
 67 |   colors: {
 68 |     [key: string]: {
 69 |       hex: string; // #1e40af (exact value for this app)
 70 |       rgb: string; // rgb(30, 64, 175)
 71 |       tailwind: string; // bg-blue-700 (specific class)
 72 |       contrast: number; // 8.2 (measured ratio)
 73 |       purpose: string; // "Primary CTA for finance app trust"
 74 |     };
 75 |   };
 76 | }
 77 | ```
 78 | 
 79 | **Pre-Implementation Validation Checklist**:
 80 | 
 81 | - [ ] All colors have exact hex values (no abstract descriptions)
 82 | - [ ] All color combinations validated for contrast (minimum 4.5:1)
 83 | - [ ] Tailwind classes specified for each visual element
 84 | - [ ] CSS variables defined with precise values for THIS app
 85 | - [ ] No abstract descriptions remain ("beautiful", "modern", "sophisticated")
 86 | 
 87 | **If design outputs lack concrete values**:
 88 | 
 89 | 1. HALT implementation immediately
 90 | 2. Request specific hex codes, RGB values, and Tailwind classes
 91 | 3. Document missing specifications before proceeding
 92 | 4. Never assume or improvise color values
 93 | 
 94 | **Then proceed with design analysis:**
 95 | 
 96 | - `MANIFEST.md` - Understand complete project scope and requirements coverage
 97 | - `IMPLEMENTATION_PLAN.md` - Extract technical specifications, NOT code snippets
 98 | - `ui-designer/wireframes.md` - Visual structure and layout specifications
 99 | - `ui-designer/component-hierarchy.md` - Component organization and relationships
100 | - `shadcn-expert/component-selection.md` - Exact shadcn/ui components to use
101 | - `browserbase-stagehand-expert/test-plan.md` - Test scenarios and coverage strategy
102 | 
103 | **1.1. Data Integration Patterns**
104 | 
105 | For apps using external data sources (JSON files, APIs):
106 | 
107 | - **Static JSON Files**: Import with proper TypeScript interfaces
108 | - **API Integration**: Plan fetch patterns and error handling
109 | - **Type Safety**: Create interfaces matching data structure
110 | 
111 | **Example for Static Data**:
112 | 
113 | ```typescript
114 | import episodesData from "@/data/episodes.json";
115 | interface Episode {
116 |   id: string;
117 |   title: string;
118 |   status: "ideas" | "production" | "editing" | "published";
119 | }
120 | const episodes: Episode[] = episodesData.episodes;
121 | ```
122 | 
123 | **2. Initialize Project Based on Design Specs**
124 | 
125 | Let the IMPLEMENTATION_PLAN.md guide setup, not predetermined patterns:
126 | 
127 | - Check if the target mvp-folder already exists
128 | - Assess current state if boilerplate exists
129 | - Install dependencies specified in design outputs
130 | - Configure testing framework (Playwright + Stagehand)
131 | 
132 | **3. Write Baseline Playwright Test**
133 | 
134 | **🔴 RED Phase**: Write the simplest Playwright test based on design requirements:
135 | 
136 | - Test derives from actual project requirements in MANIFEST.md
137 | - Use Playwright for this fundamental smoke test
138 | - Test must fail initially with clear error message
139 | 
140 | **🟢 GREEN Phase**: Implement minimal code to pass the test:
141 | 
142 | - Create only what's needed to satisfy the test
143 | - No extra features or anticipatory code
144 | 
145 | **✅ VERIFY Phase**: Confirm test passes and app loads
146 | 
147 | ### Phase 2: UI Scaffolding with Hybrid Testing (10-15 minutes)
148 | 
149 | **Testing Strategy for UI Components**
150 | 
151 | Based on the design outputs, create a hybrid testing approach:
152 | 
153 | - **Playwright Tests**: For component existence, structure, and technical validation
154 | - **Stagehand Tests**: For natural language interaction and user intent validation
155 | - Tests derive from `wireframes.md` and `component-hierarchy.md` specifications
156 | 
157 | **🔴 RED Phase - Write Scaffolding Tests**
158 | 
159 | Create tests that verify the UI structure from design specs:
160 | 
161 | - Component existence tests (Playwright)
162 | - Layout structure tests (Playwright)
163 | - Basic interaction tests (Stagehand for natural language)
164 | - All tests must fail initially with clear component-not-found errors
165 | 
166 | **Test Distribution Guidelines**:
167 | 
168 | - **Standard Apps**: 60% Playwright (structure), 40% Stagehand (interactions)
169 | - **Interactive Apps** (drag & drop, kanban, games): 30% Playwright (structure), 70% Stagehand (natural language interactions)
170 | - **Data-Heavy Apps**: 50% Playwright (data validation), 50% Stagehand (user workflows)
171 | 
172 | ### Phase 3: UI Implementation from Design (15-20 minutes)
173 | 
174 | **🟢 GREEN Phase - Implement Components to Pass Tests**
175 | 
176 | Using ONLY the design specifications as reference:
177 | 
178 | - Implement components specified in `shadcn-expert/component-selection.md`
179 | - Follow exact composition patterns from `composition-plan.md`
180 | - Match wireframe layouts from `ui-designer/wireframes.md`
181 | - Create minimal implementation to satisfy tests
182 | 
183 | **Key Principle**: The design outputs are the single source of truth:
184 | 
185 | - No improvisation or "better ideas" during implementation
186 | - Every decision traces back to a design specification
187 | - If something is unclear, refer back to design outputs, not assumptions
188 | 
189 | **✅ VERIFY Phase - Confirm All Scaffolding Tests Pass**
190 | 
191 | Run the hybrid test suite:
192 | 
193 | - All Playwright structure tests should pass
194 | - All Stagehand interaction tests should pass
195 | - Visual verification against wireframes
196 | 
197 | ### Phase 4: Feature Implementation with Progressive TDD (20-30 minutes)
198 | 
199 | **Progressive Testing Strategy**
200 | 
201 | Implement features using increasingly sophisticated testing:
202 | 
203 | 1. **Playwright Tests (40%)**: Technical validation, exact values, performance
204 | 2. **Stagehand Tests (50%)**: Natural language scenarios, user intent
205 | 3. **Hybrid Tests (10%)**: Combine both for complex validations
206 | 
207 | **Feature-by-Feature TDD Cycles**
208 | 
209 | For EACH feature from `browserbase-stagehand-expert/test-plan.md`:
210 | 
211 | **🔴 RED Phase - Write Feature Test**
212 | 
213 | - Select test type based on feature nature (technical → Playwright, user-centric → Stagehand)
214 | - Write test directly from specifications in `test-plan.md`
215 | - Run test to confirm it fails with expected error
216 | 
217 | **🟢 GREEN Phase - Minimal Implementation**
218 | 
219 | - Implement ONLY what's needed to pass the current test
220 | - Reference design outputs for implementation details
221 | - No anticipation of future features
222 | 
223 | **✅ VERIFY Phase - User Confirmation**
224 | 
225 | - Run test suite to confirm new test passes
226 | - Verify feature works as designed
227 | - Get user confirmation before proceeding to next feature
228 | - Document any deviations from design (should be rare)
229 | 
230 | ### Phase 5: Integration & Production Readiness (10-15 minutes)
231 | 
232 | **Integration Testing**
233 | 
234 | Create comprehensive tests based on the complete user journeys outlined in:
235 | 
236 | - `browserbase-stagehand-expert/test-plan.md` user scenarios
237 | - `ui-designer/user-flow-designs.md` interaction flows
238 | 
239 | **Production Readiness**
240 | 
241 | Verify against IMPLEMENTATION_PLAN.md success criteria:
242 | 
243 | - All tests passing (unit → Playwright → Stagehand)
244 | - TypeScript compilation clean
245 | - App builds successfully
246 | - Responsive design working per wireframes
247 | 
248 | ## Implementation Strategy
249 | 
250 | ### Modern TDD with Design-First Approach
251 | 
252 | The implementation strategy prioritizes design outputs and test-driven development:
253 | 
254 | **Core Workflow**:
255 | 
256 | 1. Read design specifications completely before any implementation
257 | 2. Write tests before code (Red → Green → Verify for every feature)
258 | 3. Use Playwright for technical tests, Stagehand for user-centric tests
259 | 4. Let design outputs guide ALL implementation decisions
260 | 
261 | **Testing Philosophy**:
262 | 
263 | - **Playwright**: Component structure, exact values, performance metrics
264 | - **Stagehand**: Natural language interactions, user journeys, intent-based testing
265 | - **Hybrid**: Combine both for comprehensive coverage
266 | 
267 | **Design Integration**:
268 | 
269 | - `MANIFEST.md`: Requirements and coverage tracking
270 | - `IMPLEMENTATION_PLAN.md`: Technical approach (guidance, not code)
271 | - `ui-designer outputs`: Component structure and visual design
272 | - `shadcn-expert outputs`: Component library integration
273 | - `stagehand-expert outputs`: Test scenarios and automation strategy
274 | 
275 | ### Design Integration Points
276 | 
277 | **Phase 1 - Project Setup:**
278 | 
279 | - Read MANIFEST.md to understand project scope and requirements
280 | - Extract project name and technical specifications from design folder
281 | - Follow IMPLEMENTATION_PLAN.md for setup requirements and dependencies
282 | - Assess existing project state if mvp-folder already contains code
283 | 
284 | **Phase 2 - Scaffolding from Actual Design:**
285 | 
286 | - Load wireframes.md and component-hierarchy.md from ui-designer outputs
287 | - Extract actual component structure (not example components)
288 | - Create scaffolding tests based on real wireframe specifications
289 | - Use data-testid patterns from design documentation
290 | 
291 | **Phase 3 - UI Implementation:**
292 | 
293 | - Follow specific component selections from shadcn-expert/component-selection.md
294 | - Implement composition strategy from shadcn-expert/composition-plan.md
295 | - Match exact wireframe layout from ui-designer outputs
296 | - Use design system strategy from shadcn-expert/design-system-strategy.md
297 | 
298 | **Phase 4 - Progressive Feature Testing:**
299 | 
300 | - Start with simple unit tests for basic component behavior
301 | - Progress to playwright-tests.md specifications for interaction testing
302 | - Implement stagehand-tests.md for natural language E2E automation
303 | - Follow red-green-verify cycle for each feature from test-plan.md
304 | 
305 | **Phase 5 - Integration:**
306 | 
307 | - Verify user scenarios from browserbase-stagehand-expert/test-plan.md
308 | - Test user flows from ui-designer/user-flow-designs.md
309 | - Ensure production readiness per IMPLEMENTATION_PLAN.md success criteria
310 | 
311 | ## Input
312 | 
313 | - **Design folder path** (required) - Path to design outputs folder containing MANIFEST.md and IMPLEMENTATION_PLAN.md
314 | 
315 | The command automatically determines project setup requirements and implementation approach from the design specifications.
316 | 
317 | ## Success Metrics
318 | 
319 | ### Design Integration Success
320 | 
321 | ✅ Next.js app initialized with correct dependencies
322 | ✅ Baseline smoke test passes
323 | ✅ Scaffolding tests cover all wireframe components
324 | ✅ UI implementation matches design specifications
325 | ✅ shadcn/ui components properly integrated
326 | 
327 | ### TDD Cycle Success
328 | 
329 | ✅ Each feature follows strict RED → GREEN → VERIFY cycle
330 | ✅ Scaffolding tests fail appropriately, then pass after UI implementation
331 | ✅ Feature tests fail initially, pass after minimal implementation
332 | ✅ User verifies each feature works before proceeding
333 | ✅ Tests align with browserbase-stagehand-expert specifications
334 | 
335 | ### Production Readiness
336 | 
337 | ✅ All tests passing (scaffolding + features + integration)
338 | ✅ TypeScript compilation clean
339 | ✅ App builds for production successfully
340 | ✅ Matches IMPLEMENTATION_PLAN.md requirements
341 | ✅ Ready for deployment
342 | 
343 | ## Design-Driven TDD Rules
344 | 
345 | ### Phase Integration Requirements
346 | 
347 | - **Must** read design outputs before starting implementation
348 | - **Must** follow UI designer component hierarchy in scaffolding tests
349 | - **Must** use shadcn-expert component selections in implementation
350 | - **Must** implement browserbase-stagehand-expert test specifications
351 | 
352 | ### RED Phase (Test First)
353 | 
354 | - Write failing tests based on design specifications
355 | - Scaffolding tests check component existence (Phase 2)
356 | - Feature tests check behavior expectations (Phase 4)
357 | - Tests must fail for clear, expected reasons
358 | 
359 | ### GREEN Phase (Minimal Implementation)
360 | 
361 | - Implement minimal code to pass current test
362 | - Follow design wireframes for component structure
363 | - Use shadcn-expert component selections
364 | - No additional features beyond current test
365 | 
366 | ### VERIFY Phase (User Confirmation)
367 | 
368 | - Show working feature matches design expectations
369 | - Demonstrate test passing
370 | - Get user approval before next RED cycle
371 | - Ensure design fidelity maintained
372 | 
373 | ## Testing Patterns
374 | 
375 | ### Design-to-Test Pattern
376 | 
377 | Extract test requirements directly from design outputs:
378 | 
379 | **Component Testing Strategy**:
380 | 
381 | 1. Read `ui-designer/wireframes.md` for visual structure
382 | 2. Read `ui-designer/component-hierarchy.md` for component relationships
383 | 3. Create tests that verify the EXACT specifications from design
384 | 
385 | **Test Type Selection**:
386 | 
387 | - **Structural elements** → Playwright (can verify exact DOM structure)
388 | - **User interactions** → Stagehand (natural language intent)
389 | - **Complex validations** → Hybrid approach
390 | 
391 | ### Progressive Testing Pattern
392 | 
393 | Build test complexity incrementally based on design outputs:
394 | 
395 | **Test Progression**:
396 | 
397 | 1. **Foundation**: Playwright tests for app initialization and basic structure
398 | 2. **Scaffolding**: Mixed Playwright/Stagehand for UI components
399 | 3. **Features**: Primarily Stagehand with Playwright for technical validation
400 | 4. **Integration**: Full user journeys using Stagehand natural language
401 | 
402 | **Key Principle**: Every test scenario comes from design outputs:
403 | 
404 | - Use exact scenarios from `browserbase-stagehand-expert/test-plan.md`
405 | - Follow test specifications from `playwright-tests.md` and `stagehand-tests.md`
406 | - No improvised test cases - all tests trace to design requirements
407 | 
408 | ## Troubleshooting Integration Issues
409 | 
410 | ### Design Files Not Found
411 | 
412 | - Verify the provided design folder path exists
413 | - Check for MANIFEST.md in the specified folder
414 | - Ensure design phase completed successfully with `/design-app`
415 | 
416 | ### Scaffolding Tests Too Complex
417 | 
418 | - Break down wireframes into smaller components
419 | - Focus on existence tests first, behavior tests later
420 | - Use data-testid attributes from UI designer specs
421 | 
422 | ### Feature Tests Don't Match Stagehand Specs
423 | 
424 | - Re-read browserbase-stagehand-expert test specifications
425 | - Align natural language actions with test implementation
426 | - Use Stagehand-compatible element selection strategies
427 | 
428 | ## Philosophy
429 | 
430 | ### Modern TDD Principles
431 | 
432 | 1. **Design as Single Source of Truth** - All implementation decisions derive from design outputs
433 | 2. **Test Before Code** - Every feature follows Red → Green → Verify discipline
434 | 3. **Progressive Test Complexity** - Start with Playwright basics, evolve to Stagehand sophistication
435 | 4. **No Assumptions** - If it's not in the design, don't implement it
436 | 5. **Continuous Verification** - User confirms each feature before proceeding
437 | 
438 | ### Testing Framework Strategy
439 | 
440 | **Playwright Usage (Foundation & Technical)**:
441 | 
442 | - Component existence and structure verification
443 | - Exact value validation (RGB values, hex codes)
444 | - Performance metrics and timing
445 | - DOM structure and data attributes
446 | - Accessibility compliance checks
447 | 
448 | **Stagehand Usage (User Intent & Natural Language)**:
449 | 
450 | - Natural language user interactions ("make the color warmer")
451 | - User journey validation ("create a sunset color")
452 | - Intent-based testing ("find and click the save button")
453 | - Emotional color validation ("verify the color feels calming")
454 | 
455 | **Hybrid Approach (Best of Both)**:
456 | 
457 | - Stagehand for user action, Playwright for validation
458 | - Natural language setup, technical verification
459 | - Complex scenarios requiring both frameworks
460 | 
461 | ### Implementation Excellence
462 | 
463 | The goal is to demonstrate that modern TDD with Playwright/Stagehand creates superior MVPs by:
464 | 
465 | - Following design specifications exactly (no drift)
466 | - Writing tests first (quality built-in)
467 | - Using the right tool for each test type
468 | - Maintaining continuous user feedback loops
469 | - Shipping production-ready code with comprehensive test coverage
470 | 


--------------------------------------------------------------------------------