# Prompting Template — How to Talk to the AI QA Agent

This guide covers every prompt you need — from installation to final report. Use it as your conversation script.

---

## Quick Start (Copy-Paste Ready)

After installing the template and writing a user story, open your AI editor and send:

> **"Read router.md and follow the QA workflow for my-story.md"**

That's it. The AI handles everything from there, stopping at each phase for your approval.

---

## Phase-by-Phase Prompts

### Phase 0: First Contact (Environment Check)

When you open the project for the **first time**, the AI automatically runs an environment check. If it doesn't, or if you want to re-check:

> **"Run the environment check and tell me what's ready and what's missing"**

The AI will report:
- ✅ What's installed and configured
- ✅ Pipeline state from `.qa-context/pipeline.json` (phases completed, last run)
- ✅ Auth status from `.auth/credentials.json` (credentials found or missing)
- ❌ What's missing (with commands to fix)
- 📋 What it needs from you (user story, credentials, etc.)

The AI **automatically reads `.qa-context/pipeline.json`, `.qa-context/selectors.json`, and `.qa-context/heal-history.json`** to understand the current state before starting any phase.

---

### Phase 1: Test Planning

You have a user story. You want the AI to explore the app and write a test plan.

> **"Read router.md and plan tests for my-story.md"**

The AI will:
1. Read `router.md` → routes to `playwright-test-planner.agent.md`
2. Open your app with Playwright MCP
3. Explore navigation, flows, and UI components
4. Map critical paths and edge cases
5. Write a test plan to `specs/my-story-test-plan.md`
6. **STOP and present the plan to you**

#### What you should review in the plan:
- Are all acceptance criteria covered?
- Are edge cases and negative scenarios included?
- Are the preconditions accurate?
- Does the environment URL match your running app?

#### Approval responses:
| You say | Result |
|---------|--------|
| "Looks good, continue" | AI proceeds to test generation |
| "Approved" | Same |
| "Add a scenario for X" | AI updates the plan, then waits again |
| "I'll review later, proceed" | AI proceeds (use with caution) |

---

### Phase 2: Test Generation

The plan is approved. Now you want the AI to write real Playwright tests.

> **"Generate tests from the plan in specs/my-story-test-plan.md"**

Or simply (if already in context):

> **"Generate the tests"**

The AI will:
1. Read `playwright-test-generator.agent.md`
2. Read `prompts/QAe2eprompt.md` for conventions
3. Use Playwright MCP to manually execute each scenario
4. Capture real selectors from the actual page
5. Add visual checkpoints via Applitools on critical pages (if `APPLITOOLS_API_KEY` is set)
6. Write complete Playwright `.spec.ts` files to `tests/`
7. **STOP and present the code to you**

#### What you should review in the test code:
- Are selectors using real elements? (no hallucinated CSS classes)
- Are assertions meaningful?
- Are visual checkpoints added on critical pages? (login, dashboard, checkout)
- Does the test handle auth/state correctly?
- Are there timeouts or waits that might flake?

#### Approval responses:
| You say | Result |
|---------|--------|
| "Code looks good, execute" | User runs tests, or AI suggests running |
| "Approved" | Same |
| "Fix the selector on line 23" | AI corrects it, presents again |
| "Add a test for X edge case" | AI adds the scenario, presents again |

---

### Phase 3: Execution

Tests are written and approved. Time to run them.

> **User runs:** `npm run qa:execute [test-name]`

Or, if you want the AI to trigger execution (if it has shell access):

> **"Execute the tests and report back"**

The AI runs Playwright and reports:
- ✅ Tests passed → ready for report
- ❌ Tests failed → moves to healing phase

---

### Phase 4: Healing (Debugging Failures)

Tests failed. You want the AI to fix them.

> **"Debug and fix the failing tests"**

Or specifically:

> **"Read playwright-test-healer.agent.md and debug the failures in test-results/latest-run"**

The AI will:
1. Read `playwright-test-healer.agent.md`
2. Run the failing tests with `test_run`
3. Debug with `test_debug` — examine the actual UI state
4. Classify the failure:
   - **Selector broken** → proposes 1-3 line fix
   - **Timing issue** → proposes adding a wait
   - **App bug** → marks `test.fixme()`, logs defect
5. **STOP and present diagnosis + proposed fix to you**

#### What you should review in the diagnosis:
- What exactly failed and why
- What the AI wants to change (which file, which lines)
- Is it a test issue or a real bug in your app?

#### Approval responses:
| You say | Result |
|---------|--------|
| "Fix it" | AI applies the 1-3 line fix and re-runs |
| "Approved, apply the fix" | Same |
| "That's a real bug, file it" | AI marks as defect, moves on |
| "Try a different approach" | AI suggests alternative fix |
| "Skip it, I'll investigate later" | AI marks as `test.fixme()` |

---

### Phase 5: Report

Tests are done. You want a summary.

> **"Generate the execution report"**

Or manually:

> **User runs:** `npm run qa:report [run-id]`

The AI will:
1. Run `npm run qa:report` (or read the results directly)
2. Present a summary: passed, failed, healed, defects found
3. Update `docs/application-context.md` with learned selectors and flaky areas

---

## Quick Reference — All Prompts in One Table

| Phase | Your prompt | AI does | You do |
|-------|------------|---------|--------|
| **0** | *(automatic on first open)* | Environment check | Read status report |
| **0** | "Run the environment check" | Re-check setup | Fix any missing items |
| **1** | "Read router.md and plan tests for my-story.md" | Explore app, write plan | **Review + approve** |
| **2** | "Generate tests from the plan" | Write Playwright code | **Review + approve** |
| **3** | `npm run qa:execute` | Run tests | Check results |
| **4** | "Debug and fix the failing tests" | Diagnose, propose fix | **Review + approve** |
| **5** | "Generate the report" | Summarize results | Review final report |

---

## Best Practices

### For Best Results

1. **Write structured user stories** — Use the format in the README. Clear acceptance criteria produce better test plans.

2. **Review the plan first** — The AI's understanding of your app is only as good as its exploration. Catch incorrect assumptions early.

3. **Don't skip the approval gates** — Each gate is a chance to redirect the AI before it wastes time on the wrong approach.

4. **Be specific in your feedback** — Instead of "this looks wrong", say "the selector on line 23 should use `data-testid` instead of class name".

5. **Provide context upfront** — Populate `docs/application-context.md` with stable selectors, auth details, and tech stack notes before starting. The AI also reads `.qa-context/` automatically — you don't need to tell it.

6. **Memory is persistent** — The AI stores its learning in `.qa-context/` (selectors, healing history, pipeline state). This means each session starts smarter than the last. Don't delete this folder unless you want to reset the AI's memory.

7. **Credentials are stored once** — The AI saves your login to `.auth/credentials.json` after first use. If your password changes, just update that file or delete it and the AI will ask again.

6. **Use `npm run qa:retry` for simple flakes** — If a test fails intermittently, try the mechanical retry first before asking the AI to debug.

7. **Token efficiency works both ways** — Keep your feedback concise. The AI is designed for 1-3 line fixes and targeted edits.

### Common Mistakes to Avoid

| Mistake | Better approach |
|---------|----------------|
| Sending a vague "test my app" prompt | "Read router.md and plan tests for user-story/login.md" |
| Approving without reviewing the plan | Always check: does it cover the acceptance criteria? |
| Letting the AI generate tests without a plan | Always do Phase 1 before Phase 2 |
| Running tests before reviewing the code | AI can hallucinate selectors — verify them first |
| Asking the AI to fix everything at once | One test at a time: "Debug the login test failure" |
| Skipping the approval gate | You're the supervisor for a reason |

---

## Example Full Session

```
You: "Read router.md and plan tests for login-story.md"

AI: [Explores app, writes plan to specs/login-story-test-plan.md]
    "Plan is ready. Here's what I found:
     - 3 scenarios: login success, wrong password, locked account
     - 1 concern: no visible error toast for locked accounts
     Do you approve?"

You: "Looks good, but add a scenario for empty email field."

AI: [Updates plan]
    "Added. 4 scenarios now. Approve?"

You: "Approved, generate the tests."

AI: [Writes tests/login-story.spec.ts]
    "Tests generated. I used getByRole for buttons and getByLabel for inputs.
    Do you approve the code?"

You: "Looks good, execute."

AI: "Run: npm run qa:execute login-story"

You: [Runs it] "Two tests failed — wrong password and locked account."

AI: [Debugs]
    "Diagnosis:
     - Wrong password: error message class changed, needs new selector
     - Locked account: the lock icon isn't rendering (app bug)
     Fix the selector on line 42? Approve?"

You: "Fix the selector, mark the lock icon as a bug."

AI: [Applies fix, re-runs, marks test.fixme()]
    "Fixed: wrong password now passes. Locked account marked as defect.
    Generate the report?"

You: "Yes, generate it."
```

---

## Quick Copy-Paste

### Minimal workflow (5 prompts total)

```
1. "Read router.md and plan tests for my-story.md"
2. "Approved" (after reviewing plan)
3. "Approved" (after reviewing tests)
   (run npm run qa:execute)
4. "Debug and fix the failing tests"
5. "Approved, apply the fix" (after reviewing diagnosis)
   (run npm run qa:report)
```

### Single command to start everything

```
"Read router.md and follow the QA workflow for my-story.md"
```
