Initial upload: API TestGen CLI with OpenAPI test generation
This commit is contained in:
315
README.md
315
README.md
@@ -1,3 +1,314 @@
|
||||
# api-testgen-cli
|
||||
# API TestGen CLI
|
||||
|
||||
A CLI tool that parses OpenAPI/Swagger specs and automatically generates integration test templates with mock servers
|
||||
[](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.
|
||||
|
||||
Reference in New Issue
Block a user