API TestGen CLI
A CLI tool that parses OpenAPI/Swagger specifications and automatically generates integration test templates for pytest, Jest, and Go test frameworks, with auto-generated mock server support using Prism for testing without live backends.
Overview
API TestGen streamlines the process of creating integration tests for APIs defined in OpenAPI/Swagger specifications. It:
- Parses and validates OpenAPI 2.0 and 3.0.x specifications
- Generates pytest-compatible test templates
- Generates Jest-compatible test templates for Node.js projects
- Generates Go-compatible test templates with table-driven tests
- Creates Prism/OpenAPI mock server configurations
- Supports multiple authentication methods (API Key, Bearer, Basic)
Installation
From Source
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-testgen-cli.git
cd api-testgen-cli
pip install -e .
From PyPI
pip install api-testgen
Quick Start
# Parse and validate an OpenAPI specification
api-testgen --spec openapi.yaml parse
# Generate pytest tests
api-testgen --spec openapi.yaml --output tests/ generate pytest
# Generate Jest tests
api-testgen --spec openapi.yaml --output tests/ generate jest
# Generate Go tests
api-testgen --spec openapi.yaml --output tests/ generate go
# Generate mock server configuration
api-testgen --spec openapi.yaml --output docker/ mock
# Generate all tests and mock server config
api-testgen --spec openapi.yaml --output generated/ all pytest
Usage
Commands
parse
Parse and validate an OpenAPI specification file.
api-testgen --spec openapi.yaml parse
generate
Generate test files for a specific framework.
# Generate pytest tests
api-testgen --spec openapi.yaml generate pytest
# Generate Jest tests
api-testgen --spec openapi.yaml generate jest
# Generate Go tests
api-testgen --spec openapi.yaml generate go
Options:
--output, -o: Output directory for generated files (default: ./generated)--output-file, -f: Specific output file path--package-name: Go package name (only for go framework)
mock
Generate mock server configuration files.
api-testgen --spec openapi.yaml mock
Options:
--no-prism-config: Skip generating prism-config.json--no-docker-compose: Skip generating docker-compose.yml--no-dockerfile: Skip generating Dockerfile
all
Generate test files and mock server configuration in one command.
api-testgen --spec openapi.yaml all pytest
auth
Configure authentication for a security scheme.
# Configure API Key authentication
api-testgen auth ApiKeyAuth --type apiKey --header X-API-Key --token YOUR_TOKEN
# Configure Bearer token authentication
api-testgen auth BearerAuth --type bearer --token YOUR_TOKEN
# Configure Basic authentication
api-testgen auth BasicAuth --type basic --username USERNAME --password PASSWORD
Options
Global options available for all commands:
| Option | Description |
|---|---|
--spec, -s |
Path to OpenAPI specification file (required) |
--output, -o |
Output directory for generated files |
--mock-url |
URL of mock server (default: http://localhost:4010) |
Configuration
Environment Variables
| Variable | Description |
|---|---|
OPENAPI_SPEC |
Path to OpenAPI specification file |
MOCK_SERVER_URL |
URL of mock server for testing |
AUTH_TOKEN |
Default authentication token |
Configuration File
You can create an api_testgen.yaml file for default settings:
spec: openapi.yaml
output: ./generated
mock_url: http://localhost:4010
framework: pytest
Examples
Basic API Testing
# Parse a Pet Store API specification
api-testgen --spec examples/petstore.yaml parse
# Generate pytest tests
api-testgen --spec examples/petstore.yaml --output tests/ generate pytest
# Run the tests against mock server
pytest tests/ -v
With Authentication
# Generate tests with API key authentication
api-testgen --spec openapi.yaml --output tests/ generate pytest
# The generated tests include auth headers
# Edit the generated file to set your actual API key
Mock Server
# Generate mock server configuration
api-testgen --spec openapi.yaml --output docker/ mock
# Start the mock server
cd docker
docker compose up -d
# Tests will now work against the mock server
Supported Frameworks
pytest (Python)
- Generates parameterized test functions
- Includes fixtures for mock server URL and authentication
- Supports response validation
- Ready for CI/CD integration
Jest (JavaScript/TypeScript)
- Generates describe/it test blocks
- Uses supertest for HTTP assertions
- Environment variable support for auth
- Compatible with Jest 28+
Go
- Generates table-driven test functions
- Uses net/http and testify
- Supports authentication headers
- Go 1.18+ compatible
Mock Server
API TestGen generates complete mock server configurations:
Generated Files
- prism-config.json - Prism server configuration with CORS and validation settings
- docker-compose.yml - Docker Compose file for running mock server
- Dockerfile - Standalone Docker image for the mock server
Starting the Mock Server
cd docker
docker compose up -d
curl http://localhost:4010/health
Mock Server Features
- Automatic response generation from OpenAPI spec
- Request validation against schema
- CORS support
- Health check endpoint
- HTTPS support (optional)
Error Handling
Common errors and solutions:
Invalid OpenAPI Spec Format
Error: Invalid OpenAPI specification: ...
Solution: Validate your spec before parsing. Use tools like Swagger Editor.
Missing Security Scheme
Error: Security scheme 'ApiKeyAuth' not found in spec
Solution: Define the security scheme in your OpenAPI spec components section.
Template Rendering Failure
Solution: Check that your spec includes all required fields (info, paths, etc.).
Development
Setting Up Development Environment
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-testgen-cli.git
cd api-testgen-cli
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
# Run tests
pytest tests/ -v
# Run linting
black api_testgen/
ruff check api_testgen/
Project Structure
api_testgen/
├── core/
│ ├── __init__.py
│ ├── auth.py # Authentication configuration
│ ├── exceptions.py # Custom exceptions
│ └── spec_parser.py # OpenAPI specification parser
├── generators/
│ ├── __init__.py
│ ├── go.py # Go test generator
│ ├── jest.py # Jest test generator
│ └── pytest.py # Pytest generator
├── mocks/
│ ├── __init__.py
│ └── generator.py # Mock server configuration generator
├── cli/
│ ├── __init__.py
│ └── main.py # CLI entry point
templates/
├── pytest/
│ └── test_base.py.j2
├── jest/
│ └── api.test.js.j2
└── go/
└── api_test.go.j2
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
License
MIT License - see LICENSE file for details.