@zeyue0329/xiaoma-cli 1.6.4 → 1.7.0

package/src/xmc/testarch/knowledge/file-utils.md

@@ -1,260 +0,0 @@
-# File Utilities
-
-## Principle
-
-Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
-
-## Rationale
-
-Testing file operations in Playwright requires boilerplate:
-
-- Manual download handling
-- External parsing libraries for each format
-- No validation helpers
-- Type-unsafe results
-- Repetitive path handling
-
-The `file-utils` module provides:
-
-- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
-- **Download handling**: Single function for UI or API-triggered downloads
-- **Type-safe**: TypeScript interfaces for parsed results
-- **Validation helpers**: Row count, header checks, content validation
-- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
-
-## Pattern Examples
-
-### Example 1: UI-Triggered CSV Download
-
-**Context**: User clicks button, CSV downloads, validate contents.
-
-**Implementation**:
-
-```typescript
-import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
-import path from 'node:path';
-
-const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
-
-test('should download and validate CSV', async ({ page }) => {
-  const downloadPath = await handleDownload({
-    page,
-    downloadDir: DOWNLOAD_DIR,
-    trigger: () => page.click('[data-testid="export-csv"]'),
-  });
-
-  const { content } = await readCSV({ filePath: downloadPath });
-
-  // Validate headers
-  expect(content.headers).toEqual(['ID', 'Name', 'Email', 'Role']);
-
-  // Validate data
-  expect(content.data).toHaveLength(10);
-  expect(content.data[0]).toMatchObject({
-    ID: expect.any(String),
-    Name: expect.any(String),
-    Email: expect.stringMatching(/@/),
-  });
-});
-```
-
-**Key Points**:
-
-- `handleDownload` waits for download, returns file path
-- `readCSV` auto-parses to `{ headers, data }`
-- Type-safe access to parsed content
-- Clean up downloads in `afterEach`
-
-### Example 2: XLSX with Multiple Sheets
-
-**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
-
-**Implementation**:
-
-```typescript
-import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
-
-test('should read multi-sheet XLSX', async () => {
-  const downloadPath = await handleDownload({
-    page,
-    downloadDir: DOWNLOAD_DIR,
-    trigger: () => page.click('[data-testid="export-xlsx"]'),
-  });
-
-  const { content } = await readXLSX({ filePath: downloadPath });
-
-  // Access specific sheets
-  const summarySheet = content.sheets.find((s) => s.name === 'Summary');
-  const detailsSheet = content.sheets.find((s) => s.name === 'Details');
-
-  // Validate summary
-  expect(summarySheet.data).toHaveLength(1);
-  expect(summarySheet.data[0].TotalRecords).toBe('150');
-
-  // Validate details
-  expect(detailsSheet.data).toHaveLength(150);
-  expect(detailsSheet.headers).toContain('TransactionID');
-});
-```
-
-**Key Points**:
-
-- `sheets` array with `name` and `data` properties
-- Access sheets by name
-- Each sheet has its own headers and data
-- Type-safe sheet iteration
-
-### Example 3: PDF Text Extraction
-
-**Context**: Validate PDF report contains expected content.
-
-**Implementation**:
-
-```typescript
-import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
-
-test('should validate PDF report', async () => {
-  const downloadPath = await handleDownload({
-    page,
-    downloadDir: DOWNLOAD_DIR,
-    trigger: () => page.click('[data-testid="download-report"]'),
-  });
-
-  const { content } = await readPDF({ filePath: downloadPath });
-
-  // content.text is extracted text from all pages
-  expect(content.text).toContain('Financial Report Q4 2024');
-  expect(content.text).toContain('Total Revenue:');
-
-  // Validate page count
-  expect(content.numpages).toBeGreaterThan(10);
-});
-```
-
-**Key Points**:
-
-- `content.text` contains all extracted text
-- `content.numpages` for page count
-- PDF parsing handles multi-page documents
-- Search for specific phrases
-
-### Example 4: ZIP Archive Validation
-
-**Context**: Validate ZIP contains expected files and extract specific file.
-
-**Implementation**:
-
-```typescript
-import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
-
-test('should validate ZIP archive', async () => {
-  const downloadPath = await handleDownload({
-    page,
-    downloadDir: DOWNLOAD_DIR,
-    trigger: () => page.click('[data-testid="download-backup"]'),
-  });
-
-  const { content } = await readZIP({ filePath: downloadPath });
-
-  // Check file list
-  expect(content.files).toContain('data.csv');
-  expect(content.files).toContain('config.json');
-  expect(content.files).toContain('readme.txt');
-
-  // Read specific file from archive
-  const configContent = content.zip.readAsText('config.json');
-  const config = JSON.parse(configContent);
-
-  expect(config.version).toBe('2.0');
-});
-```
-
-**Key Points**:
-
-- `content.files` lists all files in archive
-- `content.zip.readAsText()` extracts specific files
-- Validate archive structure
-- Read and parse individual files from ZIP
-
-### Example 5: API-Triggered Download
-
-**Context**: API endpoint returns file download (not UI click).
-
-**Implementation**:
-
-```typescript
-test('should download via API', async ({ page, request }) => {
-  const downloadPath = await handleDownload({
-    page,
-    downloadDir: DOWNLOAD_DIR,
-    trigger: async () => {
-      const response = await request.get('/api/export/csv', {
-        headers: { Authorization: 'Bearer token' },
-      });
-
-      if (!response.ok()) {
-        throw new Error(`Export failed: ${response.status()}`);
-      }
-    },
-  });
-
-  const { content } = await readCSV({ filePath: downloadPath });
-
-  expect(content.data).toHaveLength(100);
-});
-```
-
-**Key Points**:
-
-- `trigger` can be async API call
-- API must return `Content-Disposition` header
-- Still need `page` for download events
-- Works with authenticated endpoints
-
-## Validation Helpers
-
-```typescript
-// CSV validation
-const { isValid, errors } = await validateCSV({
-  filePath: downloadPath,
-  expectedRowCount: 10,
-  requiredHeaders: ['ID', 'Name', 'Email'],
-});
-
-expect(isValid).toBe(true);
-expect(errors).toHaveLength(0);
-```
-
-## Download Cleanup Pattern
-
-```typescript
-test.afterEach(async () => {
-  // Clean up downloaded files
-  await fs.remove(DOWNLOAD_DIR);
-});
-```
-
-## Related Fragments
-
-- `overview.md` - Installation and imports
-- `api-request.md` - API-triggered downloads
-- `recurse.md` - Poll for file generation completion
-
-## Anti-Patterns
-
-**❌ Not cleaning up downloads:**
-
-```typescript
-test('creates file', async () => {
-  await handleDownload({ ... })
-  // File left in downloads folder
-})
-```
-
-**✅ Clean up after tests:**
-
-```typescript
-test.afterEach(async () => {
-  await fs.remove(DOWNLOAD_DIR);
-});
-```

package/src/xmc/testarch/knowledge/fixture-architecture.md

@@ -1,401 +0,0 @@
-# Fixture Architecture Playbook
-
-## Principle
-
-Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
-
-## Rationale
-
-Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
-
-- **Testability**: Pure functions run in unit tests without framework overhead
-- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
-- **Reusability**: Export fixtures via package subpaths for cross-project sharing
-- **Maintainability**: One concern per fixture = clear responsibility boundaries
-
-## Pattern Examples
-
-### Example 1: Pure Function → Fixture Pattern
-
-**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
-
-**Implementation**:
-
-```typescript
-// playwright/support/helpers/api-request.ts
-// Step 1: Pure function (ALWAYS FIRST!)
-type ApiRequestParams = {
-  request: APIRequestContext;
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
-  url: string;
-  data?: unknown;
-  headers?: Record<string, string>;
-};
-
-export async function apiRequest({
-  request,
-  method,
-  url,
-  data,
-  headers = {}
-}: ApiRequestParams) {
-  const response = await request.fetch(url, {
-    method,
-    data,
-    headers: {
-      'Content-Type': 'application/json',
-      ...headers
-    }
-  });
-
-  if (!response.ok()) {
-    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
-  }
-
-  return response.json();
-}
-
-// Step 2: Fixture wrapper
-// playwright/support/fixtures/api-request-fixture.ts
-import { test as base } from '@playwright/test';
-import { apiRequest } from '../helpers/api-request';
-
-export const test = base.extend<{ apiRequest: typeof apiRequest }>({
-  apiRequest: async ({ request }, use) => {
-    // Inject framework dependency, expose pure function
-    await use((params) => apiRequest({ request, ...params }));
-  }
-});
-
-// Step 3: Package exports for reusability
-// package.json
-{
-  "exports": {
-    "./api-request": "./playwright/support/helpers/api-request.ts",
-    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
-  }
-}
-```
-
-**Key Points**:
-
-- Pure function is unit-testable without Playwright running
-- Framework dependency (`request`) injected at fixture boundary
-- Fixture exposes the pure function to test context
-- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
-
-### Example 2: Composable Fixture System with mergeTests
-
-**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
-
-**Implementation**:
-
-```typescript
-// playwright/support/fixtures/merged-fixtures.ts
-import { test as base, mergeTests } from '@playwright/test';
-import { test as apiRequestFixture } from './api-request-fixture';
-import { test as networkFixture } from './network-fixture';
-import { test as authFixture } from './auth-fixture';
-import { test as logFixture } from './log-fixture';
-
-// Compose all fixtures for comprehensive capabilities
-export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
-
-export { expect } from '@playwright/test';
-
-// Example usage in tests:
-// import { test, expect } from './support/fixtures/merged-fixtures';
-//
-// test('user can create order', async ({ page, apiRequest, auth, network }) => {
-//   await auth.loginAs('customer@example.com');
-//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
-//   await page.goto('/checkout');
-//   await page.click('[data-testid="submit-order"]');
-//   await expect(page.getByText('Order #123')).toBeVisible();
-// });
-```
-
-**Individual Fixture Examples**:
-
-```typescript
-// network-fixture.ts
-export const test = base.extend({
-  network: async ({ page }, use) => {
-    const interceptedRoutes = new Map();
-
-    const interceptRoute = async (method: string, url: string, response: unknown) => {
-      await page.route(url, (route) => {
-        if (route.request().method() === method) {
-          route.fulfill({ body: JSON.stringify(response) });
-        }
-      });
-      interceptedRoutes.set(`${method}:${url}`, response);
-    };
-
-    await use({ interceptRoute });
-
-    // Cleanup
-    interceptedRoutes.clear();
-  },
-});
-
-// auth-fixture.ts
-export const test = base.extend({
-  auth: async ({ page, context }, use) => {
-    const loginAs = async (email: string) => {
-      // Use API to setup auth (fast!)
-      const token = await getAuthToken(email);
-      await context.addCookies([
-        {
-          name: 'auth_token',
-          value: token,
-          domain: 'localhost',
-          path: '/',
-        },
-      ]);
-    };
-
-    await use({ loginAs });
-  },
-});
-```
-
-**Key Points**:
-
-- `mergeTests` combines fixtures without inheritance
-- Each fixture has single responsibility (network, auth, logs)
-- Tests import merged fixture and access all capabilities
-- No coupling between fixtures—add/remove freely
-
-### Example 3: Framework-Agnostic HTTP Helper
-
-**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
-
-**Implementation**:
-
-```typescript
-// shared/helpers/http-helper.ts
-// Pure, framework-agnostic function
-type HttpHelperParams = {
-  baseUrl: string;
-  endpoint: string;
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
-  body?: unknown;
-  headers?: Record<string, string>;
-  token?: string;
-};
-
-export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
-  const url = `${baseUrl}${endpoint}`;
-  const requestHeaders = {
-    'Content-Type': 'application/json',
-    ...(token && { Authorization: `Bearer ${token}` }),
-    ...headers,
-  };
-
-  const response = await fetch(url, {
-    method,
-    headers: requestHeaders,
-    body: body ? JSON.stringify(body) : undefined,
-  });
-
-  if (!response.ok) {
-    const errorText = await response.text();
-    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
-  }
-
-  return response.json();
-}
-
-// Playwright fixture wrapper
-// playwright/support/fixtures/http-fixture.ts
-import { test as base } from '@playwright/test';
-import { makeHttpRequest } from '../../shared/helpers/http-helper';
-
-export const test = base.extend({
-  httpHelper: async ({}, use) => {
-    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
-
-    await use((params) => makeHttpRequest({ baseUrl, ...params }));
-  },
-});
-
-// Cypress command wrapper
-// cypress/support/commands.ts
-import { makeHttpRequest } from '../../shared/helpers/http-helper';
-
-Cypress.Commands.add('apiRequest', (params) => {
-  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
-  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
-});
-```
-
-**Key Points**:
-
-- Pure function uses only standard `fetch`, no framework dependencies
-- Unit tests call `makeHttpRequest` directly with all params
-- Playwright and Cypress wrappers inject framework-specific config
-- Same logic runs everywhere—zero duplication
-
-### Example 4: Fixture Cleanup Pattern
-
-**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
-
-**Implementation**:
-
-```typescript
-// playwright/support/fixtures/database-fixture.ts
-import { test as base } from '@playwright/test';
-import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
-
-type DatabaseFixture = {
-  seedUser: (userData: Partial<User>) => Promise<User>;
-  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
-};
-
-export const test = base.extend<DatabaseFixture>({
-  seedUser: async ({}, use) => {
-    const createdUsers: string[] = [];
-
-    const seedUser = async (userData: Partial<User>) => {
-      const user = await seedDatabase('users', userData);
-      createdUsers.push(user.id);
-      return user;
-    };
-
-    await use(seedUser);
-
-    // Auto-cleanup: Delete all users created during test
-    for (const userId of createdUsers) {
-      await deleteRecord('users', userId);
-    }
-    createdUsers.length = 0;
-  },
-
-  seedOrder: async ({}, use) => {
-    const createdOrders: string[] = [];
-
-    const seedOrder = async (orderData: Partial<Order>) => {
-      const order = await seedDatabase('orders', orderData);
-      createdOrders.push(order.id);
-      return order;
-    };
-
-    await use(seedOrder);
-
-    // Auto-cleanup: Delete all orders
-    for (const orderId of createdOrders) {
-      await deleteRecord('orders', orderId);
-    }
-    createdOrders.length = 0;
-  },
-});
-
-// Example usage:
-// test('user can place order', async ({ seedUser, seedOrder, page }) => {
-//   const user = await seedUser({ email: 'test@example.com' });
-//   const order = await seedOrder({ userId: user.id, total: 100 });
-//
-//   await page.goto(`/orders/${order.id}`);
-//   await expect(page.getByText('Order Total: $100')).toBeVisible();
-//
-//   // No manual cleanup needed—fixture handles it automatically
-// });
-```
-
-**Key Points**:
-
-- Track all created resources in array during test execution
-- Teardown (after `use()`) deletes all tracked resources
-- Tests don't manually clean up—happens automatically
-- Prevents test pollution and flakiness from shared state
-
-### Anti-Pattern: Inheritance-Based Page Objects
-
-**Problem**:
-
-```typescript
-// ❌ BAD: Page Object Model with inheritance
-class BasePage {
-  constructor(public page: Page) {}
-
-  async navigate(url: string) {
-    await this.page.goto(url);
-  }
-
-  async clickButton(selector: string) {
-    await this.page.click(selector);
-  }
-}
-
-class LoginPage extends BasePage {
-  async login(email: string, password: string) {
-    await this.navigate('/login');
-    await this.page.fill('#email', email);
-    await this.page.fill('#password', password);
-    await this.clickButton('#submit');
-  }
-}
-
-class AdminPage extends LoginPage {
-  async accessAdminPanel() {
-    await this.login('admin@example.com', 'admin123');
-    await this.navigate('/admin');
-  }
-}
-```
-
-**Why It Fails**:
-
-- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
-- `AdminPage` inherits unnecessary `login` details—tight coupling
-- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
-- Hard to test `BasePage` methods in isolation
-- Hidden state in class instances leads to unpredictable behavior
-
-**Better Approach**: Use pure functions + fixtures
-
-```typescript
-// ✅ GOOD: Pure functions with fixture composition
-// helpers/navigation.ts
-export async function navigate(page: Page, url: string) {
-  await page.goto(url);
-}
-
-// helpers/auth.ts
-export async function login(page: Page, email: string, password: string) {
-  await page.fill('[data-testid="email"]', email);
-  await page.fill('[data-testid="password"]', password);
-  await page.click('[data-testid="submit"]');
-}
-
-// fixtures/admin-fixture.ts
-export const test = base.extend({
-  adminPage: async ({ page }, use) => {
-    await login(page, 'admin@example.com', 'admin123');
-    await navigate(page, '/admin');
-    await use(page);
-  },
-});
-
-// Tests import exactly what they need—no inheritance
-```
-
-## Integration Points
-
-- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
-- **Related fragments**:
-  - `data-factories.md` - Factory functions for test data
-  - `network-first.md` - Network interception patterns
-  - `test-quality.md` - Deterministic test design principles
-
-## Helper Function Reuse Guidelines
-
-When deciding whether to create a fixture, follow these rules:
-
-- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
-- **2-3 uses** → Create utility module (shared within project)
-- **1 use** → Keep inline (avoid premature abstraction)
-- **Complex logic** → Factory function pattern (dynamic data generation)
-
-_Source: Murat Testing Philosophy (lines 74-122), SEON production patterns, Playwright fixture docs._