aigent-team 0.1.0

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

@@ -0,0 +1,292 @@
+# E2E Testing Reference
+
+## Page Object Model
+
+Encapsulate page interactions behind a stable API. Tests read like user stories;
+selectors and waits live in one place.
+
+### Structure
+
+```
+e2e/
+  pages/
+    login.page.ts
+    dashboard.page.ts
+    checkout.page.ts
+  fixtures/
+    auth.fixture.ts
+  specs/
+    checkout.spec.ts
+```
+
+### Page Object Example (Playwright)
+
+```typescript
+// e2e/pages/checkout.page.ts
+import { type Page, type Locator } from '@playwright/test';
+
+export class CheckoutPage {
+  private readonly cartItems: Locator;
+  private readonly promoCodeInput: Locator;
+  private readonly applyPromoButton: Locator;
+  private readonly totalPrice: Locator;
+  private readonly placeOrderButton: Locator;
+
+  constructor(private readonly page: Page) {
+    this.cartItems = page.getByRole('list', { name: 'Cart items' }).getByRole('listitem');
+    this.promoCodeInput = page.getByLabel('Promo code');
+    this.applyPromoButton = page.getByRole('button', { name: 'Apply' });
+    this.totalPrice = page.getByTestId('total-price');
+    this.placeOrderButton = page.getByRole('button', { name: 'Place order' });
+  }
+
+  async applyPromoCode(code: string) {
+    await this.promoCodeInput.fill(code);
+    await this.applyPromoButton.click();
+  }
+
+  async placeOrder() {
+    await this.placeOrderButton.click();
+    await this.page.waitForURL('**/confirmation');
+  }
+
+  async getTotal(): Promise<string> {
+    return this.totalPrice.textContent() ?? '';
+  }
+
+  async getItemCount(): Promise<number> {
+    return this.cartItems.count();
+  }
+}
+```
+
+### Test Using Page Object
+
+```typescript
+// e2e/specs/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+import { CheckoutPage } from '../pages/checkout.page';
+
+test.describe('Checkout', () => {
+  let checkout: CheckoutPage;
+
+  test.beforeEach(async ({ page }) => {
+    // Seed cart via API — never through UI
+    await page.request.post('/api/test/seed-cart', {
+      data: { items: [{ sku: 'WIDGET-1', qty: 2 }] },
+    });
+    await page.goto('/checkout');
+    checkout = new CheckoutPage(page);
+  });
+
+  test('applies promo code and updates total', async () => {
+    await checkout.applyPromoCode('SAVE20');
+    await expect(checkout.getTotal()).resolves.toContain('$16.00');
+  });
+});
+```
+
+---
+
+## Element Selection Priority
+
+Use the most accessible selector available. Order of preference:
+
+1. **`getByRole`** — matches what assistive technology sees.
+   `page.getByRole('button', { name: 'Submit' })`
+2. **`getByLabel`** — form fields with proper labels.
+   `page.getByLabel('Email address')`
+3. **`getByPlaceholder`** — fallback for unlabelled inputs.
+4. **`getByText`** — visible text content.
+5. **`getByTestId`** — last resort; requires `data-testid` attribute.
+
+Never use CSS selectors or XPath tied to DOM structure. They break on
+refactors and provide no accessibility signal.
+
+---
+
+## Wait Strategy
+
+### Rule: Never Use Fixed Delays
+
+```typescript
+// BAD — arbitrary delay, still flaky
+await page.waitForTimeout(3000);
+
+// GOOD — wait for specific condition
+await page.waitForSelector('[data-loaded="true"]');
+await expect(page.getByText('Order confirmed')).toBeVisible();
+```
+
+### Playwright Auto-Waiting
+
+Playwright auto-waits for elements to be actionable before interacting.
+Lean on this. Additional explicit waits for:
+
+- **Navigation**: `await page.waitForURL('**/dashboard')`
+- **Network idle**: `await page.waitForLoadState('networkidle')` (use
+  sparingly — prefer waiting for specific elements)
+- **API response**: `await page.waitForResponse(resp => resp.url().includes('/api/orders') && resp.status() === 200)`
+- **Custom condition**: `await expect(locator).toHaveCount(3)`
+
+### Timeout Configuration
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  timeout: 30_000,        // per-test timeout
+  expect: {
+    timeout: 5_000,       // per-assertion timeout
+  },
+  use: {
+    actionTimeout: 10_000, // per-action timeout (click, fill, etc.)
+    navigationTimeout: 15_000,
+  },
+});
+```
+
+---
+
+## Test Data Setup via API
+
+Never create test data through the UI. It is slow, brittle, and couples
+tests to unrelated pages.
+
+### Pattern: API Seeding
+
+```typescript
+test.beforeEach(async ({ page }) => {
+  // Create user and get auth token
+  const res = await page.request.post('/api/test/users', {
+    data: { email: 'qa@test.com', role: 'admin' },
+  });
+  const { token } = await res.json();
+
+  // Set auth cookie/header
+  await page.context().addCookies([{
+    name: 'auth_token',
+    value: token,
+    domain: 'localhost',
+    path: '/',
+  }]);
+});
+```
+
+### Pattern: Storage State for Auth
+
+```typescript
+// e2e/fixtures/auth.fixture.ts — run once, reuse across tests
+import { test as setup } from '@playwright/test';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('admin@test.com');
+  await page.getByLabel('Password').fill('test-password');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await page.waitForURL('**/dashboard');
+  await page.context().storageState({ path: '.auth/admin.json' });
+});
+
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    { name: 'setup', testMatch: /auth\.fixture\.ts/ },
+    {
+      name: 'tests',
+      dependencies: ['setup'],
+      use: { storageState: '.auth/admin.json' },
+    },
+  ],
+});
+```
+
+---
+
+## Parallel Execution Safety
+
+Playwright runs tests in parallel by default. Tests must be fully isolated:
+
+- **No shared database rows.** Each test creates its own data with unique IDs.
+- **No shared files.** Use temp directories or unique filenames.
+- **No port conflicts.** Use dynamic ports or separate server instances.
+- **No sequential assumptions.** Never rely on test execution order.
+
+If a test cannot be parallelised (e.g., it modifies global settings), mark it:
+
+```typescript
+test.describe.serial('Admin settings', () => {
+  // These tests run sequentially within this describe block
+});
+```
+
+---
+
+## Flakiness Prevention
+
+### Common Causes and Fixes
+
+| Cause | Detection | Fix |
+|---|---|---|
+| Race condition (element not ready) | Passes locally, fails in CI | Replace `waitForTimeout` with explicit waits |
+| Shared test state | Fails when run order changes | Isolate data per test |
+| Animation interfering with click | Intermittent click misses | Disable animations in test config |
+| Viewport-dependent layout | Fails on different screen sizes | Set fixed viewport in config |
+| Third-party dependency | Flaky external API | Mock external services in E2E |
+| Time-dependent logic | Fails at midnight/month-end | Mock clock or use stable test dates |
+
+### Playwright Anti-Flake Config
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  retries: process.env.CI ? 2 : 0,  // Retries hide flakiness locally
+  use: {
+    video: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    trace: 'retain-on-failure',
+  },
+});
+```
+
+### Flakiness Detection
+
+Run suspect tests in a loop locally before merging:
+
+```bash
+npx playwright test checkout.spec.ts --repeat-each=20
+```
+
+If it fails once in 20, it is flaky. Fix before merging.
+
+---
+
+## Screenshot and Trace on Failure
+
+Always capture artifacts on failure for debugging:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    trace: 'retain-on-failure',
+  },
+  outputDir: 'test-results/',
+});
+```
+
+In CI, upload the `test-results/` directory as a build artifact:
+
+```yaml
+# GitHub Actions
+- uses: actions/upload-artifact@v4
+  if: failure()
+  with:
+    name: playwright-results
+    path: test-results/
+    retention-days: 7
+```
+
+Traces can be viewed at https://trace.playwright.dev — share the link in
+bug reports for full reproduction context.

package/templates/teams/qa/references/mocking.md

@@ -0,0 +1,249 @@
+# Mocking Reference
+
+## Core Rule: Mock at System Boundaries Only
+
+A mock replaces something your code *cannot control* during a test:
+
+- **HTTP requests** to external services
+- **System clock** (`Date.now`, timers)
+- **Randomness** (`Math.random`, `crypto.randomUUID`)
+- **File system** (only when testing I/O behaviour, not business logic)
+
+Everything else — internal modules, utility functions, class methods — should
+use the real implementation. If you feel the need to mock an internal module,
+it is a design smell: extract an interface and inject the dependency.
+
+### Why Not Mock Internals?
+
+```typescript
+// BAD — mocking internal module
+vi.mock('../utils/calculateTax', () => ({
+  calculateTax: vi.fn(() => 5.00),
+}));
+
+test('order total includes tax', () => {
+  // This test proves nothing. You mocked the very thing
+  // that computes the value you're asserting on.
+  expect(getOrderTotal(items)).toBe(105.00);
+});
+
+// GOOD — test the real calculation
+test('order total includes tax', () => {
+  const items = [buildOrderItem({ unitPrice: 100, quantity: 1 })];
+  // Real calculateTax runs; test verifies actual behaviour
+  expect(getOrderTotal(items)).toBe(105.00);
+});
+```
+
+---
+
+## MSW (Mock Service Worker) Setup
+
+MSW intercepts HTTP requests at the network level. Your application code
+uses real `fetch` / `axios` — no patching required.
+
+### Installation
+
+```bash
+npm install -D msw
+```
+
+### Handler Definition
+
+```typescript
+// tests/mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  http.get('/api/users/:id', ({ params }) => {
+    return HttpResponse.json({
+      id: params.id,
+      name: 'Test User',
+      email: 'test@example.com',
+    });
+  }),
+
+  http.post('/api/orders', async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json(
+      { id: 'order-123', ...body, status: 'created' },
+      { status: 201 },
+    );
+  }),
+
+  http.get('/api/inventory/:sku', () => {
+    return HttpResponse.json({ sku: 'WIDGET-1', stock: 42 });
+  }),
+];
+```
+
+### Server Setup (Node — Vitest / Jest)
+
+```typescript
+// tests/mocks/server.ts
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+
+// tests/setup.ts
+import { server } from './mocks/server';
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+**Critical**: `onUnhandledRequest: 'error'` ensures no real HTTP requests
+leak through. If a test makes an unmocked request, it fails loudly.
+
+### Per-Test Override
+
+```typescript
+import { server } from '../mocks/server';
+import { http, HttpResponse } from 'msw';
+
+test('shows error when API returns 500', async () => {
+  server.use(
+    http.get('/api/users/:id', () => {
+      return HttpResponse.json(
+        { error: 'Internal server error' },
+        { status: 500 },
+      );
+    }),
+  );
+
+  render(<UserProfile userId="1" />);
+  await expect(screen.findByText('Something went wrong')).resolves.toBeInTheDocument();
+});
+```
+
+### Browser Setup (Playwright / Cypress)
+
+For E2E tests, prefer Playwright's built-in route interception over MSW
+browser worker:
+
+```typescript
+// Playwright route mock
+await page.route('**/api/external-service/**', (route) => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({ status: 'ok' }),
+  });
+});
+```
+
+---
+
+## Never Mock What You Don't Own (Without a Contract)
+
+If you mock a third-party API, your mock can drift from reality. Protect
+against this:
+
+### Strategy 1: Record and Replay
+
+Record real API responses once, replay in tests.
+
+```typescript
+// Record phase (run manually):
+const response = await fetch('https://api.stripe.com/v1/charges');
+fs.writeFileSync('tests/fixtures/stripe-charges.json', await response.text());
+
+// Test phase:
+server.use(
+  http.get('https://api.stripe.com/v1/charges', () => {
+    const data = JSON.parse(fs.readFileSync('tests/fixtures/stripe-charges.json', 'utf-8'));
+    return HttpResponse.json(data);
+  }),
+);
+```
+
+Refresh recordings periodically (monthly or on API version bump).
+
+### Strategy 2: Schema Validation
+
+Validate your mock responses against the provider's OpenAPI spec:
+
+```typescript
+import Ajv from 'ajv';
+import stripeSpec from './fixtures/stripe-openapi.json';
+
+test('mock matches Stripe schema', () => {
+  const ajv = new Ajv();
+  const schema = stripeSpec.paths['/v1/charges'].get.responses['200'].content['application/json'].schema;
+  const valid = ajv.validate(schema, mockChargesResponse);
+  expect(valid).toBe(true);
+});
+```
+
+### Strategy 3: Contract Tests
+
+For services you own, use Pact (see `test-strategy.md` > Contract Testing).
+
+---
+
+## Verifying Mock Contracts Match Real APIs
+
+Every mock handler should be traceable to a real API endpoint. Maintain a
+mapping:
+
+```typescript
+// tests/mocks/contract-map.ts
+/**
+ * Maps mock handlers to real API documentation.
+ * Review this file when upgrading API versions.
+ *
+ * Handler: GET /api/users/:id
+ * Real endpoint: https://api.example.com/v2/users/{id}
+ * Schema: docs/openapi/users.yaml#/paths/~1users~1{id}/get
+ * Last verified: 2025-12-01
+ */
+```
+
+### Detecting Drift
+
+Add a CI job (weekly) that:
+
+1. Fetches the latest OpenAPI spec from the provider.
+2. Validates all mock response fixtures against the spec.
+3. Fails if any fixture is invalid — forces update.
+
+---
+
+## Clock and Random Mocking
+
+### Vitest Clock
+
+```typescript
+import { vi } from 'vitest';
+
+test('token expires after 1 hour', () => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date('2025-06-15T10:00:00Z'));
+
+  const token = createToken();
+  expect(token.isExpired()).toBe(false);
+
+  vi.advanceTimersByTime(60 * 60 * 1000); // 1 hour
+  expect(token.isExpired()).toBe(true);
+
+  vi.useRealTimers();
+});
+```
+
+### Deterministic Random
+
+```typescript
+test('generates reproducible IDs', () => {
+  const mockRandom = vi.spyOn(Math, 'random').mockReturnValue(0.42);
+
+  const id = generateShortId();
+  expect(id).toBe('expected-id-based-on-0.42');
+
+  mockRandom.mockRestore();
+});
+```
+
+Always restore mocks after the test — use `afterEach(() => vi.restoreAllMocks())`
+globally.