# askme-ui-e2e CLAUDE.md
## Playwright E2E Testing Suite
This directory contains comprehensive end-to-end tests for the Ask-Me MCP UI using Playwright with real MCP server integration.
## Testing Architecture
### Real Server Integration Strategy
- **Actual MCP Server**: Tests use real MCP server instances with unique ports per test suite
- **Full Integration**: Validates complete HTTP/SSE communication paths
- **Protocol Compliance**: Ensures MCP protocol compliance end-to-end
- **Authentic Behavior**: Server timing, error handling, and edge cases are realistic
### Test Structure
#### Support Infrastructure (`src/support/`)
**Server Management** (`test-utils/server-manager.ts`)
- `ServerManager` class for MCP server lifecycle management
- Unique port allocation per test suite (9001-9010)
- Process spawn/cleanup with timeout handling
- Debug logging and error detection
**Page Object Models** (`page-objects/`)
- `RequestHandlerPage`: Main application page interactions
- `ResponseInputPage`: Single question response forms
- `MultipleChoiceResponsePage`: Multiple choice question handling
- `HypothesisResponsePage`: Hypothesis challenge evaluations
- `ChooseNextResponsePage`: Decision workflow interfaces
**Test Data** (`test-utils/test-data.ts`)
- Realistic request generators using shared types
- Test scenarios for all tool types
- Edge case data (long content, empty fields, etc.)
- SSE message templates
**Helpers** (`test-utils/helpers.ts`)
- Common assertions and wait conditions
- Browser notification mocking
- Network request monitoring
- Responsive design testing utilities
#### Test Suites (`src/tests/`)
**Basic Application** (`basic.spec.ts`)
- Application loading and structure
- Connection establishment
- Blueprint background verification
- Responsive design basics
- Accessibility fundamentals
**Single Question Flow** (`single-question.spec.ts`)
- Question display and markdown rendering
- Text response submission
- Completion status buttons ( Done, =
Drill Deeper)
- Tool redirect functionality
- Timeout/cancellation handling
- Character limit validation
- Keyboard shortcuts
**Multiple Choice Flow** (`multiple-choice.spec.ts`)
- Option selection (single/multiple)
- Comment fields and priority indicators
- Selection summary and bulk actions
- Completion status and tool redirects
- Large question sets performance
- Form validation
**Hypothesis Challenge Flow** (`hypothesis-challenge.spec.ts`)
- Agreement scale interaction (7-point emoji scale)
- Individual hypothesis comments
- "Won't answer" options (individual and challenge-level)
- Complex scenarios with mixed responses
- Long hypothesis statement handling
**Choose Next Flow** (`choose-next.spec.ts`)
- Decision workflow with option cards
- Selection highlighting and submission
- Abort and "request new ideas" actions
- Markdown rendering in descriptions
- Responsive grid layout
- Keyboard navigation
**SSE Communication** (`sse-communication.spec.ts`)
- Connection establishment and reconnection
- Real-time message handling
- Browser notification functionality
- Connection status updates
- Error handling and recovery
- Multiple rapid messages
**UI/UX Features** (`ui-features.spec.ts`)
- Comprehensive responsive design testing
- Form validation and character limits
- Error state handling and recovery
- Accessibility features verification
- Visual styling consistency
- Performance with large content
- Touch interactions on mobile
- Browser zoom level handling
- Focus management
## CI/CD Optimizations
### CI-Friendly Configuration
The test suite includes several optimizations for CI environments:
**Automatic CI Detection**
```typescript
const isCI = process.env['CI'] === 'true' || process.env['GITHUB_ACTIONS'] === 'true';
```
**CI Optimizations**
- **Timeouts**: 30s per test, 10s for assertions (prevents hanging)
- **Retries**: 2 retries on failure in CI, 0 in development
- **Workers**: Single worker in CI to avoid resource conflicts
- **Video/Screenshots**: Only on failure to reduce artifacts
- **Server Management**: No reuse of existing servers in CI
- **WebServer**: Disabled in CI mode to prevent port conflicts
**Project Dependencies**
```json
{
"dependsOn": ["askme-server:build", "askme-ui:build"],
"env": { "CI": "true" }
}
```
### Execution Modes
**Development Mode** (`npx nx e2e askme-ui-e2e`)
- Starts dev server automatically via webServer config
- Reuses existing servers
- Parallel execution with 5 workers
- Full browser UI for debugging
**Headless Mode** (`npx nx run askme-ui-e2e:e2e-headless`)
- No browser UI
- Fast execution
- CI-friendly timeouts
**CI Mode** (`npx nx run askme-ui-e2e:e2e-ci`)
- All CI optimizations enabled
- Builds both UI and server first
- Single worker execution
- Minimal artifact generation
## Key Testing Patterns
### Server Lifecycle Management
```typescript
// Unique port per test suite prevents conflicts
const serverManager = new ServerManager({
port: TEST_PORTS.SINGLE_QUESTION,
debug: true
});
await serverManager.start();
// ... tests ...
await serverManager.stop();
```
### Real Request Simulation
```typescript
// Send actual HTTP requests to trigger UI updates
await page.request.post(`${serverManager.getServerUrl()}/mcp/simulate-request`, {
data: createSingleQuestionRequest()
});
// Wait for real SSE events to update UI
await expect(requestHandler.currentRequest).toBeVisible();
```
### Cross-Browser Testing
- Tests run on Chromium, Firefox, and WebKit
- Responsive design across multiple viewport sizes
- Touch interaction testing for mobile browsers
### Network Request Validation
```typescript
// Monitor actual network requests
const responsePromise = waitForNetworkRequest(page, '/mcp/response');
await responseInput.submit();
await responsePromise;
```
## Port Allocation
Test suites use unique ports to enable parallel execution:
- `TEST_PORTS.BASIC: 9001`
- `TEST_PORTS.SINGLE_QUESTION: 9002`
- `TEST_PORTS.MULTIPLE_CHOICE: 9003`
- `TEST_PORTS.HYPOTHESIS_CHALLENGE: 9004`
- `TEST_PORTS.CHOOSE_NEXT: 9005`
- `TEST_PORTS.SSE_COMMUNICATION: 9006`
- `TEST_PORTS.UI_FEATURES: 9007`
## Test Data Strategy
### Realistic Test Data
- Uses actual shared types from `@ask-me-mcp/askme-shared`
- Generates proper MCP message structures
- Includes edge cases and performance scenarios
### Example Data Generators
```typescript
// Realistic single question
const request = createSingleQuestionRequest({
question: 'What is your preferred architecture pattern?'
});
// Large multiple choice for performance testing
const largeRequest = generateLargeMultipleChoiceRequest(25);
// Markdown-rich content for rendering tests
const markdownRequest = createMarkdownQuestionRequest();
```
## Browser Setup Requirements
### Playwright Installation
```bash
npx playwright install
```
### Mock Configuration
- Browser notifications are mocked to prevent permission dialogs
- EventSource API is used for real SSE communication
- Network routes can be mocked for error scenario testing
## Running Tests
### Full Test Suite (Development)
```bash
npx nx e2e askme-ui-e2e
```
### Headless Mode (CI-friendly)
```bash
npx nx run askme-ui-e2e:e2e-headless
```
### CI Mode (Full CI simulation)
```bash
npx nx run askme-ui-e2e:e2e-ci
# OR use the dedicated script
./scripts/run-e2e-ci.sh
```
### Specific Test Files
```bash
npx nx e2e askme-ui-e2e --grep "Single Question Flow"
npx nx e2e askme-ui-e2e --grep "SSE Communication"
```
### Debug Mode
```bash
npx nx e2e askme-ui-e2e --headed --debug
```
### CI Environment Variables
- `CI=true` - Enables CI-optimized settings
- `GITHUB_ACTIONS=true` - Alternative CI detection
- `BASE_URL` - Override default application URL
## Test Coverage
### Feature Coverage
- All MCP tool types (ask-one-question, ask-multiple-choice, challenge-hypothesis, choose-next)
- Real-time SSE communication
- Browser notifications
- Responsive design (mobile to desktop)
- Accessibility features
- Error handling and recovery
- Performance with large datasets
- Markdown rendering
- Blueprint theme background
### Browser Coverage
- Chromium/Chrome
- Firefox
- WebKit/Safari
### Viewport Coverage
- Mobile (375px)
- Tablet (768px)
- Desktop Small (1024px)
- Desktop Medium (1200px)
- Desktop Large (1920px)
## Integration Testing Philosophy
These E2E tests validate the complete user experience from browser to server:
1. **Real Server Communication**: Uses actual MCP server instances
2. **Authentic User Flows**: Tests complete request/response cycles
3. **Cross-Browser Compatibility**: Ensures consistent behavior
4. **Performance Validation**: Tests with realistic data loads
5. **Error Resilience**: Validates graceful error handling
6. **Accessibility Compliance**: Ensures usable interfaces
## Maintenance Notes
### Test Stability
- All tests use unique server ports to prevent conflicts
- Proper cleanup ensures no resource leaks
- Wait conditions prevent flaky test failures
- Error scenarios are tested but don't break test suite
### Adding New Tests
1. Create test data generators in `test-data.ts`
2. Add page object methods if needed
3. Use existing helper utilities for common patterns
4. Follow the real server integration pattern
5. Include responsive design testing where applicable
### Performance Considerations
- Tests use real server communication (not mocks)
- Server startup/shutdown adds ~2-3 seconds per test suite
- Large data tests validate performance characteristics
- Parallel execution enabled via unique ports
