GitHub - openqa-labs/openqa: AI Driven Test Automation

AI Powered Natural Language Browser Test Automation

No selectors. No flake. Just plain English.

Features

• 🗣️ Write Tests in Plain English — Describe what you want, not how to find it. "Add laptop to cart" just works.
• 📝 BDD & YAML Support — Works with Playwright-BDD, Cucumber.js, or simple YAML files. Zero step definitions needed.
• 🔌 Any LLM Provider — Claude, OpenAI, or Gemini. Use the model that fits your budget and needs.
• ⚡ 2-Minute Setup — npx openqa init and you're running tests. No complex configuration.

Powered by: Claude Agent SDK • LangChain • Playwright MCP

Quick Start

New Project (YAML, Playwright-BDD, or Cucumber.js):

This single command will:

1. Prompt for framework selection (YAML, Playwright-BDD, or Cucumber.js)
2. Install dependencies and Playwright browsers
3. Prompt for AI provider (Anthropic or Other)
4. Show tailored setup instructions

Write tests in YAML or .feature files - AI handles everything!

name: Shopping Tests
tests:
  - name: Buy a product
    steps:
      - Navigate to "https://shop.example.com"
      - Search for "laptop" and add the first result to cart
      - Proceed to checkout and enter shipping details
      - Verify "Order confirmed" appears on the page

YAML with Custom Fixtures (Cloud browsers, custom data, etc.):

name: Cloud Browser Tests
fixtureFile: ./fixtures/browser.js  # Custom Playwright fixtures

tests:
  - name: Test with cloud browser
    steps:
      - Navigate to "https://shop.example.com"
      - Add laptop to cart

// fixtures/browser.js - Custom browser fixture
import { test as base } from '@playwright/test';
import { chromium } from '@playwright/test';

export const test = base.extend({
  browser: [async ({}, use) => {
    const browser = await chromium.connectOverCDP('ws://your-cloud-browser');
    await use(browser);
    await browser.close();
  }, { scope: 'worker' }],
});

Integrations with Existing Projects:

• With Existing Playwright
• With Existing Playwright-BDD
• With Existing Cucumber.js

With Existing Playwright-BDD

Step 1: Install OpenQA

Step 2: Setup authentication

Choose ONE method:

# A. Claude Code CLI (recommended)
claude login

# B. API Key
export ANTHROPIC_API_KEY=your_key

# C. .env file
echo "ANTHROPIC_API_KEY=your_key" > .env

For OpenAI/Google, create .env:

AGENT_TYPE=langchain
DEFAULT_PROVIDER=openai  # or 'google'
OPENAI_API_KEY=your_key

Step 3: Replace step definitions

// features/steps/steps.ts
export { test } from 'openqa/bdd/playwright-bdd';

Step 4: Run tests

With Existing Cucumber.js

Step 1: Install OpenQA

npm install openqa @playwright/test

Step 2: Setup authentication

Choose ONE method:

# A. Claude Code CLI (recommended)
claude login

# B. API Key
export ANTHROPIC_API_KEY=your_key

# C. .env file
echo "ANTHROPIC_API_KEY=your_key" > .env

For OpenAI/Google, create .env:

AGENT_TYPE=langchain
DEFAULT_PROVIDER=openai  # or 'google'
OPENAI_API_KEY=your_key

Step 3: Replace step definitions

// features/step_definitions/steps.js
import 'openqa/bdd/cucumber';
// Browser setup included automatically!

Step 4: Run tests

With Existing Playwright

Step 1: Install OpenQA

Step 2: Setup authentication

Choose ONE method:

# A. Claude Code CLI (recommended)
claude login

# B. API Key
export ANTHROPIC_API_KEY=your_key

# C. .env file
echo "ANTHROPIC_API_KEY=your_key" > .env

For OpenAI/Google, create .env:

AGENT_TYPE=langchain
DEFAULT_PROVIDER=openai  # or 'google'
OPENAI_API_KEY=your_key

Step 3: Use in your tests

import { test } from "@playwright/test";
import { runAgent } from "openqa";

test("AI agent fills form", async ({ page, context }) => {
  await page.goto("https://example.com/form");

  // Agent uses the same browser context
  await runAgent('Fill in the form with test data', context);

  // Verify in the same browser
  await expect(page.locator('input[name="email"]')).toHaveValue("test@example.com");
});

Step 4: Run tests

How It Works

The agent uses @playwright/mcp with createConnection() to share the browser context. This enables:

• Shared cookies and session storage
• Same page state and navigation history
• True collaborative automation between tests and AI

API Reference

runAgent(prompt, browserContext, options?)

Run AI agent with natural language instruction.

Parameters:

• prompt (string): Natural language instruction
• browserContext (BrowserContext): Playwright browser context
• options (object): Optional configuration
  • verbose (boolean): Enable logging (default: true)
  • agentType (string): 'claude' (default) or 'langchain'
  • provider (string): AI provider ('anthropic', 'openai', 'google')
  • model (string): Model name
  • recursionLimit (number): Max recursion depth (default: 100)

Returns: Promise

BDD Integration

Playwright-BDD (simple):

// features/steps/steps.ts
export { test } from 'openqa/bdd/playwright-bdd';

Playwright-BDD (custom):

import { createAIStep } from 'openqa/bdd/playwright-bdd';

createAIStep({
  verbose: false,
  agentType: 'claude',
});

Cucumber.js:

import 'openqa/bdd/cucumber';

Examples

• examples/playwright-yaml/ - YAML tests with natural language + custom fixtures
• examples/playwright/ - Standard Playwright tests
• examples/playwright-bdd-simple/ - 1-line BDD integration
• examples/playwright-bdd/ - Manual BDD setup
• examples/playwright-bdd-onkernel/ - BDD with OnKernel cloud browsers
• examples/playwright-bdd-steel/ - BDD with Steel Docker browsers

Requirements

• Node.js 18+
• @playwright/test ^1.56.0
• Claude Code login, Anthropic API key, or other provider API key

Links

• Website: https://www.auto-browse.com/
• NPM: https://www.npmjs.com/package/openqa
• GitHub: https://github.com/auto-browse/openqa

License

MIT