qa-skills 3.0.0 → 3.1.0

package/skills/qa-accessibility-test-writer/references/best-practices.md

@@ -1,184 +0,0 @@
-# Accessibility Testing Best Practices
-
-Best practices for automated and manual accessibility testing. Use with qa-accessibility-test-writer when generating tests and planning audits.
-
----
-
-## Automated vs Manual Testing
-
-### What Automation Covers
-
-| Category | Automated | Manual |
-|----------|-----------|--------|
-| Color contrast | ✓ | ✓ (verify in context) |
-| Alt text presence | ✓ | ✓ (verify accuracy) |
-| ARIA validity | ✓ | ✓ (verify semantics) |
-| Keyboard operability | Partial | ✓ |
-| Focus order | Partial | ✓ |
-| Screen reader experience | ✗ | ✓ |
-| Cognitive load | ✗ | ✓ |
-| Motion sensitivity | ✗ | ✓ |
-
-### Recommended Mix
-
-1. **Automated first** — axe-core, Pa11y, Lighthouse on every build
-2. **Manual keyboard** — Tab through critical flows (login, checkout, forms)
-3. **Manual screen reader** — NVDA/JAWS (Windows), VoiceOver (macOS/iOS), TalkBack (Android)
-4. **Manual spot checks** — Color contrast in context, zoom to 200%, reduced motion
-
----
-
-## Screen Reader Testing
-
-### Tools
-
-| Platform | Screen Reader | Notes |
-|----------|---------------|-------|
-| Windows | NVDA (free) | Most common for testing |
-| Windows | JAWS | Commercial; often required for compliance |
-| macOS | VoiceOver | Built-in; Cmd+F5 |
-| iOS | VoiceOver | Built-in; triple-click Home/Side |
-| Android | TalkBack | Built-in |
-
-### Key Scenarios
-
-1. **Landmarks** — Can user jump between main, nav, footer?
-2. **Headings** — Can user navigate by heading level?
-3. **Forms** — Are labels announced? Are errors announced?
-4. **Dynamic content** — Are live regions (`aria-live`) announced?
-5. **Custom widgets** — Do dialogs, tabs, accordions have correct roles and states?
-
-### Testing Workflow
-
-```
-1. Unplug mouse; use keyboard only
-2. Turn on screen reader
-3. Navigate page from top (headings, landmarks, links)
-4. Complete critical user flow (e.g., add to cart, checkout)
-5. Note: missing labels, wrong order, unannounced updates
-```
-
----
-
-## Keyboard Testing
-
-### Essential Keys
-
-| Key | Purpose |
-|-----|---------|
-| Tab | Move forward through focusable elements |
-| Shift+Tab | Move backward |
-| Enter | Activate links, buttons |
-| Space | Toggle checkboxes, activate buttons |
-| Arrow keys | Navigate within components (tabs, menus, sliders) |
-| Escape | Close modals, cancel |
-
-### Checklist
-
-- [ ] All interactive elements reachable via Tab
-- [ ] No keyboard traps (can always Tab out)
-- [ ] Focus order matches visual order
-- [ ] Focus indicator visible (outline or equivalent)
-- [ ] Skip link works and targets main content
-- [ ] Modals trap focus and return focus on close
-- [ ] Dropdowns/menus operable with Arrow keys
-
-### Common Failures
-
-| Issue | Fix |
-|-------|-----|
-| Custom div not focusable | Add `tabindex="0"` and keyboard handlers |
-| Focus lost after modal close | Store focused element; restore on close |
-| No visible focus | Add `:focus-visible` styles |
-| Wrong tab order | Use `tabindex` sparingly; fix DOM order |
-
----
-
-## Color Contrast
-
-### Requirements (WCAG 2.2)
-
-| Level | Normal Text | Large Text |
-|-------|-------------|------------|
-| AA | 4.5:1 | 3:1 |
-| AAA | 7:1 | 4.5:1 |
-
-Large text = 18pt+ or 14pt+ bold.
-
-### Tools
-
-- **axe-core** — Automated contrast checks
-- **WebAIM Contrast Checker** — Manual verification
-- **Chrome DevTools** — Inspect element → Accessibility panel
-
-### Edge Cases
-
-- **Logos** — Exempt; no contrast requirement
-- **Disabled elements** — No contrast requirement
-- **Placeholder text** — Should meet 4.5:1 or have visible label
-- **Focus indicators** — 3:1 against adjacent colors
-
----
-
-## Form Accessibility
-
-### Labels
-
-- Every input has a visible `<label>` or `aria-label`
-- Labels describe purpose; placeholders are supplementary
-- Error messages linked via `aria-describedby` or `aria-errormessage`
-
-### Error Handling
-
-- Errors identified in text (not color alone)
-- `aria-invalid="true"` on invalid fields
-- `role="alert"` or `aria-live="assertive"` for error announcements
-- Suggestions provided (3.3.3 Error Suggestion)
-
-### Autocomplete
-
-- Use `autocomplete` attribute for common fields (name, email, address)
-
----
-
-## Testing in CI/CD
-
-### Playwright Example
-
-```yaml
-# .github/workflows/a11y.yml
-- name: Run accessibility tests
-  run: npx playwright test tests/accessibility/
-```
-
-### Thresholds
-
-- **Zero violations** for WCAG 2.2 A/AA in critical paths
-- **Lighthouse accessibility score** ≥ 90 for key pages
-- **Allow known exceptions** via axe `disableRules` with documented rationale
-
-### Reporting
-
-- Store JSON/HTML reports as artifacts
-- Fail build on new violations
-- Track trends over time (e.g., Lighthouse CI)
-
----
-
-## When to Escalate
-
-| Situation | Action |
-|-----------|--------|
-| axe reports "needs review" | Manual verification; document decision |
-| Design conflicts with WCAG | Discuss with design; propose alternatives |
-| Third-party widget fails | Contact vendor; document as known limitation |
-| AAA required | Plan manual testing; automation covers subset |
-
----
-
-## References
-
-- [WCAG 2.2 Understanding](https://www.w3.org/WAI/WCAG22/Understanding/)
-- [WebAIM Screen Reader User Survey](https://webaim.org/projects/screenreadersurvey9/)
-- [Inclusive Design Principles](https://inclusivedesignprinciples.org/)
-- [A11y Project Checklist](https://www.a11yproject.com/checklist/)

package/skills/qa-accessibility-test-writer/references/wcag-tests.md

@@ -1,331 +0,0 @@
-# WCAG 2.2 Test Scenarios per Success Criteria
-
-Test scenarios and code examples for WCAG 2.2 success criteria. Use with qa-accessibility-test-writer when generating accessibility tests.
-
----
-
-## Principle 1: Perceivable
-
-### 1.1.1 Non-text Content (Level A)
-
-**Checkpoint:** All images have alt text; decorative images use `alt=""` or `aria-hidden`.
-
-```typescript
-// Playwright + @axe-core/playwright
-import AxeBuilder from '@axe-core/playwright';
-
-test('images have appropriate alt text', async ({ page }) => {
-  await page.goto('/gallery');
-  const results = await new AxeBuilder({ page })
-    .withTags(['wcag2a'])
-    .analyze();
-  const imageViolations = results.violations.filter(
-    v => v.id === 'image-alt' || v.ruleId === 'image-alt'
-  );
-  expect(imageViolations).toHaveLength(0);
-});
-```
-
-### 1.3.1 Info and Relationships (Level A)
-
-**Checkpoint:** Structure conveyed via markup (headings, lists, tables, form labels).
-
-```typescript
-// Cypress + cypress-axe
-it('has semantic structure', () => {
-  cy.visit('/article');
-  cy.injectAxe();
-  cy.checkA11y(null, { runOnly: { type: 'rule', values: ['landmark-one-main', 'page-has-heading-one'] } });
-});
-```
-
-### 1.4.3 Contrast (Minimum) (Level AA)
-
-**Checkpoint:** Text contrast ratio ≥ 4.5:1 (normal), 3:1 (large).
-
-```typescript
-// axe-core checks color-contrast automatically
-test('meets color contrast requirements', async ({ page }) => {
-  await page.goto('/');
-  const results = await new AxeBuilder({ page })
-    .withTags(['wcag2aa'])
-    .analyze();
-  const contrastViolations = results.violations.filter(
-    v => v.id === 'color-contrast'
-  );
-  expect(contrastViolations).toHaveLength(0);
-});
-```
-
-### 1.4.4 Resize Text (Level A)
-
-**Checkpoint:** Text can be resized to 200% without loss of content/function.
-
-```typescript
-// Playwright: simulate zoom
-test('text resizable to 200%', async ({ page }) => {
-  await page.goto('/');
-  await page.setViewportSize({ width: 1280, height: 720 });
-  await page.evaluate(() => document.body.style.zoom = '200%');
-  const main = page.locator('main');
-  await expect(main).toBeVisible();
-  const box = await main.boundingBox();
-  expect(box?.height).toBeGreaterThan(0);
-});
-```
-
-### 1.4.10 Reflow (Level AA)
-
-**Checkpoint:** Content reflows at 320px width without horizontal scroll.
-
-```typescript
-test('no horizontal scroll at 320px', async ({ page }) => {
-  await page.setViewportSize({ width: 320, height: 568 });
-  await page.goto('/');
-  const scrollWidth = await page.evaluate(() => document.documentElement.scrollWidth);
-  const clientWidth = await page.evaluate(() => document.documentElement.clientWidth);
-  expect(scrollWidth).toBeLessThanOrEqual(clientWidth + 1);
-});
-```
-
-### 1.4.13 Content on Hover or Focus (Level AA)
-
-**Checkpoint:** Dismissible, hoverable, persistent on pointer hover/focus.
-
-```typescript
-test('hover/focus content is dismissible', async ({ page }) => {
-  await page.goto('/tooltips');
-  const trigger = page.locator('[aria-haspopup="true"]').first();
-  await trigger.focus();
-  await expect(page.locator('[role="tooltip"]')).toBeVisible();
-  await page.keyboard.press('Escape');
-  await expect(page.locator('[role="tooltip"]')).toBeHidden();
-});
-```
-
----
-
-## Principle 2: Operable
-
-### 2.1.1 Keyboard (Level A)
-
-**Checkpoint:** All functionality available via keyboard.
-
-```typescript
-test('modal can be closed with Escape', async ({ page }) => {
-  await page.goto('/modal-demo');
-  await page.keyboard.press('Tab');
-  await page.keyboard.press('Enter'); // open modal
-  await expect(page.locator('[role="dialog"]')).toBeVisible();
-  await page.keyboard.press('Escape');
-  await expect(page.locator('[role="dialog"]')).toBeHidden();
-});
-```
-
-### 2.1.2 No Keyboard Trap (Level A)
-
-**Checkpoint:** Focus can be moved away from any component.
-
-```typescript
-test('no keyboard trap in modal', async ({ page }) => {
-  await page.goto('/modal-demo');
-  await page.keyboard.press('Tab');
-  await page.keyboard.press('Enter');
-  const focusable = page.locator('[role="dialog"] button, [role="dialog"] [href]');
-  const count = await focusable.count();
-  for (let i = 0; i < count + 2; i++) {
-    await page.keyboard.press('Tab');
-  }
-  const focusEl = await page.evaluate(() => document.activeElement?.tagName);
-  expect(focusEl).toBeDefined();
-});
-```
-
-### 2.4.1 Bypass Blocks (Level A)
-
-**Checkpoint:** Skip link or landmark to bypass repeated content.
-
-```typescript
-test('has skip link', async ({ page }) => {
-  await page.goto('/');
-  const skipLink = page.locator('a[href="#main"], a[href="#content"], [href^="#"]').first();
-  await expect(skipLink).toBeVisible();
-  await skipLink.click();
-  const target = await page.locator('#main, #content, [id]').first();
-  await expect(target).toBeFocused();
-});
-```
-
-### 2.4.3 Focus Order (Level A)
-
-**Checkpoint:** Tab order is logical and meaningful.
-
-```typescript
-test('focus order is logical', async ({ page }) => {
-  await page.goto('/form');
-  const order: string[] = [];
-  for (let i = 0; i < 10; i++) {
-    await page.keyboard.press('Tab');
-    const id = await page.evaluate(() => (document.activeElement as HTMLElement)?.id || '');
-    if (id) order.push(id);
-  }
-  expect(order.indexOf('submit')).toBeGreaterThan(order.indexOf('email'));
-});
-```
-
-### 2.4.7 Focus Visible (Level AA)
-
-**Checkpoint:** Keyboard focus indicator visible.
-
-```typescript
-test('focus indicator visible', async ({ page }) => {
-  await page.goto('/');
-  const link = page.locator('a').first();
-  await link.focus();
-  const outline = await link.evaluate(el => {
-    const s = getComputedStyle(el);
-    return s.outlineWidth !== '0px' || s.boxShadow !== 'none' || s.outlineStyle !== 'none';
-  });
-  expect(outline).toBeTruthy();
-});
-```
-
-### 2.5.3 Label in Name (Level A)
-
-**Checkpoint:** Accessible name includes visible label text.
-
-```typescript
-test('button accessible name matches visible text', async ({ page }) => {
-  await page.goto('/');
-  const btn = page.locator('button').first();
-  const visibleText = await btn.textContent();
-  const ariaLabel = await btn.getAttribute('aria-label');
-  const name = ariaLabel || visibleText?.trim();
-  expect(name?.length).toBeGreaterThan(0);
-});
-```
-
----
-
-## Principle 3: Understandable
-
-### 3.1.1 Language of Page (Level A)
-
-**Checkpoint:** Page has `lang` attribute.
-
-```typescript
-test('page has lang attribute', async ({ page }) => {
-  await page.goto('/');
-  const lang = await page.locator('html').getAttribute('lang');
-  expect(lang).toMatch(/^[a-z]{2}(-[A-Z]{2})?$/);
-});
-```
-
-### 3.3.1 Error Identification (Level A)
-
-**Checkpoint:** Input errors identified and described in text.
-
-```typescript
-test('form errors are announced', async ({ page }) => {
-  await page.goto('/signup');
-  await page.locator('input[type="email"]').fill('invalid');
-  await page.locator('button[type="submit"]').click();
-  const error = page.locator('[role="alert"], .error, [aria-invalid="true"]');
-  await expect(error).toBeVisible();
-  await expect(error).toContainText(/invalid|error|required/i);
-});
-```
-
-### 3.3.2 Labels or Instructions (Level A)
-
-**Checkpoint:** Labels/instructions provided for user input.
-
-```typescript
-// Cypress + cypress-axe: axe-core checks label, label-title-only, etc.
-it('form inputs have labels', () => {
-  cy.visit('/contact');
-  cy.injectAxe();
-  cy.checkA11y('form', { runOnly: { type: 'rule', values: ['label', 'input-button-name'] } });
-});
-```
-
----
-
-## Principle 4: Robust
-
-### 4.1.1 Parsing (Level A)
-
-**Checkpoint:** Markup validates; no duplicate IDs.
-
-```typescript
-test('no duplicate IDs', async ({ page }) => {
-  await page.goto('/');
-  const ids = await page.evaluate(() => {
-    const elements = document.querySelectorAll('[id]');
-    const idList = Array.from(elements).map(el => el.id);
-    return idList;
-  });
-  const unique = new Set(ids);
-  expect(unique.size).toBe(ids.length);
-});
-```
-
-### 4.1.2 Name, Role, Value (Level A)
-
-**Checkpoint:** UI components have accessible name, role, value.
-
-```typescript
-// axe-core checks aria-valid-attr, aria-required-attr, etc.
-test('components have name, role, value', async ({ page }) => {
-  await page.goto('/');
-  const results = await new AxeBuilder({ page })
-    .withTags(['wcag2a'])
-    .analyze();
-  const ariaViolations = results.violations.filter(
-    v => v.id?.includes('aria') || v.id === 'button-name'
-  );
-  expect(ariaViolations).toHaveLength(0);
-});
-```
-
-### 4.1.3 Status Messages (Level AA)
-
-**Checkpoint:** Status messages identified via role or live region.
-
-```typescript
-test('status messages use live region', async ({ page }) => {
-  await page.goto('/cart');
-  await page.locator('button:has-text("Add to cart")').click();
-  const liveRegion = page.locator('[aria-live="polite"], [aria-live="assertive"], [role="status"], [role="alert"]');
-  await expect(liveRegion).toBeVisible();
-});
-```
-
----
-
-## Full Page Audit Example
-
-```typescript
-// Playwright + @axe-core/playwright
-import { test, expect } from '@playwright/test';
-import AxeBuilder from '@axe-core/playwright';
-
-test('homepage meets WCAG 2.2 AA', async ({ page }) => {
-  await page.goto('/');
-  const results = await new AxeBuilder({ page })
-    .withTags(['wcag2a', 'wcag2aa'])
-    .analyze();
-
-  expect(results.violations).toEqual([]);
-  if (results.violations.length > 0) {
-    console.log(JSON.stringify(results.violations, null, 2));
-  }
-});
-```
-
----
-
-## References
-
-- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/)
-- [axe-core Rule Descriptions](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)

package/skills/qa-api-contract-curator/SKILL.md

@@ -1,104 +0,0 @@
----
-name: qa-api-contract-curator
-description: Manage and formalize API contracts from existing endpoints, swagger/JSON, network traffic, or developer interviews into OpenAPI specifications.
-output_dir: docs/api-contracts
----
-
-# QA API Contract Curator
-
-## Purpose
-
-Manage and formalize API contracts. Detect breaking changes, generate OpenAPI (OAS) specifications, and produce versioning rules. Transform disparate API information into a single, validated, version-controlled contract.
-
-## Input Sources
-
-| Source | Description | How to Use |
-| ------ | ----------- | ---------- |
-| **Existing endpoints** | Live API or network traffic capture | Capture requests/responses via HAR, Postman, browser DevTools; infer schema from payloads |
-| **Swagger/OpenAPI JSON/YAML** | Existing spec files | Parse, validate, normalize to OpenAPI 3.x, fill gaps |
-| **Developer interviews/descriptions** | Natural language API descriptions | Extract endpoints, methods, parameters, responses; formalize into OAS |
-| **Codebase analysis** | Express routes, FastAPI endpoints, Spring controllers, etc. | Scan route definitions, decorators, DTOs; derive contract from implementation |
-
-## Workflow
-
-1. **Collect endpoint data** — Gather from one or more input sources; merge and deduplicate.
-2. **Normalize into OpenAPI 3.x** — Convert all data into a single OpenAPI 3.x specification (YAML preferred).
-3. **Validate schema completeness** — Ensure paths, schemas, parameters, and responses are documented; flag gaps.
-4. **Detect breaking changes** — Compare against previous version (if available); produce breaking change report.
-5. **Generate request/response examples** — Add realistic examples for each operation.
-
-## Output
-
-- **OpenAPI 3.x specification** (YAML) — Single source of truth for the API contract
-- **Request/response examples** — Per-operation examples for documentation and testing
-- **Versioning rules** — Semantic versioning guidance, deprecation notes
-- **Breaking change report** — When comparing versions: list of breaking changes with severity and migration notes
-
-## Breaking Change Detection
-
-| Change Type | Description | Severity |
-| ----------- | ----------- | -------- |
-| **Removed endpoints** | Path or method no longer exists | Breaking |
-| **Changed response schemas** | Added/removed fields, type changes | Breaking or additive |
-| **Modified required fields** | New required field in request/response | Breaking |
-| **Authentication changes** | New auth requirement, changed scheme | Breaking |
-| **Parameter changes** | Removed/renamed path/query/header params | Breaking |
-| **Status code changes** | Success/error codes removed or redefined | Breaking |
-| **Additive changes** | New optional fields, new endpoints | Non-breaking |
-
-See `references/breaking-changes.md` for catalog and mitigation strategies.
-
-## Feeds Into
-
-- **qa-supertest-writer** — TypeScript/Node API tests from contract
-- **qa-httpx-writer** — Python API tests from contract
-- **qa-pact-writer** — Consumer-driven contract tests from OAS
-
-## Scope
-
-**Can do (autonomous):**
-- Generate OpenAPI 3.x from any supported input source
-- Merge multiple sources into one spec
-- Validate schema completeness and flag gaps
-- Detect breaking changes vs previous version
-- Generate request/response examples
-- Document authentication schemes
-- Define versioning strategy
-
-**Cannot do (requires confirmation):**
-- Modify production API implementation
-- Change business logic or endpoint behavior
-- Override stakeholder decisions on versioning
-
-**Will not do (out of scope):**
-- Implement API endpoints
-- Deploy or modify live services
-- Make business decisions about API design
-
-## Quality Checklist
-
-Before delivering an OpenAPI specification:
-
-- [ ] All endpoints are documented (paths, methods, parameters)
-- [ ] Request/response examples provided for each operation
-- [ ] Error responses defined (4xx, 5xx) where applicable
-- [ ] Authentication documented (security schemes, scopes)
-- [ ] Versioning strategy defined (info.version, deprecation notes)
-- [ ] Schemas are complete (no `{}` or placeholder types)
-- [ ] Breaking change report included when comparing versions
-
-## Troubleshooting
-
-| Symptom | Likely Cause | Fix |
-| ------- | ------------ | --- |
-| Missing request/response schemas | Source has no examples | Infer from code DTOs, add placeholder schemas, ask for samples |
-| Duplicate paths from multiple sources | Same API documented in different formats | Merge by path+method, reconcile differences, prefer most complete |
-| Breaking changes false positives | Optional vs required misinterpreted | Verify `required` arrays; additive optional changes are non-breaking |
-| Auth not documented | Source lacks auth info | Check codebase for middleware, add `security` at spec or operation level |
-| Invalid OpenAPI output | Schema syntax errors | Validate with `openapi-generator validate` or Swagger Editor |
-| Incomplete codebase extraction | Framework not recognized | Add framework-specific patterns to extraction logic; fall back to manual |
-
-## References
-
-- `references/openapi-structure.md` — OpenAPI 3.x specification structure with examples
-- `references/breaking-changes.md` — Catalog of breaking changes and mitigation strategies