@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/test-master/steering/automation-frameworks.md

@@ -0,0 +1,297 @@
+# Automation Frameworks
+
+> Reference for: Test Master
+> Load when: Framework design, automation patterns, scaling, maintenance strategies
+
+## Advanced Framework Patterns
+
+### Screenplay Pattern
+```typescript
+// Better separation of concerns than POM
+export class Actor {
+  constructor(private page: Page) {}
+  attemptsTo(...tasks: Task[]) {
+    return Promise.all(tasks.map(t => t.performAs(this)));
+  }
+}
+
+class Login implements Task {
+  constructor(private email: string, private password: string) {}
+  async performAs(actor: Actor) {
+    await actor.page.getByLabel('Email').fill(this.email);
+    await actor.page.getByLabel('Password').fill(this.password);
+    await actor.page.getByRole('button', { name: 'Login' }).click();
+  }
+}
+
+// Clear, maintainable test code
+await new Actor(page).attemptsTo(new Login('user@test.com', 'pass'));
+```
+
+### Keyword-Driven Testing
+```typescript
+const keywords = {
+  NAVIGATE: (page, url) => page.goto(url),
+  CLICK: (page, selector) => page.click(selector),
+  TYPE: (page, selector, text) => page.fill(selector, text),
+  VERIFY: (page, selector) => expect(page.locator(selector)).toBeVisible(),
+};
+
+// Data drives execution - ideal for non-technical authors
+const steps = [
+  { keyword: 'NAVIGATE', args: ['/login'] },
+  { keyword: 'TYPE', args: ['#email', 'user@test.com'] },
+  { keyword: 'CLICK', args: ['#submit'] },
+];
+
+for (const step of steps) await keywords[step.keyword](page, ...step.args);
+```
+
+### Model-Based Testing
+```typescript
+// State machine defines valid transitions
+const cartModel = {
+  empty: { addItem: 'hasItems' },
+  hasItems: { addItem: 'hasItems', removeItem: 'hasItems|empty', checkout: 'checkingOut' },
+  checkingOut: { confirm: 'complete', cancel: 'hasItems' },
+};
+
+// Generate comprehensive test paths automatically
+const testPaths = generatePathsFromModel(cartModel);
+```
+
+## Maintenance Strategies
+
+### Self-Healing Locators
+```typescript
+// Multi-strategy finder with automatic fallback
+async function findElement(page: Page, strategies: string[]): Promise<Locator> {
+  for (const selector of strategies) {
+    const el = page.locator(selector);
+    if (await el.count() > 0) return el;
+  }
+  throw new Error(`Not found: ${strategies.join(', ')}`);
+}
+
+// Usage: tries best -> good -> fallback
+const submit = await findElement(page, [
+  '[data-testid="submit"]',     // Best: stable test ID
+  'button:has-text("Submit")',  // Good: semantic
+  'button.primary',             // Fallback: CSS
+]);
+```
+
+### Error Recovery & Smart Retry
+```typescript
+// Auto-retry with recovery actions
+async function clickWithRecovery(page: Page, selector: string, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      await page.click(selector, { timeout: 5000 });
+      return;
+    } catch (e) {
+      if (i === retries - 1) throw e;
+      await page.reload();
+      await page.waitForLoadState('networkidle');
+    }
+  }
+}
+
+// Exponential backoff for flaky operations
+async function retryWithBackoff<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === retries - 1) throw e;
+      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
+    }
+  }
+}
+```
+
+## Scaling Strategies
+
+### Parallel & Distributed Execution
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: process.env.CI ? 8 : 4,
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  
+  // Shard tests across multiple machines
+  shard: process.env.SHARD ? {
+    current: parseInt(process.env.SHARD_INDEX),
+    total: parseInt(process.env.SHARD_TOTAL),
+  } : undefined,
+});
+```
+
+```yaml
+# GitHub Actions: distribute across 5 workers
+strategy:
+  matrix:
+    shard: [1, 2, 3, 4, 5]
+steps:
+  - run: npx playwright test --shard=${{ matrix.shard }}/5
+```
+
+### Resource Optimization
+```typescript
+// Reuse browser contexts for faster execution
+let browser: Browser;
+let context: BrowserContext;
+
+test.beforeAll(async () => {
+  browser = await chromium.launch();
+  context = await browser.newContext();
+});
+
+test('test 1', async () => {
+  const page = await context.newPage();
+  // Test logic
+  await page.close();
+});
+
+test.afterAll(async () => {
+  await context.close();
+  await browser.close();
+});
+```
+
+## CI/CD Integration
+
+### Complete Pipeline
+```yaml
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shard: [1, 2, 3, 4]
+    
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      
+      - run: npx playwright test --shard=${{ matrix.shard }}/4
+        env:
+          CI: true
+      
+      - uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: report-${{ matrix.shard }}
+          path: playwright-report/
+```
+
+### Test Data Factories
+```typescript
+export class UserFactory {
+  static create(overrides?: Partial<User>): User {
+    return {
+      id: faker.string.uuid(),
+      email: faker.internet.email(),
+      name: faker.person.fullName(),
+      role: 'user',
+      ...overrides,
+    };
+  }
+
+  static createMany(count: number) {
+    return Array.from({ length: count }, () => this.create());
+  }
+}
+
+// Seed test data
+test.beforeEach(async ({ page }) => {
+  await page.request.post('/api/test/seed', {
+    data: { users: UserFactory.createMany(10) },
+  });
+});
+```
+
+## Team Enablement
+
+### Training Program
+```markdown
+**Week 1-2**: Framework basics, page objects, first test
+**Week 3-4**: Data-driven, API integration, CI/CD
+**Week 5-6**: Performance, error handling, scaling
+**Ongoing**: Code reviews, knowledge sharing
+```
+
+### Code Review Checklist
+```markdown
+- [ ] Independent tests (no order dependency)
+- [ ] Semantic locators (getByRole, getByLabel)
+- [ ] Proper waits (no arbitrary timeouts)
+- [ ] Error cases tested
+- [ ] Test data cleanup
+- [ ] Meaningful test names
+- [ ] Page objects updated
+```
+
+## Automation Strategy
+
+### ROI Calculation
+```typescript
+const manual = { timePerRun: 30, runsPerSprint: 10 };
+const automation = { development: 120, maintenance: 5 };
+
+const timeSaved = (manual.timePerRun * manual.runsPerSprint) - automation.maintenance;
+const breakEven = Math.ceil(automation.development / timeSaved);
+const annualSavings = (timeSaved * 26 - automation.development) / 60; // hours
+
+// Example: Break-even in 1 sprint, save 110 hours/year
+```
+
+### Selection Criteria
+```markdown
+**Automate**: Repetitive, stable UI, critical paths, data-driven, positive ROI
+**Don't Automate**: Exploratory, changing UI, one-time, usability, negative ROI
+```
+
+## Reporting & Metrics
+
+### Custom Reporter
+```typescript
+class MetricsReporter implements Reporter {
+  onTestEnd(test: TestCase, result: TestResult) {
+    this.sendMetrics({
+      name: test.title,
+      duration: result.duration,
+      status: result.status,
+      retries: result.retry,
+    });
+  }
+}
+```
+
+## Quick Reference
+
+| Pattern | Best For | Complexity |
+|---------|----------|-----------|
+| Page Object | Reusable components | Medium |
+| Screenplay | Complex workflows | High |
+| Keyword-Driven | Non-tech testers | Low |
+| Model-Based | State machines | High |
+
+| Scaling | Use Case |
+|---------|----------|
+| Parallel | Reduce time |
+| Distributed | Large suites |
+| Cloud | Cross-browser |
+| Resource Reuse | Speed |
+
+| Tool | Category |
+|------|----------|
+| Playwright, Cypress | Web E2E |
+| Appium, Detox | Mobile |
+| k6, Gatling | Performance |

package/Ai Agent Workflow/powers/test-master/steering/e2e-testing.md

@@ -0,0 +1,131 @@
+# E2E Testing
+
+> Reference for: Test Master
+> Load when: E2E strategy, user flow testing
+
+## E2E Test Strategy
+
+```typescript
+// Critical user paths to test
+const criticalPaths = [
+  'User registration and login',
+  'Core product/service workflow',
+  'Payment/checkout flow',
+  'Settings and profile management',
+];
+```
+
+## User Flow Testing
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('User Registration Flow', () => {
+  test('complete registration', async ({ page }) => {
+    await page.goto('/register');
+
+    await page.getByLabel('Email').fill('new@example.com');
+    await page.getByLabel('Password').fill('SecurePass123!');
+    await page.getByLabel('Confirm Password').fill('SecurePass123!');
+    await page.getByRole('button', { name: 'Register' }).click();
+
+    await expect(page).toHaveURL(/dashboard/);
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('shows validation errors', async ({ page }) => {
+    await page.goto('/register');
+
+    await page.getByLabel('Email').fill('invalid');
+    await page.getByRole('button', { name: 'Register' }).click();
+
+    await expect(page.getByText('Invalid email')).toBeVisible();
+  });
+});
+```
+
+## Checkout Flow
+
+```typescript
+test.describe('Checkout Flow', () => {
+  test('complete purchase', async ({ page }) => {
+    // Add to cart
+    await page.goto('/products/123');
+    await page.getByRole('button', { name: 'Add to Cart' }).click();
+    await expect(page.getByTestId('cart-count')).toHaveText('1');
+
+    // Checkout
+    await page.goto('/cart');
+    await page.getByRole('button', { name: 'Checkout' }).click();
+
+    // Payment
+    await page.getByLabel('Card Number').fill('4242424242424242');
+    await page.getByLabel('Expiry').fill('12/25');
+    await page.getByLabel('CVC').fill('123');
+    await page.getByRole('button', { name: 'Pay' }).click();
+
+    // Confirmation
+    await expect(page).toHaveURL(/order-confirmation/);
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  });
+});
+```
+
+## Test Data Management
+
+```typescript
+// fixtures/testData.ts
+export const testUsers = {
+  standard: {
+    email: 'standard@test.com',
+    password: 'TestPass123!',
+  },
+  admin: {
+    email: 'admin@test.com',
+    password: 'AdminPass123!',
+  },
+};
+
+// Test setup
+test.beforeEach(async ({ page }) => {
+  // Seed test data
+  await page.request.post('/api/test/seed');
+});
+
+test.afterEach(async ({ page }) => {
+  // Clean up
+  await page.request.post('/api/test/cleanup');
+});
+```
+
+## Cross-Browser Testing
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+    { name: 'mobile-safari', use: { ...devices['iPhone 13'] } },
+  ],
+});
+```
+
+## Quick Reference
+
+| Pattern | When to Use |
+|---------|-------------|
+| Happy path | Critical user journeys |
+| Error handling | Form validation, API errors |
+| Edge cases | Empty states, max limits |
+| Cross-browser | Before major releases |
+| Mobile | Responsive features |
+
+| Priority | Test Coverage |
+|----------|---------------|
+| **P0** | Registration, login, core feature |
+| **P1** | Payment, settings, common flows |
+| **P2** | Edge cases, admin features |
+| **P3** | Rare scenarios |

package/Ai Agent Workflow/powers/test-master/steering/integration-testing.md

@@ -0,0 +1,123 @@
+# Integration Testing
+
+> Reference for: Test Master
+> Load when: API testing, Supertest, database testing
+
+## API Testing (Supertest)
+
+```typescript
+import request from 'supertest';
+import { app } from '../app';
+
+describe('POST /api/users', () => {
+  it('creates user with valid data', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'test@test.com', name: 'Test' })
+      .expect(201);
+
+    expect(response.body).toMatchObject({
+      email: 'test@test.com',
+      name: 'Test',
+    });
+    expect(response.body.id).toBeDefined();
+  });
+
+  it('returns 400 for invalid email', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'invalid', name: 'Test' })
+      .expect(400);
+
+    expect(response.body.error).toContain('email');
+  });
+
+  it('returns 401 without auth token', async () => {
+    await request(app)
+      .get('/api/users/me')
+      .expect(401);
+  });
+});
+```
+
+## Authenticated Requests
+
+```typescript
+describe('Protected endpoints', () => {
+  let authToken: string;
+
+  beforeAll(async () => {
+    const response = await request(app)
+      .post('/api/auth/login')
+      .send({ email: 'test@test.com', password: 'password' });
+    authToken = response.body.token;
+  });
+
+  it('accesses protected route', async () => {
+    await request(app)
+      .get('/api/users/me')
+      .set('Authorization', `Bearer ${authToken}`)
+      .expect(200);
+  });
+});
+```
+
+## Database Testing
+
+```typescript
+import { db } from '../database';
+
+describe('UserRepository', () => {
+  beforeEach(async () => {
+    await db.query('DELETE FROM users');
+  });
+
+  afterAll(async () => {
+    await db.end();
+  });
+
+  it('creates and retrieves user', async () => {
+    const user = await userRepo.create({
+      email: 'test@test.com',
+      name: 'Test',
+    });
+
+    const found = await userRepo.findById(user.id);
+    expect(found).toEqual(user);
+  });
+});
+```
+
+## pytest API Testing
+
+```python
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient):
+    response = await client.post("/api/users/", json={
+        "email": "test@example.com",
+        "name": "Test"
+    })
+    assert response.status_code == 201
+    assert response.json()["email"] == "test@example.com"
+
+@pytest.mark.asyncio
+async def test_invalid_email(client: AsyncClient):
+    response = await client.post("/api/users/", json={
+        "email": "invalid",
+        "name": "Test"
+    })
+    assert response.status_code == 422
+```
+
+## Quick Reference
+
+| Method | Purpose |
+|--------|---------|
+| `.send(body)` | Send request body |
+| `.set(header, value)` | Set header |
+| `.expect(status)` | Assert status code |
+| `.expect('Content-Type', /json/)` | Assert header |
+| `response.body` | Parsed JSON body |

package/Ai Agent Workflow/powers/test-master/steering/performance-testing.md

@@ -0,0 +1,121 @@
+# Performance Testing
+
+> Reference for: Test Master
+> Load when: Load testing, k6, benchmarking
+
+## k6 Load Test
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '30s', target: 20 },   // Ramp up to 20 users
+    { duration: '1m', target: 20 },    // Stay at 20 users
+    { duration: '30s', target: 0 },    // Ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500'],  // 95% requests under 500ms
+    http_req_failed: ['rate<0.01'],    // <1% errors
+  },
+};
+
+export default function () {
+  const res = http.get('http://localhost:3000/api/users');
+
+  check(res, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 200ms': (r) => r.timings.duration < 200,
+  });
+
+  sleep(1);
+}
+```
+
+## Stress Test
+
+```javascript
+export const options = {
+  stages: [
+    { duration: '2m', target: 100 },   // Ramp to 100 users
+    { duration: '5m', target: 100 },   // Stay at 100
+    { duration: '2m', target: 200 },   // Push to 200
+    { duration: '5m', target: 200 },   // Stay at 200
+    { duration: '2m', target: 0 },     // Ramp down
+  ],
+};
+```
+
+## Spike Test
+
+```javascript
+export const options = {
+  stages: [
+    { duration: '10s', target: 10 },   // Normal load
+    { duration: '1m', target: 10 },
+    { duration: '10s', target: 200 },  // Spike!
+    { duration: '3m', target: 200 },
+    { duration: '10s', target: 10 },   // Scale down
+    { duration: '3m', target: 10 },
+    { duration: '10s', target: 0 },
+  ],
+};
+```
+
+## API Testing with Auth
+
+```javascript
+import http from 'k6/http';
+
+export function setup() {
+  const loginRes = http.post('http://localhost:3000/api/login', {
+    email: 'test@test.com',
+    password: 'password',
+  });
+  return { token: loginRes.json('token') };
+}
+
+export default function (data) {
+  const params = {
+    headers: { Authorization: `Bearer ${data.token}` },
+  };
+
+  http.get('http://localhost:3000/api/protected', params);
+}
+```
+
+## Thresholds Reference
+
+```javascript
+thresholds: {
+  // Response time
+  http_req_duration: ['p(95)<500', 'p(99)<1000'],
+
+  // Error rate
+  http_req_failed: ['rate<0.01'],
+
+  // Throughput
+  http_reqs: ['rate>100'],
+
+  // Custom metrics
+  'http_req_duration{name:login}': ['p(95)<200'],
+}
+```
+
+## Quick Reference
+
+| Metric | Description |
+|--------|-------------|
+| `http_req_duration` | Response time |
+| `http_req_failed` | Failed requests rate |
+| `http_reqs` | Request rate |
+| `p(95)` | 95th percentile |
+| `rate` | Rate per second |
+
+| Test Type | Purpose |
+|-----------|---------|
+| Load | Normal expected load |
+| Stress | Find breaking point |
+| Spike | Sudden traffic surge |
+| Soak | Long duration stability |