@delorenj/pjangler 1.2.25 → 1.3.0

package/templates/commonproject/_bmad/bmm/testarch/knowledge/log.md

@@ -1,429 +0,0 @@
-# Log Utility
-
-## Principle
-
-Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
-
-## Rationale
-
-Console.log in Playwright tests has limitations:
-
-- Not visible in HTML reports
-- No test step integration
-- No structured output
-- Lost in terminal noise during CI
-
-The `log` utility provides:
-
-- **Report integration**: Logs appear in Playwright HTML reports
-- **Test step decoration**: `log.step()` creates collapsible steps in UI
-- **Object logging**: Automatically formats objects/arrays
-- **Multiple levels**: info, step, success, warning, error, debug
-- **Optional console**: Can disable console output but keep report logs
-
-## Quick Start
-
-```typescript
-import { log } from '@seontechnologies/playwright-utils';
-
-// Basic logging
-await log.info('Starting test');
-await log.step('Test step shown in Playwright UI');
-await log.success('Operation completed');
-await log.warning('Something to note');
-await log.error('Something went wrong');
-await log.debug('Debug information');
-```
-
-## Pattern Examples
-
-### Example 1: Basic Logging Levels
-
-**Context**: Log different types of messages throughout test execution.
-
-**Implementation**:
-
-```typescript
-import { log } from '@seontechnologies/playwright-utils';
-
-test('logging demo', async ({ page }) => {
-  await log.step('Navigate to login page');
-  await page.goto('/login');
-
-  await log.info('Entering credentials');
-  await page.fill('#username', 'testuser');
-
-  await log.success('Login successful');
-
-  await log.warning('Rate limit approaching');
-
-  await log.debug({ userId: '123', sessionId: 'abc' });
-
-  // Errors still throw but get logged first
-  try {
-    await page.click('#nonexistent');
-  } catch (error) {
-    await log.error('Click failed', false); // false = no console output
-    throw error;
-  }
-});
-```
-
-**Key Points**:
-
-- `step()` creates collapsible steps in Playwright UI
-- `info()`, `success()`, `warning()` for different message types
-- `debug()` for detailed data (objects/arrays)
-- `error()` with optional console suppression
-- All logs appear in test reports
-
-### Example 2: Object and Array Logging
-
-**Context**: Log structured data for debugging without cluttering console.
-
-**Implementation**:
-
-```typescript
-test('object logging', async ({ apiRequest }) => {
-  const { body } = await apiRequest({
-    method: 'GET',
-    path: '/api/users',
-  });
-
-  // Log array of objects
-  await log.debug(body); // Formatted as JSON in report
-
-  // Log specific object
-  await log.info({
-    totalUsers: body.length,
-    firstUser: body[0]?.name,
-    timestamp: new Date().toISOString(),
-  });
-
-  // Complex nested structures
-  await log.debug({
-    request: {
-      method: 'GET',
-      path: '/api/users',
-      timestamp: Date.now(),
-    },
-    response: {
-      status: 200,
-      body: body.slice(0, 3), // First 3 items
-    },
-  });
-});
-```
-
-**Key Points**:
-
-- Objects auto-formatted as pretty JSON
-- Arrays handled gracefully
-- Nested structures supported
-- All visible in Playwright report attachments
-
-### Example 3: Test Step Organization
-
-**Context**: Organize test execution into collapsible steps for better readability in reports.
-
-**Implementation**:
-
-```typescript
-test('organized with steps', async ({ page, apiRequest }) => {
-  await log.step('ARRANGE: Setup test data');
-  const { body: user } = await apiRequest({
-    method: 'POST',
-    path: '/api/users',
-    body: { name: 'Test User' },
-  });
-
-  await log.step('ACT: Perform user action');
-  await page.goto(`/users/${user.id}`);
-  await page.click('#edit');
-  await page.fill('#name', 'Updated Name');
-  await page.click('#save');
-
-  await log.step('ASSERT: Verify changes');
-  await expect(page.getByText('Updated Name')).toBeVisible();
-
-  // In Playwright UI, each step is collapsible
-});
-```
-
-**Key Points**:
-
-- `log.step()` creates collapsible sections
-- Organize by Arrange-Act-Assert
-- Steps visible in Playwright trace viewer
-- Better debugging when tests fail
-
-### Example 4: Test Step Decorators
-
-**Context**: Create collapsible test steps in Playwright UI using decorators.
-
-**Page Object Methods with @methodTestStep:**
-
-```typescript
-import { methodTestStep } from '@seontechnologies/playwright-utils';
-
-class TodoPage {
-  constructor(private page: Page) {
-    this.name = 'TodoPage';
-  }
-
-  readonly name: string;
-
-  @methodTestStep('Add todo item')
-  async addTodo(text: string) {
-    await log.info(`Adding todo: ${text}`);
-    const newTodo = this.page.getByPlaceholder('What needs to be done?');
-    await newTodo.fill(text);
-    await newTodo.press('Enter');
-    await log.step('step within a decorator');
-    await log.success(`Added todo: ${text}`);
-  }
-
-  @methodTestStep('Get all todos')
-  async getTodos() {
-    await log.info('Getting all todos');
-    return this.page.getByTestId('todo-title');
-  }
-}
-```
-
-**Function Helpers with functionTestStep:**
-
-```typescript
-import { functionTestStep } from '@seontechnologies/playwright-utils';
-
-// Define todo items for the test
-const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
-
-const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
-  await log.info('Creating default todos');
-  await log.step('step within a functionWrapper');
-  const todoPage = new TodoPage(page);
-
-  for (const item of TODO_ITEMS) {
-    await todoPage.addTodo(item);
-  }
-
-  await log.success('Created all default todos');
-});
-
-const checkNumberOfTodosInLocalStorage = functionTestStep(
-  'Check total todos count fn-step',
-  async (page: Page, expected: number) => {
-    await log.info(`Verifying todo count: ${expected}`);
-    const result = await page.waitForFunction(
-      (e) => JSON.parse(localStorage['react-todos']).length === e,
-      expected
-    );
-    await log.success(`Verified todo count: ${expected}`);
-    return result;
-  }
-);
-```
-
-### Example 5: File Logging
-
-**Context**: Enable file logging for persistent logs.
-
-**Implementation**:
-
-```typescript
-// playwright/support/fixtures.ts
-import { test as base } from '@playwright/test';
-import { log, captureTestContext } from '@seontechnologies/playwright-utils';
-
-// Configure file logging globally
-log.configure({
-  fileLogging: {
-    enabled: true,
-    outputDir: 'playwright-logs/organized-logs',
-    forceConsolidated: false, // One file per test
-  },
-});
-
-// Extend base test with file logging context capture
-export const test = base.extend({
-  // Auto-capture test context for file logging
-  autoTestContext: [async ({}, use, testInfo) => {
-    captureTestContext(testInfo);
-    await use(undefined);
-  }, { auto: true }],
-});
-```
-
-### Example 6: Integration with Auth and API
-
-**Context**: Log authenticated API requests with tokens (safely).
-
-**Implementation**:
-
-```typescript
-import { test } from '@seontechnologies/playwright-utils/fixtures';
-
-// Helper to create safe token preview
-function createTokenPreview(token: string): string {
-  if (!token || token.length < 10) return '[invalid]';
-  return `${token.slice(0, 6)}...${token.slice(-4)}`;
-}
-
-test('should log auth flow', async ({ authToken, apiRequest }) => {
-  await log.info(`Using token: ${createTokenPreview(authToken)}`);
-
-  await log.step('Fetch protected resource');
-  const { status, body } = await apiRequest({
-    method: 'GET',
-    path: '/api/protected',
-    headers: { Authorization: `Bearer ${authToken}` },
-  });
-
-  await log.debug({
-    status,
-    bodyPreview: {
-      id: body.id,
-      recordCount: body.data?.length,
-    },
-  });
-
-  await log.success('Protected resource accessed successfully');
-});
-```
-
-**Key Points**:
-
-- Never log full tokens (security risk)
-- Use preview functions for sensitive data
-- Combine with auth and API utilities
-- Log at appropriate detail level
-
-## Configuration
-
-**Defaults:** console logging enabled, file logging disabled.
-
-```typescript
-// Enable file logging in config
-log.configure({
-  console: true, // default
-  fileLogging: {
-    enabled: true,
-    outputDir: 'playwright-logs',
-    forceConsolidated: false, // One file per test
-  },
-});
-
-// Per-test override
-await log.info('Message', {
-  console: { enabled: false },
-  fileLogging: { enabled: true },
-});
-```
-
-### Environment Variables
-
-```bash
-# Disable all logging
-SILENT=true
-
-# Disable only file logging
-DISABLE_FILE_LOGS=true
-
-# Disable only console logging
-DISABLE_CONSOLE_LOGS=true
-```
-
-### Level Filtering
-
-```typescript
-log.configure({
-  level: 'warning', // Only warning, error levels will show
-});
-
-// Available levels (in priority order):
-// debug < info < step < success < warning < error
-```
-
-### Sync Methods
-
-For non-test contexts (global setup, utility functions):
-
-```typescript
-// Use sync methods when async/await isn't available
-log.infoSync('Initializing configuration');
-log.successSync('Environment configured');
-log.errorSync('Setup failed');
-```
-
-## Log Levels Guide
-
-| Level     | When to Use                         | Shows in Report   | Shows in Console |
-| --------- | ----------------------------------- | ----------------- | ---------------- |
-| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
-| `info`    | General information, state changes  | Yes               | Yes              |
-| `success` | Successful operations               | Yes               | Yes              |
-| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
-| `error`   | Failures, exceptions                | Yes               | Configurable     |
-| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
-
-## Comparison with console.log
-
-| console.log             | log Utility               |
-| ----------------------- | ------------------------- |
-| Not in reports          | Appears in reports        |
-| No test steps           | Creates collapsible steps |
-| Manual JSON.stringify() | Auto-formats objects      |
-| No log levels           | 6 log levels              |
-| Lost in CI output       | Preserved in artifacts    |
-
-## Related Fragments
-
-- `overview.md` - Basic usage and imports
-- `api-request.md` - Log API requests
-- `auth-session.md` - Log auth flow (safely)
-- `recurse.md` - Log polling progress
-
-## Anti-Patterns
-
-**DON'T log objects in steps:**
-
-```typescript
-await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
-```
-
-**DO use strings for steps, objects for debug:**
-
-```typescript
-await log.step('Creating user: test'); // Readable in UI
-await log.debug({ user: 'test', action: 'create' }); // Detailed data
-```
-
-**DON'T log sensitive data:**
-
-```typescript
-await log.info(`Password: ${password}`); // Security risk!
-await log.info(`Token: ${authToken}`); // Full token exposed!
-```
-
-**DO use previews or omit sensitive data:**
-
-```typescript
-await log.info('User authenticated successfully'); // No sensitive data
-await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
-```
-
-**DON'T log excessively in loops:**
-
-```typescript
-for (const item of items) {
-  await log.info(`Processing ${item.id}`); // 100 log entries!
-}
-```
-
-**DO log summary or use debug level:**
-
-```typescript
-await log.step(`Processing ${items.length} items`);
-await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
-```