What is Mcp Webdriverio

mcp-webdriverio is a Model Context Protocol (MCP) server implementation for WebdriverIO, enabling AI models to interact with web browsers through natural language commands.

Use cases

Use cases include automating web testing, performing user actions in a browser, and enabling AI assistants to navigate and interact with web applications.

How to use

To use mcp-webdriverio, start the server with ‘npm run dev’ or ‘npm run build’ followed by ‘node dist/lib/server.js’. Then, configure your MCP client to connect to this server.

Key features

Key features include customizable browser sessions, various element locator strategies, interaction capabilities (clicking, typing, mouse actions), file uploads, screenshot functionality, and element state checks.

Where to use

mcp-webdriverio can be used in web automation tasks across various domains such as testing, web scraping, and AI-driven browser interactions.

MCP WebdriverIO

A Message Control Protocol (MCP) server implementation for WebdriverIO, enabling remote browser automation through a message-based interface with advanced testing capabilities.

Overview

This project implements a Message Control Protocol server that wraps WebdriverIO functionality, allowing browser automation through a standardized message-based interface. It provides a comprehensive set of tools for browser control, element interaction, session management, and advanced testing features like visual regression testing and multi-user testing.

Why MCP WebdriverIO?

MCP WebdriverIO offers several advantages over traditional WebdriverIO implementations:

1. Message-Based Architecture

   • Decoupled client-server architecture
   • Language-agnostic interface
   • Easy integration with any system that can send/receive messages
   • Perfect for microservices and distributed systems

2. Advanced Testing Features

   • Built-in visual regression testing
   • Multi-user testing support
   • Detailed Allure reporting
   • Automatic screenshot capture for failed tests
   • Cross-browser testing made easy

3. Enhanced Test Management

   • Centralized test execution
   • Better resource management
   • Improved test parallelization
   • Detailed test reporting and analytics

4. Developer Experience

   • TypeScript-first approach
   • Comprehensive type definitions
   • Intuitive API design
   • Extensive documentation
   • Built-in best practices

Features

• Browser session management (start, close)
• Navigation control
• Element interaction (find, click, type, get text)
• Cross-browser support (Chrome, Firefox, Safari)
• Headless mode support
• Session-based architecture
• TypeScript support
• Visual regression testing
• Multi-user testing capabilities
• Detailed Allure reporting
• Automatic screenshot capture
• Test parallelization
• Page Object Model support

Prerequisites

• Node.js (v14 or higher)
• npm or yarn
• Chrome, Firefox, or Safari browser installed
• For Chrome/Firefox: WebDriver installed (ChromeDriver/geckodriver)

Installation

1. Clone the repository:

git clone https://github.com/hiroksarker/mcp-webdriverio.git
cd mcp-webdriverio

2. Install dependencies:

npm install

Project Structure

mcp-webdriverio/
├── src/
│   ├── lib/
│   │   ├── server/
│   │   │   ├── tools/
│   │   │   │   ├── browser.ts    # Browser control tools
│   │   │   │   ├── elements.ts   # Element interaction tools
│   │   │   │   └── navigation.ts # Navigation tools
│   │   │   └── server.ts         # MCP server implementation
│   │   ├── user/
│   │   │   └── UserFlowManager.ts # Multi-user testing support
│   │   └── types.ts              # TypeScript type definitions
│   └── index.ts                  # Main entry point
├── tests/
│   ├── pages/
│   │   └── LoginPage.ts          # Page object for login page
│   ├── specs/
│   │   ├── example.spec.ts       # Example test suite
│   │   └── visual.spec.ts        # Visual regression tests
│   └── multi-user/
│       └── example.spec.ts       # Multi-user test examples
├── screenshots/
│   ├── baseline/                 # Baseline screenshots
│   ├── current/                  # Current test screenshots
│   └── diff/                     # Visual diff screenshots
├── allure-results/              # Allure test results
├── package.json
└── README.md

Running Tests

Basic Test Execution

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests sequentially
npm run test:sequential

Test Reporting

# Run tests and generate Allure report
npm run test:report

# Generate report from existing results
npm run report:generate

# Open the report
npm run report:open

# Clean test results and reports
npm run report:clean

Visual Regression Testing

MCP WebdriverIO includes built-in visual regression testing capabilities:

// Example visual regression test
it('should compare the login page', async () => {
    await browser.url('https://example.com/login');
    
    // Take and compare screenshots
    await browser.saveScreen('login-page', { 
        fullPage: true,
        hideElements: ['.ads']
    });
    
    const result = await browser.checkScreen('login-page', { 
        fullPage: true,
        hideElements: ['.ads']
    });
    
    expect(result.misMatchPercentage).to.be.lessThan(0.1);
});

Multi-User Testing

Support for testing multiple user interactions simultaneously:

const flowManager = new UserFlowManager({
    maxConcurrentUsers: 2,
    defaultBrowserOptions: {
        browserName: 'chrome',
        headless: true
    }
});

// Create user sessions
const user1 = await flowManager.createSession();
const user2 = await flowManager.createSession();

// Define and execute user flows
const steps: UserFlowStep[] = [
    {
        name: 'user1-login',
        execute: async (session) => {
            if (session.id === user1.id) {
                await session.browser.$('#username').setValue('user1');
                await session.browser.$('#password').setValue('pass1');
                await session.browser.$('#submit').click();
            }
        }
    },
    // ... more steps
];

await flowManager.executeFlow(steps);

Test Reporting

MCP WebdriverIO uses Allure for detailed test reporting:

• Test execution details
• Step-by-step test actions
• Screenshots (including visual regression)
• Test metadata (feature, severity, test IDs)
• Console logs
• Test duration and status

Best Practices

1. Session Management

   • Always close browser sessions after use
   • Use unique session IDs for parallel test execution
   • Handle session cleanup in error cases

2. Element Interaction

   • Use appropriate selectors (prefer CSS selectors over XPath)
   • Add timeouts for dynamic elements
   • Implement proper error handling for element not found cases

3. Page Objects

   • Use page objects to encapsulate page-specific logic
   • Keep selectors in page objects
   • Implement reusable actions in page objects

4. Visual Testing

   • Maintain baseline screenshots
   • Use appropriate comparison settings
   • Handle dynamic content appropriately
   • Review visual diffs carefully

5. Multi-User Testing

   • Plan user interactions carefully
   • Use appropriate timeouts
   • Handle race conditions
   • Clean up resources properly

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• WebdriverIO team for the excellent automation framework
• Selenium WebDriver for the WebDriver protocol
• Allure Framework for test reporting
• All contributors who have helped improve this project