# API TestGen CLI

[![CI](https://img.shields.io/badge/CI-Gitea_Actions-blue)](https://7000pct.gitea.bloupla.net/7000pctAUTO/api-testgen-cli/actions)
[![Version](https://img.shields.io/badge/Version-0.1.0-green)](pyproject.toml)
[![Python](https://img.shields.io/badge/Python-3.9+-blue)](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.