@avi770/testteam 1.2.0

package/helpers/__tests__/quality-gate.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import { validateCodeQuality } from '../quality-gate';
+import type { QualityViolation } from '../quality-gate';
+
+describe('validateCodeQuality(fileContent, filePath)', () => {
+  describe('any type detection', () => {
+    it('reports a violation when `any` type is used', () => {
+      const content = `const x: any = 5;`;
+      const violations: QualityViolation[] = validateCodeQuality(content, 'test.ts');
+      expect(violations.length).toBeGreaterThan(0);
+      const v = violations.find((v) => v.rule === 'no-any');
+      expect(v).toBeDefined();
+      expect(v?.message).toMatch(/any/i);
+      expect(v?.severity).toBe('error');
+    });
+
+    it('reports no violation for a typed variable without `any`', () => {
+      const content = `const x: string = 'hello';`;
+      const violations = validateCodeQuality(content, 'test.ts');
+      const anyViolations = violations.filter((v) => v.rule === 'no-any');
+      expect(anyViolations).toHaveLength(0);
+    });
+  });
+
+  describe('long function detection (>30 lines)', () => {
+    it('reports a violation for a function body with 35 lines', () => {
+      const bodyLines = Array.from({ length: 35 }, (_, i) => `  const v${i} = ${i};`);
+      const content = `function longFn() {\n${bodyLines.join('\n')}\n}`;
+      const violations = validateCodeQuality(content, 'test.ts');
+      const v = violations.find((v) => v.rule === 'max-function-lines');
+      expect(v).toBeDefined();
+      expect(v?.severity).toBe('warning');
+    });
+
+    it('reports no violation for a function body with 10 lines', () => {
+      const bodyLines = Array.from({ length: 10 }, (_, i) => `  const v${i} = ${i};`);
+      const content = `function shortFn() {\n${bodyLines.join('\n')}\n}`;
+      const violations = validateCodeQuality(content, 'test.ts');
+      const fnViolations = violations.filter((v) => v.rule === 'max-function-lines');
+      expect(fnViolations).toHaveLength(0);
+    });
+  });
+
+  describe('hardcoded secret detection', () => {
+    it('reports a violation for a hardcoded password assignment', () => {
+      const content = `const password = 'secret123';`;
+      const violations = validateCodeQuality(content, 'test.ts');
+      const v = violations.find((v) => v.rule === 'no-hardcoded-secrets');
+      expect(v).toBeDefined();
+      expect(v?.severity).toBe('error');
+    });
+
+    it('reports no violation when password uses process.env', () => {
+      const content = `const password = process.env.PASSWORD;`;
+      const violations = validateCodeQuality(content, 'test.ts');
+      const secretViolations = violations.filter((v) => v.rule === 'no-hardcoded-secrets');
+      expect(secretViolations).toHaveLength(0);
+    });
+
+    it('reports a violation for a hardcoded apiKey assignment', () => {
+      const content = `const apiKey = 'sk-1234567890';`;
+      const violations = validateCodeQuality(content, 'test.ts');
+      const v = violations.find((v) => v.rule === 'no-hardcoded-secrets');
+      expect(v).toBeDefined();
+      expect(v?.severity).toBe('error');
+    });
+  });
+
+  describe('deep nesting detection (>3 levels)', () => {
+    it('reports a violation for 4 nested if blocks', () => {
+      const content = [
+        `if (a) {`,
+        `  if (b) {`,
+        `    if (c) {`,
+        `      if (d) {`,
+        `        doSomething();`,
+        `      }`,
+        `    }`,
+        `  }`,
+        `}`,
+      ].join('\n');
+      const violations = validateCodeQuality(content, 'test.ts');
+      const v = violations.find((v) => v.rule === 'max-nesting-depth');
+      expect(v).toBeDefined();
+      expect(v?.severity).toBe('warning');
+    });
+
+    it('reports no violation for 2 nested if blocks', () => {
+      const content = [
+        `if (a) {`,
+        `  if (b) {`,
+        `    doSomething();`,
+        `  }`,
+        `}`,
+      ].join('\n');
+      const violations = validateCodeQuality(content, 'test.ts');
+      const nestingViolations = violations.filter((v) => v.rule === 'max-nesting-depth');
+      expect(nestingViolations).toHaveLength(0);
+    });
+  });
+
+  describe('QualityViolation shape', () => {
+    it('each violation has rule, message, severity, and optional line', () => {
+      const content = `const x: any = 5;`;
+      const violations = validateCodeQuality(content, 'test.ts');
+      expect(violations.length).toBeGreaterThan(0);
+      for (const v of violations) {
+        expect(typeof v.rule).toBe('string');
+        expect(typeof v.message).toBe('string');
+        expect(['error', 'warning']).toContain(v.severity);
+        if (v.line !== undefined) {
+          expect(typeof v.line).toBe('number');
+        }
+      }
+    });
+  });
+});

package/helpers/__tests__/screenshot.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { PNG } from 'pngjs';
+import { compareScreenshots, updateBaseline } from '../screenshot';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TMP_DIR = join('/tmp', 'tf-screenshot-tests');
+
+function createSolidPng(filePath: string, r: number, g: number, b: number): void {
+  const width = 10;
+  const height = 10;
+  const png = new PNG({ width, height });
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const idx = (y * width + x) * 4;
+      png.data[idx] = r;
+      png.data[idx + 1] = g;
+      png.data[idx + 2] = b;
+      png.data[idx + 3] = 255;
+    }
+  }
+
+  writeFileSync(filePath, PNG.sync.write(png));
+}
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+beforeAll(() => {
+  if (!existsSync(TMP_DIR)) {
+    mkdirSync(TMP_DIR, { recursive: true });
+  }
+});
+
+afterAll(() => {
+  rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('compareScreenshots(currentPath, baselinePath, threshold?)', () => {
+  it('returns match=true and diffPercentage=0 for identical images', async () => {
+    const pathA = join(TMP_DIR, 'identical_a.png');
+    const pathB = join(TMP_DIR, 'identical_b.png');
+    createSolidPng(pathA, 255, 0, 0);
+    createSolidPng(pathB, 255, 0, 0);
+
+    const result = await compareScreenshots(pathA, pathB);
+
+    expect(result.match).toBe(true);
+    expect(result.diffPercentage).toBe(0);
+    expect(result.diffPath).toBeUndefined();
+  });
+
+  it('returns match=false and diffPercentage>0 for completely different images', async () => {
+    const current = join(TMP_DIR, 'diff_current.png');
+    const baseline = join(TMP_DIR, 'diff_baseline.png');
+    createSolidPng(current, 255, 0, 0);   // red
+    createSolidPng(baseline, 0, 0, 255);  // blue
+
+    const result = await compareScreenshots(current, baseline);
+
+    expect(result.match).toBe(false);
+    expect(result.diffPercentage).toBeGreaterThan(0);
+  });
+
+  it('creates a diff PNG file when images differ', async () => {
+    const current = join(TMP_DIR, 'diff_file_current.png');
+    const baseline = join(TMP_DIR, 'diff_file_baseline.png');
+    createSolidPng(current, 255, 0, 0);
+    createSolidPng(baseline, 0, 255, 0);
+
+    const result = await compareScreenshots(current, baseline);
+
+    expect(result.match).toBe(false);
+    expect(result.diffPath).toBeDefined();
+    expect(existsSync(result.diffPath!)).toBe(true);
+  });
+
+  it('returns match=false for images with different dimensions', async () => {
+    const small = new PNG({ width: 5, height: 5 });
+    small.data.fill(255);
+    writeFileSync(join(TMP_DIR, 'small.png'), PNG.sync.write(small));
+
+    const large = new PNG({ width: 10, height: 10 });
+    large.data.fill(255);
+    writeFileSync(join(TMP_DIR, 'large.png'), PNG.sync.write(large));
+
+    const result = await compareScreenshots(
+      join(TMP_DIR, 'small.png'),
+      join(TMP_DIR, 'large.png'),
+    );
+
+    expect(result.match).toBe(false);
+    expect(result.diffPercentage).toBe(100);
+  });
+
+  it('respects a custom threshold — identical images pass any positive threshold', async () => {
+    const pathA = join(TMP_DIR, 'thresh_a.png');
+    const pathB = join(TMP_DIR, 'thresh_b.png');
+    createSolidPng(pathA, 128, 128, 128);
+    createSolidPng(pathB, 128, 128, 128);
+
+    const result = await compareScreenshots(pathA, pathB, 0.5);
+
+    expect(result.match).toBe(true);
+  });
+});
+
+describe('updateBaseline(currentPath, baselineDir)', () => {
+  it('copies the current screenshot to the baseline directory', async () => {
+    const current = join(TMP_DIR, 'to_baseline.png');
+    const baselineDir = join(TMP_DIR, 'baselines');
+    createSolidPng(current, 0, 128, 0);
+
+    const resultPath = await updateBaseline(current, baselineDir);
+
+    expect(existsSync(resultPath)).toBe(true);
+    expect(resultPath).toContain('to_baseline.png');
+  });
+
+  it('creates the baseline directory if it does not exist', async () => {
+    const current = join(TMP_DIR, 'new_dir_test.png');
+    const baselineDir = join(TMP_DIR, 'new_baselines_dir');
+    createSolidPng(current, 0, 0, 128);
+
+    await updateBaseline(current, baselineDir);
+
+    expect(existsSync(baselineDir)).toBe(true);
+  });
+});

package/helpers/__tests__/seed-validator.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { writeFileSync, mkdirSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { validateSeedCompleteness } from '../seed-validator';
+
+const TMP_DIR = join('/tmp', 'tf-seed-validator-tests');
+
+const SEED_CONTENT = `
+import { PrismaClient } from '@prisma/client';
+const prisma = new PrismaClient();
+
+async function main() {
+  // Seed users
+  await prisma.user.createMany({
+    data: [
+      { email: 'admin@example.com', role: 'ADMIN' },
+      { email: 'staff@example.com', role: 'STAFF' },
+    ],
+  });
+
+  // Seed clients
+  await prisma.client.create({
+    data: { name: 'ACME Corp', abn: '12345678901' },
+  });
+
+  // Seed invoices
+  await prisma.invoice.upsert({
+    where: { id: 1 },
+    update: {},
+    create: { clientId: 1, amount: 1000 },
+  });
+
+  // Insert raw transactions
+  await prisma.$executeRaw\`INSERT INTO transactions (amount) VALUES (500)\`;
+}
+
+main();
+`;
+
+beforeAll(() => {
+  if (!existsSync(TMP_DIR)) {
+    mkdirSync(TMP_DIR, { recursive: true });
+  }
+  writeFileSync(join(TMP_DIR, 'seed.ts'), SEED_CONTENT, 'utf-8');
+});
+
+afterAll(() => {
+  rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+describe('validateSeedCompleteness(seedFilePath, moduleIds)', () => {
+  it('detects covered modules that appear near creation keywords', async () => {
+    const result = await validateSeedCompleteness(
+      join(TMP_DIR, 'seed.ts'),
+      ['user', 'client', 'invoice'],
+    );
+
+    expect(result.covered).toContain('user');
+    expect(result.covered).toContain('client');
+    expect(result.covered).toContain('invoice');
+    expect(result.missing).toHaveLength(0);
+  });
+
+  it('identifies missing modules not present in the seed file', async () => {
+    const result = await validateSeedCompleteness(
+      join(TMP_DIR, 'seed.ts'),
+      ['user', 'client', 'invoice', 'payment', 'subscription'],
+    );
+
+    expect(result.covered).toContain('user');
+    expect(result.covered).toContain('client');
+    expect(result.missing).toContain('payment');
+    expect(result.missing).toContain('subscription');
+  });
+
+  it('returns all modules as missing when seed file is empty', async () => {
+    const emptyPath = join(TMP_DIR, 'empty-seed.ts');
+    writeFileSync(emptyPath, '', 'utf-8');
+
+    const result = await validateSeedCompleteness(emptyPath, ['user', 'client']);
+
+    expect(result.covered).toHaveLength(0);
+    expect(result.missing).toContain('user');
+    expect(result.missing).toContain('client');
+  });
+
+  it('returns all modules as covered when every module matches', async () => {
+    const result = await validateSeedCompleteness(
+      join(TMP_DIR, 'seed.ts'),
+      ['user'],
+    );
+
+    expect(result.covered).toContain('user');
+    expect(result.missing).toHaveLength(0);
+  });
+
+  it('is case-insensitive for module names', async () => {
+    const result = await validateSeedCompleteness(
+      join(TMP_DIR, 'seed.ts'),
+      ['User', 'CLIENT', 'Invoice'],
+    );
+
+    expect(result.covered).toContain('User');
+    expect(result.covered).toContain('CLIENT');
+    expect(result.covered).toContain('Invoice');
+  });
+
+  it('returns empty covered and missing arrays when moduleIds is empty', async () => {
+    const result = await validateSeedCompleteness(join(TMP_DIR, 'seed.ts'), []);
+
+    expect(result.covered).toHaveLength(0);
+    expect(result.missing).toHaveLength(0);
+  });
+});

package/helpers/api-client.ts

@@ -0,0 +1,111 @@
+export interface ApiResponse {
+  status: number;
+  body: unknown;
+  headers: Record<string, string>;
+  durationMs: number;
+}
+
+interface LoginResponseBody {
+  access_token?: string;
+  token?: string;
+  accessToken?: string;
+}
+
+/**
+ * Lightweight HTTP client for integration and API tests.
+ * Automatically attaches Authorization headers when a token is present
+ * and records response duration for every request.
+ */
+export class ApiClient {
+  constructor(
+    private readonly baseUrl: string,
+    private token?: string,
+  ) {}
+
+  /**
+   * Creates an authenticated ApiClient by POSTing credentials to /api/auth/login
+   * and storing the returned JWT for subsequent requests.
+   */
+  static async createAuthenticated(
+    baseUrl: string,
+    credentials: { email: string; password: string },
+  ): Promise<ApiClient> {
+    const client = new ApiClient(baseUrl);
+    const response = await client.post('/api/auth/login', credentials);
+
+    const body = response.body as LoginResponseBody;
+    const jwt = body?.access_token ?? body?.accessToken ?? body?.token;
+
+    if (!jwt) {
+      throw new Error(
+        `Authentication failed: no token in response (status ${response.status})`,
+      );
+    }
+
+    return new ApiClient(baseUrl, String(jwt));
+  }
+
+  async get(path: string): Promise<ApiResponse> {
+    return this.request('GET', path);
+  }
+
+  async post(path: string, body?: unknown): Promise<ApiResponse> {
+    return this.request('POST', path, body);
+  }
+
+  async put(path: string, body?: unknown): Promise<ApiResponse> {
+    return this.request('PUT', path, body);
+  }
+
+  async delete(path: string): Promise<ApiResponse> {
+    return this.request('DELETE', path);
+  }
+
+  private async request(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<ApiResponse> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+
+    const init: RequestInit = {
+      method,
+      headers,
+    };
+
+    if (body !== undefined) {
+      init.body = JSON.stringify(body);
+    }
+
+    const start = Date.now();
+    const response = await fetch(url, init);
+    const durationMs = Date.now() - start;
+
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+
+    let responseBody: unknown;
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+      responseBody = await response.json();
+    } else {
+      responseBody = await response.text();
+    }
+
+    return {
+      status: response.status,
+      body: responseBody,
+      headers: responseHeaders,
+      durationMs,
+    };
+  }
+}

package/helpers/element-discovery.ts

@@ -0,0 +1,105 @@
+import type { Page } from 'playwright';
+
+export interface DiscoveredElement {
+  selector: string;
+  type: 'button' | 'link' | 'input' | 'select' | 'textarea' | 'tab' | 'menuitem' | 'other';
+  text: string;
+  isDestructive: boolean;
+  ariaLabel?: string;
+}
+
+// Keywords that indicate a destructive action
+const DESTRUCTIVE_KEYWORDS = ['delete', 'remove', 'archive', 'destroy', 'clear', 'reset'];
+
+/**
+ * Returns true when the given text (lowercased) contains any destructive keyword.
+ */
+export function classifyAsDestructive(text: string): boolean {
+  const lower = text.toLowerCase();
+  return DESTRUCTIVE_KEYWORDS.some((keyword) => lower.includes(keyword));
+}
+
+// CSS selectors targeting all interactive element categories
+const INTERACTIVE_SELECTORS = [
+  'button',
+  'a[href]',
+  'input',
+  'select',
+  'textarea',
+  '[role="button"]',
+  '[role="tab"]',
+  '[role="menuitem"]',
+  '[data-testid]',
+  '[aria-haspopup]',
+].join(', ');
+
+type ElementType = DiscoveredElement['type'];
+
+function resolveType(tag: string, role: string): ElementType {
+  if (role === 'tab') return 'tab';
+  if (role === 'menuitem') return 'menuitem';
+  if (role === 'button' || tag === 'button') return 'button';
+  if (tag === 'a') return 'link';
+  if (tag === 'input') return 'input';
+  if (tag === 'select') return 'select';
+  if (tag === 'textarea') return 'textarea';
+  return 'other';
+}
+
+function buildSelector(
+  testId: string | null,
+  ariaLabel: string | null,
+  tag: string,
+  text: string,
+): string {
+  if (testId) return `[data-testid="${testId}"]`;
+  if (ariaLabel) return `[aria-label="${ariaLabel}"]`;
+  const safeSuffix = text.trim().slice(0, 40).replace(/"/g, '\\"');
+  return safeSuffix ? `${tag}:text("${safeSuffix}")` : tag;
+}
+
+/**
+ * Discovers all interactive elements on the given Playwright page and returns
+ * a deduplicated, classified list with unique selectors.
+ */
+export async function discoverInteractiveElements(page: Page): Promise<DiscoveredElement[]> {
+  type RawElement = {
+    tag: string;
+    role: string;
+    text: string;
+    ariaLabel: string | null;
+    testId: string | null;
+  };
+
+  const rawElements: RawElement[] = await page.evaluate((selector: string) => {
+    const nodes = Array.from(document.querySelectorAll(selector));
+    return nodes.map((el) => ({
+      tag: el.tagName.toLowerCase(),
+      role: el.getAttribute('role') ?? '',
+      text: (el.textContent ?? '').trim(),
+      ariaLabel: el.getAttribute('aria-label'),
+      testId: el.getAttribute('data-testid'),
+    }));
+  }, INTERACTIVE_SELECTORS);
+
+  const seenSelectors = new Set<string>();
+  const discovered: DiscoveredElement[] = [];
+
+  for (const raw of rawElements) {
+    const selector = buildSelector(raw.testId, raw.ariaLabel, raw.tag, raw.text);
+    if (seenSelectors.has(selector)) continue;
+    seenSelectors.add(selector);
+
+    const labelText = raw.ariaLabel ?? raw.text;
+    const discovered_element: DiscoveredElement = {
+      selector,
+      type: resolveType(raw.tag, raw.role),
+      text: raw.text,
+      isDestructive: classifyAsDestructive(labelText),
+      ...(raw.ariaLabel !== null ? { ariaLabel: raw.ariaLabel } : {}),
+    };
+    discovered.push(discovered_element);
+  }
+
+  return discovered;
+}

package/helpers/env-resolver.ts

@@ -0,0 +1,69 @@
+import type { ValidatedConfig } from '../core/config';
+import type { Phase } from '../core/types';
+
+interface EnvironmentConfig {
+  baseUrl: string;
+  seed?: boolean;
+}
+
+interface ResolvedEnvironment {
+  env: EnvironmentConfig;
+  /** True when the phase's configured URL was unreachable and we fell back to alpha. */
+  fallback: boolean;
+}
+
+/**
+ * Check whether a URL responds with a non-5xx status within a timeout.
+ * Exported so agents can use it directly without duplicating the function.
+ */
+export async function isUrlReachable(url: string, timeoutMs = 5000): Promise<boolean> {
+  try {
+    const response = await fetch(url, {
+      method: 'HEAD',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return response.ok || response.status < 500;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the environment for a given phase with automatic fallback.
+ *
+ * 1. Try the phase's configured environment (`config.environments[phase]`).
+ * 2. If the URL is reachable → return `{ env, fallback: false }`.
+ * 3. If unreachable → try `config.environments['alpha']` (localhost).
+ * 4. If alpha is reachable → return `{ env: alphaEnv, fallback: true }`.
+ * 5. If neither is reachable → return the phase's env with `fallback: false`
+ *    so the agent can decide how to handle the failure.
+ */
+export async function resolveEnvironment(
+  config: ValidatedConfig,
+  phase: Phase,
+): Promise<ResolvedEnvironment> {
+  // Phase-specific environment
+  const phaseEnv = config.environments[phase];
+  if (phaseEnv) {
+    const reachable = await isUrlReachable(phaseEnv.baseUrl);
+    if (reachable) {
+      return { env: phaseEnv, fallback: false };
+    }
+  }
+
+  // Fallback chain: alpha → first available
+  const alphaEnv = config.environments['alpha'];
+  if (alphaEnv && alphaEnv.baseUrl !== phaseEnv?.baseUrl) {
+    const reachable = await isUrlReachable(alphaEnv.baseUrl);
+    if (reachable) {
+      return { env: alphaEnv, fallback: true };
+    }
+  }
+
+  // Nothing reachable — return phase env (or first available) and let agent handle it
+  const fallbackEnv = phaseEnv ?? Object.values(config.environments)[0];
+  if (!fallbackEnv) {
+    throw new Error(`No environment configured for phase "${phase}"`);
+  }
+  return { env: fallbackEnv, fallback: false };
+}