SwaggerForge

Automatic pytest test generation from OpenAPI (Swagger) specifications.

SwaggerForge is a Python library and command-line tool that reads an OpenAPI specification and generates ready-to-run pytest test files - one per resource covering positive, negative, boundary, and boolean scenarios grounded in established test-design techniques.

Features

• Reads OpenAPI 3.x specifications in JSON or YAML
• Resolves $ref references automatically
• Generates one pytest file per resource tag
• Produces six scenario types per endpoint where applicable:
  • Positive >>> valid request, expects a 2xx response and validates the response schema
  • Missing required field >>> omits a required field, expects 400
  • Wrong data type >>> sends a mistyped field, expects 400/422
  • Nonexistent resource >>> requests an unlikely identifier, expects 404
  • Boundary values >>> tests values at and just beyond declared numeric/length limits (Boundary Value Analysis)
  • Boolean coverage >>> exercises both true and false for boolean fields
• Deterministic output: the same specification always produces identical tests
• Generated files use session-scoped pytest fixtures and run with no manual edits
• Optional swaggerforge.toml config file for project-level defaults
• Authentication support: bearer, API key, and basic schemes, with environment-variable substitution for secrets

Requirements

• Python 3.10 or newer

Installation

pip install swaggerforge

Usage

Generate tests from a specification, pointing at the base URL of the API under test:

swaggerforge generate --spec swagger.json --url http://localhost:8080

This reads swagger.json, writes one test_<resource>.py file per resource tag into the output directory (default: tests_generated/), and the files can be run immediately:

pytest tests_generated

Options

Configuration

Options that stay the same across runs can be kept in a swaggerforge.toml file instead of being passed on the command line. The file is picked up automatically from the directory where the tool is run, or an explicit path can be given with --config.

# swaggerforge.toml
base_url = "http://localhost:8080"
output_dir = "tests_generated"
timeout = 30

Values given on the command line always take precedence over the config file. Without a timeout, generated tests place no time limit on requests - setting one makes test runs fail fast when the API is unreachable.

Authentication

When a specification declares security requirements, SwaggerForge embeds the matching authentication headers into the generated tests. Credentials are supplied through the config file, never taken from the specification itself.

# swaggerforge.toml
[auth.bearer]
token = "${API_TOKEN}"

[auth.api_key]
value = "${API_KEY}"

[auth.basic]
username = "${API_USER}"
password = "${API_PASSWORD}"

Three scheme kinds are supported, matching the OpenAPI security scheme types:

For an API key, the header name comes from the specification's scheme definition; the config supplies only the secret value.

Environment variables. Any auth value may reference an environment variable with ${VAR} syntax, so secrets stay out of the config file. A referenced variable that is not set is an error.

Unconfigured or unsupported schemes. If a specification requires a scheme whose credentials are not configured, SwaggerForge prints a warning and generates the tests without that header, rather than failing. Schemes that are not yet supported - API keys in a query string or cookie, and OpenID Connect - are likewise skipped with a warning.

How it works

SwaggerForge runs a six-stage pipeline: the specification is validated, parsed into an internal model (with $refs resolved), turned into test scenarios based on test-design techniques, rendered into pytest code via templates, and written to per-resource files.

Limitations

• Targets OpenAPI 3.x with JSON request bodies
• Authentication covers bearer, API key (header), and basic schemes; API keys in query or cookie, full OAuth2 flows, and OpenID Connect are not yet handled
• Boundary tests require the specification to declare numeric/length constraints

License

This project is licensed under the MIT License - see the LICENSE file.