ai-debug-local-mcp/core/packages/ai-debug-test-engine/README.md

🎯 ENHANCED AI GUIDANCE v4.1.2: Dramatically improved tool descriptions help AI users choose the right tools instead of 'close enough' options. Ultra-fast keyboard automation (10x speed), universal recording, multi-ecosystem debugging support, and compreh

# AI Debug Test Engine

The test generation and execution engine for the AI Debug platform. This package implements the "Debug Once, Test Forever" philosophy by converting debugging sessions into comprehensive, maintainable test suites.

## Overview

AI Debug Test Engine is a standalone Elixir package that:
- Generates tests from recorded debugging sessions
- Executes tests with deterministic browser automation
- Performs visual regression testing
- Provides performance profiling and validation
- Supports multiple test frameworks (ExUnit, Jest, Pytest, RSpec)

## Installation

Add `ai_debug_test_engine` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:ai_debug_test_engine, "~> 0.1.0"}
  ]
end
```

## Usage

### Test Generation

Generate tests from a debugging session:

```elixir
# Load a debugging session
session = AiDebugTestEngine.Session.load("session_id")

# Generate tests
{:ok, tests} = AiDebugTestEngine.TestGenerator.generate(session, 
  framework: :exunit,
  coverage_target: :comprehensive
)

# Write tests to file
AiDebugTestEngine.TestWriter.write(tests, "test/generated/feature_test.exs")
```

### Test Execution

Run generated tests with the deterministic browser:

```elixir
# Configure browser pool
AiDebugTestEngine.BrowserPool.start_link(
  size: 4,
  headless: true,
  deterministic: true
)

# Run tests
{:ok, results} = AiDebugTestEngine.TestRunner.run("test/generated/",
  parallel: true,
  timeout: 30_000
)
```

### Visual Regression Testing

Perform visual regression tests:

```elixir
# Capture baseline
{:ok, baseline} = AiDebugTestEngine.VisualRegression.capture_baseline(
  url: "http://localhost:4000",
  name: "homepage"
)

# Compare with current state
{:ok, comparison} = AiDebugTestEngine.VisualRegression.compare(
  baseline: baseline,
  current_url: "http://localhost:4000",
  threshold: 0.1
)
```

### Performance Profiling

Profile application performance:

```elixir
# Start profiling
{:ok, profiler} = AiDebugTestEngine.Performance.start_profiling(
  url: "http://localhost:4000",
  metrics: [:lcp, :fcp, :cls, :ttfb]
)

# Get results
{:ok, metrics} = AiDebugTestEngine.Performance.get_metrics(profiler)
```

## Architecture

The engine is organized into several key modules:

- **TestGenerator**: Converts debugging sessions into test code
- **TestRunner**: Executes tests with parallel support
- **DeterministicBrowser**: Provides consistent browser automation
- **ValidationOrchestrator**: Coordinates test validation workflows
- **VisualRegression**: Handles visual comparison testing
- **Performance**: Profiles and validates performance metrics

## Configuration

Configure the engine in your `config.exs`:

```elixir
config :ai_debug_test_engine,
  browser_pool_size: 4,
  default_timeout: 30_000,
  visual_regression_threshold: 0.1,
  storage_adapter: AiDebugTestEngine.Storage.Local,
  storage_path: "priv/test_artifacts"
```

## API Reference

### Core APIs

- `AiDebugTestEngine.generate/2` - Generate tests from session
- `AiDebugTestEngine.run/2` - Execute test suite
- `AiDebugTestEngine.validate/2` - Validate test results
- `AiDebugTestEngine.report/1` - Generate test reports

### Extension Points

The engine supports plugins for:
- Custom test frameworks
- Storage adapters
- Browser providers
- Metric collectors

## Contributing

Contributions are welcome! Please see our contributing guidelines.

## License

MIT License - see LICENSE file for details.