PWD-AIssistant
AI-powered Playwright test debugging, maintenance, and generation assistant with MCP support for AI IDEs
Version 0.6.0 | Last Updated: June 2025
📚 Quick Documentation Access
Resource |
Access Method |
Description |
📖 Complete Tutorial |
Ctrl+Shift+P → "PWD-AIssistant: Open Tutorial" |
Step-by-step guide with examples |
🚀 Quick Start |
See Installation below |
Get started in 5 minutes |
💡 Help & Troubleshooting |
Ctrl+Shift+P → "PWD-AIssistant: Open Documentation" |
Common issues and solutions |
🔧 MCP Setup |
See AI IDE Setup below |
Configure with Cursor, Windsurf, etc. |
📋 Command Reference |
Ctrl+Shift+P → Search "PWD" |
All available commands |
💡 Tip: After installing, run PWD-AIssistant: Open Tutorial
for the complete guide!
Overview
PWD-AIssistant is a VS Code extension that provides AI-powered assistance for Playwright testing workflows through the Model Context Protocol (MCP). Originally designed for Windsurf IDE, it now offers universal compatibility with multiple AI IDEs including Cursor, Windsurf, and others.
Key Features
- Universal AI IDE Integration: MCP server provides natural language interface for AI-powered testing
- Intelligent Test Analysis: Analyzes Playwright tests for issues and optimization opportunities
- Automated Test Generation: Creates API and E2E tests from specifications
- Page Object Model Validation: Validates and enhances POM implementations
- Test Fixing & Debugging: AI-powered test analysis and fixing capabilities
- Playwright Integration: Seamless integration with Microsoft Playwright extension
Quick Start
Installation
- Install the extension from VS Code marketplace
- Ensure Node.js ≥20.18.3 is installed
- Install Microsoft Playwright extension (recommended)
- Configure your AI IDE for MCP integration (see tutorial:
EXTENSION_TUTORIAL.md
)
Basic Usage
With AI IDEs (Cursor, Windsurf, etc.)
"Analyze my Playwright tests and suggest improvements"
"Generate an API test for user registration endpoint"
"Fix the failing login test in my test suite"
"Validate my page object model implementation"
VS Code Commands
PWD-AIssistant: Start MCP Server
- Launch the MCP server for AI IDE integration
PWD-AIssistant: Validate Page Object Model
- Validate Page Object Model selectors
PWD-AIssistant: Analyze Test Patterns
- Analyze test files for improvements
PWD-AIssistant: Generate API Test
- Create API tests from specifications
PWD-AIssistant: Generate E2E Test
- Create E2E tests from scenarios
PWD-AIssistant: Fix Test
- AI-powered test debugging
Architecture
MCP-Primary Bridge Architecture
PWD-AIssistant uses a MCP-Primary Bridge Architecture for consistent functionality across interfaces:
MCP Server Tools (Primary Implementation):
scan_page_for_locators
- Scans webpages for test locators with AI analysis
generate_pom_class
- Generates AI-optimized Page Object Model classes
validate_pom_selectors
- Validates POM selectors against live webpages
analyze_test_failure
- AI-powered analysis of test failures with suggestions
suggest_selector_improvements
- AI suggestions for selector stability and performance
find_missing_data_cy
- Finds elements missing data-cy attributes with suggestions
VS Code Commands (Bridge to MCP):
- All extension commands internally call MCP tools for consistency
- Same functionality whether accessed via Command Palette or AI assistant
- Single source of truth eliminates duplicate implementations
Lightweight Architecture
- Size: Only 608KB (85% reduction from previous versions)
- Dependencies: Uses Microsoft Playwright extension instead of bundling runtime
- Performance: Fast startup and minimal resource usage
- Integration: Native VS Code extension with rich UI
Module System
- Source Code: Modern ES modules for development
- Compilation: TypeScript compiles to CommonJS for VS Code compatibility
- Testing: Two-stage approach with real APIs (no mocks)
Core Features
1. POM (Page Object Model) Validation
Validates and optimizes Page Object Model implementations:
- Analyzes TypeScript/JavaScript files for POM patterns
- Extracts locators and validates their syntax
- Suggests improvements and best practices
- Converts XPath to CSS selectors
2. Test Analysis & Optimization
Analyzes Playwright tests for issues and optimization opportunities:
- Detects inefficient locators
- Identifies flaky test patterns
- Suggests performance improvements
- Validates test structure
3. Automated Test Generation
Creates comprehensive test files:
- API Tests: From OpenAPI specs or endpoint descriptions
- E2E Tests: From user stories or manual test cases
- Complete Implementation: Ready-to-run test files
4. Test Fixing & Debugging
Automatically fixes failing tests:
- Analyzes test failure messages
- Suggests specific fixes with explanations
- Handles common issues like timeouts and locator problems
Configuration
Profile-Based Configuration (v0.5.9+)
Create a .pwd-profiles.json
file in your project root for environment-specific settings:
{
"version": "1.0",
"defaults": {
"locators": {
"priority": ["data-cy", "data-testid", "id", "class"]
},
"auth": {
"protectedPaths": ["/app/"],
"loginUrl": "/account/login",
"type": "spa"
}
},
"configs": {
"development": {
"name": "development",
"baseURL": "https://dev.myapp.com",
"description": "Development environment"
}
}
}
VS Code Settings
{
"pwd-aissistant.autoStartMCPServer": true,
"pwd-aissistant.mcpServerPort": 3001
}
📖 For complete configuration examples: See EXTENSION_TUTORIAL.md
with detailed examples for Angular, .NET Zero, Legacy, and Multi-Environment setups.
AI IDE Setup
For detailed setup instructions, see the comprehensive tutorial: EXTENSION_TUTORIAL.md
Supported AI IDEs:
- Cursor IDE: Full MCP integration with configuration helper
- Windsurf IDE: Native MCP support
- Other MCP-compatible tools: Universal REST API access
Development
Prerequisites
- Node.js ≥20.18.3
- VS Code ^1.96.0
- TypeScript ^5.3.3
- Microsoft Playwright extension (recommended)
Build & Test
# Install dependencies
npm install
# Run unit tests (fast)
npm run test:mocha
# Compile extension
npm run compile
# Run VS Code integration tests (quick mode)
npm run test:vscode:quick
# Run VS Code integration tests (full debugging)
npm run test:vscode:full
# Package extension
npm run package
# Start MCP server manually
npm run start:mcp
Testing Philosophy
- Real APIs Only: No mocks for VS Code or Playwright APIs
- Two-Stage Testing: Fast unit tests + comprehensive integration tests
- ESLint Enforcement: Custom rules prevent accidental mock usage
- MCP Transition Support: Tests work during AI provider migration
Examples
Page Object Model Generation
// Generated POM with optimized selectors
export class LoginPage {
readonly page: Page;
constructor(page: Page) {
this.page = page;
}
// Optimized locators
readonly usernameInput: Locator = this.page.locator('#username');
readonly passwordInput: Locator = this.page.locator('#password');
readonly loginButton: Locator = this.page.locator('[data-testid="login-submit"]');
// Navigation
async goto() {
await this.page.goto('/login');
}
// Helper methods
async login(username: string, password: string) {
await this.usernameInput.fill(username);
await this.passwordInput.fill(password);
await this.loginButton.click();
}
}
API Test Generation
// Generated API test
test('POST /api/users - Create User', async ({ request }) => {
const response = await request.post('/api/users', {
data: {
name: 'John Doe',
email: 'john@example.com'
}
});
expect(response.status()).toBe(201);
const user = await response.json();
expect(user.name).toBe('John Doe');
expect(user.email).toBe('john@example.com');
});
Natural Language Usage with AI IDEs
User: "I need to test the checkout flow but my selectors keep breaking"
AI with PWD-AIssistant: "I'll analyze your checkout tests and suggest improvements. Let me examine your current selectors and recommend more stable alternatives."
[Uses MCP tools to analyze tests, identify issues, suggest fixes]
AI: "I found 5 fragile selectors in your checkout tests. Here are the recommended improvements with explanations..."
Troubleshooting
Common Issues
Extension Not Loading
Symptoms: Commands not appearing in Command Palette
Solutions:
- Check VS Code version (requires 1.96.0+)
- Restart VS Code
- Run:
PWD-AIssistant: Test Command Registration
MCP Server Not Starting
Symptoms: MCP tools not available in AI IDE
Solutions:
- Check Node.js version (≥20.18.3 required)
- Verify port 3001 is available
- Manually start:
PWD-AIssistant: Start MCP Server
Playwright Integration Issues
Symptoms: Playwright commands not working
Solutions:
- Install Microsoft Playwright extension
- Run:
PWD-AIssistant: Check Playwright Extension
- Install Playwright:
PWD-AIssistant: Install Playwright Runtime
- VS Code Output: View → Output → PWD-AIssistant
- Developer Tools: Help → Toggle Developer Tools (check Console)
- Extension Logs: Look for "🔥 PWD-AIssistant:" prefixed messages
Getting Help
- Tutorial: See
EXTENSION_TUTORIAL.md
for comprehensive guide
- Testing: Review
test/TESTING POLICY.md
for development guidelines
- GitHub Issues: Report bugs and feature requests
Contributing
- Fork the repository
- Create a feature branch
- Write tests (unit + integration)
- Ensure compilation succeeds
- Submit a pull request
Development Guidelines
- Follow the no-mock testing policy
- Use real VS Code and Playwright APIs
- Add comprehensive test coverage
- Update documentation for new features
License
MIT License - see LICENSE for details.
Changelog
Version 0.5.1 (May 2025)
- Major: Lightweight architecture (608KB, 85% size reduction)
- Major: Microsoft Playwright extension integration
- Major: MCP server implementation for universal AI IDE support
- Feature: Enhanced command set with Playwright integration
- Feature: Cursor IDE compatibility improvements
- Fix: Extension loading issues in Cursor IDE
- Fix: Command registration and activation improvements
Version 0.5.0 (November 2024)
- Major: MCP (Model Context Protocol) integration
- Major: Universal AI IDE compatibility
- Feature: Automated test generation (API and E2E)
- Feature: Enhanced POM validation
- Feature: Test fixing and debugging capabilities
See full changelog in CHANGELOG.md
PWD-AIssistant v0.5.6
Empowering Playwright testing through AI-powered automation
Last Updated: June 2025