📖 Browse the full documentation at automatetheplanet.github.io/Spectra

AI-native test case generation and execution framework.
From documentation to deterministic test execution.

---

What does SPECTRA mean?

The name evokes the visible spectrum — SPECTRA covers the full spectrum of test activities, from documentation analysis through generation, verification, execution, coverage, and reporting. Nothing in the workflow is left dark.

It also reads as a backronym:

Spec-driven · Protocol for · Executable · Coverage, · Testing, · Reasoning · and · Automation

In practice it's a single product with two halves that can be used independently:

1. An AI test-generation CLI that turns product documentation into versioned Markdown test cases.
2. An MCP execution engine that drives those tests through any AI orchestrator with a deterministic state machine.

Why SPECTRA?

SPECTRA reads your product documentation, generates comprehensive test suites, and executes them through a deterministic AI-orchestrated protocol. It doesn't replace your existing tools — it adds an AI layer.

• Reads your documentation — Point SPECTRA at your product docs and it generates comprehensive test suites automatically.

• AI with guardrails — Dual-model grounding verification catches hallucinated test steps before they reach your suite.

• Test cases as Markdown — Test cases are plain Markdown files with YAML frontmatter. They live in GitHub, versioned alongside your code.

• Deterministic execution — An MCP-based execution engine provides a state machine that any AI orchestrator can drive without holding state.

• Coverage visibility — Three-dimensional coverage analysis: documentation, acceptance criteria, and automation. Visual dashboard included.

• No migration needed — Integrates with Azure DevOps, Jira, Teams, Slack through their MCP servers. No data sync. No vendor lock-in.

Key Features

AI Test Generation

Generate test cases from product documentation through an iterative session. The AI analyzes your docs, identifies testable behaviors, generates structured test cases, suggests additional tests for uncovered areas, and lets you describe undocumented behaviors — all in one continuous flow.

Behavior analysis applies six ISTQB test design techniques systematically (Equivalence Partitioning, Boundary Value Analysis, Decision Table, State Transition, Error Guessing, Use Case) so the produced suites have meaningful boundary and negative coverage instead of happy-path-only scenarios. Analysis output exposes both a category breakdown and a per-technique breakdown.

spectra ai generate                    # Interactive session
spectra ai generate checkout           # Direct mode
spectra ai generate checkout --auto-complete --output-format json  # CI mode

Grounding Verification

Every generated test is verified by a second AI model against the source documentation. Hallucinated steps are caught and rejected automatically.

Coverage Analysis

Three coverage dimensions tracked automatically:

• Documentation — which docs have linked tests
• Acceptance Criteria — which criteria are tested
• Automation — which tests have automation code

spectra ai analyze --coverage --auto-link

Visual Dashboard

Static HTML dashboard with suite browser, test viewer, run history, and coverage visualizations. Deploy to Cloudflare Pages with GitHub OAuth authentication.

spectra dashboard --output ./site

MCP Execution Engine

Execute tests through Copilot Chat, Claude, or any MCP client. State machine with pause/resume, crash recovery, and three report formats (JSON, Markdown, HTML). Inline documentation lookup via Copilot Spaces — testers get answers about test steps without leaving the execution flow.

Copilot Chat Integration

Bundled SKILL files let you use SPECTRA through natural language in Copilot Chat. Say "generate test cases for checkout" and the SKILL handles CLI invocation, JSON parsing, and result presentation.

spectra init                  # Creates 12 SKILLs + 2 agent prompts
spectra update-skills         # Update SKILLs when CLI is upgraded

Generation Profiles

Customize AI output with natural language profiles — detail level, negative scenario count, domain rules, formatting preferences.

Quick Start

Prerequisites: .NET 8.0+

# Install
dotnet tool install -g Spectra.CLI

# Initialize (creates config, dirs, SKILL files, agent prompts)
spectra init

# Build the document index (also extracts acceptance criteria automatically)
spectra docs index

# Generate tests — interactive session with analysis, suggestions, and more
spectra ai generate

# Or direct mode for a specific suite
spectra ai generate checkout --count 10

# Validate generated tests
spectra validate

# Analyze coverage
spectra ai analyze --coverage

# Generate a visual dashboard
spectra dashboard --output ./site

For CI/SKILL workflows — all commands support --output-format json and --no-interaction:

spectra ai generate checkout --auto-complete --output-format json
spectra ai analyze --coverage --output-format json
spectra validate --output-format json --no-interaction

See Getting Started for auth setup and detailed instructions.

Using SPECTRA from VS Code Copilot Chat

After spectra init, the bundled spectra-quickstart SKILL turns Copilot Chat into a guided onboarding entry point. Open Copilot Chat in VS Code and ask:

"Help me get started"

The assistant walks you through every workflow (test generation, criteria extraction, coverage, dashboard, execution, customization) with copyable example prompts. For an offline reference covering the same workflows, see the auto-generated USAGE.md at your project root.

Architecture

docs/                        <- Source documentation
  |
docs/_index.md               <- Pre-built document index (incremental)
  |
AI Test Generation CLI       <- GitHub Copilot SDK (sole AI runtime)
  |                            Supports: github-models, azure-openai,
test-cases/                  <-          azure-anthropic, openai, anthropic
  |
MCP Execution Engine         <- Deterministic state machine
  |
LLM Orchestrator             <- Copilot Chat, Claude, any MCP client
  | (as needed)
Azure DevOps / Jira / Teams  <- Bug logging, notifications via their MCPs

Subsystem	Purpose	Independent?
AI CLI	Generate, update, and analyze test cases from documentation	Yes
MCP Engine	Execute tests through deterministic AI-orchestrated protocol	Yes

Ecosystem

SPECTRA is part of the Automate The Planet ecosystem:

Tool	Purpose
BELLATRIX	Test automation framework
Testimize	Test case optimization (hybrid ABC algorithm)
SPECTRA	AI test generation and execution protocol

BELLATRIX automates test execution. Testimize optimizes test case selection. SPECTRA generates and maintains the test cases themselves — closing the loop between documentation and quality assurance.

Optional Testimize integration: SPECTRA ships with the Testimize library bundled as an in-process NuGet dependency (no separate installation needed). When enabled, it replaces AI-approximated boundary values with mathematically precise ones — exact min-1/min/max/max+1 BVA, security-focused invalid patterns (XSS, SQLi), and optimized multi-field pairwise/ABC combinations. Disabled by default; set testimize.enabled to true in spectra.config.json. See Testimize Integration.

Documentation

Guide	Description
Getting Started	Install, prerequisites, auth setup, first run
CLI Reference	All commands, flags, and options
Configuration	Full spectra.config.json reference
Test Format	Markdown format, YAML frontmatter, metadata schema
Coverage Analysis	Documentation, Requirements, and Automation coverage
Generation Profiles	Customize AI output style and quality
Grounding Verification	Dual-model critic for hallucination detection
Document Index	Pre-built doc index for efficient generation
Skills Integration	Copilot Chat SKILLs and agent prompts
Usage (Copilot Chat)	Workflow-by-workflow guide for driving SPECTRA via Copilot Chat
Customization	Every customization knob — config, profiles, prompts, palettes
Testimize Integration	Optional algorithmic test data optimization (BVA / EP / pairwise / ABC)
Execution Agent	MCP tools and AI-driven test execution
Architecture	System design and key decisions
Development Guide	Building, testing, and running locally

Project Status

SPECTRA is in active development.

• Phase 1: AI Test Generation CLI ✓
• Phase 2: MCP Execution Engine ✓
• Phase 3: Dashboard & Coverage Analysis ✓
• Phase 4: Test Generation Profiles ✓
• Phase 5: Grounding Verification ✓
• Phase 6: Integrations and Ecosystem ← current

Contributing

Contributions are welcome! See CONTRIBUTING.md for build instructions, code style guidelines, and the PR process.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Copyright 2024-2026 Automate The Planet Ltd.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.