Getting Started

Install SPECTRA, authenticate, and generate your first test case suite.

Related: CLI Reference Configuration

New in spec 037: behavior analysis applies six ISTQB test design techniques (EP, BVA, DT, ST, EG, UC) and the analysis output now includes a technique breakdown alongside the category breakdown. Existing projects can adopt the new templates by running spectra prompts reset --all — your customized templates are preserved.

New in spec 038 (optional): SPECTRA can integrate with Testimize.MCP.Server for algorithmic test data optimization (BVA, EP, pairwise, ABC). Disabled by default. Install with dotnet tool install --global Testimize.MCP.Server, set testimize.enabled to true in spectra.config.json, then verify with spectra testimize check. SPECTRA works fine without Testimize.

Prerequisites

  • .NET 8.0+ SDK
  • Git
  • VS Code with GitHub Copilot (for MCP execution)
  • GitHub Copilot Chat extension (for MCP support)
  • One of the following authentication options (for AI test generation):
    • GitHub CLI authenticated (gh auth login)
    • GITHUB_TOKEN environment variable
    • OPENAI_API_KEY or ANTHROPIC_API_KEY for alternative providers

Install 

dotnet tool install -g Spectra.CLI

Initialize a Repository 

cd my-project
spectra init

This creates:

my-project/
├── spectra.config.json                          # Configuration
├── docs/                                        # Put your documentation here
│   └── _index.md                                # Document index (auto-built if docs exist)
├── test-cases/                                  # Generated test cases go here
├── docs/criteria/
│   └── _criteria_index.yaml                     # Acceptance criteria index
├── .github/
│   ├── agents/
│   │   ├── spectra-execution.agent.md           # Test execution agent (MCP)
│   │   └── spectra-generation.agent.md          # Test generation agent (CLI)
│   └── skills/
│       ├── spectra-generate/SKILL.md            # Generate tests via Copilot Chat
│       ├── spectra-coverage/SKILL.md            # Check coverage via Copilot Chat
│       ├── spectra-dashboard/SKILL.md           # Build dashboard via Copilot Chat
│       ├── spectra-validate/SKILL.md            # Validate tests via Copilot Chat
│       ├── spectra-list/SKILL.md                # Browse tests via Copilot Chat
│       ├── spectra-init-profile/SKILL.md        # Configure profile via Copilot Chat
│       ├── spectra-help/SKILL.md                # Help and command reference
│       ├── spectra-criteria/SKILL.md            # Manage acceptance criteria
│       └── spectra-docs/SKILL.md                # Index documentation via Copilot Chat
└── templates/bug-report.md                      # Bug report template

Use spectra init --skip-skills if you don’t use GitHub Copilot Chat.

Add Your Documentation

Copy your existing documentation into the docs/ folder:

docs/
├── features/
│   ├── authentication.md
│   ├── checkout.md
│   └── user-profile.md
├── api/
│   └── endpoints.md
└── criteria/
    └── _criteria_index.yaml

Configure

Edit spectra.config.json to point to your docs. See Configuration Reference for the full schema.

{
  "source": {
    "mode": "local",
    "local_dir": "docs/"
  },
  "tests": {
    "dir": "test-cases/"
  },
  "ai": {
    "providers": [
      { "name": "github-models", "model": "gpt-4.1", "enabled": true }
    ],
    "critic": {
      "enabled": true,
      "provider": "github-models",
      "model": "gpt-5-mini"
    }
  }
}

Spec 041 defaults: generator gpt-4.1 + critic gpt-5-mini are both 0× multiplier on any paid Copilot plan (Pro, Pro+, Business, Enterprise) and come from different model architectures for independent verification. Running spectra init -i offers an AI Model Preset menu with alternative pairings (Claude Sonnet 4.5 + GPT-4.1 critic for premium quality, GPT-4.1 + Claude Haiku 4.5 for cross-family verification, or Custom to edit by hand).

Authentication

SPECTRA requires authentication to access AI providers. Check your status:

spectra auth

Output:

SPECTRA Authentication Status
========================================

github-models        [OK] via gh-cli
openai               [NOT CONFIGURED]
                       Set the OPENAI_API_KEY environment variable
anthropic            [NOT CONFIGURED]
                       Set the ANTHROPIC_API_KEY environment variable

Option 1: GitHub CLI (Recommended)

gh auth login
spectra auth -p github-models

SPECTRA automatically detects gh auth token and uses it.

Option 2: Environment Variable

# Create a GitHub token at https://github.com/settings/tokens (scope: read:user)
export GITHUB_TOKEN="ghp_your_token_here"

# Windows PowerShell
$env:GITHUB_TOKEN = "ghp_your_token_here"

OpenAI 

export OPENAI_API_KEY="sk-your_key_here"
spectra auth -p openai

Anthropic 

export ANTHROPIC_API_KEY="sk-ant-your_key_here"
spectra auth -p anthropic

Custom Environment Variables

Override the default environment variable name in config:

{
  "ai": {
    "providers": [
      {
        "name": "openai",
        "model": "gpt-4.1",
        "api_key_env": "MY_CUSTOM_OPENAI_KEY",
        "enabled": true
      }
    ]
  }
}

Troubleshooting Authentication

Problem Solution
“GitHub CLI is installed but not authenticated” Run gh auth login
“GitHub CLI is not installed” Install from https://cli.github.com/ or use GITHUB_TOKEN
“API key not found” Verify with echo $OPENAI_API_KEY (or $env:OPENAI_API_KEY on Windows)
Wrong provider being used Check provider order in spectra.config.json — first enabled wins

First Run

Open VS Code with Copilot Chat and say:

  • “Generate test cases for the checkout suite”
  • “How’s our test case coverage?”
  • “Validate all test cases”

The bundled SKILLs handle CLI invocation automatically. See Skills Integration.

Option 2: CLI directly 

# Build the documentation index
spectra docs index

# Interactive generation session (analyze → generate → suggest → loop)
spectra ai generate

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

# Validate
spectra validate

Option 3: CI/SKILL automation 

# Full automated generation with JSON output
spectra ai generate checkout --auto-complete --output-format json

# Coverage check
spectra ai analyze --coverage --output-format json

# Validation with structured errors
spectra validate --output-format json --no-interaction

See CLI Reference for all available commands.