# ๐ญ agent-factory ยท AI agents for your Playwright framework
> Four AI agents โ **RCA ยท Flaky Detector ยท Self-Healing Locator ยท Triage** โ that you drop into
> an existing Playwright framework as an `ai-agents/` folder. Plus a **live dashboard**.
> Pluggable LLM (Groq ยท DeepSeek ยท Ollama). Orchestrated by Claude Code in production.
> Built for [The Testing Academy](https://thetestingacademy.com) QA Masterclass ยท **Part 4**.
[](LICENSE)
[](https://nodejs.org)
[](https://qamasterclass.vercel.app/claudeCodeForQA-Part4)
---
## What it does
| Agent | Job |
|---|---|
| ๐ **RCA** | Classify every failure โ `product / test / env / locator` + confidence + fix. Drafts Jira bugs. |
| ๐ฒ **Flaky** | Diff N runs of the same commit. Rank intermittents. Name the cause. Recommend `@flaky`. |
| ๐ฉน **Heal** | Read the real DOM. Propose a resilient locator (role > testid > text > css). Patch the Page Object. Refuses to guess (<0.7). |
| ๐ฏ **Triage** | Orchestrator. Runs all three, posts one PR-ready summary. The command you wire into CI. |
A **dashboard** (`ai-agents/dashboard/`) shows each agent's config, prompt, last verdict, and a **Run** button โ served at `localhost:4321`.
---
## This repo is the finished reference
In the masterclass you build this **inside your own framework** ([AdvancePlaywrightFramework1x](https://github.com/PramodDutta/AdvancePlaywrightFramework1x)) under an `ai-agents/` folder, prompt by prompt. This repo is the same code, packaged standalone so you can:
- run it today (`./ai-agents/demo.sh`),
- compare against your own build,
- or `npm i -g agent-factory-cli` and point it at any Playwright report.
Follow the prompts at **<https://qamasterclass.vercel.app/claudeCodeForQA-Part4>**.
---
## Layout
```
agent-factory/
โโโ ai-agents/ โ drop THIS folder into your framework
โ โโโ core/
โ โ โโโ llm.ts one OpenAI-compatible client + askJson()
โ โ โโโ loader.ts parse Playwright JSON + error-context.md
โ โ โโโ artifacts.ts write .runs/<agent>.json for the dashboard
โ โ โโโ types.ts
โ โ โโโ log.ts
โ โโโ rca/ prompt.ts + rca.agent.ts + README.md
โ โโโ flaky/ prompt.ts + flaky.agent.ts + README.md
โ โโโ heal/ prompt.ts + heal.agent.ts + README.md
โ โโโ dashboard/ index.html + registry.json
โ โโโ cli.ts dispatch rca|flaky|heal|triage|dashboard
โ โโโ demo.sh
โโโ bin/agent-factory-cli.js ts-node shim (global install)
โโโ examples/fixtures/ results.json + error-context.md + runs/*.json
โโโ .claude/ production ยท Claude Code subagents
โโโ agents/{rca,flaky,heal}.md
โโโ skills/triage/SKILL.md
```
---
## Quickstart (standalone)
```bash
git clone https://github.com/PramodDutta/agent-factory-cli
cd agent-factory-cli && npm install
./ai-agents/demo.sh # LLM_MODE=mock ยท runs offline ยท opens dashboard
```
Or global:
```bash
npm i -g agent-factory-cli
agent-factory-cli triage ./test-results/results.json ./runs
```
---
## Inside your own framework
```bash
cd AdvancePlaywrightFramework1x
# (build ai-agents/ via the Part-4 prompts, or copy this repo's ai-agents/ folder)
cp ai-agents/.env.example ai-agents/.env # set LLM_BASE_URL / LLM_API_KEY / LLM_MODEL
npm run ai:triage # rca โ heal โ flaky โ summary
npm run ai:dashboard # http://localhost:4321
```
npm scripts to add to the framework's `package.json`:
```json
{
"ai:rca": "ts-node ai-agents/cli.ts rca test-results/results.json",
"ai:flaky": "ts-node ai-agents/cli.ts flaky ./runs",
"ai:heal": "ts-node ai-agents/cli.ts heal --report test-results/results.json",
"ai:triage": "ts-node ai-agents/cli.ts triage test-results/results.json ./runs",
"ai:dashboard": "ts-node ai-agents/cli.ts dashboard"
}
```
---
## Configure the LLM
Any **OpenAI-compatible** endpoint. `cp ai-agents/.env.example ai-agents/.env`:
```bash
# Groq ยท recommended free tier
LLM_MODE=live
LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_API_KEY=gsk_xxx
LLM_MODEL=llama-3.3-70b-versatile
# Or DeepSeek โ LLM_BASE_URL=https://api.deepseek.com ยท LLM_MODEL=deepseek-chat
# Or Ollama โ LLM_BASE_URL=http://localhost:11434/v1 ยท LLM_MODEL=qwen2.5-coder:7b
```
`LLM_MODE=mock` โ deterministic offline output (demos, tests).
---
## Two paths
| Path | When | What it does |
|---|---|---|
| **CLI** (`ai-agents/`) | Local ยท CI ยท cron | Prints verdicts. Drafts Jira. Patches Page Objects with `--apply`. |
| **Claude Code** (`.claude/`) | Production | Calls Atlassian MCP for real Jira (JQL-dedup). Edits the real Page Object. Re-runs the spec to verify. |
Same prompts. The Claude Code variant adds the real side-effects.
```text
@rca ยท @heal ยท /triage # inside Claude Code
```
---
## Companion masterclass
**Part 4 ยท Build the Agent Factory** โ <https://qamasterclass.vercel.app/claudeCodeForQA-Part4>
Reference framework โ <https://github.com/PramodDutta/AdvancePlaywrightFramework1x>
---
## License
MIT ยท ยฉ Pramod Dutta ยท The Testing Academy.