@jetrabbits/agentic 0.0.1

package/areas/software/qa/skills/accessibility-testing/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: accessibility-testing
+type: skill
+description: Run automated WCAG audits, manual keyboard/screen reader testing, and CI a11y gates.
+related-rules:
+  - test-strategy.md
+  - quality-gates.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Accessibility Testing Skill
+
+> **Expertise:** axe-core automation, WCAG 2.1 AA, keyboard testing, screen reader testing (NVDA/VoiceOver), CI gates.
+
+## Automated Testing (Playwright + axe-core)
+
+```typescript
+// tests/a11y/checkout.a11y.spec.ts
+import AxeBuilder from '@axe-core/playwright';
+
+test.describe('Checkout a11y', () => {
+  test('step 1 address form has no WCAG AA violations', async ({ page }) => {
+    await page.goto('/checkout/address');
+    await page.waitForLoadState('networkidle');  // Wait for dynamic content
+
+    const results = await new AxeBuilder({ page })
+      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
+      .exclude('#third-party-widget')  // Exclude known third-party violations
+      .analyze();
+
+    // Report violations with full context for easier debugging
+    if (results.violations.length > 0) {
+      const report = results.violations.map(v => ({
+        id: v.id,
+        impact: v.impact,
+        description: v.description,
+        elements: v.nodes.map(n => n.html).slice(0, 3),
+      }));
+      console.log(JSON.stringify(report, null, 2));
+    }
+
+    // Block on critical/serious only; log moderate/minor as warnings
+    const blocking = results.violations.filter(
+      v => v.impact === 'critical' || v.impact === 'serious'
+    );
+    expect(blocking).toHaveLength(0);
+  });
+
+  test('form inputs all have associated labels', async ({ page }) => {
+    await page.goto('/checkout/address');
+    const results = await new AxeBuilder({ page })
+      .withRules(['label', 'label-content-name-mismatch'])
+      .analyze();
+    expect(results.violations).toHaveLength(0);
+  });
+});
+```
+
+## Keyboard Navigation Checklist (Manual)
+
+Run this checklist on every new feature with interactive elements:
+
+```
+Tab order:
+[ ] Tab key moves focus through all interactive elements in visual order
+[ ] Focus never gets trapped (except modals — see below)
+[ ] Focus is always visible (never hidden by CSS outline: none)
+
+Activation:
+[ ] Buttons activate with Enter and Space
+[ ] Links activate with Enter only
+[ ] Select/dropdown navigates with Arrow keys
+
+Modal dialogs:
+[ ] Focus moves to modal when it opens
+[ ] Tab is trapped inside modal while open
+[ ] Escape key closes modal
+[ ] Focus returns to the trigger element when modal closes
+
+Forms:
+[ ] Each input has a visible label (not just placeholder)
+[ ] Error messages are associated with their input (aria-describedby)
+[ ] Required fields marked with aria-required="true"
+[ ] Submit activates with Enter from any field
+```
+
+## Screen Reader Testing (Quick Reference)
+
+### VoiceOver (macOS/iOS)
+```
+Enable:  Cmd + F5
+Navigate: VO + Right (next element), VO + Left (previous)
+Forms:   VO + Shift + Down (enter form mode)
+Tables:  VO + Shift + Right/Left (navigate columns)
+```
+
+### NVDA (Windows — free)
+```
+Download: nvaccess.org/download
+Navigate: Tab (interactive), H (headings), F (forms), L (lists)
+Test:     Browse mode (default) vs. Forms mode (Enter to switch)
+```
+
+### Things to verify with screen reader:
+- [ ] Page title is descriptive and unique
+- [ ] Headings form a logical hierarchy (h1 → h2 → h3)
+- [ ] Images have meaningful alt text (or alt="" for decorative)
+- [ ] Error messages read aloud when form submitted with errors
+- [ ] Dynamic content changes (toast notifications) announced via `aria-live`
+- [ ] Form field labels and error messages read together
+
+## CI Integration
+
+```yaml
+# .github/workflows/a11y.yml
+a11y:
+  steps:
+    - name: Run accessibility audit
+      run: npx playwright test tests/a11y/ --reporter=html
+    - name: Upload report
+      uses: actions/upload-artifact@v4
+      with:
+        name: a11y-report
+        path: playwright-report/
+```
+
+## WCAG 2.1 AA Quick Reference
+
+| Criterion | Level | What it means |
+|---|---|---|
+| 1.1.1 Non-text content | A | Images need alt text |
+| 1.3.1 Info & Relationships | A | Structure conveyed programmatically |
+| 1.4.3 Contrast (Minimum) | AA | 4.5:1 normal text, 3:1 large text |
+| 2.1.1 Keyboard | A | All functionality keyboard accessible |
+| 2.4.3 Focus Order | A | Focus order preserves meaning |
+| 2.4.7 Focus Visible | AA | Keyboard focus always visible |
+| 3.3.1 Error Identification | A | Errors described in text |
+| 3.3.2 Labels or Instructions | A | Form inputs have labels |
+| 4.1.2 Name, Role, Value | A | UI components have accessible names |

package/areas/software/qa/skills/api-testing/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: api-testing
+type: skill
+description: Write API integration tests and consumer-driven contract tests (Pact) for service boundaries.
+related-rules:
+  - test-strategy.md
+  - test-data.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# API Testing Patterns Skill
+
+> **Expertise:** API integration tests (supertest/httpx), contract testing (Pact), auth flows, error path coverage.
+
+## Integration Test Structure (FastAPI/httpx)
+
+```python
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+
+# conftest.py — reusable fixtures
+@pytest_asyncio.fixture
+async def client(app, db_session) -> AsyncClient:
+    async with AsyncClient(app=app, base_url="http://test") as c:
+        yield c
+
+@pytest_asyncio.fixture
+async def auth_client(client, create_user) -> AsyncClient:
+    user = await create_user(role="viewer")
+    response = await client.post("/auth/token",
+        data={"username": user.email, "password": "test_password"})
+    token = response.json()["access_token"]
+    client.headers["Authorization"] = f"Bearer {token}"
+    return client
+
+# Test — covers happy path + all error cases
+class TestCreateOrder:
+    async def test_creates_order_for_authenticated_user(self, auth_client, product_factory):
+        product = await product_factory(price="29.99", stock=10)
+
+        response = await auth_client.post("/api/v1/orders", json={
+            "items": [{"product_id": product.id, "quantity": 2}]
+        })
+
+        assert response.status_code == 201
+        body = response.json()
+        assert body["status"] == "pending"
+        assert body["total_amount"] == "59.98"
+        assert body["id"].startswith("ord_")
+
+    async def test_returns_401_without_auth(self, client):
+        response = await client.post("/api/v1/orders", json={"items": []})
+        assert response.status_code == 401
+
+    async def test_returns_400_when_product_out_of_stock(self, auth_client, product_factory):
+        product = await product_factory(stock=0)
+        response = await auth_client.post("/api/v1/orders", json={
+            "items": [{"product_id": product.id, "quantity": 1}]
+        })
+        assert response.status_code == 400
+        assert response.json()["error"]["code"] == "PRODUCT_OUT_OF_STOCK"
+
+    async def test_returns_404_for_nonexistent_product(self, auth_client):
+        response = await auth_client.post("/api/v1/orders", json={
+            "items": [{"product_id": "prod_nonexistent", "quantity": 1}]
+        })
+        assert response.status_code == 404
+```
+
+## Error Coverage Checklist (Per Endpoint)
+
+Every endpoint must have tests for:
+- [ ] 200/201 happy path with valid input
+- [ ] 401 — missing or invalid auth token
+- [ ] 403 — authenticated but not authorized (wrong role or not owner)
+- [ ] 404 — resource not found
+- [ ] 400/422 — validation errors (missing required field, wrong type, out of range)
+- [ ] 409 — conflict (duplicate, wrong state transition)
+- [ ] Idempotency (if applicable) — same request twice returns same result
+
+## Contract Testing (Pact)
+
+Use when: two services are developed by different teams and must agree on API shape.
+
+```python
+# consumer side (frontend/service-b defines expectations)
+from pact import Consumer, Provider
+
+pact = Consumer("order-consumer").has_pact_with(Provider("order-service"))
+
+def test_get_order_contract():
+    expected = {
+        "id": "ord_123",
+        "status": "pending",
+        "total_amount": Term(r"^\d+\.\d{2}$", "59.98"),
+    }
+
+    (pact
+        .given("order ord_123 exists")
+        .upon_receiving("a request to get order ord_123")
+        .with_request("GET", "/api/v1/orders/ord_123")
+        .will_respond_with(200, body=Like(expected)))
+
+    with pact:
+        response = order_api_client.get_order("ord_123")
+        assert response["status"] == "pending"
+    # Pact saves contract to pacts/ directory
+
+# Provider side verifies against saved pact file
+# Run in CI after consumer tests generate pact files
+```
+
+## Pagination Testing Pattern
+
+```python
+async def test_list_orders_pagination(auth_client, order_factory):
+    # Create 25 orders for cursor-based pagination test
+    orders = [await order_factory(user_id=current_user.id) for _ in range(25)]
+
+    # First page
+    response = await auth_client.get("/api/v1/orders?limit=10")
+    assert response.status_code == 200
+    body = response.json()
+    assert len(body["items"]) == 10
+    assert body["next_cursor"] is not None
+
+    # Second page using cursor
+    response2 = await auth_client.get(f"/api/v1/orders?limit=10&cursor={body['next_cursor']}")
+    assert len(response2.json()["items"]) == 10
+    # Items should not overlap with first page
+    first_ids = {o["id"] for o in body["items"]}
+    second_ids = {o["id"] for o in response2.json()["items"]}
+    assert first_ids.isdisjoint(second_ids)
+
+    # Last page — fewer items, no next cursor
+    response3 = await auth_client.get(f"/api/v1/orders?limit=10&cursor={response2.json()['next_cursor']}")
+    assert len(response3.json()["items"]) == 5
+    assert response3.json()["next_cursor"] is None
+```

package/areas/software/qa/skills/e2e-patterns/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: e2e-patterns
+type: skill
+description: Write robust E2E tests with Playwright — page objects, resilient waiting, auth, and CI integration.
+related-rules:
+  - test-strategy.md
+  - flakiness-policy.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# E2E Testing Patterns (Playwright) Skill
+
+> **Expertise:** Playwright page objects, resilient locators, auth fixtures, parallel execution, CI configuration.
+
+## Page Object Model
+
+```typescript
+// pages/OrderPage.ts
+export class OrderPage {
+  readonly page: Page;
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  // ✅ Role-based locators — resilient to CSS changes + tests a11y
+  get orderItems() { return this.page.getByRole('listitem', { name: /order item/i }); }
+  get submitButton() { return this.page.getByRole('button', { name: 'Place order' }); }
+  get confirmationMessage() { return this.page.getByText('Order confirmed'); }
+
+  async addItem(productName: string, quantity: number) {
+    await this.page.getByLabel('Product').selectOption(productName);
+    await this.page.getByLabel('Quantity').fill(String(quantity));
+    await this.page.getByRole('button', { name: 'Add to cart' }).click();
+  }
+
+  async checkout(address: Address) {
+    await this.page.getByLabel('Street').fill(address.street);
+    await this.page.getByLabel('City').fill(address.city);
+    await this.submitButton.click();
+    await expect(this.confirmationMessage).toBeVisible({ timeout: 10000 });
+  }
+}
+```
+
+## Resilient Waiting — Never Use `sleep`
+
+```typescript
+// ❌ Arbitrary sleep — flaky and slow
+await page.waitForTimeout(2000);
+
+// ✅ Wait for specific condition
+await page.waitForURL('**/dashboard');
+await expect(page.getByText('Welcome back')).toBeVisible();
+
+// ✅ Wait for network request to complete
+await Promise.all([
+  page.waitForResponse(resp => resp.url().includes('/api/orders') && resp.status() === 201),
+  page.getByRole('button', { name: 'Place order' }).click(),
+]);
+
+// ✅ Wait for element to reach a specific state
+await expect(page.getByRole('status')).toHaveText('Processing...', { timeout: 5000 });
+await expect(page.getByRole('status')).toHaveText('Complete', { timeout: 30000 });
+```
+
+## Authentication Fixture (Reuse Across Tests)
+
+```typescript
+// fixtures/auth.ts — store session state, avoid re-logging in per test
+import { test as base } from '@playwright/test';
+
+export const test = base.extend<{ authenticatedPage: Page }>({
+  authenticatedPage: async ({ browser }, use) => {
+    // Load stored auth state (set up once with `playwright auth`)
+    const context = await browser.newContext({
+      storageState: 'tests/.auth/user.json',
+    });
+    const page = await context.newPage();
+    await use(page);
+    await context.close();
+  },
+});
+
+// Set up auth state (run once before test suite)
+// playwright.config.ts globalSetup points to this
+export async function setupAuth() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
+  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await page.waitForURL('**/dashboard');
+  await page.context().storageState({ path: 'tests/.auth/user.json' });
+  await browser.close();
+}
+```
+
+## Playwright Config (CI-Ready)
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,   // Retry on CI only
+  workers: process.env.CI ? 4 : 2,
+  timeout: 30000,
+
+  reporter: [
+    ['html', { outputFolder: 'test-results/html' }],
+    ['junit', { outputFile: 'test-results/junit.xml' }],  // For CI parsing
+  ],
+
+  use: {
+    baseURL: process.env.E2E_BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',      // Capture trace on failure
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+
+  projects: [
+    { name: 'setup', testMatch: /global.setup.ts/ },
+    {
+      name: 'chromium',
+      dependencies: ['setup'],
+      use: { ...devices['Desktop Chrome'], storageState: 'tests/.auth/user.json' },
+    },
+  ],
+});
+```
+
+## Flakiness Prevention Checklist
+
+- [ ] No `waitForTimeout` — all waits target specific conditions
+- [ ] Test data created fresh per test (factory functions, not shared fixtures)
+- [ ] Tests don't depend on order (can run in any sequence)
+- [ ] Network requests mocked when testing UI-only behavior
+- [ ] Assertions use `toBeVisible()` not `isVisible()` — auto-waits
+- [ ] `retries: 2` in CI config catches transient infrastructure failures (not logic bugs)
+
+## Locator Priority (Most to Least Resilient)
+
+```
+1. getByRole()         — semantic, tests a11y
+2. getByLabel()        — form elements
+3. getByText()         — visible text
+4. getByTestId()       — data-testid attribute (explicit contract)
+5. locator('css')      — fragile, avoid
+6. locator('xpath')    — most fragile, never use
+```

package/areas/software/qa/skills/performance-testing/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: performance-testing
+type: skill
+description: Design and execute load/stress tests with k6, establish SLO baselines, and identify bottlenecks.
+related-rules:
+  - quality-gates.md
+  - test-strategy.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Performance Testing Skill (k6)
+
+> **Expertise:** k6 load/stress/soak tests, SLO baselines, threshold gates, bottleneck identification, CI integration.
+
+## Test Type Selection
+
+```
+Load test    → Validate behavior at expected production traffic (steady state)
+Stress test  → Find breaking point; gradually increase load until failure
+Soak test    → Detect memory leaks / degradation over time (run 1-8 hours)
+Spike test   → Simulate sudden traffic burst (10x normal in seconds)
+```
+
+## k6 Load Test Template
+
+```javascript
+// tests/performance/create-order.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Trend, Counter } from 'k6/metrics';
+
+const orderCreationDuration = new Trend('order_creation_duration');
+const failedOrders = new Counter('failed_orders');
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 50 },   // Ramp up
+    { duration: '5m', target: 50 },   // Steady state
+    { duration: '2m', target: 200 },  // Stress
+    { duration: '2m', target: 0 },    // Ramp down
+  ],
+  thresholds: {
+    // These are your SLO gates — CI fails if breached
+    http_req_duration: ['p(95)<500', 'p(99)<2000'],
+    http_req_failed: ['rate<0.01'],       // < 1% errors
+    order_creation_duration: ['p(99)<3000'],
+  },
+};
+
+const BASE_URL = __ENV.BASE_URL || 'http://localhost:8000';
+
+export function setup() {
+  // Create test auth token once before load test
+  const res = http.post(`${BASE_URL}/auth/token`, JSON.stringify({
+    username: 'loadtest@example.com', password: __ENV.TEST_PASSWORD,
+  }), { headers: { 'Content-Type': 'application/json' } });
+  return { token: res.json('access_token') };
+}
+
+export default function (data) {
+  const headers = {
+    'Authorization': `Bearer ${data.token}`,
+    'Content-Type': 'application/json',
+  };
+
+  const start = Date.now();
+  const res = http.post(
+    `${BASE_URL}/api/v1/orders`,
+    JSON.stringify({ items: [{ product_id: 'prod_123', quantity: 1 }] }),
+    { headers },
+  );
+
+  orderCreationDuration.add(Date.now() - start);
+
+  const ok = check(res, {
+    'status is 201': (r) => r.status === 201,
+    'has order id': (r) => r.json('id') !== undefined,
+  });
+
+  if (!ok) failedOrders.add(1);
+
+  sleep(1);  // Think time between requests
+}
+```
+
+## SLO Baseline Process
+
+```bash
+# 1. Run baseline on known-good release
+k6 run --env BASE_URL=https://staging.myapp.com tests/performance/create-order.k6.js \
+  --out json=results/baseline-$(date +%Y%m%d).json
+
+# 2. Extract key metrics
+k6 stats results/baseline-$(date +%Y%m%d).json | jq '{
+  p50: .metrics.http_req_duration.values["p(50)"],
+  p95: .metrics.http_req_duration.values["p(95)"],
+  p99: .metrics.http_req_duration.values["p(99)"],
+  error_rate: .metrics.http_req_failed.values.rate
+}'
+
+# 3. Store in performance-baselines.json
+# 4. On each release candidate: compare vs. baseline
+#    - p99 regression > 20% → block deploy
+#    - p99 regression 10–20% → warning + required justification
+```
+
+## CI Integration (GitHub Actions)
+
+```yaml
+# .github/workflows/perf.yml
+performance:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - name: Run k6 load test
+      uses: grafana/k6-action@v0.3.1
+      with:
+        filename: tests/performance/create-order.k6.js
+      env:
+        BASE_URL: ${{ secrets.STAGING_URL }}
+        TEST_PASSWORD: ${{ secrets.LOADTEST_PASSWORD }}
+    - name: Upload results
+      uses: actions/upload-artifact@v4
+      with:
+        name: k6-results
+        path: results/
+```
+
+## Bottleneck Identification
+
+After a test run showing latency regression, investigate in this order:
+
+```bash
+# 1. Check application metrics during test
+# → CPU saturation? (> 80% sustained) → vertical scale or optimize hot path
+# → Memory growing? → potential leak
+# → Goroutines / threads spiking? → connection pool or lock contention
+
+# 2. Check DB during load test
+SELECT query, calls, mean_exec_time
+FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 5;
+-- High mean_exec_time on a simple query → missing index
+
+# 3. Check connection pool
+SELECT count(*), state FROM pg_stat_activity GROUP BY state;
+-- Many 'idle in transaction' → long transactions not being released
+-- Many 'waiting' → pool too small; increase max_connections or pool size
+
+# 4. Check for lock contention
+SELECT pid, wait_event_type, wait_event, query
+FROM pg_stat_activity WHERE wait_event IS NOT NULL;
+```
+
+## Performance Report Template
+
+```markdown
+## Performance Test Report — [Date] — [Endpoint/Flow]
+
+### Configuration
+- Tool: k6 | Duration: 10 min | Peak VUs: 200
+- Target: POST /api/v1/orders | Environment: staging
+
+### Results vs. SLO
+
+| Metric | Baseline | This run | SLO | Status |
+|--------|----------|----------|-----|--------|
+| p50 latency | 45ms | 52ms | < 200ms | ✅ |
+| p95 latency | 120ms | 310ms | < 500ms | ✅ |
+| p99 latency | 280ms | 890ms | < 2000ms | ⚠️ +218% |
+| Error rate | 0.02% | 0.08% | < 1% | ✅ |
+
+### Root cause of p99 regression
+N+1 query in OrderRepository.list_items() — loading items one by one inside a loop.
+
+### Remediation
+Add joinedload() to the query. Estimated p99 improvement: ~400ms.
+```