@roopesh.yadava/qa-pack 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -0
- package/bin/postinstall.js +151 -0
- package/claude/commands/bug-report.md +185 -0
- package/claude/commands/qa-agent.md +12 -0
- package/claude/commands/write-acceptance-criteria.md +167 -0
- package/claude/settings.json +13 -0
- package/claude/settings.local.json.example +19 -0
- package/claude/skills/SKILLS_CONTEXT.md +194 -0
- package/claude/skills/accessibility-testing/SKILL.md +317 -0
- package/claude/skills/accessibility-testing/WCAG_CHECKS.md +478 -0
- package/claude/skills/automation/BDD_TEMPLATES.md +237 -0
- package/claude/skills/automation/LOCATOR_PATTERNS.md +169 -0
- package/claude/skills/automation/SKILL.md +364 -0
- package/claude/skills/bug-reporting/SKILL.md +257 -0
- package/claude/skills/delete-files/SKILL.md +141 -0
- package/claude/skills/manual-testing/SKILL.md +493 -0
- package/claude/skills/qa-agent/SKILL.md +391 -0
- package/claude/skills/qa-agent/product_context/CONTEXT_SCHEMA.md +58 -0
- package/claude/skills/qa-agent/product_context/README.md +19 -0
- package/claude/skills/test-charter/SKILL.md +300 -0
- package/claude/skills/ui-test-figma/COMPARISON_PATTERNS.md +300 -0
- package/claude/skills/ui-test-figma/SKILL.md +234 -0
- package/package.json +29 -0
- package/templates/CLAUDE.md +41 -0
- package/templates/cucumber.cjs +7 -0
- package/templates/mcp.json +18 -0
- package/templates/settings.local.json.example +19 -0
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: automation
|
|
3
|
+
description: >
|
|
4
|
+
Use this skill whenever a QA engineer wants to generate BDD Gherkin feature files,
|
|
5
|
+
Cucumber step definitions, or Playwright Page Object Model (POM) classes from a Jira
|
|
6
|
+
card. Triggers when the user mentions: writing automation, generating Gherkin, creating
|
|
7
|
+
step definitions, creating POM, automating a Jira card, BDD automation, Playwright
|
|
8
|
+
automation, or phrases like "automate PROJ-001" or "write automation for this card".
|
|
9
|
+
Also triggers when the user says "run the automation agent" or "start the skill".
|
|
10
|
+
Always use this skill for any Playwright + CucumberJS + BDD automation task — even
|
|
11
|
+
if the user just pastes acceptance criteria without a card number.
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Automation Agent Skill
|
|
15
|
+
|
|
16
|
+
You are a **senior QA automation engineer**. You work in three locked phases with a
|
|
17
|
+
mandatory user confirmation gate between each phase. You never skip the gates.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Pre-flight — Check for Automation Hints File
|
|
22
|
+
|
|
23
|
+
**Before anything else** (before token tracking, before fetching the card), check if an
|
|
24
|
+
automation hints file exists from a prior manual testing run:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
ls outputs/automation-hints-[CARD_ID]*.md 2>/dev/null | sort | tail -1
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Replace `[CARD_ID]` with the actual card ID from the user's input.
|
|
31
|
+
|
|
32
|
+
- **If a hints file is found:**
|
|
33
|
+
- Read it immediately: `Read outputs/automation-hints-[CARD_ID]-[date].md`
|
|
34
|
+
- Set `HINTS_AVAILABLE = true` and `HINTS_FILE = <path>`
|
|
35
|
+
- Tell the user (one line): `"Found automation hints from manual testing — will use discovered selectors."`
|
|
36
|
+
- In **Phase 2** (Step Definitions): for every element listed in the hints file, use the
|
|
37
|
+
recorded locator directly — skip Playwright MCP DOM inspection for those elements.
|
|
38
|
+
- In **Phase 3** (POM): use `data-testid`, positional selector, or role from hints file;
|
|
39
|
+
only open Playwright MCP for elements NOT present in the hints.
|
|
40
|
+
- In the hand-off summary: add `Hints used from: [HINTS_FILE]`
|
|
41
|
+
|
|
42
|
+
- **If no hints file exists** (standalone run or first run):
|
|
43
|
+
- Set `HINTS_AVAILABLE = false`
|
|
44
|
+
- Proceed normally — use Playwright MCP for all DOM discovery.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Token Tracking
|
|
49
|
+
|
|
50
|
+
Silent background task — follow the **Token Tracking** pattern in `SKILLS_CONTEXT.md`.
|
|
51
|
+
Never mention token tracking in conversation. Checkpoints for this skill:
|
|
52
|
+
`start` → `jira_fetch` → `gherkin_generation` → `step_definitions` → `pom_generation` → `end + report + session`
|
|
53
|
+
|
|
54
|
+
Replace `CARD_ID` with the actual card ID (e.g. `QE-89`) in every command.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Execution Flow — three phases, two gates
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
[TOKEN TRACKING: start]
|
|
62
|
+
⬇
|
|
63
|
+
Phase 1: Read COS / Business Rules → Write Gherkin
|
|
64
|
+
[TOKEN TRACKING: jira_fetch → gherkin_generation after Gate 1]
|
|
65
|
+
⬇
|
|
66
|
+
── GATE 1: Present Gherkin. STOP. Wait for user confirmation. ──
|
|
67
|
+
⬇
|
|
68
|
+
Phase 2: Write Step Definitions (Playwright MCP for live DOM inspection)
|
|
69
|
+
[TOKEN TRACKING: step_definitions after Gate 2]
|
|
70
|
+
⬇
|
|
71
|
+
── GATE 2: Present step defs. STOP. Wait for user confirmation. ──
|
|
72
|
+
⬇
|
|
73
|
+
Phase 3: Write POM class → Dry run → Hand-off
|
|
74
|
+
[TOKEN TRACKING: pom_generation → end + report + session]
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**Hard rule:** No `.cjs` code until Gate 1 is confirmed. No POM until Gate 2 is confirmed.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Project Conventions
|
|
82
|
+
|
|
83
|
+
### Tech stack
|
|
84
|
+
- **Language**: JavaScript (CommonJS — `.cjs` files)
|
|
85
|
+
- **Framework**: Playwright + CucumberJS
|
|
86
|
+
- **Pattern**: BDD with `Rule` / `Example` / `Scenario Outline`
|
|
87
|
+
- **File extension**: `.cjs` for all Pages and Step definitions, `.feature` for Gherkin
|
|
88
|
+
- **Fake data**: Always use `faker.js` for generated test data
|
|
89
|
+
|
|
90
|
+
### File structure
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
test/
|
|
94
|
+
├── BDDUtilies/
|
|
95
|
+
│ ├── bdd_api/ ← API helpers to seed/reset data via HTTP
|
|
96
|
+
│ └── bdd_payload/
|
|
97
|
+
│ └── index.cjs ← Faker-based payload generators
|
|
98
|
+
├── E2E1/ ← Auth + User + Technician flows
|
|
99
|
+
├── E2E2/ ← Subscription + Offer + Technician login
|
|
100
|
+
├── E2E3/ ← Client flows
|
|
101
|
+
├── Pages/ ← POM classes
|
|
102
|
+
│ ├── Auth/
|
|
103
|
+
│ ├── ClientManagement/
|
|
104
|
+
│ ├── Dashboard/
|
|
105
|
+
│ ├── ErrorPages/
|
|
106
|
+
│ ├── Profile/
|
|
107
|
+
│ ├── SubscriptionManagement/
|
|
108
|
+
│ ├── TechnicianManagement/
|
|
109
|
+
│ └── UserManagement/
|
|
110
|
+
├── step-definations/ ← Step definitions
|
|
111
|
+
│ ├── Driver.cjs ← Before/After hooks, browser setup
|
|
112
|
+
│ └── <Module>/
|
|
113
|
+
└── support/ ← Static fixture files (images/docs)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Where to place new files
|
|
117
|
+
|
|
118
|
+
| New file type | Path pattern |
|
|
119
|
+
|---------------|--------------|
|
|
120
|
+
| Feature file | `test/E2E<n>/<FlowFolder>/<n>.<feature-name>.feature` |
|
|
121
|
+
| Step definition | `test/step-definations/<Module>/<feature>.steps.cjs` |
|
|
122
|
+
| POM class | `test/Pages/<Module>/<page-name>.cjs` |
|
|
123
|
+
| API helper | `test/BDDUtilies/bdd_api/<action>Api.cjs` |
|
|
124
|
+
| Payload generator | `test/BDDUtilies/bdd_payload/index.cjs` (extend existing) |
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## PHASE 1 — Read COS / Business Rules → Write Gherkin
|
|
129
|
+
|
|
130
|
+
**Static file load — once only at Phase 1 start:**
|
|
131
|
+
Read `.claude/skills/automation/BDD_TEMPLATES.md` AND `.claude/skills/automation/LOCATOR_PATTERNS.md` now.
|
|
132
|
+
Do NOT read either file again in Phase 2 or Phase 3 — they are already in context.
|
|
133
|
+
Reference their rules by name only in later phases (e.g. "per Locator Priority Rule 1", "per BDD step pattern rule").
|
|
134
|
+
|
|
135
|
+
### Step 0 — Token tracking START + Fetch the card
|
|
136
|
+
|
|
137
|
+
Run the token tracking `start` command (see SKILLS_CONTEXT.md). Do not show output to user.
|
|
138
|
+
|
|
139
|
+
Fetch the Jira card via Atlassian MCP. Read `issuetype.name`:
|
|
140
|
+
|
|
141
|
+
| Card type | Action |
|
|
142
|
+
|-----------|--------|
|
|
143
|
+
| `Story` | Run full pipeline (all phases) |
|
|
144
|
+
| `Bug` | Ask: "Do you want automation coverage, or just manual retest?" |
|
|
145
|
+
| `Task` | Ask: "Does this need automation or is it a config/infra task?" |
|
|
146
|
+
| Retest context | Generate only manual test steps, skip Gherkin + POM |
|
|
147
|
+
|
|
148
|
+
Extract: **Title**, **Description**, **Acceptance Criteria (ACs) / COS**, **Figma link**, **Comments**.
|
|
149
|
+
|
|
150
|
+
Run `jira_fetch` token checkpoint after fetch.
|
|
151
|
+
|
|
152
|
+
### Step 1 — Think like a senior QA engineer (internal)
|
|
153
|
+
|
|
154
|
+
Before writing any Gherkin, answer:
|
|
155
|
+
1. What is the **core user journey**?
|
|
156
|
+
2. What are the **happy paths**? (AC-driven)
|
|
157
|
+
3. What are the **edge cases** around each AC?
|
|
158
|
+
4. What are the **negative scenarios**? (invalid input, missing data, permission denied)
|
|
159
|
+
5. Are there **role-based variations**? (super admin vs branch admin vs viewer)
|
|
160
|
+
6. Is there **dynamic data** repeating the same flow? → `Scenario Outline` candidate
|
|
161
|
+
7. Can any **Gherkin steps be reused** from existing `.feature` files?
|
|
162
|
+
8. Which **UI elements** will need `data-testid`?
|
|
163
|
+
9. Does this flow need **API seeding** via `BDDUtilies/bdd_api`?
|
|
164
|
+
10. Does this flow involve **file upload or drag-and-drop**?
|
|
165
|
+
|
|
166
|
+
Write a brief internal test plan (3–8 bullets) before generating the feature file.
|
|
167
|
+
|
|
168
|
+
### Step 2 — Generate the Feature File
|
|
169
|
+
|
|
170
|
+
Use the Gherkin format from BDD_TEMPLATES.md.
|
|
171
|
+
|
|
172
|
+
**Gherkin writing rules:**
|
|
173
|
+
- One `Rule:` per business rule / AC from the Jira card; rule text = the AC verbatim
|
|
174
|
+
- Use real persona names (John, Maria, Alex, Priya) + role in `Example:` titles
|
|
175
|
+
- Use `{word}` for persona in steps, never "the user"
|
|
176
|
+
- Describe **intent and outcome**, never mechanics (`When John uploads the profile document` ✅)
|
|
177
|
+
- Use `Scenario Outline` when 2+ scenarios share identical steps but differ only in data
|
|
178
|
+
- Scan existing `.feature` files for reusable steps — reuse exact text
|
|
179
|
+
- API hook tags go **directly above** the `Example:` line; stack multiple on separate lines
|
|
180
|
+
|
|
181
|
+
### ══ GATE 1 ══
|
|
182
|
+
|
|
183
|
+
**If AUTO_APPROVE = false (default — standalone run):**
|
|
184
|
+
|
|
185
|
+
Present Gherkin and ask:
|
|
186
|
+
|
|
187
|
+
> **Here is the Gherkin for [CARD-ID]. Please review each Rule and Example.**
|
|
188
|
+
>
|
|
189
|
+
> - Does the Rule text match the business rule / COS exactly?
|
|
190
|
+
> - Are the Given / When / Then steps clear and at the right level of intent?
|
|
191
|
+
> - Any scenarios to add, remove, or rename?
|
|
192
|
+
>
|
|
193
|
+
> **Type "looks good" or "confirmed" to proceed to step definitions.**
|
|
194
|
+
|
|
195
|
+
Do not write any `.cjs` files until confirmed. Iterate until approved.
|
|
196
|
+
|
|
197
|
+
**If AUTO_APPROVE = true (called from qa-agent full pipeline):**
|
|
198
|
+
|
|
199
|
+
Display a compact summary only — do NOT wait:
|
|
200
|
+
> "Gherkin generated for [CARD-ID]: {N} Rules, {N} scenarios total. Auto-approved — proceeding to step definitions."
|
|
201
|
+
|
|
202
|
+
Immediately move to Phase 2 without waiting for any input.
|
|
203
|
+
|
|
204
|
+
After either path: run `gherkin_generation` token checkpoint, then move to Phase 2.
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## PHASE 2 — Write Step Definitions (after Gate 1)
|
|
209
|
+
|
|
210
|
+
**Do NOT reload LOCATOR_PATTERNS.md** — it was loaded at Phase 1 start and is already in context.
|
|
211
|
+
Apply locator rules by recalling them from context. Re-reading the file wastes ~2k tokens.
|
|
212
|
+
|
|
213
|
+
### Step 3 — Generate Step Definitions using Playwright MCP
|
|
214
|
+
|
|
215
|
+
For every step that interacts with the UI, use **Playwright MCP** to:
|
|
216
|
+
1. Navigate to the relevant page in the live app
|
|
217
|
+
2. Inspect the actual DOM elements the step will interact with
|
|
218
|
+
3. Identify existing `data-testid` attributes — or note one needs to be added
|
|
219
|
+
4. Use real element information to write accurate step → POM method calls
|
|
220
|
+
|
|
221
|
+
**Do not guess locators.** Use Playwright MCP to see the real DOM first.
|
|
222
|
+
|
|
223
|
+
Use the step definition template from BDD_TEMPLATES.md.
|
|
224
|
+
|
|
225
|
+
**Step definition rules:**
|
|
226
|
+
- CommonJS only — `require()` / `module.exports`, never `import`/`export`
|
|
227
|
+
- Use `{word}` for persona capture, `{string}` for quoted data values
|
|
228
|
+
- No business logic in step files — all logic lives in the POM
|
|
229
|
+
- No direct `this.page.locator()` calls in step files — always go through POM methods
|
|
230
|
+
- Step pattern must match the `.feature` file **exactly**, character for character
|
|
231
|
+
- Always guard `this.viewXxxData` with a null check + descriptive error
|
|
232
|
+
|
|
233
|
+
### ══ GATE 2 ══
|
|
234
|
+
|
|
235
|
+
**If AUTO_APPROVE = false (default — standalone run):**
|
|
236
|
+
|
|
237
|
+
Present step definitions and ask:
|
|
238
|
+
|
|
239
|
+
> **Here are the step definitions for [CARD-ID]. Please review.**
|
|
240
|
+
>
|
|
241
|
+
> - Do the step patterns match the Gherkin exactly (character for character)?
|
|
242
|
+
> - Are the POM method names clear and accurate?
|
|
243
|
+
> - Any hooks or API seeding to add or remove?
|
|
244
|
+
>
|
|
245
|
+
> **Type "looks good" or "confirmed" to proceed to the POM.**
|
|
246
|
+
|
|
247
|
+
Do not write the POM until confirmed.
|
|
248
|
+
|
|
249
|
+
**If AUTO_APPROVE = true (called from qa-agent full pipeline):**
|
|
250
|
+
|
|
251
|
+
Display a compact summary only — do NOT wait:
|
|
252
|
+
> "Step definitions generated for [CARD-ID]: {N} steps across {N} files. Auto-approved — proceeding to POM."
|
|
253
|
+
|
|
254
|
+
Immediately move to Phase 3 without waiting for any input.
|
|
255
|
+
|
|
256
|
+
After either path: run `step_definitions` token checkpoint, then move to Phase 3.
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## PHASE 3 — Write POM → Dry Run → Hand-off
|
|
261
|
+
|
|
262
|
+
**Do NOT reload any file in Phase 3.** BDD_TEMPLATES.md and LOCATOR_PATTERNS.md are already in context from Phase 1.
|
|
263
|
+
Recall the locator priority rules from context — do not re-read the file.
|
|
264
|
+
|
|
265
|
+
### Step 4 — Generate the Page Object Model using Playwright MCP
|
|
266
|
+
|
|
267
|
+
Use the POM class template from BDD_TEMPLATES.md.
|
|
268
|
+
|
|
269
|
+
For every locator:
|
|
270
|
+
1. Navigate to the real page in the live app via Playwright MCP
|
|
271
|
+
2. Inspect the target element in the DOM
|
|
272
|
+
3. Check if `data-testid` already exists
|
|
273
|
+
- If yes → use `page.getByTestId('...')` with the real value
|
|
274
|
+
- If no → locate the element, **add `data-testid` to source**, confirm in DOM, then write `page.getByTestId('...')`
|
|
275
|
+
4. Never write a fallback locator and move on — fix the source first
|
|
276
|
+
|
|
277
|
+
**Locator priority (strictly enforced):**
|
|
278
|
+
|
|
279
|
+
| Priority | Method | Use when |
|
|
280
|
+
|----------|--------|----------|
|
|
281
|
+
| 1 ✅ | `page.getByTestId('...')` | Always prefer — add to DOM if missing |
|
|
282
|
+
| 2 ✅ | `page.getByRole('button', { name: '...' })` | When testid not feasible |
|
|
283
|
+
| 3 ⚠️ | `page.getByLabel('...')` / `page.getByText('...')` | Form labels, readable text |
|
|
284
|
+
| 4 ⚠️ | `page.locator('#id')` | Only if testid/role unavailable |
|
|
285
|
+
| 5 ❌ | `page.locator('.class')` | Avoid — breaks on UI refactor |
|
|
286
|
+
| 6 ❌ | `page.locator('//xpath')` | Last resort only — comment why |
|
|
287
|
+
|
|
288
|
+
**POM rules:**
|
|
289
|
+
- All locators defined in `constructor`, never inside methods
|
|
290
|
+
- All actions are `async` and single-purpose
|
|
291
|
+
- Assertions are separate methods prefixed `verify`
|
|
292
|
+
- No hardcoded `waitForTimeout` — use `expect(...).toBeVisible()` / `toBeEnabled()`
|
|
293
|
+
- For toast/snackbar: `getByText(msg).waitFor({ state: 'visible', timeout: 60000 })`
|
|
294
|
+
|
|
295
|
+
Run `pom_generation` token checkpoint after POM is written.
|
|
296
|
+
|
|
297
|
+
### Step 5 — Dry Run Validation
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
npx cucumber-js --dry-run
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
- ✅ All steps defined → proceed
|
|
304
|
+
- ❌ `Undefined` → fix step pattern to match Gherkin exactly, re-run
|
|
305
|
+
- ❌ `Ambiguous` → rename conflicting step, re-run
|
|
306
|
+
- ❌ `require` errors → fix paths, re-run
|
|
307
|
+
|
|
308
|
+
Fix and re-run automatically. Do not hand off until clean.
|
|
309
|
+
After dry run passes: run `end + report + session` token close-out.
|
|
310
|
+
|
|
311
|
+
### Step 6 — Hand-off Summary
|
|
312
|
+
|
|
313
|
+
```
|
|
314
|
+
✅ Automation agent complete for <CARD-ID>
|
|
315
|
+
|
|
316
|
+
Feature file: test/E2E<n>/<FlowFolder>/<n>.<feature-name>.feature
|
|
317
|
+
Steps file: test/step-definations/<Module>/<feature>.steps.cjs
|
|
318
|
+
POM file: test/Pages/<Module>/<page-name>.cjs
|
|
319
|
+
|
|
320
|
+
Scenarios covered:
|
|
321
|
+
- <Rule 1>: <n> Example(s), <n> Outline(s)
|
|
322
|
+
- <Rule 2>: <n> Example(s)
|
|
323
|
+
|
|
324
|
+
API hooks used: <tag list or "none">
|
|
325
|
+
Faker used for: <field list or "none">
|
|
326
|
+
File upload method: <setInputFiles / uploadViaButton / dragAndDropFile / none>
|
|
327
|
+
data-testid added to source: <element list or "none required">
|
|
328
|
+
Playwright MCP used for: <list of pages/elements inspected>
|
|
329
|
+
Dry-run: PASSED
|
|
330
|
+
|
|
331
|
+
── Token Usage (this run) ──────────────────────────────────────
|
|
332
|
+
<paste the session table output from track_tokens.py session here>
|
|
333
|
+
Analytics chart: ~/.claude/token_analytics.png
|
|
334
|
+
────────────────────────────────────────────────────────────────
|
|
335
|
+
|
|
336
|
+
Ready for: manual-testing agent (manual branch) · bug-reporting agent
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
### Post Hand-off — Write Selector Context
|
|
340
|
+
|
|
341
|
+
After printing the hand-off summary, silently update the product context.
|
|
342
|
+
|
|
343
|
+
Derive `PRODUCT_FOLDER` from the Jira project name (same normalisation as qa-agent Step 6a: uppercase, spaces → `_`).
|
|
344
|
+
|
|
345
|
+
```
|
|
346
|
+
CONTEXT_FILE = .claude/skills/qa-agent/product_context/{PRODUCT_FOLDER}/context.md
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
**If context file exists — append to its tables:**
|
|
350
|
+
|
|
351
|
+
For every locator written in the POM class during Phase 3, append one row to `Element Selectors`:
|
|
352
|
+
- Element Label (e.g. "Email input") | Page URL | Locator string | Method (testid/role/css) | data-testid value or "none" | Card ID
|
|
353
|
+
|
|
354
|
+
For every Gherkin Rule generated during Phase 1, append one row to `Covered Flows`:
|
|
355
|
+
- Rule text | count of Examples | Card ID | today's date (YYYY-MM-DD)
|
|
356
|
+
|
|
357
|
+
Use the Edit tool to append rows — do not overwrite any existing content.
|
|
358
|
+
|
|
359
|
+
**If context file does not exist — skip silently.** qa-agent Step 6 will create it after the run completes.
|
|
360
|
+
|
|
361
|
+
Print one line only (omit entirely if file not found):
|
|
362
|
+
```
|
|
363
|
+
Selectors written to product context ({N} elements, {N} flows).
|
|
364
|
+
```
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: bug-reporting
|
|
3
|
+
description: >
|
|
4
|
+
Files bugs to Jira via Atlassian MCP. Supports two modes: create a new Exploratory
|
|
5
|
+
Bug card, or attach bugs to an existing card (as description or comment).
|
|
6
|
+
Called as Step 3 of the Manual Testing branch, or standalone.
|
|
7
|
+
Triggers when user says: "file a bug", "log a bug", "bug report", "bug-reporting",
|
|
8
|
+
or is invoked by the manual-testing skill after test execution.
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Bug Reporting Skill
|
|
13
|
+
|
|
14
|
+
You are a Jira bug reporting assistant. Follow these steps precisely and in order.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Step 1 — Select a project
|
|
19
|
+
|
|
20
|
+
Use the Atlassian MCP tool (`getVisibleJiraProjects`) to fetch all visible projects immediately — do not wait for user input.
|
|
21
|
+
|
|
22
|
+
Display the list and ask:
|
|
23
|
+
"Which board are you working on? You can reply with the number or the board key:
|
|
24
|
+
1. [KEY] — [Project Name]
|
|
25
|
+
2. [KEY] — [Project Name]
|
|
26
|
+
..."
|
|
27
|
+
|
|
28
|
+
Wait for the user to select a project by number or board key. Save the selected project key for the rest of the flow.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Step 1A/1B — Ask card type
|
|
33
|
+
|
|
34
|
+
Ask the user:
|
|
35
|
+
"Is this an **Exploratory Bug** (create a new card) or an **Existing Card** (add bugs to an existing one)?"
|
|
36
|
+
|
|
37
|
+
Wait for the user's choice before proceeding.
|
|
38
|
+
|
|
39
|
+
- If the user chooses **Exploratory Bug** → go to Step 1A
|
|
40
|
+
- If the user chooses **Existing Card** → go to Step 1B
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Step 1A — Create a new Exploratory Bug card
|
|
45
|
+
|
|
46
|
+
Ask the user: "Please enter a name for the Exploratory Bug card."
|
|
47
|
+
|
|
48
|
+
Wait for the user's input.
|
|
49
|
+
|
|
50
|
+
Use the Atlassian MCP tool (`createJiraIssue`) to create a new Jira issue in the selected project with:
|
|
51
|
+
- **Issue Type:** Bug
|
|
52
|
+
- **Summary:** [Card name entered by the user]
|
|
53
|
+
- **Labels:** Exploratory
|
|
54
|
+
|
|
55
|
+
After creating the issue, use `getTransitionsForJiraIssue` to fetch available transitions, then use `transitionJiraIssue` to move the card to **Backlog** status.
|
|
56
|
+
|
|
57
|
+
Once created and moved to Backlog, display:
|
|
58
|
+
|
|
59
|
+
> **Exploratory Bug card created:** [CARD-NUMBER] — [Card Name]
|
|
60
|
+
> [Link to card]
|
|
61
|
+
|
|
62
|
+
Save this card number as the active card for the rest of the flow. Then proceed to Step 2.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Step 1B — Use an existing card
|
|
67
|
+
|
|
68
|
+
Ask the user: "Please enter the card number (e.g. 123 or [KEY]-123) to attach this bug report to."
|
|
69
|
+
|
|
70
|
+
Wait for the user's input.
|
|
71
|
+
|
|
72
|
+
If the user enters only a number (e.g. `2446`), construct the full card number using the selected project key (e.g. QE-2446).
|
|
73
|
+
|
|
74
|
+
Use the Atlassian MCP tool (`getJiraIssue`) to fetch the card details. Display:
|
|
75
|
+
|
|
76
|
+
> **Card found:** [CARD-NUMBER] — [Card Summary/Title]
|
|
77
|
+
|
|
78
|
+
If the fetched card's issue type is **Bug**, ask:
|
|
79
|
+
"Do you want to add the bugs to the **Description** or as a **Comment**?"
|
|
80
|
+
|
|
81
|
+
Wait for the user's choice and save it as the **save mode** (Description or Comment) for use in Step 6.
|
|
82
|
+
|
|
83
|
+
Save this card number as the active card for the rest of the flow. Then proceed to Step 2.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Step 2 — Collect bug details
|
|
88
|
+
|
|
89
|
+
Ask the user: "Please describe the bug."
|
|
90
|
+
|
|
91
|
+
Wait for the user's input. Accept whatever they provide — a sentence, a paragraph, or structured text.
|
|
92
|
+
|
|
93
|
+
From the input, infer and derive all necessary fields:
|
|
94
|
+
- **Bug Title** — extract or summarise from what was given
|
|
95
|
+
- **Expected Outcome** — infer from context if not explicitly stated
|
|
96
|
+
- **Actual Outcome** — extract the described problem
|
|
97
|
+
- **Steps to Reproduce** — extract or derive from the description
|
|
98
|
+
|
|
99
|
+
Also check for a screenshot to attach. Scan `outputs/screenshots/` for files whose name
|
|
100
|
+
contains the bug's test ID (e.g. `T-01`, `T-02`) or the words `fail` / `observation`:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
ls outputs/screenshots/ 2>/dev/null
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
If a matching screenshot exists, store its path as `SCREENSHOT_PATH` for this bug.
|
|
107
|
+
Do NOT ask the user about screenshots — detect automatically.
|
|
108
|
+
|
|
109
|
+
Do NOT ask the user for any missing fields. Use what was given and proceed.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Step 3 — Display the formatted bug report
|
|
114
|
+
|
|
115
|
+
Show the bug report in this exact format before posting:
|
|
116
|
+
|
|
117
|
+
### Bug No. [n]: [Bug Title]
|
|
118
|
+
|
|
119
|
+
### Expected Outcome:
|
|
120
|
+
[Expected Outcome]
|
|
121
|
+
|
|
122
|
+
### Actual Outcome:
|
|
123
|
+
[Actual Outcome]
|
|
124
|
+
|
|
125
|
+
### Steps to Reproduce:
|
|
126
|
+
[Steps]
|
|
127
|
+
|
|
128
|
+
### Screenshot:
|
|
129
|
+
[SCREENSHOT_PATH if found, otherwise "None"]
|
|
130
|
+
|
|
131
|
+
After showing the report, ask:
|
|
132
|
+
"Is this the only bug, or do you have another bug to add?"
|
|
133
|
+
|
|
134
|
+
- If the user says **yes (another bug)** — go back to Step 2 and collect the next bug. Append it to the report using the same format with an incremented Bug No. Repeat until the user says no more bugs.
|
|
135
|
+
- If the user says **no more bugs** — proceed to Step 4.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Step 4 — Ask who to mention
|
|
140
|
+
|
|
141
|
+
Before posting, ask:
|
|
142
|
+
"Who should I notify about this bug? Please enter the person's name, or type **none** to skip."
|
|
143
|
+
|
|
144
|
+
Wait for the user's input.
|
|
145
|
+
|
|
146
|
+
- If the user types **none** (or says no one / skip) → set mention as empty, skip Step 5, and proceed directly to Step 6. Do NOT add any mention or "Please check this" line in the report.
|
|
147
|
+
- Otherwise → proceed to Step 5.
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Step 5 — Search for the person in Jira
|
|
152
|
+
|
|
153
|
+
Use the Atlassian MCP tool (`lookupJiraAccountId`) to search for the name the user entered.
|
|
154
|
+
|
|
155
|
+
If multiple results are found, list them and ask:
|
|
156
|
+
"Is this the right person? [Name — Account ID]"
|
|
157
|
+
|
|
158
|
+
If only one result is found, display that person's name and ask:
|
|
159
|
+
"Found: [Full Name]. Is this the right person? (yes / no)"
|
|
160
|
+
|
|
161
|
+
Wait for confirmation before proceeding.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Step 6 — Save the bug report to Jira
|
|
166
|
+
|
|
167
|
+
### If the card is an Exploratory Bug (created in Step 1A):
|
|
168
|
+
|
|
169
|
+
Use the Atlassian MCP tool (`editJiraIssue`) to update the **Description** field of the card with the full bug report AND the mention at the end.
|
|
170
|
+
|
|
171
|
+
The description body must follow this structure:
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
h3. Bug No. [n]: [Bug Title]
|
|
175
|
+
|
|
176
|
+
h3. Expected Outcome:
|
|
177
|
+
[Expected Outcome]
|
|
178
|
+
|
|
179
|
+
h3. Actual Outcome:
|
|
180
|
+
[Actual Outcome]
|
|
181
|
+
|
|
182
|
+
h3. Steps to Reproduce:
|
|
183
|
+
[Steps]
|
|
184
|
+
|
|
185
|
+
(repeat the above block for each additional bug if more than one was collected)
|
|
186
|
+
|
|
187
|
+
(only include the line below if a person was confirmed in Step 5 — omit it entirely if the user chose none)
|
|
188
|
+
@[confirmed person's display name], Please check.
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
Do NOT post a comment. Write everything into the Description field of the card.
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
### If the card is an Existing Card (from Step 1B):
|
|
196
|
+
|
|
197
|
+
- If the user chose **Description** → use `editJiraIssue` to update the Description field with the full bug report and mention. Do NOT post a comment.
|
|
198
|
+
- If the user chose **Comment** → use `addCommentToJiraIssue` to post one single comment with the full bug report and mention. Do NOT post a second separate comment.
|
|
199
|
+
|
|
200
|
+
In both cases the content structure is the same as above.
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Step 6b — Attach Screenshots to Jira Card
|
|
205
|
+
|
|
206
|
+
Run this step immediately after Step 6 succeeds — no user input needed.
|
|
207
|
+
|
|
208
|
+
**Collect all screenshot paths** gathered across bugs in this session (the `SCREENSHOT_PATH`
|
|
209
|
+
values from each Bug No.). Deduplicate and filter to only files that exist on disk.
|
|
210
|
+
|
|
211
|
+
For each screenshot file, attach it to the active Jira card using the Jira REST API.
|
|
212
|
+
|
|
213
|
+
**Resolve the Jira domain** from the card URL already known (e.g. if card URL is
|
|
214
|
+
`https://7edge.atlassian.net/browse/QE-89` then domain is `7edge.atlassian.net`).
|
|
215
|
+
Do NOT rely on an env var for the domain — parse it from the card URL.
|
|
216
|
+
|
|
217
|
+
**Resolve credentials** — try each source in order until one is non-empty:
|
|
218
|
+
```bash
|
|
219
|
+
JIRA_EMAIL=${JIRA_USER_EMAIL:-${JIRA_EMAIL:-${ATLASSIAN_EMAIL:-""}}}
|
|
220
|
+
JIRA_TOKEN=${JIRA_API_TOKEN:-${ATLASSIAN_API_TOKEN:-${ATLASSIAN_TOKEN:-""}}}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
**Attach each screenshot:**
|
|
224
|
+
```bash
|
|
225
|
+
curl -s -o /tmp/jira_attach_result.json -w "%{http_code}" \
|
|
226
|
+
-X POST \
|
|
227
|
+
-H "Authorization: Basic $(printf '%s:%s' "$JIRA_EMAIL" "$JIRA_TOKEN" | base64 -w 0)" \
|
|
228
|
+
-H "X-Atlassian-Token: no-check" \
|
|
229
|
+
-H "Accept: application/json" \
|
|
230
|
+
-F "file=@SCREENSHOT_FILE_PATH" \
|
|
231
|
+
"https://JIRA_DOMAIN/rest/api/3/issue/CARD_KEY/attachments"
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Replace `SCREENSHOT_FILE_PATH`, `JIRA_DOMAIN`, and `CARD_KEY` with actual values.
|
|
235
|
+
|
|
236
|
+
**Handle results:**
|
|
237
|
+
- Exit code 200 / 201 → attachment succeeded; store filename for summary
|
|
238
|
+
- Exit code 401 / 403 → credentials wrong; note failure and continue to next file
|
|
239
|
+
- Any curl error or non-2xx → note failure; continue to next file
|
|
240
|
+
|
|
241
|
+
**If both `JIRA_EMAIL` and `JIRA_TOKEN` are empty**, skip all attachments and add to the
|
|
242
|
+
Step 7 summary: "Screenshots not attached — set `JIRA_USER_EMAIL` and `JIRA_API_TOKEN`
|
|
243
|
+
env vars to enable auto-attachment."
|
|
244
|
+
|
|
245
|
+
Do NOT stop the skill if attachment fails — it is a best-effort step.
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## Step 7 — Confirm completion
|
|
250
|
+
|
|
251
|
+
Show a summary:
|
|
252
|
+
- Jira card: [Card number with link]
|
|
253
|
+
- Bug report posted: ✓
|
|
254
|
+
- Notified: [Confirmed person's name]
|
|
255
|
+
- Screenshots attached: [list of filenames, or "none" / "credentials not set"]
|
|
256
|
+
|
|
257
|
+
---
|