aigent-team 0.1.0

package/templates/teams/qa/references/performance-testing.md

@@ -0,0 +1,288 @@
+# Performance Testing Reference
+
+## Load Scenario Types
+
+| Scenario | Purpose | VUs | Duration | When to run |
+|---|---|---|---|---|
+| **Smoke** | Verify script works, baseline response | 1-5 | 1 min | Every PR (fast gate) |
+| **Load** | Validate SLOs under expected traffic | Target VUs | 10-30 min | Nightly / pre-release |
+| **Stress** | Find breaking point | Ramp beyond target | 15-30 min | Weekly / pre-release |
+| **Soak** | Detect memory leaks, connection exhaustion | Target VUs | 2-8 hours | Weekly (off-hours) |
+| **Spike** | Verify recovery from sudden traffic burst | 0 → peak → 0 | 5-10 min | Pre-release |
+
+---
+
+## k6 Script Examples
+
+### Basic Load Test
+
+```javascript
+// tests/performance/load-api.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+const errorRate = new Rate('errors');
+const orderLatency = new Trend('order_latency');
+
+export const options = {
+  scenarios: {
+    load: {
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '2m', target: 50 },   // ramp up
+        { duration: '5m', target: 50 },   // steady state
+        { duration: '2m', target: 0 },    // ramp down
+      ],
+    },
+  },
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1500'],
+    errors: ['rate<0.01'],
+    order_latency: ['p(95)<800'],
+  },
+};
+
+const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000';
+
+export default function () {
+  // GET — list products
+  const listRes = http.get(`${BASE_URL}/api/products`);
+  check(listRes, {
+    'list status 200': (r) => r.status === 200,
+    'list has items': (r) => JSON.parse(r.body).length > 0,
+  }) || errorRate.add(1);
+
+  sleep(1); // think time between actions
+
+  // POST — create order
+  const payload = JSON.stringify({
+    items: [{ sku: 'WIDGET-1', quantity: 1 }],
+  });
+  const orderRes = http.post(`${BASE_URL}/api/orders`, payload, {
+    headers: { 'Content-Type': 'application/json' },
+  });
+  orderLatency.add(orderRes.timings.duration);
+  check(orderRes, {
+    'order status 201': (r) => r.status === 201,
+  }) || errorRate.add(1);
+
+  sleep(2);
+}
+```
+
+### Smoke Test (CI-friendly)
+
+```javascript
+// tests/performance/smoke-api.js
+import http from 'k6/http';
+import { check } from 'k6';
+
+export const options = {
+  vus: 1,
+  duration: '30s',
+  thresholds: {
+    http_req_duration: ['p(95)<300'],
+    http_req_failed: ['rate<0.01'],
+  },
+};
+
+export default function () {
+  const res = http.get(`${__ENV.BASE_URL}/api/health`);
+  check(res, {
+    'status 200': (r) => r.status === 200,
+  });
+}
+```
+
+### Stress Test
+
+```javascript
+// tests/performance/stress-api.js
+export const options = {
+  scenarios: {
+    stress: {
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '2m', target: 50 },
+        { duration: '3m', target: 100 },
+        { duration: '3m', target: 200 },   // beyond expected capacity
+        { duration: '3m', target: 400 },   // find the breaking point
+        { duration: '2m', target: 0 },
+      ],
+    },
+  },
+  thresholds: {
+    http_req_duration: ['p(95)<2000'],  // relaxed for stress
+    http_req_failed: ['rate<0.05'],     // 5% error rate acceptable
+  },
+};
+```
+
+### Spike Test
+
+```javascript
+export const options = {
+  scenarios: {
+    spike: {
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '1m', target: 10 },   // baseline
+        { duration: '10s', target: 500 },  // spike
+        { duration: '2m', target: 500 },   // hold spike
+        { duration: '10s', target: 10 },   // drop back
+        { duration: '2m', target: 10 },    // recovery
+      ],
+    },
+  },
+};
+```
+
+---
+
+## Artillery Script Example
+
+```yaml
+# tests/performance/load.yml
+config:
+  target: "http://localhost:3000"
+  phases:
+    - duration: 120
+      arrivalRate: 10
+      name: "Warm up"
+    - duration: 300
+      arrivalRate: 50
+      name: "Sustained load"
+  ensure:
+    p95: 500
+    maxErrorRate: 1
+
+scenarios:
+  - name: "Browse and order"
+    flow:
+      - get:
+          url: "/api/products"
+          capture:
+            - json: "$[0].id"
+              as: "productId"
+      - think: 2
+      - post:
+          url: "/api/orders"
+          json:
+            items:
+              - productId: "{{ productId }}"
+                quantity: 1
+          expect:
+            - statusCode: 201
+```
+
+---
+
+## Threshold Definitions
+
+Thresholds must be derived from SLOs, not arbitrary numbers.
+
+### Mapping SLOs to Thresholds
+
+| SLO | k6 Threshold |
+|---|---|
+| 99.9 % availability | `http_req_failed: ['rate<0.001']` |
+| p95 latency < 500 ms | `http_req_duration: ['p(95)<500']` |
+| p99 latency < 1500 ms | `http_req_duration: ['p(99)<1500']` |
+| Zero errors on critical path | Custom metric with `rate<0.0` |
+
+### Custom Thresholds
+
+```javascript
+export const options = {
+  thresholds: {
+    // Built-in metrics
+    http_req_duration: ['p(95)<500', 'p(99)<1500'],
+    http_req_failed: ['rate<0.01'],
+
+    // Custom metrics (tagged)
+    'http_req_duration{name:createOrder}': ['p(95)<800'],
+    'http_req_duration{name:listProducts}': ['p(95)<200'],
+
+    // Custom counters
+    errors: ['rate<0.01'],
+  },
+};
+```
+
+### Tagging Requests
+
+```javascript
+http.post(`${BASE_URL}/api/orders`, payload, {
+  tags: { name: 'createOrder' },
+});
+```
+
+---
+
+## Production-Like Environment Requirement
+
+Performance tests are meaningless unless the environment matches production:
+
+### Checklist
+
+- [ ] Same instance types / resource limits (CPU, memory)
+- [ ] Same database engine, version, and dataset size (or representative subset)
+- [ ] Same network topology (load balancer, CDN excluded or simulated)
+- [ ] Same connection pool sizes and timeouts
+- [ ] Same external service latencies (mock with realistic delays)
+- [ ] Same application configuration (caching, rate limits, feature flags)
+
+### Data Volume
+
+- Load a representative dataset before running tests.
+- For a 10M-row production table, use at least 1M rows in perf test DB.
+- Index behaviour changes with data volume — small datasets hide slow queries.
+
+### Isolation
+
+- Never run performance tests against production.
+- Never share the perf environment with other test suites during a run.
+- Reset environment state between runs for reproducibility.
+
+---
+
+## Baseline Tracking
+
+### Why Track Baselines?
+
+A single performance test run is a snapshot. Trends tell the real story.
+Track baselines to detect gradual degradation.
+
+### Process
+
+1. **Establish baseline**: Run load test 3 times on a known-good build.
+   Average the results.
+2. **Store results**: Push metrics to a time-series database (InfluxDB,
+   Prometheus) or flat JSON files in the repo.
+3. **Compare on PR**: Run smoke perf test, compare against baseline.
+   Fail if p95 regresses by > 20 %.
+4. **Update baseline**: After each release, re-run and update.
+
+### k6 Output to JSON
+
+```bash
+k6 run --out json=results.json tests/performance/load-api.js
+```
+
+### k6 Output to InfluxDB
+
+```bash
+k6 run --out influxdb=http://influxdb:8086/k6 tests/performance/load-api.js
+```
+
+### Grafana Dashboard
+
+Pair InfluxDB with Grafana for visual trend tracking. Key panels:
+- p50 / p95 / p99 latency over time
+- Error rate over time
+- VUs vs response time (to spot saturation)
+- Throughput (req/s) over time

package/templates/teams/qa/references/review-checklist.md

@@ -0,0 +1,143 @@
+# Test Code Review Checklist
+
+Use this checklist when reviewing any PR that adds or modifies test code.
+Not every section applies to every PR — skip sections that are not relevant.
+
+---
+
+## 1. Test Level Selection
+
+- [ ] Test is at the lowest level that can catch the bug
+- [ ] Unit tests do not involve I/O (network, file system, database)
+- [ ] Integration tests are justified — they test module collaboration, not
+      logic that a unit test could cover
+- [ ] E2E tests protect critical user journeys only — not redundant with
+      integration tests
+- [ ] Contract tests exist for cross-service API calls
+- [ ] Comment explains why E2E was chosen over integration (if applicable)
+
+---
+
+## 2. Test Quality
+
+- [ ] Test name describes behaviour, not implementation
+      (`"calculates tax for multi-state order"`, not `"test calculateTax"`)
+- [ ] Each test has a single clear assertion focus (one reason to fail)
+- [ ] Tests are independent — no shared mutable state between tests
+- [ ] No test ordering dependency (would pass with randomised order)
+- [ ] Arrange-Act-Assert structure is clear
+- [ ] No logic in tests (no `if`, no loops, no try/catch) — use
+      `test.each` for parameterised cases
+- [ ] No `console.log` or debugging artefacts left in
+- [ ] Test fails for the right reason when the feature is broken
+      (verify by mentally removing the feature code)
+
+---
+
+## 3. Test Data
+
+- [ ] Uses factories for object creation (not inline literals)
+- [ ] Only overrides fields relevant to the test (sensible defaults for rest)
+- [ ] No hardcoded IDs that could collide across tests
+- [ ] Faker seed is set if deterministic reproduction is needed
+- [ ] Database state is isolated (transaction rollback, truncate, or unique IDs)
+- [ ] No test data leaked between tests (check `beforeEach` / `afterEach`)
+
+---
+
+## 4. Mocking
+
+- [ ] Mocks are at system boundaries only (HTTP, clock, random)
+- [ ] No internal modules are mocked — use real implementations
+- [ ] MSW handlers use `onUnhandledRequest: 'error'`
+- [ ] Per-test overrides use `server.use()` and are reset in `afterEach`
+- [ ] Mock responses are realistic (match actual API shape)
+- [ ] Mock contracts are verified against real API (schema validation or
+      contract test exists)
+- [ ] `vi.restoreAllMocks()` runs in global `afterEach`
+
+---
+
+## 5. E2E Tests
+
+- [ ] Uses Page Object Model (no raw selectors in test files)
+- [ ] Element selection follows priority: `getByRole` > `getByLabel` >
+      `getByTestId`
+- [ ] No `waitForTimeout` / `sleep` — uses explicit waits
+- [ ] Test data seeded via API, not through UI interactions
+- [ ] Test is parallelisation-safe (no shared global state)
+- [ ] Viewport is fixed in config (no layout-dependent flakiness)
+- [ ] Animations disabled in test config
+- [ ] Screenshots and traces captured on failure
+- [ ] Test passes with `--repeat-each=5` locally
+
+---
+
+## 6. Assertions
+
+- [ ] Assertions are specific (not just `toBeTruthy` or `toMatchSnapshot`)
+- [ ] Error cases are tested, not just happy path
+- [ ] Boundary values are tested where applicable
+- [ ] Negative assertions are used correctly (`not.toContain` vs missing check)
+- [ ] Async assertions use proper `await` / `resolves` / `rejects`
+- [ ] No snapshot tests for logic (snapshots only for serialised output
+      like HTML or JSON schema)
+
+---
+
+## 7. Flakiness Risk
+
+- [ ] No time-dependent logic without clock mocking
+- [ ] No reliance on execution speed (no "this runs fast enough")
+- [ ] No reliance on random values without seeding
+- [ ] No reliance on network availability (all external calls mocked)
+- [ ] No reliance on file system state (uses temp dirs or mocks)
+- [ ] Database queries do not assume row ordering without `ORDER BY`
+
+---
+
+## 8. Performance
+
+- [ ] Unit tests do not perform I/O (should complete in < 50 ms each)
+- [ ] Integration test setup is batched (not N+1 inserts)
+- [ ] E2E tests do not duplicate coverage available at lower levels
+- [ ] No excessive `beforeEach` setup that could be `beforeAll`
+      (only when safe — consider isolation)
+- [ ] Test suite stays within time budget (unit < 10 s, integration < 2 min,
+      E2E smoke < 10 min)
+
+---
+
+## 9. CI Integration
+
+- [ ] Test runs in CI (not just locally)
+- [ ] Test is in the correct pipeline stage (unit/integration/E2E)
+- [ ] Test outputs JUnit XML or other parseable format
+- [ ] Failure produces useful output (assertion messages, screenshots, traces)
+- [ ] No CI-specific environment assumptions without fallback
+      (`process.env.CI` checks are guarded)
+
+---
+
+## 10. Coverage
+
+- [ ] New code has tests (not just modified code)
+- [ ] Tests cover happy path, error path, and edge cases
+- [ ] If coverage decreased, there is a justification
+- [ ] No tests written solely to increase coverage percentage
+      (every test must catch a real bug class)
+
+---
+
+## Quick Reject Criteria
+
+Flag the PR immediately if any of these are present:
+
+- `sleep()` or `waitForTimeout()` in E2E tests
+- Mocking internal modules
+- Shared mutable state between tests
+- `test.skip` or `test.todo` without a linked issue
+- Snapshot tests for business logic
+- Hardcoded test data that will collide in parallel runs
+- No assertions in a test (or only `toMatchSnapshot`)
+- `console.log` left in test code

package/templates/teams/qa/references/security-testing.md

@@ -0,0 +1,271 @@
+# Security Testing Reference
+
+## OWASP Top 10 — Test Coverage
+
+### SQL Injection
+
+Test every user-controlled input that reaches a database query.
+
+```typescript
+const sqlInjectionPayloads = [
+  "'; DROP TABLE users; --",
+  "1' OR '1'='1",
+  "1; SELECT * FROM users",
+  "' UNION SELECT username, password FROM users --",
+  "1' AND SLEEP(5) --",
+];
+
+test.each(sqlInjectionPayloads)('rejects SQL injection: %s', async (payload) => {
+  const res = await request(app)
+    .get('/api/users')
+    .query({ search: payload });
+
+  // Should NOT return 500 (indicates unhandled query error)
+  expect(res.status).not.toBe(500);
+  // Should NOT return other users' data
+  expect(res.body).not.toContainEqual(
+    expect.objectContaining({ email: expect.stringContaining('@') }),
+  );
+});
+```
+
+**Prevention**: Use parameterised queries exclusively. Never concatenate user
+input into SQL strings. ORM usage does not guarantee safety — verify raw
+queries and `whereRaw` calls.
+
+### Cross-Site Scripting (XSS)
+
+```typescript
+const xssPayloads = [
+  '<script>alert("xss")</script>',
+  '<img src=x onerror=alert("xss")>',
+  '"><svg onload=alert("xss")>',
+  "javascript:alert('xss')",
+  '<div onmouseover="alert(\'xss\')">hover</div>',
+];
+
+test.each(xssPayloads)('sanitises XSS in user input: %s', async (payload) => {
+  // Submit payload via API
+  await request(app)
+    .post('/api/comments')
+    .send({ body: payload });
+
+  // Retrieve and verify output is escaped
+  const res = await request(app).get('/api/comments');
+  const comment = res.body[res.body.length - 1];
+  expect(comment.body).not.toContain('<script');
+  expect(comment.body).not.toContain('onerror');
+  expect(comment.body).not.toContain('onload');
+  expect(comment.body).not.toContain('onmouseover');
+});
+```
+
+**Prevention**: Escape output by default (React does this). Sanitise HTML
+input with a strict allowlist (DOMPurify). Set `Content-Security-Policy`
+headers.
+
+### Insecure Direct Object Reference (IDOR)
+
+Test that users cannot access resources belonging to other users by
+manipulating IDs.
+
+```typescript
+test('user cannot access another user\'s order', async () => {
+  // Create order as user A
+  const orderRes = await request(app)
+    .post('/api/orders')
+    .set('Authorization', `Bearer ${userAToken}`)
+    .send({ items: [{ sku: 'WIDGET-1', qty: 1 }] });
+  const orderId = orderRes.body.id;
+
+  // Attempt access as user B
+  const res = await request(app)
+    .get(`/api/orders/${orderId}`)
+    .set('Authorization', `Bearer ${userBToken}`);
+
+  expect(res.status).toBe(403);
+});
+
+test('user cannot update another user\'s profile', async () => {
+  const res = await request(app)
+    .patch(`/api/users/${userAId}`)
+    .set('Authorization', `Bearer ${userBToken}`)
+    .send({ name: 'Hacked' });
+
+  expect(res.status).toBe(403);
+});
+```
+
+**Prevention**: Always check resource ownership in the authorization layer.
+Never rely on obscured IDs (UUIDs) as a security mechanism.
+
+### Authentication Bypass
+
+```typescript
+describe('Auth bypass checks', () => {
+  const protectedEndpoints = [
+    { method: 'GET', path: '/api/users/me' },
+    { method: 'POST', path: '/api/orders' },
+    { method: 'DELETE', path: '/api/users/123' },
+    { method: 'GET', path: '/api/admin/dashboard' },
+  ];
+
+  test.each(protectedEndpoints)(
+    '$method $path returns 401 without token',
+    async ({ method, path }) => {
+      const res = await request(app)[method.toLowerCase()](path);
+      expect(res.status).toBe(401);
+    },
+  );
+
+  test('expired token is rejected', async () => {
+    const expiredToken = signToken({ userId: '1' }, { expiresIn: '-1h' });
+    const res = await request(app)
+      .get('/api/users/me')
+      .set('Authorization', `Bearer ${expiredToken}`);
+    expect(res.status).toBe(401);
+  });
+
+  test('tampered token is rejected', async () => {
+    const token = signToken({ userId: '1', role: 'member' });
+    // Modify payload to escalate role
+    const [header, , signature] = token.split('.');
+    const tamperedPayload = btoa(JSON.stringify({ userId: '1', role: 'admin' }));
+    const tamperedToken = `${header}.${tamperedPayload}.${signature}`;
+
+    const res = await request(app)
+      .get('/api/admin/dashboard')
+      .set('Authorization', `Bearer ${tamperedToken}`);
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+---
+
+## DAST with OWASP ZAP
+
+Dynamic Application Security Testing scans a running application for
+vulnerabilities.
+
+### Automated Scan in CI
+
+```yaml
+# .github/workflows/security.yml
+name: DAST Scan
+on:
+  schedule:
+    - cron: '0 3 * * 1'  # Weekly Monday 3 AM
+  workflow_dispatch:
+
+jobs:
+  zap-scan:
+    runs-on: ubuntu-latest
+    services:
+      app:
+        image: your-app:latest
+        ports: ['3000:3000']
+    steps:
+      - name: ZAP Baseline Scan
+        uses: zaproxy/action-baseline@v0.12.0
+        with:
+          target: 'http://localhost:3000'
+          rules_file_name: '.zap/rules.tsv'
+          cmd_options: '-a -j'
+
+      - name: Upload ZAP Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: zap-report
+          path: report_html.html
+```
+
+### Custom Rules File
+
+```tsv
+# .zap/rules.tsv — customize alert thresholds
+# ID	Action	(IGNORE, WARN, FAIL)
+10010	IGNORE	# Cookie No HttpOnly Flag (handled by framework)
+10011	FAIL	# Cookie Without Secure Flag
+10015	FAIL	# Incomplete or No Cache-control Header
+10021	FAIL	# X-Content-Type-Options Header Missing
+10038	FAIL	# Content Security Policy Header Not Set
+40012	FAIL	# Cross Site Scripting (Reflected)
+40014	FAIL	# Cross Site Scripting (Persistent)
+90022	FAIL	# Application Error Disclosure
+```
+
+### Authenticated Scan
+
+For scanning behind login, provide ZAP with auth context:
+
+```yaml
+- name: ZAP Full Scan
+  uses: zaproxy/action-full-scan@v0.10.0
+  with:
+    target: 'http://localhost:3000'
+    cmd_options: >
+      -z "-config auth.method=2
+          -config auth.method.loginindicator=Dashboard
+          -config auth.method.logoutindicator=Sign in"
+```
+
+---
+
+## Rate Limit Verification
+
+Test that rate limits are enforced and return proper responses.
+
+```typescript
+describe('Rate limiting', () => {
+  test('login endpoint rate-limits after 5 attempts', async () => {
+    const results = [];
+
+    for (let i = 0; i < 10; i++) {
+      const res = await request(app)
+        .post('/api/auth/login')
+        .send({ email: 'test@test.com', password: 'wrong' });
+      results.push(res.status);
+    }
+
+    // First 5 should be 401 (wrong password)
+    expect(results.slice(0, 5).every((s) => s === 401)).toBe(true);
+    // Remaining should be 429 (rate limited)
+    expect(results.slice(5).every((s) => s === 429)).toBe(true);
+  });
+
+  test('rate limit returns Retry-After header', async () => {
+    // Exhaust rate limit
+    for (let i = 0; i < 6; i++) {
+      await request(app)
+        .post('/api/auth/login')
+        .send({ email: 'test@test.com', password: 'wrong' });
+    }
+
+    const res = await request(app)
+      .post('/api/auth/login')
+      .send({ email: 'test@test.com', password: 'wrong' });
+
+    expect(res.status).toBe(429);
+    expect(res.headers['retry-after']).toBeDefined();
+    expect(parseInt(res.headers['retry-after'])).toBeGreaterThan(0);
+  });
+
+  test('rate limit resets after window', async () => {
+    // This test requires clock mocking or a short rate limit window in test config
+    // Exhaust limit, advance time, verify access restored
+  });
+});
+```
+
+### Additional Security Checks
+
+- **CORS**: Verify `Access-Control-Allow-Origin` does not include `*` on
+  authenticated endpoints.
+- **Headers**: Verify `X-Content-Type-Options: nosniff`,
+  `Strict-Transport-Security`, `X-Frame-Options`.
+- **Sensitive data in URLs**: Verify tokens and passwords are never in query
+  strings (they appear in logs).
+- **Error messages**: Verify error responses do not leak stack traces,
+  database schema, or internal paths.