# Claude Code Masterclass
A hands-on workspace from **The Testing Academy** showing how to drive Claude Code as a QA automation copilot — building reusable **Skills** and **slash commands**, wiring up the **Atlassian (Jira) MCP**, generating formal **test plans** from Jira tickets, filing **bug reports** straight into Jira, and **exploring live sites** into drop-in Playwright Page Object Models.
This README doubles as a **session log**: every prompt used to build this repo is documented below so the workflow is reproducible.
---
## What's inside
| Path | What it is |
|------|-----------|
| `test-plan-create-skill/` | Skill + `/test-plan` command — turns a Jira ticket (file, pasted text, or live issue key via MCP) into a formal Test Plan (markdown or `.docx`). |
| `bug-report-create-skill/` | Skill + `/create-bug` command — turns a screenshot + notes into a Jira **Bug**, formatted like the team's house template (modeled on VWO-24). |
| `explorer-pom-skill/` | Skill + `/explore` — opens a URL in a browser, harvests locators, and writes a Playwright TypeScript Page Object (see `SKILLs.md`). |
| `output/testplan/` | Example generated test plans (`.md` + `.docx`). |
| `output/pom/` | Example generated Page Objects (`.ts`) ready to paste into a Playwright project. |
| `output/seo-articles/` | SEO-optimized articles for `qaskills.sh` produced by parallel sub-agents. |
| `output/docs/` | User-facing docs (`qaskills-sh.md`) produced by a sub-agent. |
| `output/ux-review/` | Homepage UX review produced by a sub-agent. |
| `Playwright_8_Layer/` | A separate 8-layer Playwright TypeScript E2E framework (POM, fixtures, API). See its own README. |
| `Playwright_Advanced_Framework/` | A second, enterprise-grade Playwright TS framework built by **15 sub-agents in parallel** — 8 layers (Config, Pages, Modules, Utils, API, Fixtures, Reporting, CI/CD), TS path aliases, custom TTA reporter. See its own `README.md`. |
| `vwo-25.md`, `restful-booker-api-test-plan.md` | Sample inputs / outputs. |
| `myTest.java` | Original Hello-World Java sandbox. |
| `CLAUDE.md` | Project guidance for Claude Code (router across the sub-projects). |
> The Selenium framework (`SeleniumRepo/`) is a **separate git repository** with its own remote and is intentionally excluded from this repo (see `.gitignore`).
---
## The skills
All three are standard [Agent Skills](https://agentskills.io) (a folder with `SKILL.md` + optional `assets/`/`references/`/`scripts/`), installable globally at `~/.claude/skills/` with a matching slash command in `~/.claude/commands/`. They also work uploaded to Claude in the cloud.
### `/test-plan` — Test Plan generator
```bash
/test-plan ./ticket.md # from a markdown/text file
/test-plan VWO-105 # fetch the ticket live via the Atlassian MCP
/test-plan VWO-105 create a docx in ./output/testplan/mcp
```
Fills a fixed 14-section template (Objective, Scope, Inclusions, Test Environments, Defect Reporting, Test Strategy, Schedule, Deliverables, Entry/Exit Criteria, Tools, Risks & Mitigations, Approvals). Detects UI vs API tickets and shapes Scope/Inclusions accordingly. A bundled `scripts/md_to_docx.py` (python-docx) converts the markdown to a Word `.docx`.
### `/create-bug` — Jira Bug filer
```bash
/create-bug # then paste a screenshot + a short note
/create-bug REST # file on a different project (default VWO)
```
Reads the screenshot (extracts the page/URL + verbatim error text), fills the five-section bug template (Bug Details → Steps to Reproduce → Expected → Actual → Attachments), and creates the issue via the Atlassian MCP `createJiraIssue`.
> **MCP limitation:** the connected Atlassian MCP can create/edit/comment on issues but has **no file-upload and no delete tool**. So screenshots must be attached manually, and the skill confirms a draft before creating (a created ticket can't be removed via MCP).
### `/explore` — Page Object generator
**Concept:** `/explore` loads a URL in a real browser, reads the accessibility tree (or equivalent DOM harvest), and emits a typed Playwright Page Object class with role-first locators grouped by section (nav, CTAs, forms, footer, iframes).
**Why:** Hand-picking selectors in DevTools for every link and button on a marketing or course landing page typically costs 30–60 minutes; the skill produces a compilable `.ts` file you can refine instead of starting from scratch.
**Q&A — why use this?**
- **Q: When do I reach for it?** A: New app under test, spike on a competitor page, or bootstrapping POMs before you wire fixtures in `Playwright_8_Layer/`.
- **Q: What does it replace?** A: Ad-hoc `codegen` recordings and copy-paste selector lists — output is a class with `goto()` and named `Locator` fields, not a raw test script.
- **Q: What's the gotcha?** A: Duplicate labels (three “Enroll Now” buttons) and embedded iframes need scoping or `frameLocator`; always re-run a smoke test in *your* Playwright project before trusting every locator.
```bash
/explore https://www.saucedemo.com/
/explore https://thetestingacademy.com
/explore https://qaskills.sh
```
```mermaid
flowchart LR
A[User: /explore URL] --> B[Browser open + snapshot]
B --> C[Locator catalog by section]
C --> D[Role / label / href strategy]
D --> E["output/pom/<host>.page.ts"]
E --> F[Smoke test in Playwright project]
```
```ts
import { test, expect } from '@playwright/test';
import { TheTestingAcademyHomePage } from './output/pom/thetestingacademy-com.page';
test('TTA home shows hero and courses', async ({ page }) => {
const home = new TheTestingAcademyHomePage(page);
await home.goto();
await expect(home.heroHeading).toBeVisible();
await expect(home.ourCoursesHeading).toBeVisible();
});
```
**Generated examples in `output/pom/`:**
| File | Site | Class |
|------|------|-------|
| `www-saucedemo-com.page.ts` | [saucedemo.com](https://www.saucedemo.com/) | `SauceDemoLoginPage` |
| `thetestingacademy-com.page.ts` | [thetestingacademy.com](https://thetestingacademy.com/) | `TheTestingAcademyHomePage` |
| `qaskills-sh.page.ts` | [qaskills.sh](https://qaskills.sh/) | `QASkillsPage` |
---
## Jira / Atlassian MCP
The Atlassian MCP connects via **OAuth** (Claude connectors) — no API token is pasted anywhere. Connect it once via `/mcp` (Claude Code) or Settings → Connectors (claude.ai), then reference tickets by key or JQL and Claude fetches them live.
Tickets created during this masterclass on the public demo Jira: **VWO-105** (TTACart PRD test plan source), **VWO-106** and **VWO-107** (login bugs filed via `/create-bug`).
---
## Prompt log — how this repo was built
The exact prompts used, in order. Each produced the artifact noted.
1. **`/init`** — *Analyze the codebase and create a `CLAUDE.md`.*
→ Rewrote `CLAUDE.md` as a router across the multi-project workspace.
2. **`claude plugin install skill-creator@claude-plugins-official`**
→ Installed the skill-creator plugin (used to author the skills below).
3. **"I'm planning to create a simple skill where I give you a Jira ticket as an md file. Read it and generate a test plan into a template I'll give you. Then create a reusable **skill + command** (agentskills.io format) so next time, given a Jira ID or content, you create a test plan automatically. Folder = test-plan-create-skill, usable in the cloud, install it."**
→ Researched the agentskills.io format + local skill/command conventions; asked clarifying questions (install scope, Jira input mode, template handling).
4. **(shared the Test Plan template) + "now please create the skill so that I can use that skill"**
→ Built `test-plan-create-skill/` (SKILL.md + bundled template + Jira-mapping reference), installed globally with the `/test-plan` command, and verified end-to-end on the RESTful Booker example.
5. **`/test-plan @vwo-25.md create the output as a docx file in /output/testplan/docx`**
→ Added a bundled `md_to_docx.py` converter; produced the VWO login-dashboard test plan as `.docx`.
6. **`/test-plan VWO-105 create the test plan for this JIRA, fetch via the MCP if required, docx in /output/testplan/mcp`**
→ Live-fetched VWO-105 (TTACart PRD) via the Atlassian MCP → test plan `.docx`.
7. **`/test-plan VWO-25, VWO-101, VWO-26, VWO-100 — spawn multiple agents to do it`**
→ Spawned 4 parallel agents, each fetching its ticket via MCP and generating an `.md` + `.docx` plan into `output/testplan/batch/`.
8. **"How do I use the Atlassian MCP / how do I give you my Jira config so you can access all my tickets?"**
→ Explained the OAuth model (no token paste), listed the visible projects live, showed how to fetch tickets.
9. **"Create a skill for bug reporting — `bug-report-create-skill` + a `create a bug` command. I'll share a screenshot; create a Jira bug on the VWO project formatted like https://bugzz.atlassian.net/browse/VWO-24."**
→ Built `bug-report-create-skill/` (SKILL.md + VWO-24-style template) and the `/create-bug` command, installed globally.
10. **`/create-bug` (VWO login screenshot, "500 error on valid credentials")**
→ Flagged that the screenshot actually showed a "did not match" auth error (not a 500) and an empty password field; filed **VWO-106** after confirmation.
11. **`/create-bug` (second login screenshot, "fails for valid + invalid login", "use Claude Chrome")**
→ Flagged it as a near-duplicate of VWO-106; filed **VWO-107**; explained that the available Playwright browser can't drive the user's existing logged-in Chrome (that needs the Claude for Chrome extension).
12. **"Commit the code and push to the GitHub repo, and add a README with all the prompts I've used."**
→ Initial commit + this README.
13. **"Using explorer-pom-skill, open thetestingacademy.com and create a page object model file in the output folder."**
→ Built `explorer-pom-skill/SKILLs.md`, explored the live site, wrote `output/pom/thetestingacademy-com.page.ts` (`TheTestingAcademyHomePage`).
14. **(explore runs on saucedemo.com and qaskills.sh)**
→ Added `output/pom/www-saucedemo-com.page.ts` and `output/pom/qaskills-sh.page.ts`.
15. **"Update the parent README, commit the changes, and push the code."**
→ Documented `/explore`, the POM output folder, and shipped examples (this section).
16. **"Please create three sub-agents: SEO articles for qaskills.sh, docs MD, and a homepage improvement review."**
→ Spawned 3 parallel sub-agents. Outputs landed in `output/seo-articles/` (3 articles), `output/docs/qaskills-sh.md`, `output/ux-review/qaskills-sh-homepage-review.md`. Surfaced that `qaskills.sh` is a **skills directory for AI coding agents**, not a course platform — docs were re-scoped accordingly.
17. **"Start 30 sub-agents in parallel; all say hi."** → Confirmed the harness can dispatch ~30 concurrent sub-agents (all returned, ~22k tokens each ≈ 670k total — capacity test, not a real workflow).
18. **"Let 15+ sub-agents build the advanced Playwright framework from the architecture HTML."**
→ Spawned **15 parallel sub-agents**, each owning a specific scope with explicit import/export contracts so they didn't collide. Built `Playwright_Advanced_Framework/`: 8 layers (Config, Pages, Modules, Utils, API, Fixtures, Reporting, CI/CD), 4 page objects against saucedemo.com, 3 modules, 3 API wrappers against fakestoreapi.com, custom TTA reporter writing `tta-report/summary.json`, fixtures DI-wiring everything, JSON test data, 6 specs across 3 spec files (`@P0`/`@P1`/`@smoke` tags), 7-file `docs/` folder + README + CONTRIBUTING. TypeScript path aliases (`@pages/*`, `@modules/*`, `@utils/*`, `@api/*`, `@fixtures`, `@config/*`, `@testdata/*`) keep imports tidy. Run with `npm install && npm run install:browsers && npm test`.
19. **"Commit and push."** → This commit.
---
## Setup notes
- **Java sandbox:** `javac myTest.java && java myTest` → prints `Hello`.
- **Playwright (8-layer) framework:** see `Playwright_8_Layer/README.md` (`npm install && npm test`).
- **Playwright (advanced) framework:** see `Playwright_Advanced_Framework/README.md` (`npm install && npm run install:browsers && npm test`). Tags: `npm run test:smoke`, `npm run test:p0`.
- **Skills:** copy `test-plan-create-skill/`, `bug-report-create-skill/`, and `explorer-pom-skill/` into `~/.claude/skills/`, and matching command stubs into `~/.claude/commands/`, or upload the skill folders to Claude in the cloud.
- **POM output:** generated `.ts` files live under `output/pom/`; import them from your Playwright project or copy into `Playwright_8_Layer/src/pages/`.
---
*Built with Claude Code — The Testing Academy.*