tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/testing-patterns/SKILL.md

@@ -1,205 +1,512 @@
 ---
 name: testing-patterns
-description: Testing patterns and principles. Unit, integration, mocking strategies.
+description: Testing mastery across stacks. Unit testing with Jest/Vitest/pytest, integration testing, E2E with Playwright, mocking strategies, test architecture (AAA, Given-When-Then), code coverage, snapshot testing, API testing, component testing with Testing Library, and TDD workflow. Use when writing tests, designing test architecture, or improving test coverage.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-01
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Testing Patterns
-
-> Tests don't prove code works. They make it safe to change.
-> A codebase without tests is a codebase you're afraid to touch.
+# Testing Patterns — Cross-Stack Testing Mastery
 
 ---
 
-## Test Pyramid
+## Test Architecture
 
-Write tests at the right level. Most tests should be unit tests. Fewer integration tests. Fewest E2E tests.
+### The Testing Pyramid
 
 ```
-         /\
-        /E2E\         Fewest — expensive to write and run
-       /------\
-      /Integr. \      Some — verify component interactions  
-     /----------\
-    /  Unit Tests \   Most — fast, isolated, focused
-   /--------------\
+         /  E2E  \        ← Few: critical user flows (Playwright/Cypress)
+        /──────────\
+       / Integration \     ← Moderate: API routes, DB queries, component integration
+      /──────────────\
+     /   Unit Tests   \    ← Many: pure functions, hooks, utilities, business logic
+    /──────────────────\
+
+Rules:
+- 70% unit, 20% integration, 10% E2E
+- Unit tests: < 50ms each
+- Integration tests: < 2s each
+- E2E tests: < 30s each
+- If a test takes > 5s, it's a design problem
 ```
 
-**Why this shape:**
-- Unit tests run in milliseconds — you can have thousands
-- E2E tests take seconds — you want dozens, not hundreds
-- Inverting the pyramid = slow CI, fragile test suite, low confidence
+### AAA Pattern (Arrange-Act-Assert)
 
----
+```typescript
+// Every test follows the same structure
+it("calculates total with tax", () => {
+  // Arrange — set up the scenario
+  const cart = new Cart();
+  cart.addItem({ name: "Widget", price: 100 });
+  cart.setTaxRate(0.08);
 
-## AAA Pattern
+  // Act — perform the action being tested
+  const total = cart.calculateTotal();
 
-Every test follows this structure:
+  // Assert — verify the result
+  expect(total).toBe(108);
+});
 
-```ts
-it('should return 401 when token is expired', async () => {
-  // Arrange — set up the scenario
-  const expiredToken = generateToken({ expiresIn: '-1s' });
-  const request = buildRequest({ authorization: `Bearer ${expiredToken}` });
+// ❌ BAD: Multiple acts in one test
+it("does too many things", () => {
+  cart.addItem({ name: "A", price: 10 });
+  expect(cart.total).toBe(10);        // assert
+  cart.addItem({ name: "B", price: 20 });
+  expect(cart.total).toBe(30);        // another assert after another act
+  cart.removeItem("A");
+  expect(cart.total).toBe(20);        // yet another — split into 3 tests
+});
+```
 
-  // Act — do the thing being tested
-  const response = await authMiddleware(request);
+### Test Naming Convention
 
-  // Assert — verify the outcome
-  expect(response.status).toBe(401);
-  expect(response.body.error).toBe('Token expired');
+```typescript
+// Format: [unit] + [scenario] + [expected result]
+
+// ✅ GOOD: Descriptive, reads like a specification
+describe("calculateDiscount", () => {
+  it("returns 0% when cart total is under $50", () => {});
+  it("returns 10% when cart total is $50-$99", () => {});
+  it("returns 20% when cart total is $100+", () => {});
+  it("throws when cart is empty", () => {});
 });
-```
 
-Never combine Arrange and Assert. Never skip Arrange by relying on test state from a previous test.
+// ❌ BAD: Vague, implementation-focused
+describe("calculateDiscount", () => {
+  it("works", () => {});
+  it("test1", () => {});
+  it("should return correct value", () => {});
+});
+```
 
 ---
 
-## Unit Tests
+## Unit Testing (Vitest / Jest)
+
+### Pure Function Testing
+
+```typescript
+// utils/math.ts
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+// utils/math.test.ts
+import { describe, it, expect } from "vitest";
+import { clamp } from "./math";
 
-Unit tests test one unit of logic in isolation. Everything external is replaced with a controlled substitute.
+describe("clamp", () => {
+  it("returns the value when within range", () => {
+    expect(clamp(5, 0, 10)).toBe(5);
+  });
 
-```ts
-// Test the function's logic — not the database, not the network
-it('should hash the password before saving', async () => {
-  const mockSave = vi.fn().mockResolvedValue({ id: '1' });
-  const userRepo = { save: mockSave };
+  it("clamps to min when value is below range", () => {
+    expect(clamp(-5, 0, 10)).toBe(0);
+  });
 
-  await createUser({ email: 'a@b.com', password: 'secret' }, userRepo);
+  it("clamps to max when value is above range", () => {
+    expect(clamp(15, 0, 10)).toBe(10);
+  });
 
-  const savedUser = mockSave.mock.calls[0][0];
-  expect(savedUser.password).not.toBe('secret');          // was hashed
-  expect(savedUser.password).toMatch(/^\$2b\$/);           // bcrypt format
+  it("handles equal min and max", () => {
+    expect(clamp(5, 3, 3)).toBe(3);
+  });
+
+  it("handles floating point values", () => {
+    expect(clamp(0.5, 0, 1)).toBeCloseTo(0.5);
+  });
 });
 ```
 
-**Rules for unit tests:**
-- One assertion per concept (multiple `expect` calls are fine if they verify the same behavior)
-- No network calls, no file system, no real database
-- Tests are order-independent — they don't rely on state from other tests
-- Test names describe behavior: `should X when Y` or `returns X given Y`
+### Async Testing
 
----
+```typescript
+import { describe, it, expect, vi } from "vitest";
 
-## Integration Tests
+// Async function under test
+async function fetchUser(id: string): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json();
+}
 
-Integration tests verify that two or more components work together correctly.
+describe("fetchUser", () => {
+  it("returns user data on success", async () => {
+    const mockUser = { id: "1", name: "Alice" };
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockUser),
+    });
 
-```ts
-// Tests the real database interaction
-it('should save and retrieve a user', async () => {
-  const user = await UserService.create({ email: 'test@test.com', name: 'Test' });
-  const found = await UserService.findById(user.id);
+    const user = await fetchUser("1");
+    expect(user).toEqual(mockUser);
+    expect(fetch).toHaveBeenCalledWith("/api/users/1");
+  });
 
-  expect(found.email).toBe('test@test.com');
+  it("throws on HTTP error", async () => {
+    global.fetch = vi.fn().mockResolvedValue({ ok: false, status: 404 });
+
+    await expect(fetchUser("999")).rejects.toThrow("HTTP 404");
+  });
 });
 ```
 
-**Integration test rules:**
-- Use a real test database — not a mock
-- Clean up data before or after each test (use transactions that rollback, or seed scripts)
-- Slower than unit tests — run on CI but not on every file save
+### Timer & Date Mocking
+
+```typescript
+describe("debounce", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("delays execution by specified ms", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 300);
+
+    debounced();
+    expect(fn).not.toHaveBeenCalled(); // not yet
+
+    vi.advanceTimersByTime(200);
+    expect(fn).not.toHaveBeenCalled(); // still not
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce(); // now
+  });
+
+  it("resets timer on subsequent calls", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 300);
+
+    debounced();
+    vi.advanceTimersByTime(200);
+    debounced(); // reset timer
+    vi.advanceTimersByTime(200);
+    expect(fn).not.toHaveBeenCalled(); // timer was reset
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+});
+
+// Date mocking
+it("formats today's date", () => {
+  vi.setSystemTime(new Date("2024-06-15T12:00:00Z"));
+  expect(getFormattedDate()).toBe("June 15, 2024");
+  vi.useRealTimers();
+});
+```
 
 ---
 
-## Mocking Principles
+## Mocking Strategies
 
-Mocks replace external dependencies. Use them accurately.
+### Module Mocks
 
-```ts
-// ❌ Mock that returns nothing useful
-vi.mock('./mailer', () => ({ send: vi.fn() }));
+```typescript
+import { vi, describe, it, expect, beforeEach } from "vitest";
+import { sendEmail } from "./email-service";
+import { createUser } from "./user-service";
 
-// ✅ Mock that reflects real behavior
-vi.mock('./mailer', () => ({
-  send: vi.fn().mockResolvedValue({ messageId: 'mock-id-123' }),
+// Mock an entire module
+vi.mock("./email-service", () => ({
+  sendEmail: vi.fn().mockResolvedValue({ sent: true }),
 }));
+
+describe("createUser", () => {
+  beforeEach(() => {
+    vi.clearAllMocks(); // reset call counts between tests
+  });
+
+  it("sends welcome email after creating user", async () => {
+    await createUser({ name: "Alice", email: "alice@test.com" });
+
+    expect(sendEmail).toHaveBeenCalledWith({
+      to: "alice@test.com",
+      subject: "Welcome!",
+      body: expect.stringContaining("Alice"),
+    });
+  });
+
+  it("does not send email on validation failure", async () => {
+    await expect(createUser({ name: "", email: "" })).rejects.toThrow();
+    expect(sendEmail).not.toHaveBeenCalled();
+  });
+});
 ```
 
-**What to mock:**
-- External HTTP calls (payment gateways, third-party APIs)
-- Time (`Date.now()`, `new Date()`) when time-dependent
-- File system in unit tests
-- Email/SMS sending
+### Spy Pattern
+
+```typescript
+// Spy on an existing method (don't replace it — observe it)
+const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+await riskyOperation();
+
+expect(consoleSpy).toHaveBeenCalledWith(
+  expect.stringContaining("failed"),
+  expect.any(Error)
+);
 
-**What not to mock:**
-- Your own business logic
-- The function being tested
-- Simple pure utility functions
+consoleSpy.mockRestore(); // restore original
+```
+
+### Dependency Injection Pattern (Testable by Design)
+
+```typescript
+// ❌ BAD: Hard-coded dependency — untestable without module mocking
+class UserService {
+  async getUser(id: string) {
+    return await fetch(`/api/users/${id}`).then((r) => r.json());
+  }
+}
+
+// ✅ GOOD: Injected dependency — naturally testable
+interface HttpClient {
+  get<T>(url: string): Promise<T>;
+}
+
+class UserService {
+  constructor(private http: HttpClient) {}
+
+  async getUser(id: string): Promise<User> {
+    return this.http.get<User>(`/api/users/${id}`);
+  }
+}
+
+// In test:
+const mockHttp: HttpClient = {
+  get: vi.fn().mockResolvedValue({ id: "1", name: "Alice" }),
+};
+const service = new UserService(mockHttp);
+
+// ❌ HALLUCINATION TRAP: Prefer dependency injection over vi.mock()
+// vi.mock() is global and can leak between tests
+// DI makes tests isolated and explicit
+```
 
 ---
 
-## Test Coverage
+## React Component Testing (Testing Library)
 
-Coverage measures which lines are executed during tests. 100% coverage does not mean the code is correct.
+```tsx
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { LoginForm } from "./LoginForm";
 
-**Useful coverage:**
-- `> 80%` for business logic modules
-- Focus on statement + branch coverage (not just line coverage)
-- Low coverage on infrastructure/config files is acceptable
+describe("LoginForm", () => {
+  it("renders email and password fields", () => {
+    render(<LoginForm onSubmit={vi.fn()} />);
 
-**Coverage anti-patterns:**
-- Tests written solely to increase coverage numbers
-- Asserting that mocks were called instead of asserting real outcomes
-- Tautology tests: `expect(result).toBe(result)`
+    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /sign in/i })).toBeInTheDocument();
+  });
 
----
+  it("calls onSubmit with credentials", async () => {
+    const user = userEvent.setup();
+    const onSubmit = vi.fn();
+    render(<LoginForm onSubmit={onSubmit} />);
 
-## Scripts
+    await user.type(screen.getByLabelText(/email/i), "alice@test.com");
+    await user.type(screen.getByLabelText(/password/i), "secret123");
+    await user.click(screen.getByRole("button", { name: /sign in/i }));
 
-| Script | Purpose | Run With |
-|---|---|---|
-| `scripts/test_runner.py` | Runs test suite and reports results | `python scripts/test_runner.py <project_path>` |
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: "alice@test.com",
+      password: "secret123",
+    });
+  });
 
----
+  it("shows validation error for invalid email", async () => {
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={vi.fn()} />);
 
-## Output Format
+    await user.type(screen.getByLabelText(/email/i), "not-an-email");
+    await user.click(screen.getByRole("button", { name: /sign in/i }));
 
-When this skill produces or reviews code, structure your output as follows:
+    expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
+  });
 
-```
-━━━ Testing Patterns Report ━━━━━━━━━━━━━━━━━━━━━━━━
-Skill:       Testing Patterns
-Language:    [detected language / framework]
-Scope:       [N files · N functions]
-─────────────────────────────────────────────────
-✅ Passed:   [checks that passed, or "All clean"]
-⚠️  Warnings: [non-blocking issues, or "None"]
-❌ Blocked:  [blocking issues requiring fix, or "None"]
-─────────────────────────────────────────────────
-VBC status:  PENDING → VERIFIED
-Evidence:    [test output / lint pass / compile success]
-```
+  it("disables submit button while loading", async () => {
+    render(<LoginForm onSubmit={vi.fn()} isLoading={true} />);
 
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
+    expect(screen.getByRole("button", { name: /sign in/i })).toBeDisabled();
+  });
+});
 
+// ❌ HALLUCINATION TRAP: Query priorities (use in this order):
+// 1. getByRole — accessible role ("button", "textbox", etc.)
+// 2. getByLabelText — form inputs with labels
+// 3. getByPlaceholderText — when no label exists
+// 4. getByText — non-interactive elements
+// 5. getByTestId — LAST RESORT only
+// ❌ Never default to getByTestId — it tests implementation, not behavior
+```
 
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
+## E2E Testing (Playwright)
 
-**Slash command: `/test`**
-**Active reviewers: `logic` · `test-coverage-reviewer`**
+```typescript
+import { test, expect } from "@playwright/test";
 
-### ❌ Forbidden AI Tropes in Testing
+test.describe("Login Flow", () => {
+  test("successful login redirects to dashboard", async ({ page }) => {
+    await page.goto("/login");
 
-1. **Tautological Tests** — writing `expect(x).toBe(x)` or testing that a mock returns what it was mocked to return, ignoring actual behavior.
-2. **Missing the "Arrange" Step** — relying on test state leftover from a previous `it()` block.
-3. **Over-mocking** — mocking the system under test or mocking out so much that the test is completely useless.
-4. **Assertions in loops** — writing loops with dynamic assertions instead of explicit, readable test cases.
-5. **Ignoring Async Failures** — forgetting to `await` the assertions or the function under test, leading to false positives.
+    await page.getByLabel("Email").fill("admin@test.com");
+    await page.getByLabel("Password").fill("password123");
+    await page.getByRole("button", { name: "Sign In" }).click();
 
-### ✅ Pre-Flight Self-Audit
+    // Wait for navigation
+    await expect(page).toHaveURL("/dashboard");
+    await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+  });
 
-Review these questions before generating test code:
+  test("shows error for invalid credentials", async ({ page }) => {
+    await page.goto("/login");
+
+    await page.getByLabel("Email").fill("wrong@test.com");
+    await page.getByLabel("Password").fill("wrongpassword");
+    await page.getByRole("button", { name: "Sign In" }).click();
+
+    await expect(page.getByText("Invalid credentials")).toBeVisible();
+    await expect(page).toHaveURL("/login"); // no redirect
+  });
+
+  test("responsive: mobile menu toggles", async ({ page, isMobile }) => {
+    test.skip(!isMobile, "Mobile only");
+
+    await page.goto("/");
+    await page.getByRole("button", { name: "Menu" }).click();
+    await expect(page.getByRole("navigation")).toBeVisible();
+  });
+});
+
+// API testing with Playwright
+test("API: create user returns 201", async ({ request }) => {
+  const response = await request.post("/api/users", {
+    data: { name: "Alice", email: "alice@test.com" },
+  });
+
+  expect(response.status()).toBe(201);
+  const body = await response.json();
+  expect(body).toMatchObject({ name: "Alice", email: "alice@test.com" });
+});
 ```
-✅ Does each test explicitly follow the Arrange-Act-Assert (AAA) pattern?
-✅ Are external dependencies (DBs, Networks) isolated efficiently using proper mocks?
-✅ Is the test asserting verifying behavioral OUTCOMES rather than internal implementation details?
-✅ Did I properly `await` asynchronous operations to prevent false positives?
-✅ Are test names readable and descriptive of the tested behavior?
+
+### Playwright Config
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  timeout: 30000,
+  retries: process.env.CI ? 2 : 0, // retry in CI only
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",      // save trace on failures
+    screenshot: "only-on-failure",
+  },
+  webServer: {
+    command: "npm run dev",
+    port: 3000,
+    reuseExistingServer: !process.env.CI,
+  },
+  projects: [
+    { name: "chrome", use: { browserName: "chromium" } },
+    { name: "firefox", use: { browserName: "firefox" } },
+    { name: "mobile", use: { ...devices["iPhone 14"] } },
+  ],
+});
 ```
+
+---
+
+## API Testing
+
+```typescript
+// Testing REST APIs with supertest (Express/Fastify)
+import request from "supertest";
+import { app } from "./app";
+
+describe("POST /api/users", () => {
+  it("creates a user and returns 201", async () => {
+    const response = await request(app)
+      .post("/api/users")
+      .send({ name: "Alice", email: "alice@test.com" })
+      .expect(201)
+      .expect("Content-Type", /json/);
+
+    expect(response.body).toMatchObject({
+      id: expect.any(Number),
+      name: "Alice",
+      email: "alice@test.com",
+    });
+  });
+
+  it("returns 400 for missing required fields", async () => {
+    await request(app)
+      .post("/api/users")
+      .send({ name: "" })
+      .expect(400);
+  });
+
+  it("returns 409 for duplicate email", async () => {
+    await request(app)
+      .post("/api/users")
+      .send({ name: "Alice", email: "existing@test.com" })
+      .expect(409);
+  });
+});
+```
+
+---
+
+## Code Coverage
+
+```jsonc
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "lcov", "html"],
+      thresholds: {
+        lines: 80,
+        functions: 80,
+        branches: 75,
+        statements: 80,
+      },
+      exclude: [
+        "**/*.test.ts",
+        "**/*.spec.ts",
+        "**/types/**",
+        "**/mocks/**",
+      ],
+    },
+  },
+});
+
+// Run: npx vitest --coverage
+```
+
+```
+Coverage rules:
+- 80% is the practical threshold (not 100%)
+- 100% coverage ≠ 100% confidence
+- Cover edge cases and error paths, not just happy paths
+- Avoid testing implementation details (private methods, internal state)
+- Focus coverage on: business logic, data transformations, auth/security
+- Skip coverage on: config files, types-only files, generated code
+```
+
+---