@avi770/testteam 1.2.0

package/helpers/form-filler.ts

@@ -0,0 +1,126 @@
+import type { Page } from 'playwright';
+
+/**
+ * Generates a valid test value based on the input's name and type attributes.
+ * Handles common field patterns used across the target application.
+ */
+export function generateTestValue(inputType: string, inputName: string): string {
+  const nameLower = inputName.toLowerCase();
+
+  if (nameLower.includes('email')) {
+    const random = Math.random().toString(36).slice(2, 8);
+    return `test-${random}@example.com`;
+  }
+
+  if (nameLower.includes('phone')) {
+    const digits = Math.floor(Math.random() * 900000 + 100000).toString();
+    return `+61 400 ${digits}`;
+  }
+
+  if (nameLower.includes('abn')) {
+    return generateValidAbn();
+  }
+
+  if (nameLower.includes('date')) {
+    const future = new Date();
+    future.setDate(future.getDate() + 30);
+    return future.toISOString().split('T')[0];
+  }
+
+  if (inputType === 'number') {
+    return '100';
+  }
+
+  const random = Math.random().toString(36).slice(2, 8);
+  return `Test Value ${random}`;
+}
+
+/**
+ * Generates a valid 11-digit Australian Business Number (ABN).
+ * Applies the official ABN checksum algorithm.
+ */
+function generateValidAbn(): string {
+  // ABN weights for digits 1-11
+  const weights = [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19];
+
+  // Generate random 8-digit core (positions 3-10)
+  // We fix the last 8 digits, then solve for digits 1-2
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const digits: number[] = new Array(11).fill(0);
+    // Fill digits 3-10 randomly
+    for (let i = 2; i < 11; i++) {
+      digits[i] = Math.floor(Math.random() * 10);
+    }
+
+    // Try all combinations for digits 1-2 (first digit can't be 0 in reduced form)
+    for (let d1 = 1; d1 <= 9; d1++) {
+      for (let d2 = 0; d2 <= 9; d2++) {
+        digits[0] = d1;
+        digits[1] = d2;
+
+        // ABN validation: subtract 1 from first digit, sum weighted digits, divisible by 89
+        const checkDigits = [...digits];
+        checkDigits[0] -= 1;
+        const sum = checkDigits.reduce((acc, d, i) => acc + d * weights[i], 0);
+
+        if (sum % 89 === 0) {
+          return digits.join('');
+        }
+      }
+    }
+  }
+
+  // Known valid fallback ABN
+  return '51824753556';
+}
+
+/**
+ * Fills all visible, enabled form inputs within the given form selector.
+ * If testData is provided, uses its values for fields matching the key names;
+ * otherwise auto-generates values using generateTestValue.
+ */
+export async function fillForm(
+  page: Page,
+  formSelector: string,
+  testData?: Record<string, string>,
+): Promise<void> {
+  const inputs = await page.$$(
+    `${formSelector} input:not([type="hidden"]):not([type="submit"]):not([type="button"]):not([type="reset"]):not([disabled])`,
+  );
+
+  for (const input of inputs) {
+    const name = (await input.getAttribute('name')) ?? '';
+    const type = (await input.getAttribute('type')) ?? 'text';
+
+    if (testData && name && Object.prototype.hasOwnProperty.call(testData, name)) {
+      await input.fill(testData[name]);
+      continue;
+    }
+
+    if (type === 'checkbox' || type === 'radio') {
+      const checked = await input.isChecked();
+      if (!checked) {
+        await input.check();
+      }
+      continue;
+    }
+
+    const value = generateTestValue(type, name);
+    await input.fill(value);
+  }
+
+  const textareas = await page.$$(
+    `${formSelector} textarea:not([disabled])`,
+  );
+
+  for (const textarea of textareas) {
+    const name = (await textarea.getAttribute('name')) ?? '';
+
+    if (testData && name && Object.prototype.hasOwnProperty.call(testData, name)) {
+      await textarea.fill(testData[name]);
+    } else {
+      const random = Math.random().toString(36).slice(2, 8);
+      await textarea.fill(`Test textarea value ${random}`);
+    }
+  }
+}

package/helpers/modal-handler.ts

@@ -0,0 +1,108 @@
+import type { Page } from 'playwright';
+
+/** CSS selectors used to detect an open modal or dialog. */
+const MODAL_SELECTORS = [
+  '[role="dialog"]',
+  '[role="alertdialog"]',
+  '.modal',
+  '[data-modal]',
+  '[data-testid="modal"]',
+];
+
+/** CSS selectors used to locate the close (×) button inside a modal. */
+const CLOSE_BUTTON_SELECTORS = [
+  '[aria-label="Close"]',
+  '[aria-label="close"]',
+  '[data-testid="modal-close"]',
+  'button.modal-close',
+  'button[class*="close"]',
+  '[role="dialog"] button:first-of-type',
+];
+
+/** CSS selectors for the overlay/backdrop behind a modal. */
+const OVERLAY_SELECTORS = [
+  '[data-testid="modal-overlay"]',
+  '.modal-overlay',
+  '.modal-backdrop',
+  '[class*="overlay"]',
+  '[class*="backdrop"]',
+];
+
+/**
+ * Clicks the trigger element and waits for a modal/dialog to become visible.
+ * Returns true if a modal is detected within 5 seconds; false otherwise.
+ */
+export async function openModal(page: Page, triggerSelector: string): Promise<boolean> {
+  await page.click(triggerSelector);
+
+  for (const selector of MODAL_SELECTORS) {
+    try {
+      await page.waitForSelector(selector, { state: 'visible', timeout: 5000 });
+      return true;
+    } catch {
+      // Selector not found — try the next candidate
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Closes the currently open modal using the specified method.
+ * Returns true if the modal is no longer visible after the action; false otherwise.
+ */
+export async function closeModal(
+  page: Page,
+  method: 'x-button' | 'escape' | 'overlay',
+): Promise<boolean> {
+  switch (method) {
+    case 'x-button': {
+      for (const selector of CLOSE_BUTTON_SELECTORS) {
+        const button = page.locator(selector);
+        if (await button.isVisible().catch(() => false)) {
+          await button.click();
+          break;
+        }
+      }
+      break;
+    }
+
+    case 'escape': {
+      await page.keyboard.press('Escape');
+      break;
+    }
+
+    case 'overlay': {
+      for (const selector of OVERLAY_SELECTORS) {
+        const overlay = page.locator(selector);
+        if (await overlay.isVisible().catch(() => false)) {
+          await overlay.click({ position: { x: 1, y: 1 } });
+          break;
+        }
+      }
+      break;
+    }
+  }
+
+  // Give the DOM a moment to react then verify the modal is gone
+  await page.waitForTimeout(300);
+  return !(await isModalOpen(page));
+}
+
+/**
+ * Returns true if any recognised modal or dialog element is currently visible.
+ */
+export async function isModalOpen(page: Page): Promise<boolean> {
+  for (const selector of MODAL_SELECTORS) {
+    try {
+      const locator = page.locator(selector);
+      if (await locator.isVisible()) {
+        return true;
+      }
+    } catch {
+      // Element not present — continue checking
+    }
+  }
+
+  return false;
+}

package/helpers/navigation.ts

@@ -0,0 +1,100 @@
+import type { Page } from 'playwright';
+
+/** Default milliseconds to wait for all loading indicators to disappear. */
+const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
+
+/**
+ * Selectors that represent loading / skeleton states produced by React Suspense
+ * fallback components. All must be absent before `waitForSectionLoad` resolves.
+ */
+const LOADING_SELECTORS = [
+  '[aria-label="Loading"]',
+  '[data-testid="loading-spinner"]',
+  '[data-testid="skeleton"]',
+  '.loading-spinner',
+  '.skeleton',
+] as const;
+
+/**
+ * Navigate to `loginUrl`, fill the email and password inputs, submit the form,
+ * and wait for the browser to navigate away from the login page.
+ */
+export async function login(
+  page: Page,
+  credentials: { email: string; password: string },
+  loginUrl: string,
+): Promise<void> {
+  await page.goto(loginUrl, { waitUntil: 'domcontentloaded', timeout: 10000 });
+  await page.fill('input[type="email"], input[name="email"], #login-email', credentials.email);
+  await page.fill('input[type="password"], input[name="password"], #login-password', credentials.password);
+  // Use Promise.race — SPAs may not trigger a traditional navigation after login
+  await Promise.all([
+    page.waitForURL((url) => !url.toString().includes('/login'), { timeout: 10000 }).catch(() => {
+      // SPA fallback: wait for the login form to disappear
+      return page.waitForSelector('input[type="email"], #login-email', { state: 'hidden', timeout: 5000 }).catch(() => {
+        // Graceful return — login may have failed (wrong credentials, no API)
+        // Caller should check page URL to determine if login succeeded
+      });
+    }),
+    page.click('button[type="submit"]'),
+  ]);
+}
+
+/**
+ * Resolve `moduleId` to its route via `config.modules`, navigate to that route,
+ * and wait for the section's lazy-loaded content to appear.
+ *
+ * @throws {Error} when `moduleId` is not found in `config.modules`.
+ */
+export async function navigateToSection(
+  page: Page,
+  moduleId: string,
+  config: { modules: Array<{ id: string; route: string }> },
+): Promise<void> {
+  const module = config.modules.find((m) => m.id === moduleId);
+  if (module === undefined) {
+    throw new Error(
+      `navigateToSection: moduleId "${moduleId}" not found in config. ` +
+        `Available ids: [${config.modules.map((m) => m.id).join(', ')}]`,
+    );
+  }
+  // Resolve relative routes against the current page origin
+  const currentUrl = page.url();
+  const origin = currentUrl.startsWith('http') ? new URL(currentUrl).origin : '';
+  const fullUrl = module.route.startsWith('http') ? module.route : `${origin}${module.route}`;
+  await page.goto(fullUrl);
+  await waitForSectionLoad(page);
+}
+
+/**
+ * Wait for all React Suspense loading fallbacks (spinners, skeletons) to
+ * disappear, indicating that lazy-loaded section content has fully rendered.
+ *
+ * @param timeout Maximum time in milliseconds to wait (default: 10 000 ms).
+ */
+export async function waitForSectionLoad(page: Page, timeout = DEFAULT_WAIT_TIMEOUT_MS): Promise<void> {
+  for (const selector of LOADING_SELECTORS) {
+    // waitForSelector with state "hidden" resolves immediately if the element
+    // is already absent, so this is safe even when the spinner never appears.
+    await page.waitForSelector(selector, { state: 'hidden', timeout });
+  }
+}
+
+/**
+ * Switch between the bookkeeper portal and the client portal by manipulating
+ * the `portal` query-string parameter on the current page URL.
+ *
+ * @param portalQueryParam Pass `"client"` (or any portal slug) to set
+ *   `?portal=<value>`, or `null` to remove the query parameter entirely.
+ */
+export async function switchPortal(page: Page, portalQueryParam: string | null): Promise<void> {
+  const currentUrl = new URL(page.url());
+
+  if (portalQueryParam === null) {
+    currentUrl.searchParams.delete('portal');
+  } else {
+    currentUrl.searchParams.set('portal', portalQueryParam);
+  }
+
+  await page.goto(currentUrl.toString());
+}

package/helpers/quality-gate.ts

@@ -0,0 +1,180 @@
+import { readFileSync } from 'fs';
+
+export interface QualityViolation {
+  rule: string;
+  message: string;
+  line?: number;
+  severity: 'error' | 'warning';
+}
+
+// Matches `: any` type annotations
+const ANY_TYPE_PATTERN = /:\s*any\b/;
+
+// Matches function declarations and arrow functions that open a block body on the same line
+const FUNCTION_START_PATTERN =
+  /(?:function\s+\w+\s*\([^)]*\)\s*\{|(?:\([^)]*\)|\w+)\s*=>\s*\{)/;
+
+// Matches hardcoded secret assignments with literal string values
+const HARDCODED_SECRET_PATTERN =
+  /(?:password|secret|apiKey|api_key|token)\s*=\s*['"][^'"]+['"]/i;
+
+// Matches lines that safely read from process.env
+const PROCESS_ENV_PATTERN = /process\.env\./;
+
+// Maximum lines allowed inside a single function body before a violation is raised
+const MAX_FUNCTION_LINES = 30;
+
+// Maximum brace-nesting depth before a violation is raised
+const MAX_NESTING_DEPTH = 3;
+
+function isCommentLine(line: string): boolean {
+  const trimmed = line.trim();
+  return (
+    trimmed.startsWith('//') ||
+    trimmed.startsWith('*') ||
+    trimmed.startsWith('/*')
+  );
+}
+
+function checkAnyType(lines: string[]): QualityViolation[] {
+  const violations: QualityViolation[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isCommentLine(line)) continue;
+    // Strip string literals to avoid false positives from values containing "any"
+    const stripped = line.replace(/(['"`])(?:(?!\1)[^\\]|\\.)*\1/g, '""');
+    if (ANY_TYPE_PATTERN.test(stripped)) {
+      violations.push({
+        rule: 'no-any',
+        message: `Avoid \`any\` type — use explicit types to preserve TypeScript safety (line ${i + 1}).`,
+        line: i + 1,
+        severity: 'error',
+      });
+    }
+  }
+  return violations;
+}
+
+function checkLongFunctions(lines: string[]): QualityViolation[] {
+  const violations: QualityViolation[] = [];
+
+  // Stack entries: { startLine (0-based), braceDepthAtStart }
+  const stack: Array<{ startLine: number; braceDepthAtStart: number }> = [];
+  let braceDepth = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const opens = (line.match(/\{/g) ?? []).length;
+    const closes = (line.match(/\}/g) ?? []).length;
+
+    if (FUNCTION_START_PATTERN.test(line)) {
+      // Record function start; its body starts at the `{` on this line, so the
+      // depth before processing this line's braces is `braceDepth`.
+      stack.push({ startLine: i, braceDepthAtStart: braceDepth });
+    }
+
+    braceDepth += opens - closes;
+
+    // Pop any functions whose body just closed (depth returned to start level)
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1];
+      if (braceDepth <= top.braceDepthAtStart) {
+        const functionLineCount = i - top.startLine + 1;
+        if (functionLineCount > MAX_FUNCTION_LINES) {
+          violations.push({
+            rule: 'max-function-lines',
+            message:
+              `Function starting at line ${top.startLine + 1} is ${functionLineCount} lines long ` +
+              `— keep functions under ${MAX_FUNCTION_LINES + 1} lines.`,
+            line: top.startLine + 1,
+            severity: 'warning',
+          });
+        }
+        stack.pop();
+      } else {
+        break;
+      }
+    }
+  }
+
+  return violations;
+}
+
+function checkHardcodedSecrets(lines: string[]): QualityViolation[] {
+  const violations: QualityViolation[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isCommentLine(line)) continue;
+    if (PROCESS_ENV_PATTERN.test(line)) continue;
+    if (HARDCODED_SECRET_PATTERN.test(line)) {
+      violations.push({
+        rule: 'no-hardcoded-secrets',
+        message: `Hardcoded secret detected at line ${i + 1} — use environment variables instead.`,
+        line: i + 1,
+        severity: 'error',
+      });
+    }
+  }
+  return violations;
+}
+
+function checkDeepNesting(lines: string[]): QualityViolation[] {
+  const violations: QualityViolation[] = [];
+  let depth = 0;
+  let violationActive = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const opens = (line.match(/\{/g) ?? []).length;
+    const closes = (line.match(/\}/g) ?? []).length;
+
+    depth += opens - closes;
+
+    if (depth > MAX_NESTING_DEPTH && !violationActive) {
+      violations.push({
+        rule: 'max-nesting-depth',
+        message:
+          `Nesting depth exceeds ${MAX_NESTING_DEPTH} levels at line ${i + 1} ` +
+          `— refactor to reduce complexity.`,
+        line: i + 1,
+        severity: 'warning',
+      });
+      violationActive = true;
+    }
+
+    if (depth <= MAX_NESTING_DEPTH) {
+      violationActive = false;
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Validates the given source code content against AVI-OS coding quality rules.
+ * Returns an array of QualityViolation objects; an empty array means the code
+ * passes all checks.
+ */
+export function validateCodeQuality(
+  fileContent: string,
+  filePath: string,
+): QualityViolation[] {
+  // filePath is available for future rule extensions (e.g. path-based exclusions)
+  void filePath;
+
+  const lines = fileContent.split('\n');
+  return [
+    ...checkAnyType(lines),
+    ...checkHardcodedSecrets(lines),
+    ...checkLongFunctions(lines),
+    ...checkDeepNesting(lines),
+  ];
+}
+
+/**
+ * Reads a file from disk and runs validateCodeQuality on its contents.
+ */
+export function runQualityGate(filePath: string): QualityViolation[] {
+  const content = readFileSync(filePath, 'utf-8');
+  return validateCodeQuality(content, filePath);
+}

package/helpers/screenshot.ts

@@ -0,0 +1,111 @@
+import { mkdir, copyFile, readFile, writeFile, stat } from 'node:fs/promises';
+import { join, basename } from 'path';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import type { Page } from 'playwright';
+
+export interface ScreenshotCompareResult {
+  match: boolean;
+  diffPercentage: number;
+  diffPath?: string;
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try { await stat(p); return true; } catch { return false; }
+}
+
+/**
+ * Captures a screenshot of the current page state and saves it to outputDir.
+ * Returns the absolute file path of the saved screenshot.
+ */
+export async function captureScreenshot(
+  page: Page,
+  name: string,
+  outputDir: string,
+): Promise<string> {
+  const dirExists = await fileExists(outputDir);
+  if (!dirExists) {
+    await mkdir(outputDir, { recursive: true });
+  }
+
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '_');
+  const filePath = join(outputDir, `${safeName}.png`);
+
+  await page.screenshot({ path: filePath, fullPage: false });
+
+  return filePath;
+}
+
+/**
+ * Compares two PNG screenshots using pixelmatch.
+ * Returns match=true when the diff percentage is at or below the threshold.
+ * Default threshold: 0.1 (0.1% pixel difference).
+ * Writes a diff PNG alongside the current screenshot when images differ.
+ */
+export async function compareScreenshots(
+  currentPath: string,
+  baselinePath: string,
+  threshold = 0.1,
+): Promise<ScreenshotCompareResult> {
+  const currentData = await readFile(currentPath);
+  const baselineData = await readFile(baselinePath);
+
+  const current = PNG.sync.read(currentData);
+  const baseline = PNG.sync.read(baselineData);
+
+  if (current.width !== baseline.width || current.height !== baseline.height) {
+    return {
+      match: false,
+      diffPercentage: 100,
+    };
+  }
+
+  const { width, height } = current;
+  const diff = new PNG({ width, height });
+
+  const diffPixels = pixelmatch(
+    current.data,
+    baseline.data,
+    diff.data,
+    width,
+    height,
+    { threshold: 0.1 },
+  );
+
+  const totalPixels = width * height;
+  const diffPercentage = totalPixels > 0 ? (diffPixels / totalPixels) * 100 : 0;
+  const match = diffPercentage <= threshold;
+
+  let diffPath: string | undefined;
+  if (!match) {
+    diffPath = currentPath.replace(/\.png$/, '_diff.png');
+    await writeFile(diffPath, PNG.sync.write(diff));
+  }
+
+  return {
+    match,
+    diffPercentage,
+    ...(diffPath ? { diffPath } : {}),
+  };
+}
+
+/**
+ * Copies the current screenshot to the baseline directory, establishing it
+ * as the new reference image. Returns the path of the new baseline file.
+ */
+export async function updateBaseline(
+  currentPath: string,
+  baselineDir: string,
+): Promise<string> {
+  const dirExists = await fileExists(baselineDir);
+  if (!dirExists) {
+    await mkdir(baselineDir, { recursive: true });
+  }
+
+  const fileName = basename(currentPath);
+  const baselinePath = join(baselineDir, fileName);
+
+  await copyFile(currentPath, baselinePath);
+
+  return baselinePath;
+}

package/helpers/seed-validator.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from 'fs';
+
+export interface SeedValidationResult {
+  covered: string[];
+  missing: string[];
+}
+
+/**
+ * Validates that a Prisma seed file contains data creation entries for each
+ * of the supplied module IDs.
+ *
+ * Detection heuristic: for each moduleId the function looks for the module
+ * identifier (case-insensitive) appearing in a data-creation context — i.e.
+ * adjacent to keywords such as create, createMany, insert, upsert, seed, or
+ * model within 120 characters. This covers common Prisma and raw-SQL patterns.
+ */
+export async function validateSeedCompleteness(
+  seedFilePath: string,
+  moduleIds: string[],
+): Promise<SeedValidationResult> {
+  const content = readFileSync(seedFilePath, 'utf-8');
+  const contentLower = content.toLowerCase();
+
+  const covered: string[] = [];
+  const missing: string[] = [];
+
+  for (const moduleId of moduleIds) {
+    if (isCoveredByContent(contentLower, moduleId.toLowerCase())) {
+      covered.push(moduleId);
+    } else {
+      missing.push(moduleId);
+    }
+  }
+
+  return { covered, missing };
+}
+
+/**
+ * Returns true if the seed content appears to create data for the given module.
+ * Checks for the module name near data-creation keywords or as a Prisma model reference.
+ */
+function isCoveredByContent(contentLower: string, moduleIdLower: string): boolean {
+  const creationKeywords = ['create', 'createmany', 'insert', 'upsert', 'seed', 'model'];
+
+  let searchStart = 0;
+  const moduleIndex = contentLower.indexOf(moduleIdLower, searchStart);
+
+  if (moduleIndex === -1) {
+    return false;
+  }
+
+  // Scan all occurrences of the module name for a nearby creation keyword
+  let idx = moduleIndex;
+  while (idx !== -1) {
+    const windowStart = Math.max(0, idx - 120);
+    const windowEnd = Math.min(contentLower.length, idx + moduleIdLower.length + 120);
+    const window = contentLower.slice(windowStart, windowEnd);
+
+    for (const keyword of creationKeywords) {
+      if (window.includes(keyword)) {
+        return true;
+      }
+    }
+
+    searchStart = idx + 1;
+    idx = contentLower.indexOf(moduleIdLower, searchStart);
+  }
+
+  return false;
+}