@hailer/mcp 1.1.12 → 1.1.13

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

@@ -1,630 +0,0 @@
----
-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.