{"_id":"@arslanars/agentic-qa","name":"@arslanars/agentic-qa","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@arslanars/agentic-qa","version":"0.1.0","description":"Local Playwright + BDD framework with a visual test runner UI. Turns user stories into executable browser tests, auto-heals failures, tracks flakiness, and maps git diff to affected features. No paid API required.","bin":{"agentic-qa":"bin/agentic-qa.js"},"scripts":{"bddgen":"bddgen","test":"bddgen && playwright test --grep-invert=@destructive","test:chromium":"bddgen && playwright test --project=chromium --grep-invert=@destructive","test:firefox":"bddgen && playwright test --project=firefox --grep-invert=@destructive","test:webkit":"bddgen && playwright test --project=webkit --grep-invert=@destructive","test:bdd":"bddgen && playwright test --project=chromium --grep-invert=@destructive","test:destructive":"bddgen && playwright test --project=chromium --grep=@destructive","test:ui":"bddgen && playwright test --ui","test:headed":"bddgen && playwright test --headed","test:debug":"bddgen && playwright test --debug","test:report":"playwright show-report","baselines:update":"bddgen && playwright test --update-snapshots --grep-invert=@destructive","setup":"node bin/setup.js","ui":"node bin/agentic-qa.js ui","allure:clean":"node -e \"require('fs').rmSync('allure-results',{recursive:true,force:true});require('fs').rmSync('allure-report',{recursive:true,force:true})\"","allure:generate":"allure generate allure-results --clean -o allure-report","allure:open":"allure open allure-report","allure:serve":"allure serve allure-results"},"keywords":["playwright","playwright-bdd","cucumber","gherkin","qa","automation","page-object-model","test-runner","test-generator","allure","e2e","claude","claude-code","ai-testing"],"author":{"name":"Arslan Tufail"},"license":"MIT","homepage":"https://github.com/Arslanars/agentic-qa#readme","repository":{"type":"git","url":"git+https://github.com/Arslanars/agentic-qa.git"},"bugs":{"url":"https://github.com/Arslanars/agentic-qa/issues"},"publishConfig":{"access":"public"},"type":"commonjs","engines":{"node":">=20"},"dependencies":{"exceljs":"^4.4.0","express":"^5.2.1","marked":"^18.0.5"},"peerDependencies":{"@playwright/test":">=1.40.0","allure-playwright":">=3.0.0","playwright-bdd":">=9.0.0"},"peerDependenciesMeta":{"allure-playwright":{"optional":true}},"devDependencies":{"@playwright/test":"^1.60.0","@types/node":"^25.9.1","allure-commandline":"^2.41.0","allure-playwright":"^3.9.0","playwright-bdd":"^9.2.0","typescript":"^6.0.3"},"gitHead":"13a5a939abbf61236da50b26382f804fc4317afa","_id":"@arslanars/agentic-qa@0.1.0","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-cq/vDxoieDx0UKLOlvATX4/bQk6Lx9bPT8iObOtNhd9rWPPq/FENzVGRAd1RDDI+XyaOe518HJZbrUsNtp1FuA==","shasum":"051f16f0f6802f441aa677da51955d15f34a76ea","tarball":"https://registry.npmjs.org/@arslanars/agentic-qa/-/agentic-qa-0.1.0.tgz","fileCount":26,"unpackedSize":543726,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD/y2DcMbmH949EY2mL5+3HPuo7rGSqrKztHjiZ9G7m4wIhALgyZ5Ma8msQWph3YRpWo69/CgbTk85MTZWXldPONPx/"}]},"_npmUser":{"name":"arslanars","email":"arslanars.sul@gmail.com"},"directories":{},"maintainers":[{"name":"arslanars","email":"arslanars.sul@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentic-qa_0.1.0_1782923475433_0.29831827601941385"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-01T16:31:15.198Z","0.1.0":"2026-07-01T16:31:15.604Z","modified":"2026-07-01T16:31:15.912Z"},"maintainers":[{"name":"arslanars","email":"arslanars.sul@gmail.com"}],"description":"Local Playwright + BDD framework with a visual test runner UI. Turns user stories into executable browser tests, auto-heals failures, tracks flakiness, and maps git diff to affected features. No paid API required.","homepage":"https://github.com/Arslanars/agentic-qa#readme","keywords":["playwright","playwright-bdd","cucumber","gherkin","qa","automation","page-object-model","test-runner","test-generator","allure","e2e","claude","claude-code","ai-testing"],"repository":{"type":"git","url":"git+https://github.com/Arslanars/agentic-qa.git"},"author":{"name":"Arslan Tufail"},"bugs":{"url":"https://github.com/Arslanars/agentic-qa/issues"},"license":"MIT","readme":"# Agentic QA Automation Pipeline\n\nA local Playwright + BDD framework with a **visual test runner UI** on top. Turns user stories into executable browser tests, auto-heals failures, tracks flakiness, and tells you which tests to run before you commit.\n\n> **No paid API required.** All AI features go through your local `claude` CLI (Claude Code subscription). Everything else — schedulers, tag management, PR impact analysis, coverage detection — is pure Node + Playwright, no third-party keys.\n\n---\n\n## Pipeline flow\n\n```mermaid\nflowchart TD\n    A[\"📝 User Story + ACs\"] --> B{\"🔬 Critique Story<br/>(Spec Doctor)\"}\n    B -- Issues found --> C[\"Accept AI Rewrites\"]\n    B -- Clean --> D\n    C --> D[\"💾 Save & Generate Tests\"]\n    D -- \"Claude drafts\" --> E[\"📄 .feature + .steps.ts<br/>+ Page Object Model\"]\n\n    E --> F[\"📊 Coverage Gap Detector\"]\n    F -- Uncovered ACs --> G[\"⚙ Draft scenario<br/>(Claude fills gap)\"]\n    G --> E\n    F -- All covered --> H\n\n    H[\"▶ Run Tests<br/>(headed / headless / all-browsers)\"]\n    H --> I{\"Result?\"}\n    I -- ✅ Pass --> J[\"📈 Reports + History\"]\n    I -- ❌ Fail --> K{\"🩹 Failure Triage\"}\n    K -- Heal --> L[\"Claude fixes test\"]\n    K -- Explain --> M[\"📢 Plain-English bug narrative\"]\n    L --> H\n\n    J --> N[\"🌊 Flaky Detection\"]\n    J --> O[\"📡 PR Impact Radar\"]\n    O -- \"Before commit\" --> P[\"Run only impacted features\"]\n    P --> H\n\n    Q[\"⏰ Scheduled Runs\"] -. cron .-> H\n    R[\"🏷 Tag Filter\"] -. \"@smoke / @slow\" .-> H\n\n    style A fill:#eef2ff,stroke:#6366f1,color:#1e1b4b\n    style E fill:#f0fdf4,stroke:#10b981,color:#052e16\n    style H fill:#faf5ff,stroke:#8b5cf6,color:#3b0764\n    style K fill:#fef2f2,stroke:#ef4444,color:#450a0a\n    style J fill:#fffbeb,stroke:#f59e0b,color:#451a03\n```\n\nThe dashed arrows show cross-cutting features that plug into the same run pipeline: **Scheduled Runs** fire tests on a cron; **Tag Filter** narrows what runs.\n\n---\n\n## What's inside\n\n| Capability | How to use |\n|---|---|\n| **Visual test runner** with NDJSON log streaming, run history sparkline, ETA | `npm run ui` → http://localhost:3001 |\n| **Playwright + playwright-bdd** — Gherkin `.feature` scenarios, POM + shared step libraries | `features/<name>/*.feature` + `<name>.steps.ts` |\n| **Story → Tests** — paste ACs, Claude scaffolds the full `.feature` + `.steps.ts` | `Save & Generate Tests` button |\n| **Spec Doctor** — lints ACs for vague verbs, missing negatives, un-measurable outcomes | `Critique Story` button |\n| **Coverage Gap Detector** — per-AC ✓/✗ with auto-fill for missing scenarios | Coverage panel + `Close N gaps` CTA |\n| **Test Recorder** — Playwright codegen wrapped so captures become Gherkin | `Record New Scenario` button |\n| **Failure Triage** — cards for each failure with **Heal** (Claude fix) + **Explain** (plain-English narrative) | Below the run status |\n| **Auto-implement missing steps** — scans compiled BDD for undefined steps, drafts implementations | Amber banner during runs |\n| **Liquid Step Timeline** — live green beams fill each Given/When/Then as they execute | Custom Playwright reporter (`ui/live-step-reporter.js`) |\n| **Test Tags Manager** — add/remove `@smoke @regression @critical @slow @wip @flaky` on any scenario | `🏷 Tags` button on the Coverage panel |\n| **Tag Filter** — runs only scenarios matching a Playwright grep expression | Input under Run Configuration |\n| **Scheduled Runs** — interval / daily / weekly cron-like scheduler, persisted per-machine | `⏰ Schedules` button in the topbar |\n| **PR Impact Radar** — maps `git diff` to affected features; run only those | `📡 N impacted` pill in the status bar |\n| **Flaky test detection** — rolling 20-run window per test | `🌊 N flaky` pill |\n| **Screenshot gallery** with lightbox + close button | Below the run panel |\n| **Log search** — Ctrl+F inside the log with next/prev navigation | Log toolbar |\n| **Light / dark theme** — system-aware, persisted via localStorage | Sun/moon toggle top-right |\n| **Playwright HTML + Allure** reports auto-rebuilt after each run | Report links in footer |\n\n---\n\n## Setup\n\nRequires **Node 20+**, **Git**, and (for AI features) the **`claude` CLI** on `$PATH` — install from https://claude.ai/download.\n\n```bash\ngit clone https://github.com/Arslanars/agentic-qa.git\ncd agentic-qa\nnpm install\nnpm run setup             # downloads Chromium / Firefox / WebKit binaries (~400 MB, one-time)\nclaude --version          # verify the CLI is reachable (optional but recommended)\nnpm run ui                # → http://127.0.0.1:3001\n```\n\n### Install into an existing Playwright project (npm)\n\n```bash\n# in your Playwright project's root\nnpm install --save-dev @arslanars/agentic-qa\nnpx agentic-qa init      # scaffolds framework files (idempotent, non-destructive)\nnpm run qa:ui            # opens http://localhost:3001\n```\n\n`init` copies templates (BasePage, config, gitignore additions), creates empty story/spec/report dirs, and adds `qa`, `qa:ui`, `qa:run` scripts to your `package.json`. See `INTEGRATE.md` (bundled with the package) for the full integration walkthrough.\n\n### Peer dependencies (installed alongside)\n\nThe framework relies on Playwright + BDD tooling that consumers should own directly. Install if missing:\n\n```bash\nnpm install --save-dev @playwright/test playwright-bdd allure-playwright\n```\n\n### Without a Claude subscription\n\nEverything non-AI still works: running tests, reports, screenshots, history, flaky detection, PR Impact Radar, coverage detection (read-only), Test Tags Manager, Scheduled Runs. AI-authored features (`Save & Generate`, `Critique Story`, `Draft scenario`, `Heal`, `Explain`, `Voice`, auto-scaffold missing steps) return `501` and show *\"Claude CLI not detected\"* in the UI.\n\n---\n\n## Quick start — three minutes\n\n1. **Open the UI**: `npm run ui` → http://localhost:3001\n2. **Paste a story**: URL + Story ID + Acceptance Criteria. Optionally add test credentials.\n3. **Click** `Save & Generate Tests` → Claude drafts the `.feature` + `.steps.ts` (~30s).\n4. **Click** `▶ Run Tests` (`Ctrl+R`) → watch green beams fill each step in real time.\n5. **On failure**: click the red triage card → `Heal` fixes the test, `Explain` writes a bug narrative.\n6. **Before pushing code**: check the `📡 impacted` pill → run only affected features.\n\n---\n\n## Feature walkthrough\n\n### Story → Tests (Save & Generate)\nPaste ACs into the story form, click **Save & Generate Tests**. The endpoint calls `claude --print` with a prompt that includes your existing POM style, step definitions, and Gherkin conventions, so the generated code matches the rest of your project. Output streams live into the log panel.\n\n### Spec Doctor (Critique Story)\nBefore wasting a generate call on vague ACs, click **Critique Story**. Claude lints against 6 rules: `AMBIGUOUS_VERB`, `VAGUE_QUANTITY`, `MISSING_NEGATIVE`, `UNTESTABLE_ASSERTION`, `MISSING_PRECONDITION`, `SCOPE_CREEP`. Each issue shows the exact snippet, description, severity, and a suggested rewrite you can accept with one click.\n\n### Coverage Gap Detector + Closer\nWhen you pick a feature, the Coverage panel shows `N/M ACs covered` with a progress bar and per-AC ✓/✗ rows. Uncovered ACs get a `⚙ Draft scenario` button — click it and Claude drafts a Gherkin scenario using your existing step library. Review, append, and any new step phrases get auto-scaffolded implementations.\n\n### Test Recorder\nClick **Record New Scenario** → Playwright's `codegen` opens a real browser. Drive the flow. Click stop → captured Playwright code is converted to Gherkin (reusing existing steps where possible). Review, append, done.\n\n### Test Tags Manager\nClick **🏷 Tags** on the Coverage panel. Modal lists every scenario in the feature; each row has removable tag chips + a `+ Add tag` inline input. Six preset chips (`@smoke @regression @critical @slow @wip @flaky`) for quick reference. Colored variants for known tags.\n\n### Tag Filter\nInput in Run Configuration. Enter `@smoke` or `@smoke and not @slow` — Playwright's grep syntax supports boolean expressions. Filter routes to `--grep=` on the CLI.\n\n### Scheduled Runs\nClick **⏰ Schedules** in the topbar. Three modes:\n- **Every N min** — interval mode (5, 15, 30, 60…)\n- **Daily at HH:MM** — 24-hour time\n- **Weekly on <day> at HH:MM** — pick day-of-week + time\n\nPersisted in `.claude/schedules.json` (per-user, gitignored). A 30-second tick loop fires due schedules headlessly; output goes to `reports/scheduled-runs/`. Results flow into normal history + flaky detection.\n\n### PR Impact Radar\nThe pill `📡 N impacted` shows how many features are affected by your current `git diff` vs `main`. Click it to see per-feature reasons (direct file edit, POM reference, story change, global config). Click **Run N impacted features** to run all of them in a single Playwright pass. Once tested, the pill flips to `✓ N impacted` and a green banner appears with pass/fail counts.\n\n### Failure Triage (Heal + Explain)\nEvery failure gets a card with a screenshot thumbnail, error excerpt, jump-to-source / jump-to-trace links, and two AI buttons:\n- **Heal** — Claude reads the trace + error + step definitions and fixes the test. Streaming.\n- **Explain** — plain-English bug narrative with severity, user impact, and next steps (useful for filing tickets).\n\n### Auto-implement missing steps\nWhen a run detects undefined step phrases (via `Missing step definitions: N` log lines), an amber banner appears with **Implement with Claude**. One click → Claude reads your POM + existing step style and writes implementations for each undefined step into the matching `.steps.ts` file.\n\n### Liquid Step Timeline\nA custom Playwright reporter (`ui/live-step-reporter.js`) emits per-step lifecycle events as `[LIVE_STEP]<json>` on stdout. The UI parses them and renders each Given/When/Then as a horizontal beam that fills green during the step, red on error. Real-time.\n\n---\n\n## Running tests\n\n```bash\nnpm test                       # all browsers × all features\nnpm run test:chromium          # chromium only\nnpm run test:firefox\nnpm run test:webkit\nnpm run test:headed            # visible browsers (workers=1)\nnpm run test:ui                # Playwright's own interactive UI mode\nnpm run test:report            # open Playwright HTML report\nnpm run baselines:update       # re-record visual regression snapshots\n```\n\nInside the UI, three run modes:\n- **▶ Run Tests** — the selected feature on the selected browser\n- **All browsers** — the selected feature across chromium + firefox + webkit\n- **Re-run failed** — Playwright `--last-failed`\n\nKeyboard shortcuts:\n- `Ctrl+R` — Run\n- `Ctrl+.` — Stop / abort\n- `Ctrl+F` — search in log\n- `Esc` — close any open modal\n\n---\n\n## Reports\n\nEvery run produces four artifacts:\n\n| Artifact | Location | What's in it |\n|---|---|---|\n| Playwright HTML report | `playwright-report/index.html` | Native trace viewer per test |\n| Allure HTML report | `allure-report/index.html` | Rich UI, trends, history (requires Java for CLI) |\n| Markdown execution summaries | `reports/<Feature-Slug>.md` | Human-readable per-feature summary |\n| `Test-Cases.xlsx` | `reports/Test-Cases.xlsx` | All scenarios + pass/fail status |\n\n### Allure CLI (optional — for local report browsing)\n\n```bash\nnpm run allure:serve           # one-shot: build + open\nnpm run allure:generate        # write static HTML to allure-report/\nnpm run allure:clean           # wipe results + report\n```\n\nRequires Java: `winget install Microsoft.OpenJDK.21` (Windows), `brew install openjdk` (macOS), `apt install default-jdk` (Linux).\n\n---\n\n## API endpoints (server.js)\n\nThe Express server exposes these — all local, all called by the UI. Useful for scripting your own automations.\n\n| Endpoint | Method | Purpose |\n|---|---|---|\n| `/api/features` | GET | List available features |\n| `/api/save-story` | POST | Write a `user-stories/<id>-<slug>.md` file |\n| `/api/generate-tests` | POST (NDJSON) | Claude drafts feature + steps |\n| `/api/generate-status` | GET | Claude CLI availability + running-job flag |\n| `/api/critique-spec` | POST | Spec Doctor — lint ACs |\n| `/api/run` | POST (NDJSON) | Execute tests (accepts `feature`, `features[]`, `project`, `headed`, `lastFailed`, `tagFilter`) |\n| `/api/abort` | POST | Kill in-flight run |\n| `/api/heal` | POST (NDJSON) | Claude fixes a failing test |\n| `/api/explain-failure` | POST | Plain-English bug narrative |\n| `/api/scaffold-missing-steps` | POST (NDJSON) | Auto-implement undefined step phrases |\n| `/api/last-failures` | GET | Triage cards data |\n| `/api/history` | GET | Run history (for sparkline + ETA) |\n| `/api/flaky-tests` | GET | Tests that flipped in the last N runs |\n| `/api/coverage-gaps` | GET | Per-AC covered/uncovered breakdown |\n| `/api/coverage/draft-scenario` | POST | Claude drafts a scenario for a specific uncovered AC |\n| `/api/tags` | GET / POST | Read + write Gherkin tags per scenario |\n| `/api/schedules` | GET / POST / DELETE | Scheduled runs CRUD |\n| `/api/pr-impact` | GET | Which features are affected by current git diff |\n| `/api/recorder/start` `/status` `/stop` `/convert` `/append` | POST | Test Recorder state machine |\n| `/api/screenshots` | GET | Screenshot gallery data |\n| `/api/report-status` | GET | Which reports are available |\n| `/api/allure-generate` | POST | Rebuild the Allure HTML |\n\nFull validators — safe-name regex on user input, `X-Accel-Buffering: no` for streaming, `activeGenerate` concurrency guard on all Claude endpoints.\n\n---\n\n## Repo layout\n\n```\n.\n├── .claude/\n│   ├── agents/                  # Claude Code agent prompts (planner / generator / healer)\n│   ├── schedules.json           # Per-user scheduled runs (gitignored)\n│   └── settings.local.json      # Claude Code local settings\n├── .github/workflows/\n│   └── playwright.yml           # CI: runs the suite on push/PR\n├── .vscode/mcp.json             # VSCode MCP server config\n├── user-stories/                # INPUT: one .md per user story\n│   └── _TEMPLATE.md\n├── specs/                       # Test plans (markdown) — output of the planner\n├── pages/                       # Page Object Model\n│   ├── BasePage.ts\n│   └── <feature>/<PageName>Page.ts\n├── features/                    # Gherkin scenarios\n│   ├── _TEMPLATE.feature\n│   ├── _shared/                 # Shared step libraries (visual, common navigation, etc.)\n│   ├── README.md                # BDD authoring guide\n│   └── <feature>/\n│       ├── <name>.feature       # Gherkin scenarios\n│       ├── <name>.steps.ts      # Step definitions\n│       └── testcases.json       # Test case metadata (for Excel export)\n├── reports/                     # Execution summaries (markdown)\n│   ├── history.jsonl            # Per-run summaries (gitignored)\n│   ├── test-history.jsonl       # Per-test flakiness data (gitignored)\n│   ├── scheduled-runs/          # Logs from scheduled fires (gitignored)\n│   └── Test-Cases.xlsx          # Master spreadsheet\n├── test-results/                # Playwright runtime artifacts (gitignored)\n├── ui/\n│   ├── server.js                # Express + all API endpoints\n│   ├── index.html               # Full UI in one file (CSS + JS inline)\n│   ├── live-step-reporter.js    # Custom Playwright reporter for step timeline\n│   └── report-writer.js         # Post-run markdown + Excel report generator\n├── QAEnd2EndPromptFile.md       # Reusable Claude Code prompts\n├── playwright.config.js         # chromium / firefox / webkit projects + BDD compile\n├── ONBOARDING.md                # New-teammate onboarding\n└── README.md                    # (this file)\n```\n\n---\n\n## CI\n\n`.github/workflows/playwright.yml` runs the suite on push/PR and uploads:\n\n- `playwright-report` — native Playwright HTML\n- `allure-results` — raw Allure JSON (upload to a hosted Allure server if you don't want Java in CI)\n- `allure-report` — pre-built Allure HTML\n- `reports` — markdown execution summaries\n\nWire test credentials via GitHub Secrets if your specs read from `process.env`.\n\n---\n\n## Page Object Model — at a glance\n\n```typescript\n// pages/auth/LoginPage.ts\nimport { type Locator, type Page } from '@playwright/test';\nimport { BasePage } from '../BasePage';\n\nexport class LoginPage extends BasePage {\n  readonly url = 'https://example.com/login';\n  readonly emailInput: Locator;\n  readonly submitButton: Locator;\n\n  constructor(page: Page) {\n    super(page);\n    this.emailInput = page.getByRole('textbox', { name: 'Email' });\n    this.submitButton = page.getByRole('button', { name: 'Sign In' });\n  }\n\n  async login(email: string, password: string) {\n    await this.emailInput.fill(email);\n    // ...\n  }\n}\n```\n\nA UI change touches one file (the page object), not every test. Full conventions in `pages/README.md`.\n\n---\n\n## Tech stack\n\n- [Playwright](https://playwright.dev) — browser automation + test runner\n- [playwright-bdd](https://github.com/vitalets/playwright-bdd) — Cucumber/Gherkin support\n- [Playwright MCP](https://github.com/microsoft/playwright-mcp) — browser tools for Claude Code agents\n- [Allure](https://docs.qameta.io/allure/) — rich HTML reports\n- [Express](https://expressjs.com) — UI server\n- Claude Code CLI (subscription) — AI authoring / healing / explaining\n\n---\n\n## Author\n\n**Arslan Tufail**\n\nFramework design, UI, backend endpoints, and Claude Code agent integration.\n\n---\n\n## License\n\nISC\n","readmeFilename":"README.md","_rev":"1-55e71ac85e91e4b8eb655b3170ecfb5e"}