Skip to content
BranchesTags
 
 

Repository files navigation

qa-agent

License: Apache-2.0 Node.js 22+ Install

Composable QA agent for AI coding assistants. Installs multi-specialist analysis, exploratory testing, and test generation into any project. Supports Claude Code, Cursor, Windsurf, GitHub Copilot, and Octobots.

Install

cd your-project
npx github:onetest-ai/qa-agent init

Interactive installer with arrow-key navigation — walks you through:

  1. Prerequisites — checks Chrome, Node.js 22+, gh CLI
  2. Targets — Claude Code, Cursor, Windsurf, GitHub Copilot, Octobots
  3. Skills — 10 specialist domains + integration connectors
  4. MCP servers — optional tool integrations with credential setup
  5. Install — copies agents, skills, permissions, MCP configs

Non-interactive (agents + skills only, no MCP):

npx github:onetest-ai/qa-agent init --all

Installs all skills to Claude Code target. MCP servers are skipped — configure them via .mcp.json.example or re-run the interactive installer.

Update existing installation:

npx github:onetest-ai/qa-agent init --update

Overwrites agent + skills. Preserves settings and .gitignore.

Getting Started

After installation, start the QA agent and onboard it to your product:

claude --agent qa
> /qa-init

The Onboarding Pipeline

/qa-init is a 6-phase data ingestion pipeline that teaches the QA agent about your product:

Phase What happens
1. Interview Asks about your product, user flows, environments, pain points, documentation sources, test infrastructure, team process
2. Pre-flight Maps your answers to required tooling (MCPs, CLIs, auth). Presents a checklist. Waits for you.
3. Ingest Reads codebase, clones related repos, fetches wikis/docs URLs, parses API specs, scans test infrastructure
4. Synthesize Generates project-context.md — the agent's knowledge base about your product
5. Configure Suggests CLAUDE.md additions, MCP setup, specialist tuning
6. Verify Smoke tests the app to confirm everything works

Re-run /qa-init anytime the product changes significantly. It merges new info with existing context.

Usage

claude --agent qa                   # Start the QA agent
> /qa-init                          # Onboard to the product (do this first)
> audit https://example.com         # Multi-specialist bug analysis
> reproduce issue #42               # Confirm and document a bug report
> explore the checkout flow         # Exploratory testing session
> write tests for the login page    # Generate test scripts
> verify the fix for #42            # Re-test a reported issue
> persona review for homepage       # Diverse user perspective analysis
> /qa-research stripe integeation   # Build domain knowledge before testing
> /qa-github push findings          # Create GitHub issues from audit
> /qa-onetest run                   # Execute a OneTest test run

What Gets Installed

your-project/
  .claude/
    agents/qa/
      AGENT.md                        # QA agent
      references/
        qa-methodology.md             # Shared audit workflow, finding schema
        specialists.md                # Check-type → skill mapping
        html-templates.md             # Report templates (light theme)
        persona-review.md             # Persona review methodology
    skills/
      browser-verify/                 # CDP browser automation (Chrome + Node 22)
      qa-accessibility/               # Accessibility + WCAG (axe-core, WCAG checklist)
      qa-security/                    # Security + OWASP (OWASP Top 10 checklist)
      qa-privacy/                     # Privacy + GDPR (tracker detection, GDPR checklist)
      qa-performance/                 # Performance + Console + JS (CWV thresholds)
      qa-mobile/                      # Mobile + Responsive (touch targets, emulation)
      qa-content/                     # Content + SEO (meta tags, copy quality)
      qa-ux/                          # UI/UX + 20 page-type checks
      qa-testgen/                     # Test case generation (4 suites)
      qa-reproduce/                   # Bug reproduction + verification
      qa-research/                    # Topic research + domain knowledge
      qa-onetest/                     # OneTest integration (optional)
      qa-github/                      # GitHub Issues integration (optional)
      qa-init/                        # Onboarding pipeline
    settings.json                     # Permissions (merged additively)
  .mcp.json                           # MCP server configs (if configured)
  .mcp.json.example                   # MCP config template
  reports/                            # HTML report output
  tests/                              # Generated test scripts

Architecture

User asks QA question
  → Claude delegates to qa agent (AGENT.md)
    → Agent reads qa-methodology.md (shared workflow)
      → Loads specialist skills on demand (only what's needed)
        → Each skill has its own references (WCAG, OWASP, GDPR, CWV...)
      → Generates findings with p0-p3 priorities
    → Produces HTML report (light theme, glass morphism)
    → Optionally syncs to OneTest or GitHub (data bridges)

Design Principles

  • Agent is thin — personality + pointers to references. Methodology lives in shared files consumable by both standalone and team contexts.
  • Skills load on demand — only relevant specialists enter the context. An accessibility audit doesn't load performance thresholds.
  • Integration skills are data bridges — qa-onetest and qa-github don't contain QA logic. They read/write to external systems; the actual analysis stays in specialist skills.
  • Persona perspective is embedded — every specialist considers diverse user impact, not just technical correctness.
  • Never touches CLAUDE.md — everything lives in .claude/agents/ and .claude/skills/.

Priority System

Aligned with OneTest:

Priority Meaning Color
p0 Critical — blocks UX, security risk, data loss Red
p1 High — degrades experience, affects many users Orange
p2 Medium — noticeable, workaround exists Gray
p3 Low — minor polish, edge case Blue

Specialist Skills

Each specialist has its own SKILL.md with focused methodology and domain-specific references.

Skill Domain References
qa-accessibility Accessibility + WCAG 2.1 wcag-checklist.md — AA/AAA criteria with priority mapping
qa-security Security + OWASP owasp-checklist.md — Top 10 browser-visible indicators
qa-privacy Privacy + GDPR gdpr-checklist.md — consent, notices, technical compliance
qa-performance Performance + Console + JS cwv-thresholds.md — Core Web Vitals, resource budgets
qa-mobile Mobile + Responsive Touch targets, viewport, device emulation
qa-content Content + SEO Meta tags, structured data, copy quality
qa-ux UI/UX + Page Types page-types.md — 20 page-type specific checks
qa-testgen Test Case Generation 4 suites: smoke, regression, accessibility, negative
qa-reproduce Bug Reproduction 5-phase: intake, setup, attempt, evidence, confirm
qa-research Topic Research Web search, domain knowledge for unfamiliar products

Integration Skills

Optional connectors — no QA logic, just data bridges.

qa-github

Syncs with GitHub Issues via gh CLI. No MCP needed.

Command What it does
/qa-github push findings Audit findings → GitHub issues with priority labels
/qa-github pull issues Fetch bugs for reproduction
/qa-github verify Re-test fixed issues, comment results
/qa-github status Open bugs by priority, verification queue

qa-onetest

Syncs with OneTest test management via MCP.

Command What it does
/qa-onetest push findings Audit findings → OneTest test cases
/qa-onetest pull tests Fetch test cases for execution
/qa-onetest run Create, execute, and complete test runs
/qa-onetest status Execution queue and active runs

Supports multi-browser parallel execution via CDP_PORT for non-conflicting tests.

MCP Servers

The interactive installer offers a multi-select of MCP servers grouped by capability. Each server that requires credentials will prompt during installation. Or copy .mcp.json.example to .mcp.json and configure manually.

Browser Automation

Server Package Auth What it does
playwright @playwright/mcp None Multi-browser automation via MCP
chrome-devtools chrome-devtools-mcp None Chrome automation + Lighthouse built-in

browser-verify (included by default) handles browser automation without MCP. These are alternatives for teams already using Playwright or Chrome DevTools.

QA Analysis

Server Package Auth What it does
accessibility-scanner mcp-accessibility-scanner None Automated axe-core WCAG scanning
snyk snyk CLI Snyk auth SAST, SCA, IaC, container security scanning
sentry @sentry/mcp-server Auth token Correlate findings with production errors
browserstack @browserstack/mcp-server Username + key Real cross-browser/device testing
postman @postman/postman-mcp-server API key API collections, requests, mock servers

Research

Server URL Auth What it does
context7 https://mcp.context7.com/mcp API key Library docs lookup for up-to-date API knowledge
websearch https://mcp.tavily.com/mcp/ API key (in URL) Web search, extract, and crawl for domain research

Integrations

Server Package / URL Auth What it does
github https://api.githubcopilot.com/mcp/ GitHub PAT Issues, PRs, actions, code search
atlassian https://mcp.atlassian.com/v1/mcp OAuth or API token Jira issues, Confluence pages, Compass
test-management OneTest HTTP MCP API key Sync with OneTest TMS

Additional MCPs

The /qa-init pre-flight phase may recommend these based on your stack:

Source MCP
Notion @notionhq/notion-mcp-server
Figma figma-developer-mcp
Stripe @stripe/mcp
Database @bytebase/dbhub
GitLab @zereight/mcp-gitlab

Shared Methodology

The QA methodology at agents/qa/references/qa-methodology.md is designed to be consumed by multiple contexts:

  • Standalone agent — AGENT.md reads it directly
  • Team integration (e.g. octobots) — qa-engineer role's CLAUDE.md reads the same file

This means the same audit workflow, finding schema, and testing methodology works whether you're using qa-agent standalone or as part of a multi-agent team.

Requirements

  • Chrome/Chromium installed
  • Node.js 22+ (for browser-verify CDP scripts and installer)
  • At least one supported AI coding assistant (Claude Code, Cursor, Windsurf, GitHub Copilot)
  • gh CLI (optional, for qa-github)

Contributing

Contributions are welcome! Here's how to get involved:

Adding a new specialist skill

  1. Create skills/qa-<name>/SKILL.md with YAML frontmatter (name, description)
  2. Add domain-specific references in skills/qa-<name>/references/
  3. Register the skill in agents/qa/references/specialists.md
  4. Add it to the installer's specialist selection in bin/init.mjs

Adding a new MCP server

  1. Add the server definition to mcpDefs in bin/init.mjs
  2. Add it to the mcpItems array with the appropriate group
  3. If it needs credentials, add a prompt block or an entry in envMcpCredentials
  4. Add the config to templates/mcp.json.example
  5. Update the MCP table in this README

Adding a new installation target

  1. Create a install<Target>() function in bin/init.mjs
  2. Add a target compiler if the format differs from SKILL.md
  3. Add it to the target selection in Step 2
  4. Wire it up in the Step 5 install loop

Development

git clone https://github.com/onetest-ai/qa-agent
cd qa-agent

# Test the installer locally
mkdir /tmp/qa-test && cd /tmp/qa-test
node /path/to/qa-agent/bin/init.mjs init

# Syntax check
node --check bin/init.mjs

Guidelines

  • Keep skills self-contained — each SKILL.md should work independently
  • No build step — the repo is distributed as-is via npx
  • Never modify the target project's CLAUDE.md
  • MCP credential prompts must be non-fatal (skip gracefully if user hits Enter)
  • Test the interactive installer flow end-to-end after changes

License

Apache-2.0 — see LICENSE for details.

About

No description, website, or topics provided.

Resources

Readme
License

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages