Metadata-Version: 2.4
Name: swaggerforge
Version: 0.2.0
Summary: Automatic pytest test generation from OpenAPI (Swagger) specifications
Author: Viktor Pylypenko
License-Expression: MIT
Keywords: openapi,swagger,pytest,test generation,api testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: prance>=23.6.21.0
Requires-Dist: openapi-spec-validator>=0.7
Requires-Dist: jinja2>=3.0
Requires-Dist: requests>=2.28
Requires-Dist: jsonschema>=4.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0; extra == "dev"
Requires-Dist: tox>=4.0; extra == "dev"
Dynamic: license-file

# 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

## Requirements

- Python 3.10 or newer

## Installation

```bash
pip install swaggerforge
```

## Usage

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

```bash
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:

```bash
pytest tests_generated
```

### Options

| Option     | Description                                        | Default                           |
|------------|----------------------------------------------------|-----------------------------------|
| `--spec`   | Path to the OpenAPI specification (JSON or YAML)   | *(required)*                      |
| `--url`    | Base URL of the API under test                     | *(required unless in config)*     |
| `--output` | Directory for the generated test files             | `tests_generated`                 |
| `--config` | Path to a configuration file                       | `./swaggerforge.toml` if present  |

## 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`.

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

| Key          | Type    | Effect                                                        |
|--------------|---------|---------------------------------------------------------------|
| `base_url`   | string  | Base URL of the API; makes `--url` optional                   |
| `output_dir` | string  | Directory for generated files                                 |
| `timeout`    | integer | Embeds `timeout=<n>` into every generated HTTP request call   |

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.

## How it works

SwaggerForge runs a six-stage pipeline: the specification is validated, parsed
into an internal model (with `$ref`s 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 is not yet handled (planned)
- Boundary tests require the specification to declare numeric/length constraints

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file.
