Antigen - AI-Powered Test Generation Library

⚠️ Experimental Project

This project is currently in experimental/development phase. Features and APIs may change without notice. The library is temporarily hosted on GitHub Packages while implementation is being stabilized

Antigen is a Gradle plugin that automatically generates comprehensive, high-quality API tests using Claude Code AI, with built-in validation through MetaTest fault injection.

What is Antigen?

Antigen orchestrates an iterative test generation pipeline:

Generate - Claude Code AI creates tests from your API specification
Build - Validates tests compile successfully
Test - Ensures tests execute and pass
MetaTest - Injects faults to validate test quality

If any phase fails, Antigen provides feedback to Claude and retries until tests meet your quality threshold.

Key Features

AI-Powered: Uses Claude Code CLI to generate intelligent, comprehensive tests
Quality Validation: MetaTest fault injection ensures tests catch real bugs
Iterative Refinement: Automatic retry with feedback until tests pass quality checks
Zero Code: Just provide an API spec and configuration
Framework Support: Generates JUnit 5 + RestAssured + AssertJ tests
Configurable: Customize requirements, timeouts, and quality thresholds

Quick Start

1. Add the Plugin

From GitHub Packages:

// build.gradle.kts
repositories {
    mavenCentral()
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/at-boundary/antigen-lib")
        credentials {
            username = System.getenv("GITHUB_ACTOR")
            password = System.getenv("GITHUB_TOKEN")
        }
    }
}

plugins {
    java
    id("io.antigen") version "1.0.0-dev-<commit>"
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
    testImplementation("io.rest-assured:rest-assured:5.3.0")
    testImplementation("org.assertj:assertj-core:3.24.2")
}

From Local Maven:

// build.gradle.kts
repositories {
    mavenLocal()
}

plugins {
    java
    id("io.antigen") version "1.0.0-SNAPSHOT"
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
    testImplementation("io.rest-assured:rest-assured:5.3.0")
    testImplementation("org.assertj:assertj-core:3.24.2")
}

2. Create Configuration

# antigen.yml
spec: api-spec.yaml
outputDir: generated
maxRetries: 3

validation:
  enabled: true
  faultDetectionThreshold: 0.95  # Require 95% fault detection

3. Generate Tests

./gradlew generateAITests

Tests will be generated in src/test/java/generated/

Installation

Prerequisites

Java 17+
Gradle 7.3+
Claude Code CLI installed and available in PATH
- Install from: https://claude.com/claude-code
- Verify: claude --version

Option 1: Install from GitHub Packages

Antigen is published to GitHub Packages. To use it:

Create a GitHub Personal Access Token with read:packages permission
- Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- Generate new token with read:packages scope

Configure credentials (choose one):

Environment variables:

export GITHUB_ACTOR=your-github-username
export GITHUB_TOKEN=your-personal-access-token

Or ~/.gradle/gradle.properties:

githubActor=your-github-username
githubToken=your-personal-access-token

Add the repository to your build.gradle.kts:

repositories {
    mavenCentral()
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/at-boundary/antigen-lib")
        credentials {
            username = System.getenv("GITHUB_ACTOR") ?: findProperty("githubActor") as String?
            password = System.getenv("GITHUB_TOKEN") ?: findProperty("githubToken") as String?
        }
    }
}

plugins {
    id("io.antigen") version "1.0.0-dev-<commit>"
}

Option 2: Build and Publish Locally

cd antigen-lib
./gradlew publishToMavenLocal

Then add to your project's build.gradle.kts:

repositories {
    mavenLocal()
}

plugins {
    id("io.antigen") version "1.0.0-SNAPSHOT"
}

Configuration Reference

antigen.yml

# Required: Path to API specification (OpenAPI/Swagger)
spec: api-spec.yaml

# Optional: Output directory (relative to src/test/java)
# Default: "generated"
outputDir: generated

# Optional: Maximum retry attempts
# Default: 5
maxRetries: 3

# Optional: Custom prompt template file
# If not specified, uses built-in default template
# Supports placeholders: {SPEC_PATH}, {ADDITIONAL_REQUIREMENTS}, {FEEDBACK}
promptTemplate: prompt-template.txt

# Optional: Custom test requirements
# These are appended to the prompt under {ADDITIONAL_REQUIREMENTS}
requirements:
  - "Test authentication flows"
  - "Validate all required fields"
  - "Test boundary conditions"

# Optional: Timeout configurations
timeouts:
  llm: 5m        # Claude Code timeout
  build: 5m      # Build phase timeout
  test: 10m      # Test execution timeout
  metatest: 30m  # MetaTest validation timeout

# Optional: MetaTest validation settings
validation:
  enabled: true  # Enable fault injection validation
  faultDetectionThreshold: 1.0  # 0.0 - 1.0 (100% = all faults caught)

Duration Format

Timeouts support: 5m (minutes), 300s (seconds), 1h (hours)

How It Works

Architecture

Antigen uses a 4-state pipeline with retry loops:

┌─────────────────────────────────────────────────────────┐
│                    ORCHESTRATOR                         │
│  (Manages retry loop & phase transitions)              │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
         ┌────────────────────────────────┐
         │   STATE 1: GENERATION          │
         │   (Claude Code generates tests) │
         └────────────────────────────────┘
                          │
                    [Success?]
                          │
                          ▼
         ┌────────────────────────────────┐
         │   STATE 2: BUILD               │
         │   (Compile tests)              │
         └────────────────────────────────┘
                          │
                    [Success?]
                          │
                          ▼
         ┌────────────────────────────────┐
         │   STATE 3: TEST                │
         │   (Execute tests)              │
         └────────────────────────────────┘
                          │
                    [Success?]
                          │
                          ▼
         ┌────────────────────────────────┐
         │   STATE 4: METATEST            │
         │   (Fault injection validation) │
         └────────────────────────────────┘
                          │
                  [Meets threshold?]
                          │
                    ┌─────┴─────┐
                  Yes          No
                    │            │
                  DONE      RETRY
                              │
                    ┌─────────┘
                    │
                    └─> [Add feedback & retry from STATE 1]

Phase Details

Generation Phase

Reads API specification
Constructs prompt for Claude Code
Claude generates JUnit tests with RestAssured
Tests written to src/test/java/generated/

Build Phase

Runs ./gradlew compileTestJava
Parses compilation errors if any
Provides error feedback to Claude for retry

Test Phase

Runs ./gradlew test
Parses test failures from XML reports
Points Claude to failed tests for fixing

MetaTest Phase

Runs ./gradlew test with MetaTest fault injection
Analyzes fault_simulation_report.json
Checks if tests catch injected faults
Calculates fault detection rate

Feedback Loop

When a phase fails:

Error details are captured (compilation errors, test failures, escaped faults)
Feedback is formatted for Claude Code
Claude is asked to fix the issues
Process repeats until success or max retries

MetaTest Integration

MetaTest validates test quality by injecting faults into API responses and checking if tests catch them.

Fault Types

Null values - Required fields set to null
Empty arrays - Lists returned empty
Wrong types - String instead of integer
Missing fields - Required fields removed
Boundary values - Edge case values

Validation

validation:
  enabled: true
  faultDetectionThreshold: 0.95  # Require 95% detection rate

If 95% threshold is set and only 90% of faults are caught, Antigen will retry with feedback pointing to escaped faults.

Report Structure

MetaTest generates fault_simulation_report.json:

{
  "/api/endpoint": {
    "fieldName": {
      "fault_type": {
        "caught_by_any_test": false,  // Escaped fault
        "details": [
          {
            "test": "TestClass.testMethod",
            "caught": false,
            "error": "Expected assertion not found"
          }
        ]
      }
    }
  }
}

Requirements

Dependencies

Antigen requires these test dependencies in your project:

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
    testImplementation("io.rest-assured:rest-assured:5.3.0")
    testImplementation("org.assertj:assertj-core:3.24.2")
}

Claude Code CLI

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

API Specification

Provide an OpenAPI 3.0 specification (YAML or JSON format)

Examples

For a complete working example, check the project repository at: https://github.com/at-boundary/antigen-lib

Advanced Usage

Custom Prompt Templates

You can customize the prompt sent to Claude Code by providing your own template file:

Create a template file (e.g., prompt-template.txt):

Generate comprehensive JUnit 5 tests for the API specification.

API SPECIFICATION FILE: {SPEC_PATH}
IMPORTANT: Read this file using the Read tool.

FOCUS ENDPOINTS:
- Test ONLY authentication endpoints
- Skip other endpoints

REQUIREMENTS:
- Write tests in src/test/java/generated/
- Use RestAssured for HTTP calls
- Use AssertJ for assertions
- Test happy path only (2xx responses)
- Validate response schemas
{ADDITIONAL_REQUIREMENTS}
{FEEDBACK}

Reference it in antigen.yml:

promptTemplate: prompt-template.txt

Template Placeholders

{SPEC_PATH} - Replaced with the relative path to your API spec
{ADDITIONAL_REQUIREMENTS} - Replaced with requirements from antigen.yml
{FEEDBACK} - Replaced with error feedback during retry attempts

Use Cases

Focus on specific endpoints - Test only authentication or critical paths
Custom testing frameworks - Use different assertion libraries
Project-specific conventions - Enforce your coding standards
Language-specific instructions - Add Kotlin/Groovy-specific requirements

See the project repository for example configurations.

Custom Claude Configuration

Antigen auto-detects Claude CLI location. For custom setups, the detection logic is in AntigenConfig.java:detectClaudeCommand().

Programmatic Usage

// Create configuration
AntigenConfig config = AntigenConfig.builder()
    .maxRetries(3)
    .faultDetectionThreshold(0.95)
    .build();

// Create orchestrator
Orchestrator orchestrator = new Orchestrator(config);

// Generate tests
GenerationResult result = orchestrator.generate(
    Paths.get("api-spec.yaml"),
    Paths.get("."),
    List.of("Test authentication", "Validate schemas")
);

if (result.isSuccess()) {
    System.out.println("Tests generated: " + result.getGeneratedFiles());
}

Troubleshooting

Claude CLI Not Found

Error: Claude CLI is not available

Solution:

Install Claude Code: npm install -g @anthropic-ai/claude-code
Ensure claude is in PATH
On Windows, Antigen checks: %APPDATA%\npm\node_modules\@anthropic-ai\claude-code\cli.js

Compilation Errors

Error: Build phase fails with compilation errors

Solution:

Review build/classes output
Claude will auto-retry with error feedback
Check that all test dependencies are included

Tests Fail

Error: Test phase fails

Solution:

Review test reports in build/test-results/test/
Claude will read XML reports and fix tests
Ensure your API server is running if tests need it

MetaTest Failures

Error: Fault detection rate below threshold

Solution:

Review fault_simulation_report.json to see escaped faults
Claude will strengthen assertions automatically
Lower threshold if tests are at maximum quality

Timeout Errors

Error: Process times out

Solution:

timeouts:
  llm: 10m       # Increase if Claude needs more time
  metatest: 60m  # MetaTest can be slow for large specs

Project Structure

antigen-lib/
├── src/main/java/io/antigen/
│   ├── config/          # YAML config loading
│   ├── orchestrator/    # Main orchestration logic
│   ├── llm/             # Claude Code integration
│   ├── runners/         # Gradle runner, process executor
│   ├── phases/          # Phase implementations
│   ├── model/           # Data models
│   ├── feedback/        # Error parsing
│   └── plugin/          # Gradle plugin & task
├── build.gradle.kts     # Build configuration
└── README.md           # This file

Contributing

Fork the repository at https://github.com/at-boundary/antigen-lib
Create a feature branch
Make your changes
Test your changes with a sample project
Submit a pull request

License

MIT License

Related Projects

MetaTest - Fault injection framework for API testing
Claude Code - AI-powered coding assistant
RestAssured - API testing framework
JUnit 5 - Testing framework

Support

For issues or questions:

Open an issue on GitHub: https://github.com/at-boundary/antigen-lib/issues
Check troubleshooting section above
Review the documentation in this README

Built with Claude Code - AI-powered test generation for modern APIs

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github/workflows		.github/workflows
gradle/wrapper		gradle/wrapper
src/main/java/io/antigen		src/main/java/io/antigen
.gitignore		.gitignore
README.md		README.md
build.gradle.kts		build.gradle.kts
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

at-boundary/antigen

Folders and files

Latest commit

History

Repository files navigation

Antigen - AI-Powered Test Generation Library

Table of Contents

What is Antigen?

Key Features

Quick Start

1. Add the Plugin

2. Create Configuration

3. Generate Tests

Installation

Prerequisites

Option 1: Install from GitHub Packages

Option 2: Build and Publish Locally

Configuration Reference

antigen.yml

Duration Format

How It Works

Architecture

Phase Details

Feedback Loop

MetaTest Integration

Fault Types

Validation

Report Structure

Requirements

Dependencies

Claude Code CLI

API Specification

Examples

Advanced Usage

Custom Prompt Templates

Template Placeholders

Use Cases

Custom Claude Configuration

Programmatic Usage

Troubleshooting

Claude CLI Not Found

Compilation Errors

Tests Fail

MetaTest Failures

Timeout Errors

Project Structure

Contributing

License

Related Projects

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages