QC Agent Pro+

Overview

The QC Agent is a browser-driven regression testing system that runs inside Claude Code sessions. You write test scenarios in plain YAML, and the agent executes them visually in Google Chrome using the Claude in Chrome extension.

Use the QC Agent when you need to:

• Verify UI behavior before merging a branch
• Run smoke tests after staging deploys
• Perform sprint acceptance testing
• Run on-demand verification of specific user flows

The workflow is straightforward: define test suites in YAML, run /run-qc in your Claude Code session, the agent executes each step in Chrome, results are persisted as JSON reports, and an optional enforcement gate can block task completion if tests fail.

Prerequisites

Chrome Extension (Required)

The QC Agent requires Google Chrome. Chromium-based browsers such as Brave, Edge, Arc, Opera, and Vivaldi are not supported.

Install the Claude in Chrome extension from the Chrome Web Store. Minimum required version: v1.0.36.

The extension shares your browser's existing login state with test sites. This is particularly useful for staging environments where you are already authenticated.

Launching Claude with Chrome

There are two ways to enable Chrome access for the QC Agent:

Option 1: Start with the flag

claude --chrome

Option 2: Enable within an active session

/chrome

Use the /chrome command to enable Chrome access or to reconnect if the connection drops.

What Chrome access unlocks

Enabling Chrome gives the agent access to the Chrome MCP tools:

Important notes

• Spawned subagent sessions inherit Chrome access automatically. No re-enabling is needed.
• The extension's service worker can idle during long sessions. If Chrome tools stop responding, run /chrome to reconnect.

Setup

Initialize the QC Agent directory structure with a single command:

bpsai-pair qc init

This creates:

The command is non-destructive: it is safe to re-run and will not overwrite existing files.

Defining Test Suites

Test suites are YAML files with the .qa.yaml extension, stored in .paircoder/qc/suites/.

Full annotated example

name: Login Flow
description: Tests user authentication
tags: [smoke, critical]
preconditions:
  - "App running at ${QC_BASE_URL}"

scenarios:
  - name: "Successful login"
    tags: [login]
    steps:
      - navigate: "${QC_BASE_URL}/login"
      - verify: "Login form with email and password fields visible"
      - fill:
          field: "Email"
          value: "${QC_TEST_EMAIL}"
      - fill:
          field: "Password"
          value: "${QC_TEST_PASSWORD}"
      - click: "Sign in"
      - wait: "2"
      - verify: "Dashboard page with welcome message"
      - check_console: "No JavaScript errors"

Step types

Key points

• Natural language targets — steps describe what to find, not CSS selectors. The agent uses Chrome's AI vision to locate elements.
• ${VAR} interpolation — variables are resolved from the environment config, falling back to OS environment variables.
• Tags — defined at both the suite level and per-scenario. Use tags to filter runs and to skip scenarios in restricted environments.
• Preconditions — checked before running. If a precondition is unmet (for example, the app is not running), the suite reports SKIPPED instead of failing.

Environment Configuration

Environment profiles are defined in .paircoder/qc/config.yaml:

environments:
  dev:
    variables:
      QC_BASE_URL: "http://localhost:3000"
      QC_TEST_EMAIL: "test@localhost"
      QC_TEST_PASSWORD: "${QC_TEST_PASSWORD}"   # pulled from OS env
    chrome:
      require_login: false
    restrictions:
      read_only: false
      skip_tags: []

  staging:
    variables:
      QC_BASE_URL: "https://staging.example.com"
      QC_TEST_EMAIL: "qa@example.com"
      QC_TEST_PASSWORD: "${STAGING_QC_PASSWORD}"
    chrome:
      require_login: true
      login_url: "https://staging.example.com/login"

  prod:
    variables:
      QC_BASE_URL: "https://example.com"
      QC_TEST_EMAIL: "qa-readonly@example.com"
      QC_TEST_PASSWORD: "${PROD_QC_PASSWORD}"
    chrome:
      require_login: true
      login_url: "https://example.com/login"
    restrictions:
      read_only: true                     # blocks all fill/click steps
      skip_tags: [destructive, write]     # skips matching scenarios entirely

default_environment: dev

Important points

• Never inline credentials — always use ${VAR} to pull sensitive values from OS environment variables.
• read_only: true — when enabled, all fill and click steps become SKIPPED (not FAILED). This makes production runs safe by preventing any write operations.
• skip_tags — scenarios tagged with any listed tag are skipped entirely. Use this for write or destructive operations that are not safe to run in production.
• If require_login: true is set, log in to the target site manually in Chrome before running QC. The agent uses your existing browser session.

Running QC Tests

Pre-flight CLI checks

# Discover all suites
bpsai-pair qc list

# Filter by tag
bpsai-pair qc list --tags critical

# Validate YAML syntax and required fields
bpsai-pair qc validate

Run via Claude Code slash command

# All suites, default environment
/run-qc

# Target a specific environment
/run-qc --env staging

# Only suites/scenarios tagged "smoke"
/run-qc --tags smoke

# Single suite by name
/run-qc --suite login-flow

View results

# Latest run summary (human-readable)
bpsai-pair qc report

# Machine-readable output
bpsai-pair qc report --json

Results are persisted as timestamped JSON files in .paircoder/qc/reports/.

Each step and scenario receives one of these verdicts:

Enabling the Enforcement Gate

The QC gate reads the latest QC report when a task is marked complete. It does not auto-run suites — you must run them manually before completing your task.

Step 1: Add the hook

Add qc_check to your completion hooks in .paircoder/config.yaml:

hooks:
  on_task_complete:
    - arch_check_modified
    - contract_break_check
    - qc_check              # add this line
    - stop_timer
    - workspace_impact_scan
    - telemetry_snapshot
    - feedback_calibrate
    - sync_trello
    - update_state
    - check_unblocked

Step 2: Set the enforcement level

enforcement:
  qc_gate: block    # or: warn, off

Enforcement modes

Workflow with gate enabled

1. Finish your task work
2. Run /run-qc to execute suites
3. Check bpsai-pair qc report — all green?
4. Run bpsai-pair ttask done CARD-ID --summary "..."
5. Gate reads latest report and passes or blocks accordingly

Note: If no report exists yet, the gate is skipped (not blocked). Create at least one report before relying on block mode.

Troubleshooting