@esimplicitylabs/katalyst-xspec 0.6.0

package/skills/katalyst-bdd-architecture/references/adapters.md

@@ -0,0 +1,310 @@
+# Adapters Reference
+
+Complete reference for all built-in adapters in the Katalyst BDD framework.
+
+## PlaywrightApiAdapter
+
+Implements `ApiPort` using Playwright's `APIRequestContext`.
+
+### Constructor
+
+```typescript
+class PlaywrightApiAdapter implements ApiPort {
+  constructor(private readonly request: APIRequestContext) {}
+}
+```
+
+### Configuration
+
+```typescript
+// In fixtures.ts
+import { createBddTest, PlaywrightApiAdapter } from '@esimplicitylabs/katalyst-xspec';
+
+const test = createBddTest({
+  createApi: ({ apiRequest }) => new PlaywrightApiAdapter(apiRequest),
+});
+```
+
+### Environment Variables
+
+```bash
+API_BASE_URL=http://localhost:3000
+```
+
+### Features
+
+- Automatic JSON serialization/deserialization
+- Header management via World state
+- Response capture for assertions
+
+## PlaywrightUiAdapter
+
+Implements `UiPort` using Playwright's `Page`.
+
+### Constructor
+
+```typescript
+class PlaywrightUiAdapter implements UiPort {
+  constructor(private readonly page: Page) {}
+}
+```
+
+### Configuration
+
+```typescript
+import { createBddTest, PlaywrightUiAdapter } from '@esimplicitylabs/katalyst-xspec';
+
+const test = createBddTest({
+  createUi: ({ page }) => new PlaywrightUiAdapter(page),
+});
+```
+
+### Environment Variables
+
+```bash
+FRONTEND_URL=http://localhost:3000
+BASE_URL=http://localhost:3000
+HEADLESS=true
+```
+
+### Features
+
+- Intelligent element location (by role, label, text, etc.)
+- Automatic waiting for elements
+- Multiple click modes (normal, force, dispatch)
+- Screenshot and debugging support
+
+## TuiTesterAdapter
+
+Implements `TuiPort` using the `tui-tester` library (wraps tmux).
+
+### Constructor
+
+```typescript
+class TuiTesterAdapter implements TuiPort {
+  constructor(config: TuiConfig) {}
+}
+
+type TuiConfig = {
+  command: string[];          // Command to run
+  size?: { cols: number; rows: number };  // Terminal size
+  cwd?: string;               // Working directory
+  env?: Record<string, string>;  // Environment variables
+  debug?: boolean;            // Enable debug output
+  snapshotDir?: string;       // Snapshot directory
+  shell?: string;             // Shell to use
+};
+```
+
+### Configuration
+
+```typescript
+import { createBddTest, TuiTesterAdapter } from '@esimplicitylabs/katalyst-xspec';
+
+const test = createBddTest({
+  createTui: () => new TuiTesterAdapter({
+    command: ['node', 'dist/cli.js'],
+    size: { cols: 100, rows: 30 },
+    cwd: process.cwd(),
+    env: { NODE_ENV: 'test' },
+    debug: false,
+    snapshotDir: './snapshots',
+  }),
+});
+```
+
+### Prerequisites
+
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt-get install tmux
+```
+
+### Environment Variables
+
+```bash
+TUI_COLS=80
+TUI_ROWS=24
+DEBUG=false
+```
+
+### Features
+
+- Full terminal emulation
+- Keyboard input (including modifiers)
+- Screen capture and assertions
+- Snapshot testing
+- Mouse support (for TUI apps that support it)
+
+## UniversalAuthAdapter
+
+Implements `AuthPort` for both API and UI authentication.
+
+### Constructor
+
+```typescript
+class UniversalAuthAdapter implements AuthPort {
+  constructor(private readonly deps: { api: ApiPort; ui: UiPort }) {}
+}
+```
+
+### Configuration
+
+```typescript
+import { createBddTest, UniversalAuthAdapter } from '@esimplicitylabs/katalyst-xspec';
+
+const test = createBddTest({
+  createAuth: ({ api, ui }) => new UniversalAuthAdapter({ api, ui }),
+});
+```
+
+### Environment Variables
+
+```bash
+# Admin credentials
+DEFAULT_ADMIN_USERNAME=admin@example.com
+DEFAULT_ADMIN_PASSWORD=admin123
+
+# User credentials
+DEFAULT_USER_USERNAME=user@example.com
+DEFAULT_USER_PASSWORD=user123
+
+# Auth endpoint
+API_AUTH_LOGIN_PATH=/auth/login
+```
+
+### Behavior
+
+**API Authentication:**
+1. POSTs to `API_AUTH_LOGIN_PATH`
+2. Stores token in `world.headers['Authorization']`
+3. If credentials not set, skips silently with `console.warn`
+
+**UI Authentication:**
+1. Navigates to `UI_LOGIN_PATH` (default: `/login`)
+2. Fills fields by placeholder (configurable via `UI_USERNAME_FIELD`, `UI_PASSWORD_FIELD`)
+3. Clicks login button (configurable via `UI_LOGIN_BUTTON`)
+4. If credentials not set, skips silently with `console.warn`
+
+> **Note:** No hardcoded default credentials are used. All credentials must be set via env vars.
+
+## DefaultCleanupAdapter
+
+Implements `CleanupPort` for automatic resource cleanup.
+
+### Constructor
+
+```typescript
+class DefaultCleanupAdapter implements CleanupPort {
+  constructor(input?: {
+    rules?: CleanupRule[];
+    allowHeuristic?: boolean;
+  }) {}
+}
+
+type CleanupRule = {
+  varMatch: string;  // Variable name pattern
+  method?: 'DELETE' | 'POST' | 'PATCH' | 'PUT';  // Default: DELETE
+  path: string;      // Cleanup path (with {id} placeholder)
+  body?: unknown;    // Optional request body
+};
+```
+
+### Configuration
+
+```typescript
+import { createBddTest, DefaultCleanupAdapter } from '@esimplicitylabs/katalyst-xspec';
+
+const test = createBddTest({
+  createCleanup: () => new DefaultCleanupAdapter({
+    rules: [
+      { varMatch: 'userId', path: '/admin/users/{id}' },
+      { varMatch: 'projectId', path: '/projects/{id}' },
+    ],
+    allowHeuristic: true,
+  }),
+});
+```
+
+### Environment Variables
+
+```bash
+# JSON array of cleanup rules (no built-in rules -- consumers must define their own)
+CLEANUP_RULES='[{"varMatch":"userId","path":"/api/users/{id}"}]'
+
+# Allow heuristic matching
+CLEANUP_ALLOW_ALL=false
+
+# Static auth token for cleanup (alternative to login-based auth)
+CLEANUP_AUTH_TOKEN=your-admin-token
+```
+
+### Behavior
+
+1. Matches variable names against rules (from `CLEANUP_RULES` env var or constructor)
+2. At test teardown, executes cleanup requests (DELETE by default)
+3. Authenticates via `getCleanupAuth` (configurable on `createBddTest`)
+4. Recognizes UUIDs, prefixed IDs, numeric IDs, MongoDB ObjectIDs, CUIDs, and ULIDs
+
+### Heuristic Matching
+
+When `allowHeuristic` is true, the adapter guesses cleanup paths:
+- `userId` → DELETE `/users/{id}`
+- `projectId` → DELETE `/projects/{id}`
+
+## FetchInterceptAuthAdapter
+
+Helper for UI authentication via fetch request interception.
+
+### Functions
+
+```typescript
+// Setup fetch interception with auth data
+async function setupFetchIntercept(
+  page: Page,
+  authData: AuthData,
+  config?: InterceptConfig
+): Promise<void>;
+
+// Bypass auth with specific user
+async function setupBypassAuth(
+  page: Page,
+  userId: string,
+  roles: string[],
+  tenantId?: string
+): Promise<void>;
+
+// Use bearer token
+async function setupBearerAuth(
+  page: Page,
+  token: string
+): Promise<void>;
+```
+
+### Usage
+
+```typescript
+// In a custom auth adapter
+class CustomUiAuthAdapter implements AuthPort {
+  async uiLoginAsAdmin(world: World): Promise<void> {
+    await setupBypassAuth(this.page, 'admin-id', ['admin']);
+  }
+}
+```
+
+### How It Works
+
+1. Injects a script via `page.addInitScript()`
+2. Intercepts all fetch requests
+3. Adds authentication headers automatically
+4. Works without actual login flow
+
+### Benefits
+
+- Faster tests (no login page interaction)
+- Test protected pages directly
+- Switch users mid-test
+- Test role-based access

package/skills/katalyst-bdd-architecture/references/custom-steps.md

@@ -0,0 +1,360 @@
+# Custom Steps Guide
+
+How to create custom step definitions for the Katalyst BDD framework.
+
+## Basic Step Structure
+
+```typescript
+import { Given, When, Then } from '@cucumber/cucumber';
+
+When('I do something', async ({ world }) => {
+  // Step implementation
+});
+```
+
+## Step with Parameters
+
+### String Parameter
+
+```typescript
+When('I click the {string} button', async ({ ui }, buttonName: string) => {
+  await ui.clickButton(buttonName);
+});
+```
+
+**Usage:**
+```gherkin
+When I click the "Submit" button
+When I click the "Cancel" button
+```
+
+### Integer Parameter
+
+```typescript
+Then('the response status should be {int}', async ({ world }, status: number) => {
+  expect(world.lastStatus).toBe(status);
+});
+```
+
+**Usage:**
+```gherkin
+Then the response status should be 200
+Then the response status should be 404
+```
+
+### Multiple Parameters
+
+```typescript
+When('I fill {string} with {string}', async ({ ui }, field: string, value: string) => {
+  await ui.fillLabel(field, value);
+});
+```
+
+**Usage:**
+```gherkin
+When I fill "Email" with "test@example.com"
+```
+
+## Step with Doc String
+
+```typescript
+When('I POST {string} with JSON body:', async ({ api, world }, path: string, docString: string) => {
+  const body = JSON.parse(docString);
+  const result = await api.sendJson('POST', path, body, world.headers);
+  world.lastStatus = result.status;
+  world.lastJson = result.json;
+});
+```
+
+**Usage:**
+```gherkin
+When I POST "/users" with JSON body:
+  """
+  {
+    "name": "Test User",
+    "email": "test@example.com"
+  }
+  """
+```
+
+## Step with Data Table
+
+```typescript
+import { DataTable } from '@cucumber/cucumber';
+
+When('I fill the form:', async ({ ui }, dataTable: DataTable) => {
+  const rows = dataTable.hashes();
+  // rows = [{ Field: 'Email', Value: 'test@...' }, ...]
+  
+  for (const row of rows) {
+    await ui.fillLabel(row.Field, row.Value);
+  }
+});
+```
+
+**Usage:**
+```gherkin
+When I fill the form:
+  | Field    | Value            |
+  | Email    | test@example.com |
+  | Password | secret123        |
+```
+
+### Data Table Methods
+
+```typescript
+// Get as array of hashes (row objects)
+const rows = dataTable.hashes();
+// [{ Field: 'Email', Value: '...' }, { Field: 'Password', Value: '...' }]
+
+// Get raw 2D array
+const raw = dataTable.raw();
+// [['Field', 'Value'], ['Email', '...'], ['Password', '...']]
+
+// Get rows as arrays (without header)
+const rowsArray = dataTable.rows();
+// [['Email', '...'], ['Password', '...']]
+
+// Get as key-value pairs (2 column table)
+const pairs = dataTable.rowsHash();
+// { Email: '...', Password: '...' }
+```
+
+## Tag-Restricted Steps
+
+```typescript
+// Only available in @api scenarios
+When('I make an API call', { tags: '@api' }, async ({ api }) => {
+  // ...
+});
+
+// Available in @api or @hybrid
+When('I GET {string}', { tags: '@api or @hybrid' }, async ({ api, world }, path) => {
+  // ...
+});
+
+// Only available in @ui
+When('I click something', { tags: '@ui' }, async ({ ui }) => {
+  // ...
+});
+
+// Available everywhere (no tag restriction)
+Given('I set variable {string} to {string}', async ({ world }, name, value) => {
+  world.vars[name] = value;
+});
+```
+
+## Available Fixtures
+
+Steps receive these fixtures:
+
+```typescript
+When('my step', async (fixtures) => {
+  const {
+    world,      // World state object
+    api,        // ApiPort adapter
+    ui,         // UiPort adapter
+    tui,        // TuiPort adapter (if configured)
+    auth,       // AuthPort adapter
+    cleanup,    // CleanupPort adapter
+    page,       // Playwright Page (raw)
+    apiRequest, // Playwright APIRequestContext (raw)
+  } = fixtures;
+});
+```
+
+## Using World State
+
+```typescript
+// Store a variable
+Given('I set {string} to {string}', async ({ world }, name, value) => {
+  world.vars[name] = value;
+});
+
+// Read a variable
+When('I use the variable {string}', async ({ world }, name) => {
+  const value = world.vars[name];
+  // Use value...
+});
+
+// Store API response
+When('I make request', async ({ api, world }) => {
+  const result = await api.sendJson('GET', '/endpoint');
+  world.lastStatus = result.status;
+  world.lastJson = result.json;
+  world.lastText = result.text;
+  world.lastHeaders = result.headers;
+});
+
+// Set headers for subsequent requests
+Given('I set auth header', async ({ world }) => {
+  world.headers['Authorization'] = 'Bearer token';
+});
+```
+
+## Variable Interpolation
+
+Use the `interpolate` utility:
+
+```typescript
+import { interpolate } from '@esimplicitylabs/katalyst-xspec';
+
+When('I GET {string}', async ({ api, world }, path) => {
+  // Replaces {varName} with world.vars values
+  const interpolatedPath = interpolate(path, world.vars);
+  await api.sendJson('GET', interpolatedPath);
+});
+```
+
+## Registering Steps
+
+### Register Individual Categories
+
+```typescript
+// steps.ts
+import { test } from './fixtures';
+import {
+  registerApiSteps,
+  registerUiSteps,
+  registerTuiSteps,
+  registerSharedSteps,
+  registerHybridSuite,
+} from '@esimplicitylabs/katalyst-xspec/steps';
+
+// Register specific categories
+registerApiSteps(test);
+registerUiSteps(test);
+registerSharedSteps(test);
+
+export { test };
+```
+
+### Register All Steps
+
+```typescript
+import { test } from './fixtures';
+import { registerAllSteps } from '@esimplicitylabs/katalyst-xspec/steps';
+
+registerAllSteps(test);
+
+export { test };
+```
+
+### Register Custom Steps
+
+```typescript
+// custom-steps.ts
+import { test } from './fixtures';
+import { Given, When, Then } from '@cucumber/cucumber';
+
+// Define custom steps
+When('I do my custom thing', async ({ world }) => {
+  // Implementation
+});
+
+Given('I have custom setup', async ({ api }) => {
+  // Implementation
+});
+
+// Import in steps.ts
+export { test };
+```
+
+## Step Organization
+
+Recommended file structure:
+
+```
+features/steps/
+├── fixtures.ts           # Adapter configuration
+├── steps.ts              # Main step registration
+└── custom/
+    ├── auth.steps.ts     # Custom auth steps
+    ├── data.steps.ts     # Data setup steps
+    └── verify.steps.ts   # Custom verification steps
+```
+
+## Example: Complete Custom Step File
+
+```typescript
+// features/steps/custom/reporting.steps.ts
+import { When, Then } from '@cucumber/cucumber';
+import { expect } from '@playwright/test';
+
+/**
+ * Custom steps for report generation testing
+ */
+
+When('I generate a {string} report', { tags: '@api or @hybrid' }, 
+  async ({ api, world }, reportType: string) => {
+    const result = await api.sendJson('POST', '/reports/generate', {
+      type: reportType,
+      format: 'pdf',
+    }, world.headers);
+    
+    world.lastStatus = result.status;
+    world.lastJson = result.json;
+    
+    if (result.json?.reportId) {
+      world.vars['reportId'] = result.json.reportId;
+    }
+  }
+);
+
+When('I wait for the report to complete', { tags: '@api or @hybrid' },
+  async ({ api, world }) => {
+    const reportId = world.vars['reportId'];
+    let attempts = 0;
+    const maxAttempts = 30;
+    
+    while (attempts < maxAttempts) {
+      const result = await api.sendJson('GET', `/reports/${reportId}`, undefined, world.headers);
+      
+      if (result.json?.status === 'completed') {
+        world.vars['reportUrl'] = result.json.downloadUrl;
+        return;
+      }
+      
+      await new Promise(r => setTimeout(r, 1000));
+      attempts++;
+    }
+    
+    throw new Error('Report generation timed out');
+  }
+);
+
+Then('the report should be downloadable', { tags: '@api or @hybrid' },
+  async ({ api, world }) => {
+    const reportUrl = world.vars['reportUrl'];
+    expect(reportUrl).toBeDefined();
+    
+    const result = await api.sendJson('GET', reportUrl, undefined, world.headers);
+    expect(result.status).toBe(200);
+    expect(result.contentType).toContain('application/pdf');
+  }
+);
+
+When('I view the report in the UI', { tags: '@ui or @hybrid' },
+  async ({ ui, world }) => {
+    const reportId = world.vars['reportId'];
+    await ui.goto(`/reports/${reportId}`);
+  }
+);
+
+Then('I should see the report preview', { tags: '@ui or @hybrid' },
+  async ({ ui }) => {
+    await ui.expectText('Report Preview');
+    await ui.expectElementState('first', 'pdf-viewer', 'locator', 'visible');
+  }
+);
+```
+
+## Best Practices
+
+1. **Keep steps focused** - Each step should do one thing
+2. **Use meaningful names** - Steps should read like English
+3. **Handle errors gracefully** - Provide helpful error messages
+4. **Use World for state** - Don't use module-level variables
+5. **Tag appropriately** - Restrict steps to relevant test types
+6. **Document complex steps** - Add JSDoc comments
+7. **Reuse existing steps** - Don't duplicate functionality