@hailer/mcp 1.1.14 → 1.1.16

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

@@ -0,0 +1,630 @@
+---
+name: testing-patterns
+description: Testing patterns for Hailer projects - vitest for function fields, playwright for apps, build verification
+version: 1.0.0
+triggers: Run tests, vitest, playwright, test failure, build error, coverage
+---
+
+# Testing Patterns
+
+## Overview
+
+| Project Type | Test Framework | Location |
+|--------------|---------------|----------|
+| SDK (function fields) | Vitest | `workspace/[Workflow]/main.test.ts` |
+| Apps (E2E) | Playwright | `apps/[app]/test/` or `test/` |
+| Apps (unit) | Vitest | `apps/[app]/src/**/*.test.ts` |
+
+---
+
+## Vitest - Function Field Tests
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Watch mode (re-run on changes)
+npm run test:watch
+
+# Interactive UI
+npm run test:ui
+
+# Specific file
+npm test -- workspace/Orders_abc/main.test.ts
+
+# Specific test by name
+npm test -- -t "calculates total"
+
+# With coverage
+npm test -- --coverage
+
+# Verbose output
+npm test -- --reporter=verbose
+```
+
+### Test File Structure
+
+```typescript
+// workspace/Orders_abc/main.test.ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { total_cost_abc } from './functions/total_cost_abc';
+import { discount_def } from './functions/discount_def';
+
+describe('total_cost_abc', () => {
+  describe('basic calculations', () => {
+    it('multiplies quantity by unit price', () => {
+      const result = total_cost_abc({
+        quantity: 10,
+        unitPrice: 25.50
+      });
+      expect(result).toBe(255);
+    });
+
+    it('returns 0 for zero quantity', () => {
+      const result = total_cost_abc({
+        quantity: 0,
+        unitPrice: 100
+      });
+      expect(result).toBe(0);
+    });
+  });
+
+  describe('null handling', () => {
+    it('handles null quantity', () => {
+      const result = total_cost_abc({
+        quantity: null,
+        unitPrice: 50
+      });
+      expect(result).toBe(0);
+    });
+
+    it('handles undefined unit price', () => {
+      const result = total_cost_abc({
+        quantity: 10,
+        unitPrice: undefined
+      });
+      expect(result).toBe(0);
+    });
+
+    it('handles both null', () => {
+      const result = total_cost_abc({
+        quantity: null,
+        unitPrice: null
+      });
+      expect(result).toBe(0);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles string numbers', () => {
+      const result = total_cost_abc({
+        quantity: '10',
+        unitPrice: '5'
+      } as any);
+      expect(result).toBe(50);
+    });
+
+    it('handles negative values', () => {
+      const result = total_cost_abc({
+        quantity: -5,
+        unitPrice: 10
+      });
+      expect(result).toBe(-50);
+    });
+  });
+});
+```
+
+### Testing Backlink Aggregations
+
+```typescript
+describe('total_from_invoices_abc', () => {
+  it('sums array of invoice amounts', () => {
+    const result = total_from_invoices_abc({
+      invoiceAmounts: [100, 200, 300]
+    });
+    expect(result).toBe(600);
+  });
+
+  it('handles empty array', () => {
+    const result = total_from_invoices_abc({
+      invoiceAmounts: []
+    });
+    expect(result).toBe(0);
+  });
+
+  it('handles null values in array', () => {
+    const result = total_from_invoices_abc({
+      invoiceAmounts: [100, null, 200, undefined, 300]
+    });
+    expect(result).toBe(600);
+  });
+
+  it('handles undefined array', () => {
+    const result = total_from_invoices_abc({
+      invoiceAmounts: undefined
+    });
+    expect(result).toBe(0);
+  });
+});
+```
+
+### Testing Parallel Arrays
+
+```typescript
+describe('weighted_average_abc', () => {
+  it('calculates weighted average from parallel arrays', () => {
+    // Arrays from same source workflow are guaranteed same length
+    const result = weighted_average_abc({
+      values: [80, 90, 70],
+      weights: [1, 2, 1]
+    });
+    // (80*1 + 90*2 + 70*1) / (1+2+1) = 330/4 = 82.5
+    expect(result).toBe(82.5);
+  });
+
+  it('handles null values at same index', () => {
+    const result = weighted_average_abc({
+      values: [80, null, 70],
+      weights: [1, 2, 1]  // Weight at index 1 should be ignored
+    });
+    // Should skip index 1 entirely
+    expect(result).toBe(75); // (80*1 + 70*1) / 2
+  });
+});
+```
+
+### Testing JSON Output Functions
+
+```typescript
+describe('line_items_json_abc', () => {
+  it('returns valid JSON string', () => {
+    const result = line_items_json_abc({
+      names: ['Item A', 'Item B'],
+      quantities: [2, 3],
+      prices: [10, 20]
+    });
+
+    const parsed = JSON.parse(result);
+    expect(parsed).toEqual([
+      { name: 'Item A', quantity: 2, price: 10 },
+      { name: 'Item B', quantity: 3, price: 20 }
+    ]);
+  });
+
+  it('returns empty array JSON for no items', () => {
+    const result = line_items_json_abc({
+      names: [],
+      quantities: [],
+      prices: []
+    });
+    expect(result).toBe('[]');
+  });
+});
+```
+
+---
+
+## Playwright - App E2E Tests
+
+### Running Tests
+
+```bash
+# Run all tests
+npm run test
+
+# With UI
+npm run test:open
+
+# Headed (see browser)
+npm run test -- --headed
+
+# Specific file
+npm run test -- test/suites/dashboard.spec.ts
+
+# Specific test
+npm run test -- -g "displays activity count"
+
+# Debug mode
+npm run test -- --debug
+
+# Generate report
+npm run test -- --reporter=html
+npx playwright show-report
+```
+
+### Test File Structure
+
+```typescript
+// test/suites/dashboard.spec.ts
+import { test, expect } from '@playwright/test';
+import { login, setupTestData } from '../helpers/setup';
+
+test.describe('Dashboard', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page);
+    await page.goto('/');
+    await page.waitForSelector('[data-testid="dashboard"]');
+  });
+
+  test('displays activity count', async ({ page }) => {
+    const count = page.locator('[data-testid="activity-count"]');
+    await expect(count).toBeVisible();
+    await expect(count).toHaveText(/\d+/);
+  });
+
+  test('shows workflow list', async ({ page }) => {
+    const workflows = page.locator('[data-testid="workflow-item"]');
+    await expect(workflows).toHaveCount.greaterThan(0);
+  });
+
+  test('navigates to workflow on click', async ({ page }) => {
+    await page.click('[data-testid="workflow-item"]:first-child');
+    await expect(page).toHaveURL(/\/workflow\//);
+  });
+});
+```
+
+### Page Object Pattern
+
+```typescript
+// test/locators/Dashboard.ts
+import { Page, Locator } from '@playwright/test';
+
+export class DashboardPage {
+  readonly page: Page;
+  readonly activityCount: Locator;
+  readonly workflowList: Locator;
+  readonly searchInput: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.activityCount = page.locator('[data-testid="activity-count"]');
+    this.workflowList = page.locator('[data-testid="workflow-list"]');
+    this.searchInput = page.locator('[data-testid="search-input"]');
+  }
+
+  async goto() {
+    await this.page.goto('/');
+    await this.page.waitForSelector('[data-testid="dashboard"]');
+  }
+
+  async search(query: string) {
+    await this.searchInput.fill(query);
+    await this.searchInput.press('Enter');
+  }
+
+  async getWorkflowCount(): Promise<number> {
+    return this.workflowList.locator('[data-testid="workflow-item"]').count();
+  }
+}
+
+// Usage in test
+test('search filters workflows', async ({ page }) => {
+  const dashboard = new DashboardPage(page);
+  await dashboard.goto();
+
+  const initialCount = await dashboard.getWorkflowCount();
+  await dashboard.search('Orders');
+
+  const filteredCount = await dashboard.getWorkflowCount();
+  expect(filteredCount).toBeLessThanOrEqual(initialCount);
+});
+```
+
+### Test Helpers
+
+```typescript
+// test/helpers/setup.ts
+import { Page } from '@playwright/test';
+
+export async function login(page: Page) {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', process.env.TEST_EMAIL!);
+  await page.fill('[data-testid="password"]', process.env.TEST_PASSWORD!);
+  await page.click('[data-testid="login-button"]');
+  await page.waitForURL('/');
+}
+
+export async function createTestActivity(page: Page, workflowId: string, data: any) {
+  // Create via API for faster setup
+  const response = await page.request.post('/api/activities', {
+    data: { workflowId, ...data }
+  });
+  return response.json();
+}
+
+export async function cleanupTestData(page: Page, activityIds: string[]) {
+  for (const id of activityIds) {
+    await page.request.delete(`/api/activities/${id}`);
+  }
+}
+```
+
+---
+
+## Build Verification
+
+### Commands
+
+```bash
+# TypeScript compilation
+npm run build
+
+# Type check only (no output)
+npx tsc --noEmit
+
+# ESLint
+npm run lint
+npm run lint -- --fix
+
+# All checks
+npm run build && npm run lint && npm test
+```
+
+### Common Build Errors
+
+**Cannot find module**
+```
+error TS2307: Cannot find module './utils' or its corresponding type declarations.
+```
+Fix: Check import path, ensure file exists, run `npm install`
+
+**Type mismatch**
+```
+error TS2322: Type 'string' is not assignable to type 'number'.
+```
+Fix: Check variable types, add type assertion or fix logic
+
+**Missing property**
+```
+error TS2339: Property 'value' does not exist on type 'Field'.
+```
+Fix: Add optional chaining (`?.`) or check type definition
+
+---
+
+## Common Test Failures & Fixes
+
+### Vitest Failures
+
+**TypeError: Cannot read property of undefined**
+```typescript
+// Problem
+const total = dep.quantity * dep.price;
+
+// Fix
+const qty = Number(dep.quantity) || 0;
+const price = Number(dep.price) || 0;
+const total = qty * price;
+```
+
+**Expected X but received Y**
+```typescript
+// Check calculation logic
+// Check return type (string vs number)
+// Check floating point: use toBeCloseTo() for decimals
+expect(result).toBeCloseTo(expected, 2);
+```
+
+**Test timeout**
+```typescript
+// Increase timeout for slow tests
+test('slow operation', async () => {
+  // ...
+}, 30000); // 30 second timeout
+```
+
+### Playwright Failures
+
+**Timeout waiting for selector**
+```typescript
+// Problem
+await page.click('[data-testid="submit"]');
+
+// Fix - wait first
+await page.waitForSelector('[data-testid="submit"]');
+await page.click('[data-testid="submit"]');
+
+// Or use auto-waiting locator
+await page.locator('[data-testid="submit"]').click();
+```
+
+**Element not visible**
+```typescript
+// Scroll into view
+await page.locator('[data-testid="element"]').scrollIntoViewIfNeeded();
+await page.click('[data-testid="element"]');
+```
+
+**Navigation timeout**
+```typescript
+// Increase navigation timeout
+await page.goto('/', { timeout: 60000 });
+
+// Or wait for specific element instead
+await page.goto('/');
+await page.waitForSelector('[data-testid="loaded"]', { timeout: 60000 });
+```
+
+---
+
+## Output Parsing
+
+### Vitest Output
+
+```
+ ✓ workspace/Orders_abc/main.test.ts (8)
+   ✓ total_cost_abc (4)
+     ✓ multiplies quantity by price
+     ✓ handles null quantity
+     ✓ handles undefined price
+     ✓ handles string numbers
+   ✗ discount_abc (4)
+     ✓ applies percentage discount
+     ✓ applies fixed discount
+     ✗ handles negative discount
+       AssertionError: expected 100 to be 0
+     ✓ caps at total amount
+
+ Test Files  1 passed (1)
+ Tests       7 passed | 1 failed (8)
+ Time        1.23s
+```
+
+**Extract:**
+- Total: 8
+- Passed: 7
+- Failed: 1
+- Failed test: "discount_abc > handles negative discount"
+- Error: "expected 100 to be 0"
+
+### Playwright Output
+
+```
+Running 12 tests using 4 workers
+
+  ✓  1 login.spec.ts:5:1 › Login › shows form (1.2s)
+  ✓  2 login.spec.ts:15:1 › Login › logs in (2.3s)
+  ✗  3 dashboard.spec.ts:8:1 › Dashboard › shows count (10.0s)
+
+  1 failed
+    dashboard.spec.ts:8:1 › Dashboard › shows count
+    Timeout of 10000ms exceeded.
+    waiting for locator('[data-testid="activity-count"]')
+```
+
+**Extract:**
+- Total: 12
+- Passed: 2 (shown)
+- Failed: 1
+- Failed: "Dashboard > shows count"
+- Error: Timeout waiting for selector
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Unit tests
+        run: npm test -- --coverage
+
+      - name: Install Playwright
+        run: npx playwright install --with-deps
+
+      - name: E2E tests
+        run: npm run test:e2e
+        env:
+          TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
+          TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+```
+
+---
+
+## Best Practices
+
+1. **Test null/undefined inputs** - Every function field test should cover these
+2. **Use data-testid** - More stable than CSS selectors
+3. **Page Objects** - Reduce duplication in E2E tests
+4. **Parallel tests** - Playwright runs in parallel by default
+5. **Test isolation** - Each test should be independent
+6. **CI integration** - Run tests on every PR
+7. **Coverage tracking** - Monitor test coverage over time
+
+---
+
+## Test Data Creation Order
+
+**ActivityLink targets must exist before creating linking activities.**
+
+When creating test data for workflows with relationships, follow this order:
+
+```
+1. Customers (no dependencies)
+2. Contacts + Products (parallel - both link to Customers)
+3. Deals (links to Customers)
+4. Deal Lines (links to Deals + Products)
+5. Activities with links (targets must exist first)
+```
+
+### Example Test Setup
+
+```typescript
+// test/helpers/test-data.ts
+export async function createTestData(hailer: HailerClient) {
+  // 1. Create independent entities first
+  const customer = await hailer.activity.create({
+    workflow: WorkflowIds.customers,
+    fields: { name: 'Test Customer' }
+  });
+
+  // 2. Create entities that link to customer (can be parallel)
+  const [contact, product] = await Promise.all([
+    hailer.activity.create({
+      workflow: WorkflowIds.contacts,
+      fields: {
+        name: 'Test Contact',
+        customer: customer._id  // Link to existing customer
+      }
+    }),
+    hailer.activity.create({
+      workflow: WorkflowIds.products,
+      fields: { name: 'Test Product', price: 100 }
+    })
+  ]);
+
+  // 3. Create deal (links to customer)
+  const deal = await hailer.activity.create({
+    workflow: WorkflowIds.deals,
+    fields: {
+      name: 'Test Deal',
+      customer: customer._id
+    }
+  });
+
+  // 4. Create deal lines (links to deal + product)
+  const dealLine = await hailer.activity.create({
+    workflow: WorkflowIds.deal_lines,
+    fields: {
+      deal: deal._id,
+      product: product._id,
+      quantity: 5
+    }
+  });
+
+  return { customer, contact, product, deal, dealLine };
+}
+```
+
+**Common mistake:** Creating a Deal Line before the Deal exists → ActivityLink validation fails.