verdexhq/verdex-mcp

AI-First Browser Automation for Playwright Test Authoring

Verdex helps AI coding assistants write robust Playwright tests. It combines:

• MCP tools for token-efficient DOM exploration (100-1K tokens vs 10K+ dumps)
• Cursor rules & Claude skills that teach LLMs modern Playwright patterns and the Container → Content → Role methodology
• Multi-role browser isolation for testing authenticated flows in parallel

AI assistants don't know how to write good Playwright tests or efficiently explore page structure. Verdex gives them both the tools and the knowledge.

The Difference

Without Verdex — AI generates brittle selectors:

await page.getByRole('button', { name: 'Add to Cart' }).nth(8).click(); // 💀 Breaks on reorder
await page.locator('.btn-primary').first().click(); // 💀 Breaks on CSS change

With Verdex — AI generates stable selectors:

await page
  .getByTestId('product-card')
  .filter({ hasText: 'iPhone 15 Pro' })
  .getByRole('button', { name: 'Add to Cart' })
  .click(); // ✅ Survives any DOM restructuring

Verdex vs Playwright MCP

Playwright MCP gives AI a browser. Verdex teaches AI to write tests like a senior QA engineer.

Quick Start

1. Add MCP Server

{
  "mcpServers": {
    "verdex": {
      "command": "npx",
      "args": ["@verdex/mcp@latest"]
    }
  }
}

2. Add AI Instructions

For Cursor:

mkdir -p .cursor/rules
cp node_modules/@verdex/mcp/.cursor/rules/*.mdc .cursor/rules/

For Claude: Use skills from node_modules/@verdex/mcp/.claude/skills/verdex-playwright-complete/

3. Write Tests

User: "Write a test that adds an iPhone to the cart"

AI (with Verdex):
  → Navigates to page, takes snapshot
  → Uses resolve_container to find stable test IDs
  → Uses inspect_pattern to find unique content
  → Generates container-scoped, role-based selector
  → Writes test following Playwright best practices

👉 — See the full workflow in action

The Workflow: Explore → Select → Test

Phase 1: Explore

Use browser tools to understand the app:

browser_initialize()
browser_navigate("https://shop.example.com")
browser_click("e5")  // Click using ref from snapshot
browser_snapshot()   // See what changed

Phase 2: Select

Build stable selectors with progressive DOM exploration:

resolve_container("e25")    // Find containers with test IDs
inspect_pattern("e25", 2)   // Analyze sibling structure  
extract_anchors("e25", 1)   // Mine deep content if needed

Phase 3: Test

Write idiomatic Playwright tests:

test('should add product to cart', async ({ page }) => {
  await page.goto('/products');
  
  await page
    .getByTestId('product-card')
    .filter({ hasText: 'iPhone 15 Pro' })
    .getByRole('button', { name: 'Add to Cart' })
    .click();
  
  await expect(page.getByText('Item added')).toBeVisible();
});

Tools Reference

Browser Tools

DOM Exploration Tools

Multi-Role Tools

Multi-Role Configuration

Test different user roles in isolated browser contexts:

{
  "mcpServers": {
    "verdex": {
      "command": "npx",
      "args": [
        "@verdex/mcp@latest",
        "--role", "admin", "/path/to/admin-auth.json", "https://admin.example.com",
        "--role", "user", "/path/to/user-auth.json", "https://app.example.com"
      ]
    }
  }
}

Uses Playwright's storageState format for auth files.

AI Instructions

The rules and skills are essential — they teach AI the patterns that make selectors stable.

What They Teach

Installation

Cursor Rules (.cursor/rules/):

cp node_modules/@verdex/mcp/.cursor/rules/*.mdc .cursor/rules/

Claude Skills (.claude/skills/):

• Works automatically with Claude Code and Claude Agent SDK
• For Claude.ai: ZIP and upload via Settings > Features

Resources

• — 60-second hands-on walkthrough
• — Core methodology
• — App exploration
• — Test best practices
• — Quick reference

Contributing

We welcome contributions! See for guidelines.

Areas we'd love help with:

• Token efficiency benchmarks
• Additional browser actions (drag-and-drop, hover)
• Cross-origin iframe handling
• More examples and tutorials

License

Apache 2.0 — see