UI Test Gen MCP Server

A Model Context Protocol (MCP) server that generates Playwright visual testing scripts from CSV data with advanced configuration management, environment switching capabilities, and organized code structure.

🚀 Overview

This MCP server provides automated generation of Playwright visual testing scripts, helping developers quickly create comprehensive UI test suites from CSV test specifications. It includes automatic Playwright configuration validation, organized folder structure creation, intelligent code generation following best practices, and environment switching capabilities for multi-environment testing.

📦 Installation

$3

bash

Install globally for system-wide access

npm install -g ui-test-gen-mcp



Or install locally in your project

npm install ui-test-gen-mcp

$3

bash

Clone the repository

git clone 

cd ui-test-gen-mcp



Install dependencies

npm install



Build the TypeScript code

npm run build





🏗️ Project Structure



ui-test-gen-mcp/

├── main.ts                 # MCP server entry point

├── tools/

│   ├── index.ts           # Tool exports

│   ├── visual-test-generator.ts  # Main test generation tool

│   └── tool-lister.ts     # Tool listing utility

├── helper/

│   ├── index.ts           # Helper function exports

│   ├── template.ts        # Test templates and tag definitions

│   ├── test-tags.ts       # Tag utility functions

│   ├── env-config.ts      # Environment configuration helpers

│   ├── test-data.ts       # Test data management

│   └── register.ts        # Tool registration helper

├── data/

│   ├── core-test-script.content.txt  # Test script template

│   └── template-usage-guide.md       # Template usage documentation

└── dist/                  # Compiled JavaScript output





🛠️ Available Tools



$3

Purpose: Generate comprehensive Playwright visual testing scripts from CSV data



Features:

- Automatic Playwright Config Validation: Checks and updates

playwright.config.ts for proper snapshotDir

 configuration

- Organized Folder Structure: Creates

./tests/ui/, ./utils/ui/, ./data/ui/, and ./pages/ui/

 directories

- CSV-Based Test Generation: Processes CSV data to create test files following a strict template

- Environment Switching: NEW - Single test file handles multiple environments (prep, int, qa, prod, etc.)

- Smart Code Organization: Extracts utilities and organizes code during refactoring phase

- Project Style Integration: Analyzes existing code to match project's coding conventions

- Improved Tag System: NEW - Pre-calculated tag constants instead of function calls



Input Schema:

typescript

{

  csvData: string  // CSV content with test information

}





Required CSV Columns:

-

file_name

: Name for the generated test file

-

test_url

: URL to test

-

test_description

: Description of what to test

-

test_selector

: CSS selector for the element

-

test_hide

: Elements to hide during testing (component-specific)

-

test_action

: Action to perform (optional)

-

test_env

: NEW - Environment name (prep, int, qa, prod, staging, etc.)



$3

Purpose: Display all available tools with simple descriptions



Usage: Call this tool to see what's available in the MCP server



🔧 Key Features



$3

- Automatically validates

playwright.config.ts

 files

- Ensures

snapshotDir is set to "./__screenshots__"



- Updates configuration if missing or incorrect (only modifies snapshotDir)



$3

- Single Test File: One test file per component handles all environments

- Dynamic Environment Config: Environment configuration generated from CSV data

- User-Controlled Switching: Users manually configure environment selection

- Flexible Environment Support: Supports any environment name (prep, int, qa, prod, staging, etc.)



$3

- Clean Paths:

__screenshots__/fileName/fileName.png

 format

- No Environment Nesting: Simple, clean structure without unnecessary directories

- Consistent Naming: Predictable and maintainable screenshot organization



$3

- Pre-calculated Constants: Uses

fullPageTags and sectionTags

 constants

- No Function Calls: Eliminates

getTagsForSelector()

 function calls

- Proper Playwright Syntax: Implements tags using

test('Name', { tag: tags }, async ({ page }) => {})



- Automatic Tag Selection: Body selector gets

fullPageTags, others get sectionTags





$3

-

./tests/ui/

 - Generated test files (single file per component)

-

./utils/ui/

 - Utility functions organized by type:

  -

selectors.ts

 - Reusable selectors and constants

  -

helpers.ts

 - Common helper functions

  -

test-actions.ts

 - Generated test action functions

  -

page-objects.ts

 - Page object model patterns

  -

validation.ts

 - Validation and error handling

  -

env-config.ts

 - NEW Environment configuration utilities

  -

test-tags.ts

 - NEW Tag management utilities

-

./data/ui/

 - Test data and configuration

-

./pages/ui/

 - Page object classes and locators



$3

- Follows the embedded core test script template strictly

- Generates proper test action functions following Playwright best practices

- Preserves component-specific test_hide selectors

- Maintains separation between test files and utility/data files



$3

The server uses a mandatory core test script template that ensures consistency:

- Standard Playwright test structure

- Proper screenshot handling with

toMatchSnapshot



- Element hiding for clean visual testing

- Scroll handling for element visibility

- Proper tag implementation



📋 Workflow



$3

1. Locate

playwright.config.ts

 files in the project

2. Verify

snapshotDir is set to "./__screenshots__"



3. Update configuration if necessary



$3

1. Parse CSV data for test specifications

2. Detect environment column and use appropriate template

3. Create single test file per component in

./tests/ui/

 folder

4. Apply the core test script template with environment switching

5. Replace template variables with CSV data



$3

1. Create organized folder structure

2. Generate utility files in appropriate locations

3. Create data and page object files

4. Generate environment configuration files



$3

1. Extract common utilities to grouped files

2. Organize code for maintainability

3. Follow project's existing coding style

4. Ensure proper separation of concerns

5. Implement proper tag system



🚀 Setup & Usage



$3

- Node.js (v18 or higher)

- npm or yarn

- Playwright installed in your project



$3



1. Install the package:

bash

   npm install ui-test-gen-mcp





2. Configure your MCP client (e.g., Cursor, VS Code with MCP extension):

json

   {

     "mcpServers": {

       "ui-test-gen-mcp": {

         "command": "npx",

         "args": ["-y", "ui-test-gen-mcp"]

       }

     }

   }





3. Alternative configuration (if using local installation):

json

   {

     "mcpServers": {

       "ui-test-gen-mcp": {

         "command": "node",

         "args": ["./node_modules/ui-test-gen-mcp/dist/main.js"]

       }

     }

   }





4. Restart your MCP client to load the new server



$3



If you're developing or want to run from source:

bash

Start development mode with auto-reload

npm run dev



Build for production

npm run build



Start the built server

npm start





🔌 MCP Configuration Examples



$3

Add to your Cursor settings:

json

{

  "mcpServers": {

    "ui-test-gen-mcp": {

      "command": "npx",

      "args": ["-y", "ui-test-gen-mcp"]

    }

  }

}





$3

Add to your VS Code settings:

json

{

  "mcp.servers": {

    "ui-test-gen-mcp": {

      "command": "npx",

      "args": ["ui-test-gen-mcp"]

    }

  }

}

$3

json

{

  "mcpServers": {

    "ui-test-gen-mcp": {

      "command": "npx",

      "args": ["-y", "ui-test-gen-mcp"]

    }

  }

}





🧪 Testing



Test the MCP connection:

bash

If installed globally

ui-test-gen-mcp



If installed locally

npx ui-test-gen-mcp



If running from source

node test-connection.js





📝 CSV Format Example



$3

csv

file_name,test_url,test_description,test_selector,test_hide,test_action

homepage,https://example.com,Homepage hero section,.hero-section,.ad-banner,click

product,https://example.com/product,Product image,.product-image,.cookie-banner,screenshot

$3

csv

file_name,test_url,test_description,test_selector,test_hide,test_action,test_env

pdp,https://prep.example.com/product,PDP Full Page,body,.banner,.modal,prep

pdp,https://int.example.com/product,PDP Full Page,body,.banner,.modal,int

pdp,https://qa.example.com/product,PDP Full Page,body,.banner,.modal,qa





💡 Usage Examples



$3

Once configured, you can use the MCP server to:



1. Generate tests from CSV data:

   - Call

create_playwright_visual_tests

 with your CSV content

   - The server will automatically create test files and folder structure



2. List available tools:

   - Call

list_tools

 to see what's available



$3

csv

file_name,test_url,test_description,test_selector,test_hide,test_action,test_env

landing,https://myapp.com,Landing page header,.header-section,.notification-banner,screenshot,prep

dashboard,https://myapp.com/dashboard,Dashboard sidebar,.sidebar-nav,.ads-container,click,int





$3

The server will create:

-

./tests/ui/landing.spec.ts

 - Single test file for landing page (handles all environments)

-

./tests/ui/dashboard.spec.ts

 - Single test file for dashboard (handles all environments)

-

./utils/ui/

 - Organized utility files including environment config

-

./data/ui/

 - Test data files

-

./pages/ui/

 - Page object classes



$3

typescript

// Generated test file with environment switching

test.describe('Landing - Visual testing', () => {

  test('Landing page header', {

    tag: sectionTags  // Pre-calculated constant, no function call

  }, async ({ page }) => {

    const testData = landingTestData.find(t => 

      t.test_description === 'Landing page header' && 

      t.test_env === getCurrentEnv()

    );

    

    if (!testData) throw new Error('Test data not found');

    

    await page.goto(testData.test_url);

    

    // Hide elements specific to this component

    await hideElements(page, testData.test_hide);

    

    const locator = page.locator(testData.test_selector);

    await locator.scrollIntoViewIfNeeded();

    

    // Clean screenshot path structure

    const fileName = generateFileName(testData.test_description);

    expect(await locator.screenshot()).toMatchSnapshot(

${fileName}/${fileName}.png

);

  });

});





⚠️ Important Notes



$3

- The core test script template is mandatory and non-negotiable

- Never deviate from the template structure

- Always use exact import statements and test patterns



$3

- Single Test File: One test file per component handles all environments

- User Control: Users manually configure environment selection

- No Automatic Switching:

switchEnvironment()

 calls are not automatically generated

- Flexible Implementation: Users implement

getCurrentEnv()

 based on their configuration



$3

- No Function Calls: Tags use pre-calculated constants (

fullPageTags, sectionTags

)

- Proper Syntax: Implements Playwright tag syntax correctly

- Automatic Selection: Body selector gets

fullPageTags, others get sectionTags





$3

- Each CSV component maintains its own

test_hide

 selectors

- No cross-component selector sharing

- Preserve component-specific configurations during refactoring



$3

- Test files must be created in

./tests/ui/

 folder

- Utilities must be organized in appropriate grouped files

- Data files and page objects must be separate from

.spec.ts

 files



🎯 Benefits



- Rapid Test Creation: Generate comprehensive test suites from CSV data

- Consistent Structure: Enforced template compliance ensures consistency

- Professional Organization: Industry-standard folder structure

- Automatic Configuration: Playwright config validation and updates

- Maintainable Code: Clean, organized, and well-structured test files

- Project Integration: Follows existing project coding styles and conventions

- Easy Installation: Available as npm package for quick setup

- Environment Support: NEW - Single test file handles multiple environments

- Clean Screenshots: NEW - Simple, organized screenshot paths

- Proper Tags: NEW - No function calls, uses pre-calculated constants



🐛 Troubleshooting



$3

1. MCP Connection Failed: Ensure the server is installed and configured correctly

2. Template Errors: Verify CSV data follows required format

3. Configuration Issues: Check that

playwright.config.ts

 exists and is editable

4. Folder Creation Errors: Ensure write permissions in the project directory

5. Environment Issues: NEW - Verify

test_env

 column is present in CSV for environment switching



$3

1. Verify installation:

npm list ui-test-gen-mcp



2. Test MCP connection:

npx ui-test-gen-mcp



3. Check console logs for error messages

4. Verify CSV data format and content

5. Ensure project structure is properly set up

6. Check for environment column in CSV data



📚 Additional Resources



- Model Context Protocol Documentation

- Playwright Testing Framework

- TypeScript Documentation

- npm Package Page



🤝 Contributing



Contributions are welcome! Please ensure:

- Code follows existing patterns and style

- Tests are updated for new features

- Documentation is kept current



📄 License



ISC License - see package.json for details



---



Note: This MCP server is designed for generating Playwright visual testing scripts with environment switching capabilities. Ensure you have Playwright properly configured in your project before using the generated tests.



Package: Available on npm as

ui-test-gen-mcp`

Recent Updates:
- ✅ Environment switching capabilities
- ✅ Improved screenshot path structure
- ✅ Enhanced tag system (no function calls)
- ✅ Single test file per component
- ✅ User-controlled environment configuration

UI Test Gen MCP Server

🚀 Overview

📦 Installation

$3

bash

Install globally for system-wide access

npm install -g ui-test-gen-mcp



Or install locally in your project

npm install ui-test-gen-mcp

$3

bash

Clone the repository

git clone 

cd ui-test-gen-mcp



Install dependencies

npm install



Build the TypeScript code

npm run build





🏗️ Project Structure



ui-test-gen-mcp/

├── main.ts                 # MCP server entry point

├── tools/

│   ├── index.ts           # Tool exports

│   ├── visual-test-generator.ts  # Main test generation tool

│   └── tool-lister.ts     # Tool listing utility

├── helper/

│   ├── index.ts           # Helper function exports

│   ├── template.ts        # Test templates and tag definitions

│   ├── test-tags.ts       # Tag utility functions

│   ├── env-config.ts      # Environment configuration helpers

│   ├── test-data.ts       # Test data management

│   └── register.ts        # Tool registration helper

├── data/

│   ├── core-test-script.content.txt  # Test script template

│   └── template-usage-guide.md       # Template usage documentation

└── dist/                  # Compiled JavaScript output





🛠️ Available Tools



$3

Purpose: Generate comprehensive Playwright visual testing scripts from CSV data



Features:

- Automatic Playwright Config Validation: Checks and updates

playwright.config.ts for proper snapshotDir

 configuration

- Organized Folder Structure: Creates

./tests/ui/, ./utils/ui/, ./data/ui/, and ./pages/ui/

 directories

- CSV-Based Test Generation: Processes CSV data to create test files following a strict template

- Environment Switching: NEW - Single test file handles multiple environments (prep, int, qa, prod, etc.)

- Smart Code Organization: Extracts utilities and organizes code during refactoring phase

- Project Style Integration: Analyzes existing code to match project's coding conventions

- Improved Tag System: NEW - Pre-calculated tag constants instead of function calls



Input Schema:

typescript

{

  csvData: string  // CSV content with test information

}





Required CSV Columns:

-

file_name

: Name for the generated test file

-

test_url

: URL to test

-

test_description

: Description of what to test

-

test_selector

: CSS selector for the element

-

test_hide

: Elements to hide during testing (component-specific)

-

test_action

: Action to perform (optional)

-

test_env

: NEW - Environment name (prep, int, qa, prod, staging, etc.)



$3

Purpose: Display all available tools with simple descriptions



Usage: Call this tool to see what's available in the MCP server



🔧 Key Features



$3

- Automatically validates

playwright.config.ts

 files

- Ensures

snapshotDir is set to "./__screenshots__"



- Updates configuration if missing or incorrect (only modifies snapshotDir)



$3

- Single Test File: One test file per component handles all environments

- Dynamic Environment Config: Environment configuration generated from CSV data

- User-Controlled Switching: Users manually configure environment selection

- Flexible Environment Support: Supports any environment name (prep, int, qa, prod, staging, etc.)



$3

- Clean Paths:

__screenshots__/fileName/fileName.png

 format

- No Environment Nesting: Simple, clean structure without unnecessary directories

- Consistent Naming: Predictable and maintainable screenshot organization



$3

- Pre-calculated Constants: Uses

fullPageTags and sectionTags

 constants

- No Function Calls: Eliminates

getTagsForSelector()

 function calls

- Proper Playwright Syntax: Implements tags using

test('Name', { tag: tags }, async ({ page }) => {})



- Automatic Tag Selection: Body selector gets

fullPageTags, others get sectionTags





$3

-

./tests/ui/

 - Generated test files (single file per component)

-

./utils/ui/

 - Utility functions organized by type:

  -

selectors.ts

 - Reusable selectors and constants

  -

helpers.ts

 - Common helper functions

  -

test-actions.ts

 - Generated test action functions

  -

page-objects.ts

 - Page object model patterns

  -

validation.ts

 - Validation and error handling

  -

env-config.ts

 - NEW Environment configuration utilities

  -

test-tags.ts

 - NEW Tag management utilities

-

./data/ui/

 - Test data and configuration

-

./pages/ui/

 - Page object classes and locators



$3

- Follows the embedded core test script template strictly

- Generates proper test action functions following Playwright best practices

- Preserves component-specific test_hide selectors

- Maintains separation between test files and utility/data files



$3

The server uses a mandatory core test script template that ensures consistency:

- Standard Playwright test structure

- Proper screenshot handling with

toMatchSnapshot



- Element hiding for clean visual testing

- Scroll handling for element visibility

- Proper tag implementation



📋 Workflow



$3

1. Locate

playwright.config.ts

 files in the project

2. Verify

snapshotDir is set to "./__screenshots__"



3. Update configuration if necessary



$3

1. Parse CSV data for test specifications

2. Detect environment column and use appropriate template

3. Create single test file per component in

./tests/ui/

 folder

4. Apply the core test script template with environment switching

5. Replace template variables with CSV data



$3

1. Create organized folder structure

2. Generate utility files in appropriate locations

3. Create data and page object files

4. Generate environment configuration files



$3

1. Extract common utilities to grouped files

2. Organize code for maintainability

3. Follow project's existing coding style

4. Ensure proper separation of concerns

5. Implement proper tag system



🚀 Setup & Usage



$3

- Node.js (v18 or higher)

- npm or yarn

- Playwright installed in your project



$3



1. Install the package:

bash

   npm install ui-test-gen-mcp





2. Configure your MCP client (e.g., Cursor, VS Code with MCP extension):

json

   {

     "mcpServers": {

       "ui-test-gen-mcp": {

         "command": "npx",

         "args": ["-y", "ui-test-gen-mcp"]

       }

     }

   }





3. Alternative configuration (if using local installation):

json

   {

     "mcpServers": {

       "ui-test-gen-mcp": {

         "command": "node",

         "args": ["./node_modules/ui-test-gen-mcp/dist/main.js"]

       }

     }

   }





4. Restart your MCP client to load the new server



$3



If you're developing or want to run from source:

bash

Start development mode with auto-reload

npm run dev



Build for production

npm run build



Start the built server

npm start





🔌 MCP Configuration Examples



$3

Add to your Cursor settings:

json

{

  "mcpServers": {

    "ui-test-gen-mcp": {

      "command": "npx",

      "args": ["-y", "ui-test-gen-mcp"]

    }

  }

}





$3

Add to your VS Code settings:

json

{

  "mcp.servers": {

    "ui-test-gen-mcp": {

      "command": "npx",

      "args": ["ui-test-gen-mcp"]

    }

  }

}

$3

json

{

  "mcpServers": {

    "ui-test-gen-mcp": {

      "command": "npx",

      "args": ["-y", "ui-test-gen-mcp"]

    }

  }

}





🧪 Testing



Test the MCP connection:

bash

If installed globally

ui-test-gen-mcp



If installed locally

npx ui-test-gen-mcp



If running from source

node test-connection.js





📝 CSV Format Example



$3

csv

file_name,test_url,test_description,test_selector,test_hide,test_action

homepage,https://example.com,Homepage hero section,.hero-section,.ad-banner,click

product,https://example.com/product,Product image,.product-image,.cookie-banner,screenshot

$3

csv

file_name,test_url,test_description,test_selector,test_hide,test_action,test_env

pdp,https://prep.example.com/product,PDP Full Page,body,.banner,.modal,prep

pdp,https://int.example.com/product,PDP Full Page,body,.banner,.modal,int

pdp,https://qa.example.com/product,PDP Full Page,body,.banner,.modal,qa





💡 Usage Examples



$3

Once configured, you can use the MCP server to:



1. Generate tests from CSV data:

   - Call

create_playwright_visual_tests

 with your CSV content

   - The server will automatically create test files and folder structure



2. List available tools:

   - Call

list_tools

 to see what's available



$3

csv

file_name,test_url,test_description,test_selector,test_hide,test_action,test_env

landing,https://myapp.com,Landing page header,.header-section,.notification-banner,screenshot,prep

dashboard,https://myapp.com/dashboard,Dashboard sidebar,.sidebar-nav,.ads-container,click,int





$3

The server will create:

-

./tests/ui/landing.spec.ts

 - Single test file for landing page (handles all environments)

-

./tests/ui/dashboard.spec.ts

 - Single test file for dashboard (handles all environments)

-

./utils/ui/

 - Organized utility files including environment config

-

./data/ui/

 - Test data files

-

./pages/ui/

 - Page object classes



$3

typescript

// Generated test file with environment switching

test.describe('Landing - Visual testing', () => {

  test('Landing page header', {

    tag: sectionTags  // Pre-calculated constant, no function call

  }, async ({ page }) => {

    const testData = landingTestData.find(t => 

      t.test_description === 'Landing page header' && 

      t.test_env === getCurrentEnv()

    );

    

    if (!testData) throw new Error('Test data not found');

    

    await page.goto(testData.test_url);

    

    // Hide elements specific to this component

    await hideElements(page, testData.test_hide);

    

    const locator = page.locator(testData.test_selector);

    await locator.scrollIntoViewIfNeeded();

    

    // Clean screenshot path structure

    const fileName = generateFileName(testData.test_description);

    expect(await locator.screenshot()).toMatchSnapshot(

${fileName}/${fileName}.png

);

  });

});





⚠️ Important Notes



$3

- The core test script template is mandatory and non-negotiable

- Never deviate from the template structure

- Always use exact import statements and test patterns



$3

- Single Test File: One test file per component handles all environments

- User Control: Users manually configure environment selection

- No Automatic Switching:

switchEnvironment()

 calls are not automatically generated

- Flexible Implementation: Users implement

getCurrentEnv()

 based on their configuration



$3

- No Function Calls: Tags use pre-calculated constants (

fullPageTags, sectionTags

)

- Proper Syntax: Implements Playwright tag syntax correctly

- Automatic Selection: Body selector gets

fullPageTags, others get sectionTags





$3

- Each CSV component maintains its own

test_hide

 selectors

- No cross-component selector sharing

- Preserve component-specific configurations during refactoring



$3

- Test files must be created in

./tests/ui/

 folder

- Utilities must be organized in appropriate grouped files

- Data files and page objects must be separate from

.spec.ts

 files



🎯 Benefits



- Rapid Test Creation: Generate comprehensive test suites from CSV data

- Consistent Structure: Enforced template compliance ensures consistency

- Professional Organization: Industry-standard folder structure

- Automatic Configuration: Playwright config validation and updates

- Maintainable Code: Clean, organized, and well-structured test files

- Project Integration: Follows existing project coding styles and conventions

- Easy Installation: Available as npm package for quick setup

- Environment Support: NEW - Single test file handles multiple environments

- Clean Screenshots: NEW - Simple, organized screenshot paths

- Proper Tags: NEW - No function calls, uses pre-calculated constants



🐛 Troubleshooting



$3

1. MCP Connection Failed: Ensure the server is installed and configured correctly

2. Template Errors: Verify CSV data follows required format

3. Configuration Issues: Check that

playwright.config.ts

 exists and is editable

4. Folder Creation Errors: Ensure write permissions in the project directory

5. Environment Issues: NEW - Verify

test_env

 column is present in CSV for environment switching



$3

1. Verify installation:

npm list ui-test-gen-mcp



2. Test MCP connection:

npx ui-test-gen-mcp



3. Check console logs for error messages

4. Verify CSV data format and content

5. Ensure project structure is properly set up

6. Check for environment column in CSV data



📚 Additional Resources



- Model Context Protocol Documentation

- Playwright Testing Framework

- TypeScript Documentation

- npm Package Page



🤝 Contributing



Contributions are welcome! Please ensure:

- Code follows existing patterns and style

- Tests are updated for new features

- Documentation is kept current



📄 License



ISC License - see package.json for details



---



Note: This MCP server is designed for generating Playwright visual testing scripts with environment switching capabilities. Ensure you have Playwright properly configured in your project before using the generated tests.



Package: Available on npm as