qa-skills 3.0.0

package/skills/qa-linear-integration/references/field-mapping.md

@@ -0,0 +1,121 @@
+# QA → Linear Field Mapping
+
+*Mapping local QA fields (from qa-bug-ticket-creator, qa-task-creator) to Linear issue fields.*
+
+---
+
+## Bug Report → Linear Issue
+
+| QA Bug Field | Linear Field | Notes |
+| ------------ | ------------ | ----- |
+| Title | `title` | Direct mapping; keep concise |
+| Expected Result | `description` | In **Expected** section |
+| Actual Result | `description` | In **Actual** section |
+| Steps to Reproduce | `description` | In **Steps** section |
+| Environment | `description` | In **Environment** section |
+| Evidence | `description` | In **Evidence** section (code blocks) |
+| Severity | `priority` + `labelIds` | See severity mapping below |
+| Priority (P1–P5) | `priority` | See priority mapping below |
+| Component/Module | `labelIds` | Map to Linear labels (e.g., `auth`, `frontend`) |
+
+### Severity → Linear Priority
+
+| QA Severity | Linear Priority |
+| ----------- | --------------- |
+| Blocker | 1 (Urgent) |
+| Critical | 1 (Urgent) |
+| Major | 2 (High) |
+| Minor | 3 (Medium) |
+| Trivial | 4 (Low) |
+
+### Priority (P1–P5) → Linear Priority
+
+| P1 | 1 (Urgent) |
+| P2 | 2 (High) |
+| P3 | 3 (Medium) |
+| P4 | 4 (Low) |
+| P5 | 4 (Low) |
+
+---
+
+## Task → Linear Issue
+
+| QA Task Field | Linear Field | Notes |
+| -------------- | ------------ | ----- |
+| Title | `title` | Direct mapping |
+| Description | `description` | Full context |
+| Acceptance criteria | `description` | In **Acceptance Criteria** section |
+| Task type | `labelIds` | `development`, `qa`, `documentation`, `enhancement` |
+| Component | `labelIds` | Same as bug component labels |
+| Links (bug, requirement) | `description` + relations | "Fixes BUG-123" in body; use `issueRelationCreate` for blocks |
+| Parent bug | `parentId` or relation | Sub-task: `parentId`; fix task: "blocks" relation |
+
+### Task Type → Linear Labels
+
+| QA Task Type | Suggested Label |
+| ------------ | --------------- |
+| Development | `development` |
+| QA | `qa` |
+| Documentation | `documentation` |
+| Enhancement | `enhancement` |
+
+---
+
+## Description Format (Markdown)
+
+Use consistent structure for both bugs and tasks:
+
+```markdown
+## Expected
+[Expected result]
+
+## Actual
+[Actual result]
+
+## Steps to Reproduce
+1. Step one
+2. Step two
+
+## Environment
+- OS: ...
+- Browser: ...
+
+## Evidence
+```
+[Logs, stack trace]
+```
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+For tasks, omit Expected/Actual/Steps when not applicable; include Acceptance Criteria.
+
+---
+
+## Labels
+
+Create or reuse labels in Linear for:
+
+- **Component:** `auth`, `checkout`, `api`, `frontend`, `backend`
+- **Type:** `bug`, `task`, `story`, `enhancement`
+- **Source:** `qa`, `test-failure`, `coverage-gap`, `spec-audit`
+
+Query existing labels:
+
+```graphql
+query { issueLabels { nodes { id name } } }
+```
+
+Use `labelIds` (array of UUIDs) in issueCreate.
+
+---
+
+## Team and Project
+
+- **teamId** — Required for issue creation. Resolve from team key (e.g., `ENG`) via teams query.
+- **projectId** — Optional; assign to project.
+- **cycleId** — Optional; add to active cycle (sprint).
+
+When user specifies "add to project X" or "add to cycle Y", query projects/cycles and use matching IDs.

package/skills/qa-locust-writer/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: qa-locust-writer
+description: Generate Locust performance tests in Python for load testing with distributed mode, custom load shapes, and real-time web UI monitoring.
+output_dir: tests/performance
+---
+
+# QA Locust Writer
+
+## Purpose
+
+Write Locust performance tests from test case specifications and performance plans. Transform structured test cases (from qa-testcase-from-docs, qa-manual-test-designer) and performance plans (from qa-plan-creator, qa-nfr-analyst) into executable Locust load tests with distributed mode, custom load shapes, real-time web UI, and event hooks.
+
+## Trigger Phrases
+
+- "Write Locust tests for [API/endpoint]"
+- "Generate Locust load tests from performance plan"
+- "Create Locust stress tests for [service]"
+- "Add Locust tests with custom load shape"
+- "Locust distributed load test for [URL]"
+- "Python load tests with Locust"
+- "Locust soak test for [endpoint]"
+- "Spike test with Locust"
+- "Locust tests with web UI"
+
+## Key Features
+
+| Feature | Description |
+| ------- | ----------- |
+| **HttpUser class** | Base class for HTTP-based load; `self.client` for requests |
+| **TaskSets** | Group related tasks; nest for complex flows |
+| **@task decorator** | Define user behaviors with optional weight |
+| **wait_time** | `between`, `constant`, `constant_pacing` for think time |
+| **Custom load shapes** | `LoadTestShape` for ramp, spike, soak, custom profiles |
+| **Event hooks** | `events.request`, `events.init`, `events.test_start/stop` |
+| **Distributed mode** | Master/worker for scaling across machines |
+| **Real-time web UI** | Built-in dashboard at `http://localhost:8089` |
+
+## Test Types
+
+| Type | Description | Use Case |
+| ---- | ----------- | -------- |
+| **Load** | Steady load to verify baseline capacity | Baseline, capacity planning |
+| **Stress** | Increase load until failure | Find breaking point |
+| **Spike** | Sudden burst of traffic | Black Friday, flash sales |
+| **Soak** | Sustained load over hours | Memory leaks, stability |
+| **Custom shapes** | User-defined profile via LoadTestShape | Complex scenarios |
+
+## Workflow
+
+1. **Read performance plan** — From qa-plan-creator, qa-nfr-analyst, or test case specs
+2. **Define user classes** — Create `HttpUser` subclasses per user type (e.g., `ApiUser`, `WebUser`)
+3. **Set task weights** — Use `@task(weight=N)` for probability distribution
+4. **Generate locustfile** — Produce `locustfile.py` with user classes, tasks, wait_time
+5. **Configure** — Add `locust.conf` or CLI args; document distributed setup
+
+## Context7 MCP
+
+Use **Context7 MCP** for Locust documentation when:
+- HttpUser, TaskSet, or LoadTestShape APIs need verification
+- Event hooks or distributed mode options are uncertain
+- wait_time, task weights, or configuration syntax require clarification
+
+## Key Patterns
+
+| Pattern | Usage |
+| ------- | ----- |
+| `class MyUser(HttpUser)` | Define user class; inherits `self.client` |
+| `@task` / `@task(weight=3)` | Task method; weight = relative probability |
+| `wait_time = between(1, 3)` | Random wait between tasks (seconds) |
+| `wait_time = constant(2)` | Fixed wait |
+| `wait_time = constant_pacing(1)` | Maintain ~1 req/sec per user |
+| `self.client.get(url)` / `self.client.post(url)` | HTTP requests |
+| `on_start` / `on_stop` | Setup/teardown per user instance |
+| `LoadTestShape` | Custom load profile; override `tick()` |
+| `events.request.add_listener` | Request-level hooks (success/failure) |
+
+See `references/patterns.md` for user classes, task sets, load shapes, events, distributed.
+
+## Distributed Setup
+
+| Role | Command | Purpose |
+| ---- | ------- | ------- |
+| **Master** | `locust -f locustfile.py --master` | Coordinates workers, aggregates stats |
+| **Worker** | `locust -f locustfile.py --worker --master-host=<master-ip>` | Runs load |
+| **Expect workers** | `--expect-workers=4` | Master waits for N workers before starting |
+
+## Configuration
+
+- **CLI args** — `--host`, `--users`, `--spawn-rate`, `--run-time`, `--headless`
+- **locust.conf** — Same options in config file
+- **Environment variables** — `LOCUST_HOST`, `LOCUST_USERS`, etc.
+
+See `references/config.md` for full configuration guide.
+
+## File Naming
+
+- `locustfile.py` — Default; or `locustfile_{service}.py` for multiple files
+- `locust.conf` — Optional configuration
+- Place in `tests/load/` or project root per convention
+
+## Scope
+
+**Can do (autonomous):**
+- Generate Locust load tests from performance plans and test cases
+- Define HttpUser classes, tasks, task weights, wait_time
+- Implement LoadTestShape for load, stress, spike, soak profiles
+- Add event hooks for request logging, custom metrics
+- Document distributed setup (master/worker)
+- Configure locust.conf, CLI args, env vars
+- Use Context7 MCP for Locust docs
+
+**Cannot do (requires confirmation):**
+- Change production API implementation
+- Add dependencies not in requirements.txt/pyproject.toml
+- Override project config without approval
+- Target production URLs without explicit request
+
+**Will not do (out of scope):**
+- Execute load tests (user runs `locust`)
+- Write E2E browser tests (use qa-playwright-ts-writer)
+- Modify CI/CD pipelines
+- Bypass rate limits or ToS
+
+## References
+
+- `references/patterns.md` — User classes, task sets, load shapes, events, distributed
+- `references/config.md` — CLI, locust.conf, environment variables, distributed setup
+- `references/best-practices.md` — Realistic scenarios, correlation, custom shapes, CI integration
+
+## Quality Checklist
+
+- [ ] User classes match performance plan user types
+- [ ] Task weights reflect realistic user behavior distribution
+- [ ] wait_time is appropriate (avoid constant(0) unless intentional)
+- [ ] No hardcoded secrets; use env vars for host, auth
+- [ ] LoadTestShape tick() returns (user_count, spawn_rate) or None
+- [ ] Event hooks do not block or slow down requests
+- [ ] Distributed setup documented when scaling required
+- [ ] Traceability to performance plan / NFR criteria
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| Connection refused | Wrong host or service down | Verify `--host`; ensure target is reachable |
+| Low RPS despite many users | wait_time too high or blocking | Reduce wait_time; avoid sync I/O in tasks |
+| Workers not connecting | Firewall, wrong master host | Check `--master-host`; open port 5557 |
+| Memory growth in soak test | Leaks in app or test code | Profile app; avoid accumulating state in tasks |
+| Inconsistent results | Shared state, non-determinism | Use per-user state; avoid global variables |
+| Task distribution wrong | Incorrect weights | Verify @task(weight=N) sums; check task selection |
+| Load shape not applied | LoadTestShape not used | Pass `--class-picker` or ensure shape in locustfile |

package/skills/qa-locust-writer/references/best-practices.md

@@ -0,0 +1,126 @@
+# Locust Best Practices
+
+## Realistic Scenarios
+
+### Match Production Traffic Mix
+
+- **User mix:** Define multiple `HttpUser` classes with `weight` to reflect real user types (e.g., 80% readers, 20% writers).
+- **Task distribution:** Use `@task(weight=N)` so high-frequency actions (e.g., browse) have higher weight than rare ones (e.g., checkout).
+- **Think time:** Use `wait_time = between(1, 5)` or `constant_pacing` to avoid unrealistic burst patterns.
+
+### Avoid Constant Zero Wait
+
+```python
+# Avoid (unless intentional stress)
+wait_time = constant(0)  # Max RPS, no think time
+
+# Prefer
+wait_time = between(1, 3)  # Simulates user think time
+```
+
+## Correlation and Session State
+
+### Extract Dynamic Data from Responses
+
+```python
+class ApiUser(HttpUser):
+    wait_time = between(1, 2)
+
+    @task
+    def create_and_get(self):
+        r = self.client.post("/api/items", json={"name": "test"})
+        if r.status_code == 201:
+            item_id = r.json()["id"]
+            self.client.get(f"/api/items/{item_id}")
+```
+
+### Use on_start for Auth
+
+```python
+def on_start(self):
+    r = self.client.post("/auth/login", json={"user": "u", "pass": "p"})
+    self.token = r.json()["token"]
+
+@task
+def authenticated_request(self):
+    self.client.get("/api/secure", headers={"Authorization": f"Bearer {self.token}"})
+```
+
+### Avoid Global Mutable State
+
+- Keep state per user instance (e.g., `self.token`).
+- Do not use module-level variables that all users share; this can cause race conditions and skewed results.
+
+## Custom Load Shapes
+
+### Design for Test Type
+
+| Test Type | Shape Pattern |
+| --------- | ------------- |
+| **Load** | Ramp up → sustain → optional ramp down |
+| **Stress** | Gradual increase until failure |
+| **Spike** | Low → sudden high → recovery |
+| **Soak** | Ramp to target → hold for hours |
+
+### Return Correct Tuple from tick()
+
+```python
+def tick(self):
+    run_time = self.get_run_time()
+    # Return (user_count, spawn_rate) or None to stop
+    if run_time < 60:
+        return (50, 5)
+    return None
+```
+
+## CI Integration
+
+### Headless Execution
+
+```bash
+locust -f locustfile.py --host $TARGET_HOST --headless \
+  -u $USERS -r $SPAWN_RATE -t $DURATION \
+  --html report.html --csv results
+```
+
+### Exit Codes
+
+- Locust exits 0 on success, non-zero on failure.
+- Use `--run-time` to ensure tests complete; otherwise Ctrl+C is needed.
+
+### Environment-Specific Hosts
+
+```yaml
+# GitHub Actions example
+- name: Run Locust
+  env:
+    LOCUST_HOST: ${{ secrets.STAGING_URL }}
+    LOCUST_USERS: 100
+    LOCUST_RUN_TIME: 5m
+  run: |
+    locust -f locustfile.py --headless
+```
+
+## Performance of the Test Itself
+
+### Minimize Work in Tasks
+
+- Avoid heavy computation, large allocations, or blocking I/O inside tasks.
+- Use `self.client` (connection pooling) rather than creating new clients per request.
+
+### Event Hooks
+
+- Keep `events.request` listeners lightweight.
+- Do not perform slow operations (e.g., DB writes) in listeners; use async or queue if needed.
+
+## Security and Safety
+
+- **No production by default:** Use staging/QA hosts unless explicitly requested.
+- **Secrets:** Use environment variables for host, tokens, API keys.
+- **Rate limits:** Respect target system limits; coordinate with team before large runs.
+
+## Traceability
+
+- Link load tests to performance plans (e.g., NFR IDs, plan section references).
+- Document target SLAs (e.g., p95 < 500ms) in comments or a separate doc.
+- Use consistent naming for user classes and tasks to align with plan scenarios.

package/skills/qa-locust-writer/references/config.md

@@ -0,0 +1,170 @@
+# Locust Configuration
+
+## CLI Arguments
+
+### Common Options
+
+| Option | Short | Description | Example |
+| ------ | ----- | ----------- | ------- |
+| `--host` | `-H` | Base URL for requests | `--host https://api.example.com` |
+| `--users` | `-u` | Number of users to simulate | `--users 100` |
+| `--spawn-rate` | `-r` | Users spawned per second | `--spawn-rate 10` |
+| `--run-time` | `-t` | Test duration | `--run-time 5m` |
+| `--headless` | | Run without web UI | `--headless` |
+| `--locustfile` | `-f` | Path to locustfile | `-f locustfile.py` |
+| `--web-host` | | Web UI bind address | `--web-host 0.0.0.0` |
+| `--web-port` | | Web UI port | `--web-port 8089` |
+
+### Distributed Options
+
+| Option | Description |
+| ------ | ----------- |
+| `--master` | Run as master node |
+| `--worker` | Run as worker node |
+| `--master-host` | Master node hostname/IP |
+| `--master-port` | Master port (default 5557) |
+| `--expect-workers` | Master waits for N workers before starting |
+
+### Example Commands
+
+```bash
+# Web UI mode
+locust -f locustfile.py --host https://api.example.com
+
+# Headless (CI)
+locust -f locustfile.py --host https://api.example.com --headless -u 100 -r 10 -t 5m
+
+# With custom user class
+locust -f locustfile.py ApiUser --host https://api.example.com
+```
+
+## locust.conf
+
+Create `locust.conf` in project root or same directory as locustfile:
+
+```ini
+# locust.conf
+locustfile = locustfile.py
+host = https://api.example.com
+
+# Web UI
+web-host = 0.0.0.0
+web-port = 8089
+
+# Headless defaults
+users = 100
+spawn-rate = 10
+run-time = 5m
+headless = false
+
+# Logging
+loglevel = INFO
+logfile = locust.log
+```
+
+### Using Config File
+
+```bash
+locust  # Uses locust.conf in cwd
+locust -f locustfile.py --config locust.conf
+```
+
+CLI args override config file values.
+
+## Environment Variables
+
+| Variable | Description |
+| -------- | ----------- |
+| `LOCUST_HOST` | Base URL (same as `--host`) |
+| `LOCUST_LOCUSTFILE` | Path to locustfile |
+| `LOCUST_USERS` | Number of users |
+| `LOCUST_SPAWN_RATE` | Spawn rate |
+| `LOCUST_RUN_TIME` | Run time (e.g., `5m`, `1h`) |
+| `LOCUST_HEADLESS` | Set to `true` for headless |
+| `LOCUST_WEB_HOST` | Web UI host |
+| `LOCUST_WEB_PORT` | Web UI port |
+
+### Example
+
+```bash
+export LOCUST_HOST=https://api.staging.example.com
+export LOCUST_USERS=200
+export LOCUST_SPAWN_RATE=20
+export LOCUST_RUN_TIME=10m
+locust -f locustfile.py --headless
+```
+
+## Distributed Setup
+
+### Architecture
+
+```
+[Master] ---- port 5557 ---- [Worker 1]
+    |                         [Worker 2]
+    |                         [Worker 3]
+    +---- Web UI :8089        [Worker 4]
+```
+
+### Master Configuration
+
+```bash
+locust -f locustfile.py \
+  --master \
+  --expect-workers=4 \
+  --host https://api.example.com \
+  --users 1000 \
+  --spawn-rate 50 \
+  --run-time 10m \
+  --headless
+```
+
+### Worker Configuration
+
+```bash
+locust -f locustfile.py \
+  --worker \
+  --master-host=192.168.1.100 \
+  --master-port=5557
+```
+
+### Docker Compose Example
+
+```yaml
+services:
+  master:
+    image: locustio/locust
+    command: -f /mnt/locustfile.py --master --expect-workers=4
+    ports:
+      - "8089:8089"
+      - "5557:5557"
+    volumes:
+      - ./locustfile.py:/mnt/locustfile.py
+    environment:
+      - LOCUST_HOST=https://api.example.com
+
+  worker:
+    image: locustio/locust
+    command: -f /mnt/locustfile.py --worker --master-host=master
+    volumes:
+      - ./locustfile.py:/mnt/locustfile.py
+    deploy:
+      replicas: 4
+```
+
+## Host in Code
+
+Override host per user class or at runtime:
+
+```python
+class ApiUser(HttpUser):
+    host = "https://api.example.com"  # Overrides --host for this class
+```
+
+Or use environment:
+
+```python
+import os
+
+class ApiUser(HttpUser):
+    host = os.environ.get("LOCUST_HOST", "http://localhost:8000")
+```