clearctx 3.0.0 → 3.1.0

package/skills/testing-qa/SKILL.md

@@ -0,0 +1,842 @@
+---
+name: testing-qa
+description: Production-grade testing strategy, unit/integration/e2e patterns, mocking, test data, and CI integration
+domain: testing
+keywords: [testing, unit-tests, integration-tests, e2e, mocking, fixtures, coverage, ci, jest, vitest]
+version: 1.0.0
+---
+
+# Testing & QA — Expertise Guide
+
+## Worker Context
+
+You are a testing specialist. Your role: design test strategies, write comprehensive test suites, and ensure code quality through automated testing. You apply the testing pyramid, write fast deterministic tests, and integrate with CI/CD pipelines.
+
+### Testing Pyramid (Token Budget Distribution)
+
+| Level | Coverage | Speed | Isolation | Cost | When to Use |
+|-------|----------|-------|-----------|------|-------------|
+| **Unit** | 70% | <10ms | Full | Low | Business logic, utilities, pure functions |
+| **Integration** | 20% | <500ms | Partial | Medium | API endpoints, DB operations, service interactions |
+| **E2E** | 10% | >2s | None | High | Critical user flows only (checkout, signup, payment) |
+
+**Decision Tree:**
+1. Testing pure function/utility? → Unit test
+2. Testing API endpoint? → Integration test (real DB, mocked external APIs)
+3. Testing multi-page user flow? → E2E test (only if critical business path)
+4. Testing UI component? → Unit test (render + interactions), NOT snapshot unless stable contract
+
+### AAA Pattern (CRITICAL: Use for ALL tests)
+
+```javascript
+// GOOD: Clear AAA structure
+describe('OrderService', () => {
+  describe('createOrder', () => {
+    it('should return 201 when valid order data provided', async () => {
+      // Arrange
+      const validOrder = { userId: 1, items: [{ id: 101, qty: 2 }] };
+      const mockDb = { insert: jest.fn().mockResolvedValue({ id: 5 }) };
+      const service = new OrderService(mockDb);
+
+      // Act
+      const result = await service.createOrder(validOrder);
+
+      // Assert
+      expect(result.status).toBe(201);
+      expect(result.data.id).toBe(5);
+      expect(mockDb.insert).toHaveBeenCalledWith(validOrder);
+    });
+  });
+});
+
+// BAD: Mixed concerns, unclear phases
+it('order test', async () => {
+  const service = new OrderService(mockDb);
+  const result = await service.createOrder({ userId: 1, items: [] });
+  expect(mockDb.insert).toHaveBeenCalled();
+  expect(result.status).toBe(201); // Assert before full setup clear
+  const validOrder = { userId: 1, items: [{ id: 101, qty: 2 }] };
+});
+```
+
+### Mocking Decision Tree (CRITICAL: Follow this exactly)
+
+```
+Is this what I'm testing?
+├─ YES → NEVER mock it
+└─ NO → Continue...
+    │
+    Is this an external dependency?
+    ├─ External API/service → ALWAYS mock (network unreliable)
+    ├─ Database
+    │  ├─ Unit test → Mock (speed + isolation)
+    │  └─ Integration test → Real DB with transaction rollback
+    ├─ Time/Date → ALWAYS mock (determinism)
+    ├─ File system → Mock for unit, real tmpdir for integration
+    └─ Internal module
+       ├─ Simple logic → Use real implementation (test integration)
+       └─ Complex/slow → Mock ONLY if needed for isolation
+```
+
+**Examples:**
+
+```javascript
+// GOOD: Mock external API, use real internal services
+describe('PaymentProcessor', () => {
+  it('should charge customer via Stripe', async () => {
+    // Mock external Stripe API
+    const mockStripe = { charge: jest.fn().mockResolvedValue({ id: 'ch_123' }) };
+
+    // Use REAL internal services (no mocking)
+    const realOrderService = new OrderService(testDb);
+    const processor = new PaymentProcessor(mockStripe, realOrderService);
+
+    const result = await processor.processPayment(orderId);
+
+    expect(mockStripe.charge).toHaveBeenCalledWith(expect.objectContaining({
+      amount: 5000,
+      currency: 'usd'
+    }));
+  });
+});
+
+// BAD: Overmocking — test proves nothing
+it('should process payment', async () => {
+  const mockStripe = { charge: jest.fn().mockResolvedValue({ id: 'ch_123' }) };
+  const mockOrderService = { getOrder: jest.fn().mockResolvedValue({ total: 50 }) };
+  const mockLogger = { log: jest.fn() };
+  const processor = new PaymentProcessor(mockStripe, mockOrderService, mockLogger);
+
+  // You've mocked everything — this test only verifies your mocks work
+  const result = await processor.processPayment(1);
+  expect(result.id).toBe('ch_123'); // Circular: you mocked this response
+});
+
+// GOOD: Always mock time
+describe('SubscriptionService', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date('2026-02-15'));
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('should expire subscription after 30 days', () => {
+    const service = new SubscriptionService();
+    const sub = service.createSubscription();
+
+    jest.advanceTimersByTime(30 * 24 * 60 * 60 * 1000);
+
+    expect(service.isExpired(sub)).toBe(true);
+  });
+});
+```
+
+### Test Data Factories (IMPORTANT: Use for ALL test data)
+
+```javascript
+// GOOD: Deterministic factory functions
+function createTestUser(overrides = {}) {
+  return {
+    id: 1,
+    email: 'test@example.com',
+    name: 'Test User',
+    createdAt: new Date('2026-01-01'),
+    ...overrides
+  };
+}
+
+function createTestOrder(overrides = {}) {
+  return {
+    id: 100,
+    userId: 1,
+    items: [{ productId: 10, quantity: 2, price: 25.00 }],
+    total: 50.00,
+    status: 'pending',
+    ...overrides
+  };
+}
+
+// Usage
+it('should apply discount to order', () => {
+  const order = createTestOrder({ total: 100.00 });
+  const result = applyDiscount(order, 0.1);
+  expect(result.total).toBe(90.00);
+});
+
+// BAD: Inline data, hard to maintain, not reusable
+it('test discount', () => {
+  const order = {
+    id: 999,
+    userId: 42,
+    items: [{ productId: 88, quantity: 1, price: 100.00 }],
+    total: 100.00,
+    status: 'pending'
+  };
+  // ... test continues
+});
+
+// BAD: Non-deterministic (breaks randomly)
+function createTestUser() {
+  return {
+    id: Math.floor(Math.random() * 10000), // NEVER use random in tests
+    email: `user${Date.now()}@example.com`, // NEVER use current time
+    name: 'Test User'
+  };
+}
+```
+
+### Assertion Patterns (Prefer specific over generic)
+
+```javascript
+// GOOD: Specific assertions
+expect(response.status).toBe(201);
+expect(response.body).toEqual({ id: 5, name: 'Widget' });
+expect(user.roles).toContain('admin');
+expect(result.errors).toHaveLength(2);
+
+// BAD: Generic assertions (low signal)
+expect(response).toBeTruthy(); // What are you actually testing?
+expect(response.status).toBeGreaterThan(0); // Too broad
+expect(result).toBeDefined(); // Useless — undefined would throw earlier
+
+// GOOD: Custom matchers for domain concepts
+expect.extend({
+  toBeValidOrder(received) {
+    const pass = received.id > 0 &&
+                 Array.isArray(received.items) &&
+                 received.total >= 0;
+    return {
+      pass,
+      message: () => `Expected ${received} to be a valid order`
+    };
+  }
+});
+
+expect(order).toBeValidOrder();
+
+// GOOD: Snapshot testing (use sparingly)
+// ONLY for: API response schemas, component trees, serialized config
+// NEVER for: dates, IDs, timestamps, random data
+it('should return correct API response shape', () => {
+  const response = api.getUserProfile(1);
+  expect(response).toMatchSnapshot({
+    id: expect.any(Number),
+    createdAt: expect.any(String), // Ignore dynamic values
+    email: expect.any(String)
+  });
+});
+
+// BAD: Snapshot with dynamic data (flaky)
+it('snapshot test', () => {
+  const response = { id: Date.now(), user: 'test' };
+  expect(response).toMatchSnapshot(); // Fails every run
+});
+```
+
+### Integration Testing Pattern
+
+```javascript
+// GOOD: Integration test with real DB, transaction rollback
+describe('POST /api/orders', () => {
+  let app, db;
+
+  beforeAll(async () => {
+    db = await createTestDatabase(); // Real test DB
+    app = createApp(db);
+  });
+
+  beforeEach(async () => {
+    await db.raw('BEGIN'); // Start transaction
+  });
+
+  afterEach(async () => {
+    await db.raw('ROLLBACK'); // Rollback after each test (clean slate)
+  });
+
+  afterAll(async () => {
+    await db.destroy();
+  });
+
+  it('should create order and return 201', async () => {
+    // Arrange: Seed test data
+    await db('users').insert({ id: 1, email: 'test@example.com' });
+    const orderData = { userId: 1, items: [{ id: 10, qty: 2 }] };
+
+    // Act: Make real HTTP request
+    const response = await request(app)
+      .post('/api/orders')
+      .send(orderData);
+
+    // Assert: Check response + DB state
+    expect(response.status).toBe(201);
+    expect(response.body.id).toBeGreaterThan(0);
+
+    const dbOrder = await db('orders').where({ id: response.body.id }).first();
+    expect(dbOrder.user_id).toBe(1);
+    expect(dbOrder.status).toBe('pending');
+  });
+
+  it('should return 400 when userId missing', async () => {
+    const response = await request(app)
+      .post('/api/orders')
+      .send({ items: [] });
+
+    expect(response.status).toBe(400);
+    expect(response.body.error).toContain('userId');
+  });
+});
+
+// BAD: Mocking DB in "integration" test (not actually integrated)
+it('should create order', async () => {
+  const mockDb = { insert: jest.fn().mockResolvedValue({ id: 5 }) };
+  // This is a UNIT test pretending to be integration
+});
+```
+
+### Coverage Strategy (IMPORTANT: Branch coverage > line coverage)
+
+| Code Type | Target | Priority | Why |
+|-----------|--------|----------|-----|
+| Business logic | 90%+ | CRITICAL | Core value, high bug impact |
+| API routes | 80%+ | High | User-facing contracts |
+| Utils/helpers | 85%+ | High | Reused everywhere |
+| Config files | 0% | Ignore | Static data |
+| Generated code | 0% | Ignore | Not hand-written |
+| UI components | 70%+ | Medium | Snapshot + interaction tests |
+
+**Branch coverage example:**
+
+```javascript
+// This function has 4 branches
+function calculateDiscount(user, orderTotal) {
+  if (!user) return 0;                    // Branch 1
+  if (user.isPremium) return 0.2;         // Branch 2
+  if (orderTotal > 100) return 0.1;       // Branch 3
+  return 0;                                // Branch 4
+}
+
+// GOOD: Test ALL branches
+describe('calculateDiscount', () => {
+  it('should return 0 when user is null', () => {
+    expect(calculateDiscount(null, 50)).toBe(0);
+  });
+
+  it('should return 0.2 when user is premium', () => {
+    expect(calculateDiscount({ isPremium: true }, 50)).toBe(0.2);
+  });
+
+  it('should return 0.1 when order total > 100', () => {
+    expect(calculateDiscount({ isPremium: false }, 150)).toBe(0.1);
+  });
+
+  it('should return 0 when order total <= 100 and not premium', () => {
+    expect(calculateDiscount({ isPremium: false }, 50)).toBe(0);
+  });
+});
+
+// BAD: Only 50% branch coverage
+describe('calculateDiscount', () => {
+  it('should calculate discount', () => {
+    expect(calculateDiscount({ isPremium: true }, 50)).toBe(0.2);
+    expect(calculateDiscount({ isPremium: false }, 50)).toBe(0);
+    // Missing: null user, orderTotal > 100 cases
+  });
+});
+```
+
+**NEVER chase 100% coverage:**
+- 80-90% is optimal (diminishing returns after)
+- Focus on business-critical paths first
+- Ignore defensive error handling you can't trigger
+- Coverage is a guide, not a goal
+
+### CI Integration Pattern
+
+```yaml
+# GOOD: Optimized test pipeline
+name: Test
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+
+      # Step 1: Unit tests (fail fast)
+      - name: Unit tests
+        run: npm run test:unit
+        timeout-minutes: 2
+
+      # Step 2: Integration tests (parallel)
+      - name: Integration tests
+        run: npm run test:integration -- --maxWorkers=4
+        timeout-minutes: 5
+
+      # Step 3: E2E tests (only if unit + integration pass)
+      - name: E2E tests
+        run: npm run test:e2e
+        timeout-minutes: 10
+
+      # Step 4: Coverage check
+      - name: Coverage check
+        run: |
+          npm run test:coverage
+          if [ $(cat coverage/coverage-summary.json | jq '.total.branches.pct') -lt 80 ]; then
+            echo "Branch coverage below 80%"
+            exit 1
+          fi
+
+      # Step 5: Flaky test detection
+      - name: Re-run failures once
+        if: failure()
+        run: npm test -- --onlyFailures
+```
+
+**CI Rules:**
+- Run unit tests FIRST (fastest feedback)
+- Parallelize test suites (--maxWorkers)
+- Fail build on coverage regression (compare against main branch)
+- Re-run failures ONCE (detect flaky tests, don't mask real failures)
+- Separate unit/integration/e2e jobs (fail fast on unit tests)
+
+## Conventions
+
+### Test File Naming
+
+```
+src/
+  services/
+    OrderService.js
+    OrderService.test.js        ← Unit tests next to source
+  api/
+    routes/
+      orders.js
+      orders.test.js             ← Integration tests next to routes
+  __tests__/
+    e2e/
+      checkout-flow.e2e.test.js  ← E2E tests in separate directory
+```
+
+**Rules:**
+- Unit tests: `{module}.test.js` next to source file
+- Integration tests: `{module}.test.js` or `{module}.integration.test.js`
+- E2E tests: `{flow}.e2e.test.js` in `__tests__/e2e/`
+- Factories: `__tests__/factories/{entity}.js`
+- Fixtures: `__tests__/fixtures/{data}.json`
+
+### Test Naming Pattern (CRITICAL: Describe behavior, not implementation)
+
+```javascript
+// GOOD: Behavior-focused names
+describe('OrderService', () => {
+  describe('createOrder', () => {
+    it('should return 201 when valid order data provided', () => {});
+    it('should return 400 when userId is missing', () => {});
+    it('should return 400 when items array is empty', () => {});
+    it('should calculate total by summing item prices', () => {});
+  });
+
+  describe('cancelOrder', () => {
+    it('should set status to cancelled when order is pending', () => {});
+    it('should return 400 when order is already shipped', () => {});
+  });
+});
+
+// BAD: Implementation-focused names (brittle)
+describe('OrderService', () => {
+  it('test createOrder method', () => {});
+  it('should call db.insert', () => {}); // Testing implementation detail
+  it('works correctly', () => {}); // Vague
+  it('order test 1', () => {}); // Meaningless
+});
+```
+
+**Template:** `should [expected behavior] when [condition]`
+
+### Assertion Conventions
+
+```javascript
+// Prefer toBe for primitives
+expect(result.status).toBe(201);
+expect(result.isValid).toBe(true);
+
+// Prefer toEqual for objects/arrays (deep equality)
+expect(result.data).toEqual({ id: 5, name: 'Widget' });
+
+// Prefer toContain for arrays
+expect(user.roles).toContain('admin');
+
+// Prefer toHaveLength for length checks
+expect(errors).toHaveLength(2);
+
+// Prefer toHaveBeenCalledWith for mock verification
+expect(mockDb.insert).toHaveBeenCalledWith(expectedData);
+expect(mockDb.insert).toHaveBeenCalledTimes(1);
+
+// NEVER use toBeTruthy/toBeFalsy for specific values
+expect(result.status).toBe(201); // NOT .toBeTruthy()
+```
+
+## Common Patterns
+
+### 1. Test Isolation (beforeEach/afterEach)
+
+```javascript
+describe('UserService', () => {
+  let service, mockDb;
+
+  beforeEach(() => {
+    mockDb = createMockDb();
+    service = new UserService(mockDb);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks(); // Clear call history
+  });
+
+  it('test 1', () => {
+    // service and mockDb are fresh for EACH test
+  });
+
+  it('test 2', () => {
+    // No shared state from test 1
+  });
+});
+```
+
+### 2. Async Testing (async/await)
+
+```javascript
+// GOOD: async/await (modern, readable)
+it('should fetch user', async () => {
+  const user = await service.getUser(1);
+  expect(user.id).toBe(1);
+});
+
+// BAD: Nested promises (callback hell)
+it('should fetch user', (done) => {
+  service.getUser(1).then((user) => {
+    expect(user.id).toBe(1);
+    done();
+  });
+});
+```
+
+### 3. Error Testing
+
+```javascript
+// GOOD: Test error cases explicitly
+it('should throw when user not found', async () => {
+  mockDb.findById.mockResolvedValue(null);
+
+  await expect(service.getUser(999)).rejects.toThrow('User not found');
+});
+
+it('should return 404 when resource missing', async () => {
+  const response = await request(app).get('/api/users/999');
+
+  expect(response.status).toBe(404);
+  expect(response.body.error).toBe('User not found');
+});
+
+// GOOD: Test error validation
+it('should validate email format', async () => {
+  const response = await request(app)
+    .post('/api/users')
+    .send({ email: 'invalid-email' });
+
+  expect(response.status).toBe(400);
+  expect(response.body.errors).toContainEqual(
+    expect.objectContaining({ field: 'email', message: 'Invalid email format' })
+  );
+});
+```
+
+### 4. Parameterized Tests (test.each)
+
+```javascript
+// GOOD: Reduce duplication with test.each
+describe('calculateDiscount', () => {
+  test.each([
+    [{ isPremium: true }, 100, 0.2],
+    [{ isPremium: false }, 150, 0.1],
+    [{ isPremium: false }, 50, 0],
+    [null, 100, 0]
+  ])('should return %p for user %p with total %p', (user, total, expected) => {
+    expect(calculateDiscount(user, total)).toBe(expected);
+  });
+});
+
+// BAD: Repetitive tests
+it('test case 1', () => {
+  expect(calculateDiscount({ isPremium: true }, 100)).toBe(0.2);
+});
+it('test case 2', () => {
+  expect(calculateDiscount({ isPremium: false }, 150)).toBe(0.1);
+});
+// ... repeated pattern
+```
+
+### 5. Spy Pattern (Verify behavior without mocking)
+
+```javascript
+// GOOD: Spy on real implementation
+it('should call logger when error occurs', async () => {
+  const logger = { error: jest.fn() };
+  const service = new PaymentService(realStripe, logger);
+
+  realStripe.charge = jest.fn().mockRejectedValue(new Error('Payment failed'));
+
+  await expect(service.processPayment(1)).rejects.toThrow();
+
+  expect(logger.error).toHaveBeenCalledWith(
+    expect.stringContaining('Payment failed')
+  );
+});
+```
+
+## Anti-Patterns
+
+### 1. Testing Implementation Details (NEVER do this)
+
+```javascript
+// BAD: Test breaks on refactor even if behavior unchanged
+it('should call db.insert with correct params', () => {
+  service.createOrder(orderData);
+  expect(mockDb.insert).toHaveBeenCalled(); // Implementation detail
+});
+
+// GOOD: Test observable behavior
+it('should create order and return ID', async () => {
+  const result = await service.createOrder(orderData);
+  expect(result.id).toBeGreaterThan(0);
+
+  // Verify side effect (DB state)
+  const order = await db('orders').where({ id: result.id }).first();
+  expect(order.user_id).toBe(orderData.userId);
+});
+```
+
+**Why:** Implementation can change (switch from INSERT to UPSERT, change ORM) but behavior stays same. Test behavior, not implementation.
+
+### 2. Shared Mutable State (NEVER share state between tests)
+
+```javascript
+// BAD: Shared state causes order-dependent failures
+describe('OrderService', () => {
+  let orders = []; // SHARED across tests
+
+  it('test 1', () => {
+    orders.push({ id: 1 });
+    expect(orders).toHaveLength(1);
+  });
+
+  it('test 2', () => {
+    expect(orders).toHaveLength(0); // FAILS if test 1 runs first
+  });
+});
+
+// GOOD: Fresh state for each test
+describe('OrderService', () => {
+  let orders;
+
+  beforeEach(() => {
+    orders = []; // Fresh for EACH test
+  });
+
+  it('test 1', () => {
+    orders.push({ id: 1 });
+    expect(orders).toHaveLength(1);
+  });
+
+  it('test 2', () => {
+    expect(orders).toHaveLength(0); // Always passes
+  });
+});
+```
+
+### 3. Testing Framework Code (NEVER do this)
+
+```javascript
+// BAD: Testing that Express works (not your code)
+it('should have a POST /api/orders route', () => {
+  const routes = app._router.stack.filter(r => r.route);
+  expect(routes.some(r => r.route.path === '/api/orders')).toBe(true);
+});
+
+// GOOD: Test that YOUR route handler works correctly
+it('should create order via POST /api/orders', async () => {
+  const response = await request(app)
+    .post('/api/orders')
+    .send({ userId: 1, items: [{ id: 10, qty: 2 }] });
+
+  expect(response.status).toBe(201);
+  expect(response.body.id).toBeGreaterThan(0);
+});
+```
+
+### 4. Overmocking (Test proves nothing)
+
+```javascript
+// BAD: Everything is mocked
+it('should process payment', async () => {
+  const mockStripe = { charge: jest.fn().mockResolvedValue({ id: 'ch_123' }) };
+  const mockOrderService = { getOrder: jest.fn().mockResolvedValue({ total: 50 }) };
+  const mockUserService = { getUser: jest.fn().mockResolvedValue({ id: 1 }) };
+
+  const processor = new PaymentProcessor(mockStripe, mockOrderService, mockUserService);
+  const result = await processor.processPayment(1);
+
+  expect(result.id).toBe('ch_123'); // Circular: you defined this response
+});
+
+// GOOD: Mock only external dependencies
+it('should process payment via Stripe', async () => {
+  const mockStripe = { charge: jest.fn().mockResolvedValue({ id: 'ch_123' }) };
+
+  // Use REAL internal services
+  const realOrderService = new OrderService(testDb);
+  const realUserService = new UserService(testDb);
+
+  // Seed test data
+  await testDb('users').insert({ id: 1, email: 'test@example.com' });
+  await testDb('orders').insert({ id: 1, user_id: 1, total: 50.00 });
+
+  const processor = new PaymentProcessor(mockStripe, realOrderService, realUserService);
+  const result = await processor.processPayment(1);
+
+  expect(mockStripe.charge).toHaveBeenCalledWith(
+    expect.objectContaining({ amount: 5000 }) // Verify integration
+  );
+});
+```
+
+### 5. Slow Tests in Unit Suite (Move to integration)
+
+```javascript
+// BAD: Unit test that hits real DB (slow, 500ms+)
+describe('OrderService (unit)', () => {
+  it('should create order', async () => {
+    await db('orders').insert({ userId: 1, total: 50 }); // Real DB call
+    // This is an INTEGRATION test
+  });
+});
+
+// GOOD: Fast unit test (<10ms)
+describe('OrderService (unit)', () => {
+  it('should calculate total correctly', () => {
+    const items = [{ price: 10, qty: 2 }, { price: 15, qty: 1 }];
+    const total = OrderService.calculateTotal(items);
+    expect(total).toBe(35);
+  });
+});
+
+// GOOD: Slow test in integration suite
+describe('OrderService (integration)', () => {
+  it('should persist order to database', async () => {
+    const result = await service.createOrder(orderData);
+    const dbOrder = await db('orders').where({ id: result.id }).first();
+    expect(dbOrder.total).toBe(50.00);
+  });
+});
+```
+
+## Integration Notes
+
+**Multi-Session Workflow:**
+
+You are `testing-qa` worker in a clearctx orchestrated team. Follow this protocol:
+
+1. **Check inbox FIRST** (ENFORCED):
+   ```javascript
+   await mcp__multi_session__team_check_inbox({ name: "testing-qa" })
+   ```
+   Required before using artifact/contract tools.
+
+2. **Read shared artifacts**:
+   - `db-schema` from db-dev worker (for test fixtures matching real schema)
+   - `api-contracts` from backend-dev worker (for endpoint integration tests)
+   - `shared-conventions` (for response format, error format, status codes)
+
+3. **Publish test-results artifact**:
+   ```javascript
+   await mcp__multi_session__artifact_publish({
+     artifactId: "test-results",
+     type: "test-results",
+     name: "Test Suite Results",
+     publisher: "testing-qa",
+     data: {
+       summary: {
+         total: 156,
+         passed: 154,
+         failed: 2,
+         skipped: 0
+       },
+       coverage: {
+         lines: 87.5,
+         branches: 82.3,
+         functions: 91.2
+       },
+       duration: "12.4s",
+       failedTests: [
+         { file: "services/OrderService.test.js", test: "should handle concurrent orders", error: "..." }
+       ],
+       files: [
+         "services/OrderService.test.js",
+         "api/routes/orders.test.js",
+         "__tests__/e2e/checkout-flow.e2e.test.js"
+       ]
+     }
+   })
+   ```
+
+4. **Broadcast completion**:
+   ```javascript
+   await mcp__multi_session__team_broadcast({
+     from: "testing-qa",
+     content: "✅ Test suite complete: 154/156 passed (87.5% coverage). 2 failures in OrderService concurrent handling."
+   })
+   ```
+
+5. **File paths**: ALWAYS use relative paths
+   - ✅ `src/services/OrderService.test.js`
+   - ❌ `E:/Projects/app/src/services/OrderService.test.js`
+
+6. **Test file creation**: Create test files NEXT to source files (unless e2e)
+   - Unit: `src/services/OrderService.test.js` (next to `OrderService.js`)
+   - Integration: `src/api/routes/orders.test.js` (next to `orders.js`)
+   - E2E: `__tests__/e2e/checkout-flow.e2e.test.js`
+
+7. **Communicate test failures**: If tests fail due to API contract mismatch, use `team_send_message` to backend-dev:
+   ```javascript
+   await mcp__multi_session__team_send_message({
+     from: "testing-qa",
+     to: "backend-dev",
+     content: "POST /api/orders returning 200 instead of 201 per shared conventions. Expected statusCodes.create=201."
+   })
+   ```
+
+**Dependency Chain:**
+1. db-dev publishes `db-schema` artifact
+2. backend-dev publishes `api-contracts` artifact
+3. testing-qa reads both artifacts → writes tests → publishes `test-results`
+4. Orchestrator verifies via `artifact_readers` that testing-qa consumed upstream artifacts
+
+**Status Management:**
+- Auto-set to "active" on spawn (no action needed)
+- Auto-set to "idle" when session stops (no action needed)
+- Only use `team_update_status` for custom statuses like "blocked"
+
+**Convention Compliance:**
+Always follow `shared-conventions` artifact for:
+- Response format (e.g., `{ data: <result> }`)
+- Error format (e.g., `{ error: <message> }`)
+- Status codes (create=201, read=200, etc.)
+- Date formats, enum values, boolean handling
+
+If a test fails due to convention mismatch, it's likely the implementation is wrong (not your test). Report to orchestrator.