@avi770/testteam 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - Unreleased
+
+### Added
+- Release phase (phase 4) with Agent 10 (Reporter) generating consolidated release reports
+- 4-gate pipeline architecture: Alpha -> Beta -> UAT -> Release with blocking/advisory classification
+- Graceful degradation for agents that encounter missing dependencies or unavailable services
+- Environment variable resolver with `TF_` prefix convention and fallback chain support
+
+### Changed
+- Browser Crawler (Agent 5) optimized: reduced redundant page visits, shared browser context across phases, parallel screenshot capture
+- Pipeline orchestrator now supports `--phase release` and `--phase all` includes the release phase
+- Improved error messages with structured error codes across all agents
+
+### Fixed
+- Environment resolver now correctly merges `.env`, `.env.local`, and process environment with proper precedence
+- Browser Crawler no longer re-authenticates between module crawls within the same phase
+- Gate evaluation handles advisory-only phases without false-positive blocking
+- Reporter agent correctly aggregates findings across all prior phases when run standalone
+
+## [1.0.0] - 2026-03-15
+
+### Added
+- 23 specialized testing agents covering unit, integration, e2e, security, accessibility, performance, and more
+- 3-tier licensing model: Free (8 agents), Pro (17 agents), Enterprise (all 23 agents)
+- 4-phase pipeline: Alpha, Beta, UAT, Release with quality gates between each phase
+- Interactive init wizard (`npx testteam init`) with automatic framework and test runner detection
+- CLI with `init`, `--phase`, `--dry-run`, `--agent`, and `--config` commands
+- HTML report generation with per-agent findings, screenshots, and severity classification
+- CI/CD templates for GitHub Actions, Azure DevOps, and GitLab CI
+- Mintlify documentation site with full API reference and guides
+- Self-healing fix loops: Healer (Agent 9) for test bugs, Fixer (Agent 11) for code bugs
+- Visual regression detection with pixel-level diffing and baseline management
+- Accessibility scanning via axe-core integration (Agent 8)
+- Security auditing with dependency scanning and header validation (Agent 7)
+- Performance profiling with Lighthouse scores, FCP, LCP, and memory tracking (Agent 13)
+- Cost budget tracking with per-run and per-agent limits and configurable exceed policies
+- Configurable agent classification (blocking vs. advisory) per phase
+- Evidence collection: screenshots, DOM snapshots, network logs
+- Enterprise features: chaos testing, tenant isolation, workflow completion, state/session testing, migration safety
+- Multi-tenant isolation verification for SaaS applications (Agent 19)
+- Database migration safety testing with up/down/idempotency checks (Agent 23)
+- Helper utilities: navigation, API client, form filler, element discovery, modal handler, quality gate, screenshot comparison, seed validator
+- 595 unit tests
+- TypeScript strict mode throughout with full type safety
+
+[1.1.0]: https://github.com/BAS-More/E2E-Tester/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/BAS-More/E2E-Tester/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BAS & More Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+<p align="center">
+  <img src="docs/logo-placeholder.png" alt="TestTeam" width="200" />
+</p>
+
+<h1 align="center">TestTeam</h1>
+
+<p align="center">
+  <strong>23-agent AI testing orchestration framework</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/testteam"><img src="https://img.shields.io/npm/v/testteam.svg" alt="npm version" /></a>
+  <a href="https://github.com/BAS-More/E2E-Tester/actions"><img src="https://img.shields.io/github/actions/workflow/status/BAS-More/E2E-Tester/ci.yml?label=CI" alt="CI Status" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
+  <img src="https://img.shields.io/badge/tests-passing-brightgreen.svg" alt="Tests: passing" />
+  <img src="https://img.shields.io/badge/TypeScript-strict-blue.svg" alt="TypeScript strict" />
+</p>
+
+---
+
+Autonomous multi-phase testing pipeline with 23 specialized agents. Runs Alpha through Release with quality gates, self-healing fix loops, and zero manual intervention.
+
+## Quick Start
+
+```bash
+# 1. Initialize in your project
+npx testteam init
+
+# 2. Configure (edit the generated config)
+vi testteam.config.ts
+
+# 3. Run
+npx testteam --phase alpha
+```
+
+The init wizard auto-detects your framework, test runner, and scaffolds configuration.
+
+## Why TestTeam
+
+- **4-phase pipeline** -- Alpha, Beta, UAT, Release with quality gates that block promotion on failure
+- **23 specialized agents** -- each owns a single testing concern (a11y, security, perf, visual regression, chaos, and more)
+- **Self-healing fix loop** -- Healer and Fixer agents attempt automatic remediation before gate evaluation
+- **Visual regression** -- pixel-level screenshot diffing with baseline management
+- **Cost-controlled** -- per-run and per-agent budget limits with configurable abort/alert policies
+- **Framework-agnostic** -- React, Next.js, Vue, Angular, NestJS, Express, or any project
+
+## Agent Roster
+
+| # | Agent | Phase(s) | Tier |
+|---|-------|----------|------|
+| 1 | Analyst | Alpha | Free |
+| 2 | Seed Architect | Alpha | Free |
+| 3 | Test Generator | Alpha | Free |
+| 4 | Unit Runner | Alpha | Free |
+| 5 | Browser Crawler | Alpha, Beta, UAT | Free |
+| 6 | API Exerciser | Beta, UAT | Free |
+| 7 | Security Scout | Beta | Free |
+| 8 | A11y Guardian | Beta | Free |
+| 9 | Healer | Fix Loop | Pro |
+| 10 | Reporter | Release | Pro |
+| 11 | Fixer | Fix Loop | Pro |
+| 12 | UX Inspector | Beta, UAT | Pro |
+| 13 | Performance Profiler | Beta, UAT | Pro |
+| 14 | Data Integrity Auditor | Beta, UAT | Pro |
+| 15 | Regression Sentinel | Beta, UAT | Pro |
+| 16 | Chaos Agent | Beta | Enterprise |
+| 17 | Documentation Validator | UAT | Enterprise |
+| 18 | Integration Watchdog | Beta, UAT | Enterprise |
+| 19 | Tenant Isolation Auditor | Beta, UAT | Enterprise |
+| 20 | Workflow Completion Tester | UAT | Enterprise |
+| 21 | State/Session Tester | Beta, UAT | Enterprise |
+| 22 | Email/Notification Verifier | Beta, UAT | Enterprise |
+| 23 | Migration Tester | Alpha | Enterprise |
+
+## Architecture
+
+```
+Alpha --> [gate] --> Beta --> [gate] --> UAT --> [gate] --> Release
+  |                   |                  |
+  +------- Fix Loop (Healer + Fixer) ---+
+```
+
+Each phase dispatches its agents, evaluates findings against blocking/advisory classification, and promotes to the next phase only if the gate passes. The fix loop runs automatically when agents detect issues.
+
+## Pricing
+
+| Plan | Price | Agents | Support |
+|------|-------|--------|---------|
+| **Free** | $0 | 8 agents (1--8) | Community |
+| **Pro** | $49/mo | 17 agents (1--15) | Priority email |
+| **Enterprise** | $199/mo | All 23 agents + custom | Dedicated support, SLA |
+
+All plans include the CLI, init wizard, and config validation. Pro and Enterprise unlock the fix loop, Reporter, and advanced agents.
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+name: TestTeam
+on: [push, pull_request]
+
+jobs:
+  testteam:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx testteam --phase all
+        env:
+          TF_ADMIN_EMAIL: ${{ secrets.TF_ADMIN_EMAIL }}
+          TF_ADMIN_PASSWORD: ${{ secrets.TF_ADMIN_PASSWORD }}
+```
+
+## CLI Reference
+
+```
+Usage: testteam [options]
+
+Commands:
+  init                                     Initialize TestTeam
+
+Options:
+  --phase <alpha|beta|uat|release|all>     Phase to run
+  --dry-run                                Show dispatch plan without executing
+  --agent <id>                             Run a single agent by ID
+  --config <path>                          Path to config file
+  --help                                   Show help
+```
+
+## Configuration
+
+```ts
+import type { TestTeamConfig } from 'testteam/config';
+
+const config: TestTeamConfig = {
+  schemaVersion: 1,
+  name: 'my-app',
+  modules: [
+    { id: 'dashboard', route: '/dashboard', sidebarIcon: true },
+  ],
+  environments: {
+    alpha: { baseUrl: 'http://localhost:3000', seed: true },
+    beta:  { baseUrl: 'https://staging.example.com', seed: false },
+  },
+};
+
+export default config;
+```
+
+See the [full configuration reference](https://docs.testteam.dev/configuration) for all options including auth, breakpoints, cost budgets, thresholds, and agent classification.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, how to create custom agents, code style, and PR workflow.
+
+## Documentation
+
+Full docs: [docs.testteam.dev](https://docs.testteam.dev)
+
+## License
+
+[MIT](LICENSE) -- Copyright 2026 BAS & More Pty Ltd

package/agents/01-analyst.ts

@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BaseAgent } from './base-agent';
+import type { Finding } from '../core/types';
+
+const execFileAsync = promisify(execFile);
+
+/** Shared-dependency file patterns whose changes elevate all modules to critical risk */
+const SHARED_DEPENDENCY_PATTERNS = ['AuthContext', 'App.tsx', 'router'];
+
+interface TestPlanModule {
+  id: string;
+  risk: 'critical' | 'high' | 'low';
+  changedFiles: string[];
+}
+
+interface TestPlan {
+  modules: TestPlanModule[];
+}
+
+export class AnalystAgent extends BaseAgent {
+  readonly agentId = 1;
+  readonly agentName = 'Analyst';
+
+  protected async preFlight(): Promise<void> {
+    await execFileAsync('git', ['--version'], { shell: true });
+  }
+
+  /** Auto-detect the default branch: try 'main', fall back to 'master', then 'HEAD'. */
+  private async detectDefaultBranch(): Promise<string> {
+    for (const candidate of ['main', 'master']) {
+      try {
+        await execFileAsync('git', ['rev-parse', '--verify', candidate], { shell: true });
+        return candidate;
+      } catch {
+        // branch does not exist, try next
+      }
+    }
+    return 'HEAD';
+  }
+
+  protected async execute(): Promise<Finding[]> {
+    const defaultBranch = await this.detectDefaultBranch();
+    const { stdout } = await execFileAsync('git', ['diff', `${defaultBranch}...HEAD`, '--name-only'], { shell: true });
+    const changedFiles = stdout.split('\n').map(f => f.trim()).filter(Boolean);
+
+    this.addEvidence({
+      type: 'log',
+      path: join(this.runDir, 'changed-files.txt'),
+      description: `${changedFiles.length} files changed since ${defaultBranch}`,
+    });
+
+    const hasSharedDependencyChange = changedFiles.some(file =>
+      SHARED_DEPENDENCY_PATTERNS.some(pattern => file.includes(pattern)),
+    );
+
+    const moduleMap = new Map<string, string[]>();
+    for (const module of this.config.modules) {
+      moduleMap.set(module.id, []);
+    }
+
+    for (const file of changedFiles) {
+      for (const module of this.config.modules) {
+        const routeKey = module.route.replace(/^\//, '');
+        if (routeKey && file.includes(routeKey)) {
+          moduleMap.get(module.id)?.push(file);
+        }
+      }
+    }
+
+    const testPlanModules: TestPlanModule[] = this.config.modules.map(module => {
+      const moduleChangedFiles = moduleMap.get(module.id) ?? [];
+
+      let risk: 'critical' | 'high' | 'low';
+      if (hasSharedDependencyChange) {
+        risk = 'critical';
+      } else if (moduleChangedFiles.length > 0) {
+        risk = 'high';
+      } else {
+        risk = 'low';
+      }
+
+      return { id: module.id, risk, changedFiles: moduleChangedFiles };
+    });
+
+    const testPlan: TestPlan = { modules: testPlanModules };
+    const testPlanPath = join(this.runDir, 'test-plan.json');
+    await writeFile(testPlanPath, JSON.stringify(testPlan, null, 2), 'utf-8');
+
+    this.addEvidence({
+      type: 'report',
+      path: testPlanPath,
+      description: 'Generated test plan with module risk scores',
+    });
+
+    return [];
+  }
+}

package/agents/02-seed-architect.ts

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { BaseAgent } from './base-agent';
+import { validateSeedCompleteness } from '../helpers/seed-validator';
+import type { Finding } from '../core/types';
+
+export class SeedArchitectAgent extends BaseAgent {
+  readonly agentId = 2;
+  readonly agentName = 'Seed Architect';
+
+  private get projectRoot(): string {
+    const envConfig = this.config.environments['alpha'] ?? Object.values(this.config.environments)[0];
+    // Use projectRoot from environment config if available, otherwise fall back to cwd
+    const root = (envConfig as unknown as Record<string, unknown> | undefined)?.['projectRoot'];
+    return typeof root === 'string' ? root : process.cwd();
+  }
+
+  private get seedFilePath(): string {
+    return join(this.projectRoot, 'prisma', 'seed.ts');
+  }
+
+  protected async preFlight(): Promise<void> {
+    // Seed file is optional — missing file produces a warning finding instead of throwing
+  }
+
+  protected async execute(): Promise<Finding[]> {
+    if (!existsSync(this.seedFilePath)) {
+      return [{
+        id: `${this.agentId}-seed-file-missing`,
+        type: 'infra-issue' as const,
+        severity: 'medium' as const,
+        agentId: this.agentId,
+        module: 'seed',
+        description: `Seed file not found at ${this.seedFilePath}. Seed validation skipped.`,
+        suggestedFix: `Create a seed file at prisma/seed.ts or set projectRoot in your environment config.`,
+      }];
+    }
+
+    const moduleIds = this.config.modules.map(m => m.id);
+    const result = await validateSeedCompleteness(this.seedFilePath, moduleIds);
+
+    this.addEvidence({
+      type: 'report',
+      path: this.seedFilePath,
+      description: `Seed validation: ${result.covered.length} covered, ${result.missing.length} missing`,
+    });
+
+    return result.missing.map((moduleId, index) => ({
+      id: `${this.agentId}-seed-missing-${index}`,
+      type: 'code-bug-logic' as const,
+      severity: 'medium' as const,
+      agentId: this.agentId,
+      module: moduleId,
+      description: `Module "${moduleId}" has no seed data in prisma/seed.ts`,
+      file: this.seedFilePath,
+      suggestedFix: `Add a data-creation block for module "${moduleId}" in prisma/seed.ts`,
+    }));
+  }
+}

package/agents/03-test-generator.ts

@@ -0,0 +1,191 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'path';
+import type { Finding } from '../core/types';
+import { BaseAgent } from './base-agent';
+import { validateCodeQuality } from '../helpers/quality-gate';
+
+interface FileCoverage {
+  lines: { pct: number };
+  functions: { pct: number };
+  branches: { pct: number };
+  statements: { pct: number };
+}
+
+type CoverageSummary = Record<string, FileCoverage>;
+
+const COVERAGE_DIR = 'coverage';
+const GENERATED_TESTS_DIR = 'tests/generated';
+const VITEST_CONFIG_PATHS = ['vitest.config.ts', 'vitest.config.js', 'vite.config.ts'];
+
+async function fileExists(p: string): Promise<boolean> {
+  try { await stat(p); return true; } catch { return false; }
+}
+
+async function findCoverageJsonFiles(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir);
+    return entries.filter((f) => f.endsWith('.json')).map((f) => join(dir, f));
+  } catch {
+    return [];
+  }
+}
+
+async function parseCoverageSummary(filePath: string): Promise<CoverageSummary | null> {
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === 'object' && 'total' in parsed) {
+      return parsed as CoverageSummary;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function findGeneratedTestFiles(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir);
+    return entries
+      .filter((f) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js'))
+      .map((f) => join(dir, f));
+  } catch {
+    return [];
+  }
+}
+
+export class TestGeneratorAgent extends BaseAgent {
+  readonly agentId = 3;
+  readonly agentName = 'Test Generator';
+
+  protected async preFlight(): Promise<void> {
+    // Audit: verify coverage data availability (advisory only — may not exist on first run)
+    const coverageFiles = await findCoverageJsonFiles(COVERAGE_DIR);
+    if (coverageFiles.length === 0) {
+      // Advisory — not a hard pre-flight failure; coverage may not exist on first run
+    }
+
+    // Validate: verify vitest config is present so generated tests can actually run
+    const vitestConfigChecks = await Promise.all(VITEST_CONFIG_PATHS.map((p) => fileExists(p)));
+    const vitestConfigExists = vitestConfigChecks.some(Boolean);
+    if (!vitestConfigExists) {
+      // Advisory only — project may use a differently-named config
+    }
+
+    // Pre-check: note whether generated tests directory exists
+    const generatedDirExists = await fileExists(GENERATED_TESTS_DIR);
+    if (!generatedDirExists) {
+      // Advisory — directory will be created when tests are first generated
+    }
+  }
+
+  protected async execute(): Promise<Finding[]> {
+    const findings: Finding[] = [];
+
+    // -----------------------------------------------------------------------
+    // Phase 1: Coverage gap detection
+    // -----------------------------------------------------------------------
+
+    const coverageFiles = await findCoverageJsonFiles(COVERAGE_DIR);
+
+    if (coverageFiles.length === 0) {
+      findings.push({
+        id: '3-no-coverage-data',
+        type: 'code-bug-logic',
+        severity: 'medium',
+        agentId: this.agentId,
+        module: 'test-coverage',
+        description:
+          'Coverage analysis not available: no JSON files found in coverage/. ' +
+          'Run vitest with --coverage to generate coverage data.',
+      });
+    } else {
+      const thresholds = this.config.thresholds.unitCoverage;
+
+      for (const filePath of coverageFiles) {
+        const summary = await parseCoverageSummary(filePath);
+        if (!summary) continue;
+
+        this.addEvidence({
+          type: 'report',
+          path: filePath,
+          description: `Coverage summary from ${filePath}`,
+        });
+
+        for (const [entry, coverage] of Object.entries(summary)) {
+          if (entry === 'total') continue;
+
+          const gaps: string[] = [];
+
+          if (coverage.lines.pct < thresholds.lines) {
+            gaps.push(`lines ${coverage.lines.pct.toFixed(1)}% < ${thresholds.lines}%`);
+          }
+          if (coverage.functions.pct < thresholds.functions) {
+            gaps.push(`functions ${coverage.functions.pct.toFixed(1)}% < ${thresholds.functions}%`);
+          }
+          if (coverage.branches.pct < thresholds.branches) {
+            gaps.push(`branches ${coverage.branches.pct.toFixed(1)}% < ${thresholds.branches}%`);
+          }
+          if (coverage.statements.pct < thresholds.statements) {
+            gaps.push(`statements ${coverage.statements.pct.toFixed(1)}% < ${thresholds.statements}%`);
+          }
+
+          if (gaps.length > 0) {
+            findings.push({
+              id: `3-coverage-gap-${entry.replace(/[^a-zA-Z0-9]/g, '-').slice(0, 60)}`,
+              type: 'code-bug-logic',
+              severity: 'medium',
+              agentId: this.agentId,
+              module: 'test-coverage',
+              description: `Coverage below threshold for "${entry}": ${gaps.join(', ')}`,
+              file: entry,
+            });
+          }
+        }
+      }
+    }
+
+    // -----------------------------------------------------------------------
+    // Phase 2: Quality gate on generated test files
+    // AVI-OS: validate code quality of any previously generated tests
+    // -----------------------------------------------------------------------
+
+    const generatedTestFiles = await findGeneratedTestFiles(GENERATED_TESTS_DIR);
+
+    for (const testFilePath of generatedTestFiles) {
+      let fileContent: string;
+      try {
+        fileContent = await readFile(testFilePath, 'utf-8');
+      } catch {
+        // If we cannot read the file, skip it silently
+        continue;
+      }
+
+      const violations = validateCodeQuality(fileContent, testFilePath);
+
+      for (const violation of violations) {
+        findings.push({
+          id: `3-quality-violation-${testFilePath.replace(/[^a-zA-Z0-9]/g, '-').slice(-50)}-L${violation.line ?? 0}`,
+          type: 'code-bug-logic',
+          severity: violation.severity === 'error' ? 'high' : 'medium',
+          agentId: this.agentId,
+          module: 'test-quality-gate',
+          description:
+            `Quality violation in generated test "${testFilePath}" [${violation.rule}]: ${violation.message}`,
+          file: testFilePath,
+          suggestedFix: `Fix the ${violation.rule} violation to comply with AVI-OS coding quality standards`,
+        });
+      }
+
+      if (violations.length === 0) {
+        this.addEvidence({
+          type: 'log',
+          path: testFilePath,
+          description: `Quality gate passed for generated test: ${testFilePath}`,
+        });
+      }
+    }
+
+    return findings;
+  }
+}