315 lines
7.5 KiB
Markdown
315 lines
7.5 KiB
Markdown
# API TestGen CLI
|
|
|
|
[](https://7000pct.gitea.bloupla.net/7000pctAUTO/api-testgen-cli/actions)
|
|
[](pyproject.toml)
|
|
[](https://python.org)
|
|
|
|
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
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-testgen-cli.git
|
|
cd api-testgen-cli
|
|
pip install -e .
|
|
```
|
|
|
|
### From PyPI
|
|
|
|
```bash
|
|
pip install api-testgen
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
api-testgen --spec openapi.yaml parse
|
|
```
|
|
|
|
#### generate
|
|
Generate test files for a specific framework.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
api-testgen --spec openapi.yaml all pytest
|
|
```
|
|
|
|
#### auth
|
|
Configure authentication for a security scheme.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
spec: openapi.yaml
|
|
output: ./generated
|
|
mock_url: http://localhost:4010
|
|
framework: pytest
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Basic API Testing
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. **prism-config.json** - Prism server configuration with CORS and validation settings
|
|
2. **docker-compose.yml** - Docker Compose file for running mock server
|
|
3. **Dockerfile** - Standalone Docker image for the mock server
|
|
|
|
### Starting the Mock Server
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Run tests and linting
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|