Specter 👻

AI-native testing framework where AI uses tools to create specs, generate tests, and keep everything in sync.

What is Specter?

Specter is a monorepo containing:

• @codervisor/specter - AI-native testing framework with tool-augmented spec creation
• webapp - Enterprise Next.js web application for project and task management

The monorepo is managed with pnpm workspaces.

Testing Framework Features

Specter is an innovative testing framework that leverages AI and tools to automate the entire testing workflow:

System → AI explores with tools → Specs → Tests → Results → AI heals/syncs

• 🤖 AI-Powered Spec Creation - AI explores your application and creates comprehensive test specifications
• 🔧 Tool-Augmented Testing - Uses Playwright, MCP tools, and code analysis to understand your system
• 🔄 Self-Healing Tests - AI automatically fixes broken tests by re-inspecting the implementation
• 🔌 Provider-Agnostic - Works with OpenAI, Anthropic, or any provider supported by Vercel AI SDK
• 📝 Framework-Agnostic - Generate tests for Vitest, Jest, or Playwright
• 🎯 Spec-First Approach - Human-readable specs that sync with implementation

Monorepo Structure

specter/
├── packages/
│   ├── specter/          # Core testing framework
│   │   ├── src/          # Source code
│   │   ├── tests/        # Tests
│   │   ├── docs/         # Documentation
│   │   └── examples/     # Examples
│   └── webapp/           # Next.js web application
│       ├── src/          # App source
│       ├── prisma/       # Database schema
│       └── public/       # Static assets
├── pnpm-workspace.yaml   # Workspace configuration
└── package.json          # Root package.json

Quick Start

Prerequisites

• Node.js 20 or later
• pnpm 8 or later

Installation

1. Clone the repository:

git clone https://github.com/codervisor/specter.git
cd specter

2. Install dependencies:

pnpm install

3. Build all packages:

pnpm run build

Working with the Testing Framework

Navigate to the specter package:

cd packages/specter

1. Copy .env.example to .env and configure your AI provider:

cp .env.example .env

2. Edit .env with your API keys:

AI_PROVIDER=openai
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-4o

Basic Usage

1. Explore a URL and Generate Specs

specter explore https://example.com/login \
  --description "Test login flow with valid and invalid credentials"

This will:

• Launch a browser and navigate to the URL
• Use AI to analyze the page structure
• Generate a detailed test specification
• Save the spec to ./specs/

2. Generate Test Code from Spec

specter generate ./specs/login-flow.md \
  --framework vitest \
  --output ./tests/generated

3. Run Tests

specter run ./tests/generated/*.test.ts \
  --framework vitest \
  --reporter markdown,json,html

4. Heal Broken Tests

specter heal ./tests/generated/login-flow.test.ts \
  ./specs/login-flow.md \
  --output ./tests/generated/login-flow.test.ts

5. Sync Specs with Implementation

specter sync ./specs/login-flow.md \
  https://example.com/login \
  --output ./specs/login-flow.md

Workflow

1. AI Exploration

import { AIEngine, SpecCreator, PlaywrightTool } from '@codervisor/specter';

const playwrightTool = new PlaywrightTool();
const aiEngine = new AIEngine({ config: aiConfig });
const specCreator = new SpecCreator(aiEngine, playwrightTool);

const spec = await specCreator.createSpecFromURL('https://example.com');

2. Test Generation

import { CodeGenerator } from '@codervisor/specter';

const codeGenerator = new CodeGenerator(aiEngine);
const testCode = await codeGenerator.generateTest(spec, 'vitest');

3. Self-Healing

import { Healer } from '@codervisor/specter';

const healer = new Healer(aiEngine, playwrightTool);
const healedCode = await healer.healTest(testCode, testResult, spec);

Architecture

Specter is built on modern, production-ready technologies:

• Vercel AI SDK - Provider-agnostic LLM integration with tool calling
• MCP (Model Context Protocol) - Extensible tool system
• Playwright - Browser automation and UI exploration
• TypeScript 5.x - Type-safe, modern ES modules
• Node.js 20+ - Latest JavaScript runtime features

See packages/specter/docs/architecture.md for detailed design information.

Configuration

Create a specter.config.ts file:

import type { SpecterConfig } from '@codervisor/specter';

const config: SpecterConfig = {
  ai: {
    provider: 'openai',
    model: 'gpt-4o',
    temperature: 0.7,
  },
  playwright: {
    headless: true,
    viewport: { width: 1280, height: 720 },
  },
  output: {
    specsDir: './specs',
    testsDir: './tests/generated',
    reportsDir: './results',
    format: ['markdown', 'json', 'html'],
  },
};

export default config;

AI Providers

Specter works with multiple AI providers. See docs/ai-providers.md for details.

OpenAI

AI_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o

Anthropic

AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

Examples

Check out the packages/specter/examples/ directory for:

• Example workflows in examples/workflows/
• Generated specs in examples/specs/
• Configuration examples in examples/configs/

Development

Monorepo Commands

# Install dependencies for all packages
pnpm install

# Build all packages
pnpm run build

# Run tests in all packages
pnpm test

# Run dev mode for all packages (parallel)
pnpm run dev

# Typecheck all packages
pnpm run typecheck

# Lint all packages
pnpm run lint

# Format all packages
pnpm run format

# Clean all build artifacts
pnpm run clean

Working in a Specific Package

# Navigate to the package
cd packages/specter
# or
cd packages/webapp

# Run package-specific commands
pnpm run build
pnpm run test
pnpm run dev

Testing Framework Development

cd packages/specter

# Build
pnpm run build

# Run tests
pnpm test

# Run in development mode
pnpm run dev

Web Application Development

cd packages/webapp

# Start development server
pnpm run dev

# Build for production
pnpm run build

# Start production server
pnpm start

Project Documentation

• Testing Framework: See packages/specter/README.md and packages/specter/docs/
• Web Application: See packages/webapp/README.md and WEBAPP_README.md

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

MIT - see LICENSE file for details.

Learn More

• Getting Started Guide
• Architecture Overview
• AI Provider Configuration
• Agents Guide - Build Custom AI Agents
• Contributing Guidelines
• Web Application Features

---

Built with ❤️ by codervisor