Spectra

Full-Spectrum Test Automation

One command. Complete coverage.

Spectra uses AI agents to explore your app, generate Playwright tests, and automatically fix failures — all without manual intervention.

Quick Start • How It Works • Examples • Documentation

✨ Features

🔵 Multi-Agent Architecture

Three specialized AI agents work in harmony:

• Planner - Explores your app via browser
• Generator - Creates Page Objects & tests
• Healer - Runs tests and fixes failures

🎯 Feature Scoping

Test specific features, not entire pages:

spectra --url http://localhost:5173 \
  --page /checkout \
  --scope "payment form"

🟣 Self-Healing Tests

When tests fail, the Healer agent:

• Inspects current UI state
• Identifies what changed
• Automatically fixes locators
• Re-runs until passing

📋 Page Object Model

Generates clean, maintainable code:

• Semantic locators (getByRole, getByLabel)
• Reusable Page Object classes
• Well-structured test files

🌈 The Spectrum

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│                            PLAYWRIGHT ENGINE                                │
│   ┌─────────────────────────────┐    ┌─────────────────────────────────┐   │
│   │   Chrome DevTools Protocol  │    │  Browser Automation & Execution │   │
│   └─────────────────────────────┘    └─────────────────────────────────┘   │
│                                              ▲                              │
└──────────────────────────────────────────────┼──────────────────────────────┘
                                               │ Runs Tests
┌──────────────────────────────────────────────┼──────────────────────────────┐
│                                 LLM LAYER    │                              │
│  ┌───────────────────┐ ┌─────────────────┐ ┌─┴───────────────────┐         │
│  │ Interprets Results│ │ Understands DOM │ │ Generates Structured│         │
│  │ & Suggests Fixes  │ │ & Routes        │ │ Commands            │         │
│  └───────────────────┘ └─────────────────┘ └─────────────────────┘         │
└─────────────┬───────────────────────────────────────────┬───────────────────┘
              │                                           │
              │ Executes via MCP                          │ Sends commands
              ▼                                           ▼
┌─────────────────────────┐              ┌────────────────────────────────────┐
│  MODEL CONTEXT PROTOCOL │              │            DEVELOPER               │
│  ┌───────────────────┐  │              │  ┌────────────────────────────┐   │
│  │ Structured Command│  │              │  │  Natural Language Prompt   │   │
│  │ Interface         │  │              │  │  or Scope Definition       │   │
│  └───────────────────┘  │              │  └────────────────────────────┘   │
└─────────────────────────┘              └──────────────┬─────────────────────┘
                                                        │
                    ┌───────────────────────────────────┘
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              SPECTRA AGENTS                                 │
│                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │  🟣 HEALER                                                             │ │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐   │ │
│  │  │  Applies Fixes  │  │  Executes Tests │  │  Detects Failures   │   │ │
│  │  └─────────────────┘  └─────────────────┘  └─────────────────────┘   │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    ▲                                        │
│  ┌─────────────────────────────────┴─────────────────────────────────────┐ │
│  │  🔵 PLANNER                                                            │ │
│  │  ┌─────────────────────────┐  ┌─────────────────────────────────┐    │ │
│  │  │     Explores App        │  │    Generates Markdown Plan      │    │ │
│  │  └─────────────────────────┘  └─────────────────────────────────┘    │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                        │
│  ┌─────────────────────────────────▼─────────────────────────────────────┐ │
│  │  🟢 GENERATOR                                                          │ │
│  │  ┌─────────────────────────┐  ┌─────────────────────────────────┐    │ │
│  │  │      Reads Plan         │  │   Generates Playwright Tests    │    │ │
│  │  └─────────────────────────┘  └─────────────────────────────────┘    │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

| Requirement | Version | Check | |------------|---------|-------| | Node.js | LTS (v22.x) | node --version | | pnpm | Latest | pnpm --version | | Git | Any | git --version |

Installation

Option A: Install as npm package

# Install in your project
pnpm add -D spectra-test-automation @playwright/test

# Scaffold project structure
npx spectra --init

# Install Playwright browsers
pnpm exec playwright install chromium

Option B: Install from Git

# Install directly from the repository
pnpm add -D "git+https://github.com/fifijo/spectra.git" @playwright/test

Option C: Clone and develop locally

git clone https://github.com/fifijo/spectra.git
cd spectra
pnpm install
pnpm run build

Generate Your First Tests

# Start your web application (in another terminal)
cd /path/to/your/app && pnpm dev

# Run the seed spec to verify environment
pnpm test:seed

# Run Spectra
npx spectra --url http://localhost:5173

That's it! Check the tests/ folder for your generated tests.

📖 How It Works

🔵 Planner

Explores your application using Playwright MCP, documenting pages, elements, and user flows.

Output: test-plan.md

🟢 Generator

Reads the test plan and generates Page Object classes and test files.

Output: pages/*.ts, tests/*.spec.ts

🟣 Healer

Runs tests, detects failures, inspects UI, and automatically fixes broken locators.

Output: Passing tests ✅

Agent Pipeline Flow

flowchart LR
    A[Developer Input] --> B[🔵 Planner]
    B --> |test-plan.md| C[🟢 Generator]
    C --> |pages/*.ts\ntests/*.spec.ts| D[🟣 Healer]
    D --> |Fix & Retry| D
    D --> E[✅ Passing Tests]

    style A fill:#e1f5fe
    style B fill:#DBEAFE
    style C fill:#D1FAE5
    style D fill:#EDE9FE
    style E fill:#c8e6c9

💡 Examples

Example 1: Full Spectrum Scan

npx spectra --url http://localhost:5173

Spectra explores all accessible pages and generates comprehensive tests.

   ◐◑◒ SPECTRA
   Full-spectrum test automation
   ───────────────────────────────────────────

   Target: http://localhost:5173
   Mode: full-spectrum

   ═══════════════════════════════════════════
   🔵 PLANNER
   ═══════════════════════════════════════════

   ✓ Navigated to http://localhost:5173
   ✓ Discovered 5 pages
   ✓ Documented 23 interactive elements
   ✓ Generated test-plan.md

   ═══════════════════════════════════════════
   🟢 GENERATOR
   ═══════════════════════════════════════════

   ✓ Created pages/HomePage.ts
   ✓ Created pages/LoginPage.ts
   ✓ Created pages/DashboardPage.ts
   ✓ Created tests/auth.spec.ts
   ✓ Created tests/dashboard.spec.ts

   ═══════════════════════════════════════════
   🟣 HEALER
   ═══════════════════════════════════════════

   Running tests...
   ✗ 2 tests failed

   Healing auth.spec.ts...
   ✓ Fixed: Button 'Sign In' → 'Log In'
   ✓ Fixed: Input label 'Email' → 'Email Address'

   Re-running tests...
   ✓ All 8 tests passed

   ═══════════════════════════════════════════
   ✨ SPECTRUM COMPLETE
   ═══════════════════════════════════════════

   Generated:
     📄 Page Objects: 3
     🧪 Test files: 2
     ✓ Passed: 8

Example 2: Single Page Focus

npx spectra --url http://localhost:5173 --page /login

Focus only on the login page.

Example 3: Feature Scoping

When a page has multiple features but you only want to test one:

npx spectra \
  --url http://localhost:5173 \
  --page /checkout \
  --scope "credit card payment form"

Spectra agents will:

1. 🔵 Planner navigates to /checkout and focuses ONLY on the payment form
2. 🟢 Generator creates PaymentFormPage.ts and payment.spec.ts
3. 🟣 Healer runs and fixes only payment-related tests

Other features on the checkout page (shipping form, order summary, etc.) are ignored.

Example 4: Scope File

For complex requirements, create a scope file:

# Create scope file from template
cp docs/SCOPE-template.md SCOPE.md

Edit SCOPE.md:

# Test Scope Definition

## Target Feature
**Feature Name**: User Registration

## Location
**Page URL**: /register

## Elements to Test
- [ ] Email input with validation
- [ ] Password input with strength indicator
- [ ] Confirm password with matching validation
- [ ] Terms checkbox
- [ ] Submit button
- [ ] Success message

## Out of Scope
DO NOT test:
- Login form
- Social login buttons
- Navigation header

Run with scope file:

npx spectra --url http://localhost:5173 --file SCOPE.md

Example 5: Multiple Scopes (Batch Mode)

Run multiple scopes sequentially using a batch JSON config.

Create scopes-batch.json:

{
  "url": "http://localhost:5173",
  "scopes": [
    {
      "name": "Login Form",
      "file": "SCOPE-login.md",
      "description": "Test user authentication flow"
    },
    {
      "name": "Payment Form",
      "file": "SCOPE-payment.md",
      "description": "Test credit card payment processing"
    }
  ]
}

JSON Structure:

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string | No | Target URL (overridden by --url flag if provided) | | scopes | array | Yes | Array of scope definitions | | scopes[].name | string | No | Human-readable name (for documentation) | | scopes[].file | string | Yes | Path to scope file (relative or absolute) | | scopes[].description | string | No | Description of what this scope tests |

Notes:

• The url field is optional. If not provided, use --url flag or set SPECTRA_URL environment variable
• The name and description fields are optional and used for documentation only
• The file field is required and must point to a valid scope file
• File paths can be relative to the current directory or absolute paths

Run with batch config:

npx spectra --batch scopes-batch.json

📖 See BATCH-CONFIG.md for complete JSON schema documentation

The batch runner will:

1. Collect all scopes from directory, files, or JSON config
2. Run each scope sequentially:
   • 🔵 Planner explores the feature
   • 🟢 Generator creates tests
   • 🟣 Healer fixes failures
3. Continue to next scope even if one fails (with option to stop)
4. Show summary of successful/failed scopes

Perfect for comprehensive test coverage across your entire application!

📁 Project Structure

spectra/
│
├── 📂 src/                      # TypeScript source (CLI & library)
│   ├── cli.ts                   # CLI entry point
│   ├── index.ts                 # Public API exports
│   ├── 📂 agents/               # Agent runner & scaffolding
│   └── 📂 utils/                # Shared utilities
│
├── 📂 dist/                     # Compiled output (npm package)
│
├── 📂 templates/                # Shipped with the package
│   ├── 📂 agents/               # Agent definitions (Planner, Generator, Healer)
│   ├── 📂 docs/                 # Scope template
│   └── 📂 fixtures/             # Test fixture template
│
├── 📂 specs/                    # Pipeline gate docs & Markdown plans
│   ├── PLANNER-GATE.md          # Planner review checklist
│   ├── GENERATOR-GATE.md        # Generator review rules
│   ├── CI-HEALER-POLICY.md      # CI traces, Healer limits, triage
│   └── PILOT.md                 # Verification pilot instructions
│
├── 📂 tests/e2e/                # End-to-end seed & integration tests
│   └── seed.spec.ts             # Environment readiness contract
│
├── 📂 .github/                  # CI/CD configuration (optional)
│   └── workflows/
│       └── test.yml             # GitHub Actions workflow
│
├── 📂 docs/                     # Documentation
│   ├── BATCH-CONFIG.md          # Batch configuration guide
│   ├── QUICK-REFERENCE.md       # Quick reference guide
│   ├── SCOPE-template.md        # Template for feature scoping
│   └── WALKTHROUGH.md           # Walkthrough guide
├── 📋 scopes-batch.json         # Example batch config
│
├── 📂 .spectra/                 # Spectra configuration (generated via --init)
│   ├── 📂 agents/
│   │   ├── 📂 planner/
│   │   │   ├── AGENT.md         # Planner instructions
│   │   │   └── prompt.md
│   │   ├── 📂 generator/
│   │   │   ├── AGENT.md         # Generator instructions
│   │   │   └── prompt.md
│   │   ├── 📂 healer/
│   │   │   ├── AGENT.md         # Healer instructions
│   │   │   └── prompt.md
│   │   └── 📂 shared/
│   │       ├── context.md        # Static shared context
│   │       └── current-scope.md  # Dynamically created scope (runtime)
│   │
│   └── 📂 output/               # Agent outputs
│       ├── 📂 plans/
│       │   └── test-plan.md
│       ├── 📂 reports/
│       │   ├── results.json
│       │   ├── status.json      # Machine-readable status
│       │   └── healing-report.md
│       └── 📂 test-results/      # Playwright test results
│
├── 📂 .cursor/
│   └── mcp.json                 # Playwright MCP config
│
├── 📂 pages/                    # Generated Page Objects
│   ├── LoginPage.ts
│   ├── DashboardPage.ts
│   └── ...
│
├── 📂 tests/                    # Generated test files
│   ├── auth.spec.ts
│   ├── dashboard.spec.ts
│   └── ...
│
├── 📂 fixtures/                 # Test fixtures
│   └── pages.ts                 # Reusable page fixtures
│
├── ⚙️ playwright.config.ts
├── ⚙️ tsconfig.json             # TypeScript build config
├── ⚙️ tsconfig.test.json        # TypeScript config for Playwright tests
└── 📦 package.json              # npm package definition

⚙️ Configuration

CLI Options

| Option | Short | Description | Example | |--------|-------|-------------|---------| | --url | -u | Target URL (required) | -u http://localhost:5173 | | --page | -p | Specific page to test | -p /checkout | | --scope | -s | Feature to focus on | -s "payment form" | | --file | -f | Scope file path | -f SCOPE.md | | --batch | -b | JSON file with scope definitions | -b scopes-batch.json | | --manual | -m | Force manual Cursor mode | -m | | --init | | Scaffold project structure | --init | | --debug | | Enable debug output | --debug | | --help | -h | Show help | -h |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SPECTRA_URL | Base URL for tests | http://localhost:5173 | | SPECTRA_BROWSERS | Browsers to test (chromium,firefox,webkit,mobile,all) | chromium | | SPECTRA_TAGS | Filter tests by tags (@smoke,@critical) | (all tests) | | SPECTRA_DEBUG | Enable debug output | (unset) |

# Set base URL
export SPECTRA_URL=http://localhost:5173

# Run without --url flag
npx spectra

# Cross-browser testing
SPECTRA_BROWSERS=chromium,firefox npx spectra --url http://localhost:5173

# Run only smoke tests
SPECTRA_TAGS=@smoke pnpm test

Playwright Configuration

Edit playwright.config.ts:

export default defineConfig({
  use: {
    baseURL: process.env.SPECTRA_URL || 'http://localhost:5173',
    testIdAttribute: 'data-testid',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

Note: The default port 5173 is the Vite dev server default. Adjust to match your application.

🧪 Running Tests

# Run all tests
pnpm test

# Run with visible browser
pnpm test:headed

# Run with Playwright UI
pnpm test:ui

# Run specific test file
pnpm exec playwright test tests/auth.spec.ts

# View HTML report
pnpm report

# Cross-browser testing
SPECTRA_BROWSERS=firefox pnpm test
SPECTRA_BROWSERS=chromium,firefox pnpm test
SPECTRA_BROWSERS=all pnpm test   # All browsers + mobile

# Filter by tags
pnpm test --grep @smoke          # Only smoke tests
pnpm test --grep @critical       # Only critical tests
pnpm test --grep-invert @slow    # Skip slow tests
pnpm test --grep "@auth|@login"  # Multiple tags (OR)

Test Tags

Generated tests can include tags for filtering:

| Tag | Use For | |-----|---------| | @smoke | Quick sanity tests | | @critical | Business-critical paths | | @e2e | Full end-to-end flows | | @slow | Long-running tests | | @flaky | Known flaky tests |

🔧 Modes of Operation

Fully Automated Mode

When cursor-agent or claude CLI is installed:

npx spectra --url http://localhost:5173

All three agents run automatically without intervention.

Manual Cursor Mode

If no CLI is available, or you prefer control:

npx spectra --url http://localhost:5173 --manual

Spectra guides you to run each agent in Cursor.

Installing CLI Tools

# Option 1: cursor-agent
curl https://cursor.com/install -fsS | bash

# Option 2: Claude Code
npm install -g @anthropic-ai/claude-code

🔄 CI/CD Integration (Optional)

Spectra includes an optional GitHub Actions workflow for running tests in CI.

Enable CI

The workflow file is at .github/workflows/test.yml. It will:

1. Install dependencies and Playwright browsers
2. Start your application
3. Run all Playwright tests
4. Upload test reports as artifacts

Configuration

Edit .github/workflows/test.yml to match your application:

# Update the "Start application" section:
- name: Start application
  working-directory: your-app-directory
  run: npm start &

Environment Variables in CI

| Variable | Description | Default | |----------|-------------|---------| | CI | Set automatically by GitHub Actions | true | | SPECTRA_URL | Base URL for tests | http://localhost:5173 |

Manual Trigger

You can manually trigger the workflow from the GitHub Actions tab using workflow_dispatch.

📊 Generated Output Examples

Test Plan (.spectra/output/plans/test-plan.md)

# Test Plan: E-Commerce App

## Pages Discovered
| Page | URL | Elements |
|------|-----|----------|
| Home | / | 12 |
| Login | /login | 5 |
| Dashboard | /dashboard | 18 |

## Test Scenarios

### Scenario 1: Valid Login
- **Priority**: High
- **Type**: Smoke
- **Steps**: Enter valid credentials → Submit → See dashboard

Page Object (pages/LoginPage.ts)

import { Page, Locator } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email Address');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Log In' });
  }

  async login(email: string, password: string): Promise<void> {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
}

Healing Report (.spectra/output/reports/healing-report.md)

# Healing Report

## Summary
| Metric | Count |
|--------|-------|
| Tests Run | 8 |
| Initially Failed | 2 |
| Healed | 2 |
| Final Passed | 8 |

## Fixes Applied

### Fix 1: LoginPage.ts
- **Error**: `Can't find button 'Sign In'`
- **Fix**: Updated to `getByRole('button', { name: 'Log In' })`

❓ Troubleshooting

1. Completely close Cursor
2. Verify .cursor/mcp.json exists
3. Reopen Cursor
4. Test: "Use playwright mcp to navigate to google.com"

pnpm exec playwright install chromium

1. Verify your app is running
2. Check SPECTRA_URL is correct
3. Review .spectra/output/reports/healing-report.md
4. Try with a more specific scope

Use --page and --scope to narrow focus:

npx spectra --url http://localhost:5173 --page /login --scope "login form"

📦 Publishing to npm

Build and publish

# Build the package
pnpm run build

# Publish to npm registry
npm publish

# Or publish to a private registry
npm publish --registry https://your-registry.example.com

Install from private registry

Add a .npmrc to consuming projects:

@yourorg:registry=https://your-registry.example.com
//your-registry.example.com/:_authToken=${NPM_TOKEN}

Then install:

pnpm add -D @yourorg/spectra-test-automation @playwright/test

Install from Git (Bitbucket / GitHub)

# SSH
pnpm add -D "git+ssh://[email protected]/yourorg/spectra.git"

# HTTPS
pnpm add -D "git+https://github.com/fifijo/spectra.git"

Versioning

Follow semver:

• Patch (0.1.1): bug fixes, doc updates
• Minor (0.2.0): new features, new agent templates
• Major (1.0.0): breaking CLI changes or peer @playwright/test range changes

🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Install dependencies: pnpm install
4. Build: pnpm run build
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file.

🙏 Acknowledgments

• Playwright - Browser automation framework
• Anthropic Claude - AI assistance
• Model Context Protocol - MCP standard
• Cursor - AI-powered IDE

⬆ Back to Top

◐ ◑ ◒

Spectra — Full-spectrum test automation

Made with ❤️ by developers, for developers