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

Debug Information

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

PWD-AIssistant

green-erl-pastures

PWD-AIssistant

📚 Quick Documentation Access

Overview

Key Features

Quick Start

Installation

Basic Usage

With AI IDEs (Cursor, Windsurf, etc.)

VS Code Commands

Architecture

MCP-Primary Bridge Architecture

Lightweight Architecture

Module System

Core Features

1. POM (Page Object Model) Validation

2. Test Analysis & Optimization

3. Automated Test Generation

4. Test Fixing & Debugging

Configuration

Profile-Based Configuration (v0.5.9+)

VS Code Settings

AI IDE Setup

Development

Prerequisites

Build & Test

Testing Philosophy

Examples

Page Object Model Generation

API Test Generation

Natural Language Usage with AI IDEs

Troubleshooting

Common Issues

Extension Not Loading

MCP Server Not Starting

Playwright Integration Issues

Debug Information

Getting Help

Contributing

Development Guidelines

License

Changelog

Version 0.5.1 (May 2025)

Version 0.5.0 (November 2024)