QA Flow Tester / Pre-Release Readiness Checker 🧪

Automated Web Application Discovery, Interactive Flow Testing, and Deterministic Pre-Release Quality Evaluation.

qa-flow-tester is a comprehensive quality assurance platform that automates user flow discovery using AI, validates design token and accessibility conformance, monitors runtime console/network health, captures visual diffs, and aggregates findings into actionable release reports.

---

Table of Contents

• Overview & Architecture
• Monorepo Structure
• Prerequisites
• Quick Start
  • 1. Clone and Set Up
  • 2. Start the QA Tool
  • 3. Environment Configuration (Optional)
• Running the Applications
  • One Command (pnpm start)
  • Working on the Wizard (Hot Reload)
• End-to-End (E2E) Testing Guide
  • Step 1: Pick a Site to Check
  • Step 2: Use Release check-up
• Testing & Quality Checks
• Troubleshooting & FAQ

---

Overview & Architecture

The platform has three layers: the Wizard you use, the server that runs checks, and the engine behind it.

flowchart TD
    subgraph UI ["User Interfaces"]
        Wizard["Release check-up (@qa/wizard)\nServed by the QA Tool on port 3001, for everyone:\nplain words on top, details for developers under each finding"]
    end

    subgraph CoreEngine ["Execution & Discovery Core"]
        Runner["QA Tool server (@qa/runner)\nPort 3001: API (HTTP + SSE) and the Wizard"]
        Orchestrator["Flow Test Orchestrator (@qa/core)"]
        AI["AI Discovery Agent\n(Claude / OpenAI / Gemini / OpenRouter / Mock)"]
        Checkers["Audit Checkers (@qa/checkers)\n(Axe WCAG, Design Tokens, Visual Diff, Console/Network)"]
    end

    subgraph Target ["Target Under Test"]
        App["Target Web Application\n(Your test copy or a public site)"]
    end

    Wizard -->|POST /api/runner/run| Runner
    Runner --> Orchestrator
    Orchestrator --> AI
    Orchestrator --> Checkers
    Checkers -->|Playwright Automation| App

Core Capabilities

1. AI Discovery Agent: Crawls the whole site (up to 200 pages), records which page links to which, and has the AI plan every page, link and journey from what it found (see ADR 0009).
2. Complete plan review: The plan lists everything a run will do and what won't run, and is exactly what runs. Review it, change it and approve it before anything is tested.
3. Deterministic Checkers:
   • Accessibility: WCAG 2.2 AA audits via axe-core.
   • Design Token Conformance: Validates live getComputedStyle() against committed design-tokens.json (colors, radii, typography).
   • Visual Baselines: Perceptual visual diffing across multiple breakpoints (375px, 768px, 1440px).
   • Runtime Health: Intercepts unhandled console errors and failed HTTP network calls.
4. Checking a fix: After you fix a problem, run the check-up again on the same address. Test again reuses the approved plan, and the finding should no longer appear.

---

Monorepo Structure

Package / Directory	Purpose
packages/core	Core test orchestration, AI discovery agent, test planner, crawler, benchmarking engine, and AI providers
packages/checkers	Automated checkers (A11y/WCAG, design tokens, visual diffs, console errors, network failures)
packages/runner	The QA Tool server: runs checks over HTTP with Server-Sent Events (SSE) streaming, keeps every check-up's report, and serves the Wizard on the same port
packages/wizard	"Release check-up": the one app, in plain language, with details for developers under each finding (ADR 0010)
packages/types	Shared TypeScript type definitions, schemas, and interfaces

---

Prerequisites

Before starting, ensure you have:

• Node.js: 22.9.0 or newer (node -v)
• Package Manager: pnpm 11, pinned in package.json (corepack enable)
• Browsers: Playwright browser binaries

---

Quick Start

1. Clone and Set Up

You need Node.js 22.9 or newer and pnpm 11 (the pnpm version is pinned in package.json).

git clone https://github.com/CJCreator/qa-flow-tester.git
cd "qa-flow-tester"

# Installs dependencies and Playwright's Chromium, then builds every package
pnpm bootstrap

Run pnpm bootstrap again after every git pull. (It isn't called pnpm setup because that is a built-in pnpm command.)

2. Start the QA Tool

pnpm start

This builds anything that's missing or older than its source, and opens Release check-up at http://localhost:3001/ in your browser. Every screen has its own address:

• /: a new check-up
• /reports: past check-ups, and /reports/<runId> for one report
• /settings: the AI key

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗