MoltQA

A lightweight browser automation toolkit using Chrome DevTools Protocol (CDP). No Playwright or Puppeteer dependencies - just raw WebSocket communication with Chrome.

Features

• Zero heavy dependencies - Only requires ws (WebSocket client)
• React-compatible - Works with controlled inputs using native value setters
• Screenshot automation - Capture at multiple viewports with one command
• Configurable - Project-specific selectors via qa.config.js
• Claude Code integration - Includes personas for AI-assisted QA workflows

Quick Start

1. Install

# Copy to your project
cp -r cdp-qa-toolkit/qa your-project/qa
cp cdp-qa-toolkit/qa.config.example.js your-project/qa.config.js

# Install dependency
npm install ws

Or add to your package.json:

{
  "scripts": {
    "qa": "node qa/cdp-qa.js",
    "qa:responsive": "node qa/cdp-qa.js responsive",
    "qa:mobile": "node qa/cdp-qa.js screenshot mobile",
    "qa:desktop": "node qa/cdp-qa.js screenshot desktop"
  },
  "devDependencies": {
    "ws": "^8.18.0"
  }
}

2. Launch Chrome with Debugging

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Windows
chrome.exe --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

3. Verify Connection

npm run qa status

Commands

Screenshots

npm run qa screenshot mobile     # 375x812
npm run qa screenshot tablet     # 768x1024
npm run qa screenshot desktop    # 1920x1080
npm run qa screenshot 1440 900   # Custom size
npm run qa responsive            # All breakpoints at once

Navigation & Interaction

npm run qa navigate /dashboard
npm run qa click "[data-testid='submit-btn']"
npm run qa type "input[name='email']" "test@example.com"
npm run qa select "#country" "US"
npm run qa wait "[data-testid='loaded']"
npm run qa eval "document.title"

Modal Handling

npm run qa modal wait            # Wait for modal to appear
npm run qa modal fill "#name" "John"
npm run qa modal select "#plan" "pro"
npm run qa modal submit
npm run qa modal close

Utilities

npm run qa status                # Check Chrome connection
npm run qa audit                 # Page stats (DOM elements, forms, etc.)
npm run qa console               # Stream console.log output

Configuration

Create qa.config.js in your project root:

module.exports = {
  // Chrome debugging URL
  cdpUrl: 'http://127.0.0.1:9222',

  // Screenshot output directory
  screenshotDir: './qa-screenshots',

  // Custom viewports
  viewports: {
    mobile: { width: 375, height: 812, mobile: true },
    tablet: { width: 768, height: 1024, mobile: true },
    desktop: { width: 1920, height: 1080, mobile: false },
  },

  // Project-specific selectors
  selectors: {
    modal: '[role="dialog"]',
    modalClose: '[data-testid="modal-close"]',
    submitButton: 'button[type="submit"]',
  },
};

Claude Code Integration

This toolkit includes Claude Code personas for AI-assisted QA workflows.

Setup

Copy the .claude folder to your project:

cp -r cdp-qa-toolkit/.claude your-project/.claude

Personas

Persona	Invoke With	Purpose
QA Tester	"Hey QA Claude..."	Browser automation, screenshots, verification
Orchestrator	"Orchestrator mode"	Task breakdown, persona coordination

Usage with Claude

User: Hey QA Claude, verify the login form works

Claude: I'll verify the login form using CDP.

1. First, let me check the connection:
   [Runs: npm run qa status]

2. Taking a screenshot of the login page:
   [Runs: npm run qa screenshot desktop]

3. Testing form interaction:
   [Runs: npm run qa type "input[name='email']" "test@example.com"]
   [Runs: npm run qa screenshot desktop]

## QA Verification Report

**Test:** Login form functionality
**Result:** PASS

### Evidence
- Screenshot: `qa-screenshots/login_desktop_1707123456.png`
- Form accepts input correctly
- Submit button is visible and clickable

Mandatory QA Rule

The personas enforce a critical rule: All code changes must be verified in the browser before marking complete.

TypeScript compiling ≠ working code. Build passing ≠ correct UI. Only visual verification counts.

Programmatic Usage

const {
  waitFor,
  clickElement,
  typeInto,
  takeScreenshot,
  cdp,
  getLocalhost
} = require('./qa/cdp-qa.js');

async function testLogin() {
  const page = await getLocalhost();
  const { send, close } = await cdp(page.webSocketDebuggerUrl);

  try {
    await typeInto(send, 'input[name="email"]', 'test@example.com');
    await typeInto(send, 'input[name="password"]', 'password123');
    await clickElement(send, 'button[type="submit"]');
    await waitFor(send, '[data-testid="dashboard"]', { timeout: 5000 });
    console.log('Login successful!');
  } finally {
    close();
  }
}

Why CDP Instead of Playwright?

	CDP QA	Playwright
Dependencies	1 (ws)	100+
Install size	~100KB	~100MB
Startup time	Instant	2-5 seconds
Use case	Quick visual checks	Full E2E suites

Use CDP for rapid development verification. Use Playwright for comprehensive test suites and CI.

File Structure

cdp-qa-toolkit/
├── qa/
│   └── cdp-qa.js           # Main CLI tool
├── .claude/
│   ├── personas/
│   │   ├── qa-tester.md    # QA automation persona
│   │   └── orchestrator.md # Task coordination persona
│   └── LESSONS-LEARNED.md  # Common issues and solutions
├── qa.config.example.js    # Configuration template
├── package.json
└── README.md

License

MIT