swaggerforge 0.1.0__tar.gz → 0.3.0__tar.gz

swaggerforge-0.3.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: swaggerforge
+Version: 0.3.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
+- Authentication support: bearer, API key, and basic schemes, with
+  environment-variable substitution for secrets
+
+## 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.
+
+## 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.
+
+```toml
+# 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:
+
+| Section         | Applies to                                  | Generated header                          |
+|-----------------|---------------------------------------------|-------------------------------------------|
+| `[auth.bearer]` | `http` bearer, and `oauth2` (pre-obtained token) | `Authorization: Bearer <token>`      |
+| `[auth.api_key]`| `apiKey` in header                          | the header named by the specification     |
+| `[auth.basic]`  | `http` basic                                | `Authorization: Basic <base64>`           |
+
+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 `$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 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](LICENSE) file.

swaggerforge-0.3.0/README.md

@@ -0,0 +1,146 @@
+# 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
+
+```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.
+
+## 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.
+
+```toml
+# 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:
+
+| Section         | Applies to                                  | Generated header                          |
+|-----------------|---------------------------------------------|-------------------------------------------|
+| `[auth.bearer]` | `http` bearer, and `oauth2` (pre-obtained token) | `Authorization: Bearer <token>`      |
+| `[auth.api_key]`| `apiKey` in header                          | the header named by the specification     |
+| `[auth.basic]`  | `http` basic                                | `Authorization: Basic <base64>`           |
+
+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 `$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 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](LICENSE) file.

{swaggerforge-0.1.0 → swaggerforge-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swaggerforge"
-version = "0.1.0"
+version = "0.3.0"
 description = "Automatic pytest test generation from OpenAPI (Swagger) specifications"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -16,11 +16,11 @@ keywords = ["openapi", "swagger", "pytest", "test generation", "api testing"]
 dependencies = [
     "click>=8.0",
     "prance>=23.6.21.0",
-    "openapi-core>=0.18",
     "openapi-spec-validator>=0.7",
     "jinja2>=3.0",
     "requests>=2.28",
     "jsonschema>=4.0",
+    'tomli>=2.0; python_version < "3.11"',
 ]
 
 [project.scripts]
@@ -38,4 +38,4 @@ addopts = "--import-mode=importlib"
 testpaths = ["tests"]
 
 [project.optional-dependencies]
-dev = ["pytest>=9.0", "flake8>=7.0"]
+dev = ["pytest>=9.0", "flake8>=7.0", "pytest-cov>=7.0", "tox>=4.0"]

swaggerforge-0.3.0/src/swaggerforge/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for running SwaggerForge as a module (python -m swaggerforge)."""
+from swaggerforge.cli import main
+
+if __name__ == "__main__":
+    main()

swaggerforge-0.3.0/src/swaggerforge/auth.py

@@ -0,0 +1,143 @@
+"""Resolution of authentication for generated tests.
+
+Given an endpoint's declared security requirement, the specification's
+security schemes, and the user's configured credentials, this module
+decides which authentication headers to inject into the generated tests.
+
+Supported schemes (v0.3.0): HTTP bearer, HTTP basic, and API key in a
+header. OAuth2 is treated as bearer (the user supplies a pre-obtained
+token). Other schemes - API key in query or cookie, OpenID Connect,
+and any undefined scheme name - are skipped with a warning.
+"""
+
+import base64
+from typing import NamedTuple
+
+
+class ResolvedAuth(NamedTuple):
+    """The outcome of resolving auth for one endpoint.
+
+    ``headers`` holds the authentication headers to inject (empty when no
+    auth applies). ``warning`` is a human-readable message when a declared
+    scheme was skipped, or None otherwise.
+    """
+
+    headers: dict
+    warning: str | None
+
+
+_NO_AUTH = ResolvedAuth(headers={}, warning=None)
+
+
+def resolve_auth(endpoint, security_schemes, auth_config):
+    """Resolve the authentication headers for a single endpoint.
+
+    Args:
+        endpoint: The Endpoint whose security requirement is resolved.
+        security_schemes: The specification's securitySchemes definitions.
+        auth_config: The AuthConfig carrying user-supplied credentials.
+
+    Returns:
+        A ResolvedAuth with the headers to inject and an optional warning.
+
+    Raises:
+        AuthError: If a supported scheme is required but its credentials
+            are not configured.
+    """
+    if not endpoint.security:
+        return _NO_AUTH
+
+    scheme_name = endpoint.security[0]
+    scheme = security_schemes.get(scheme_name)
+    if scheme is None:
+        return ResolvedAuth(
+            headers={},
+            warning=(
+                f"Security scheme '{scheme_name}' required by "
+                f"{endpoint.method.upper()} {endpoint.path} is not defined in "
+                f"the specification; skipping authentication for it."
+            ),
+        )
+
+    scheme_type = scheme.get("type")
+
+    if scheme_type == "oauth2":
+        return _resolve_bearer(scheme_name, auth_config)
+    if scheme_type == "http":
+        http_scheme = scheme.get("scheme", "").lower()
+        if http_scheme == "bearer":
+            return _resolve_bearer(scheme_name, auth_config)
+        if http_scheme == "basic":
+            return _resolve_basic(scheme_name, auth_config)
+    if scheme_type == "apiKey" and scheme.get("in") == "header":
+        return _resolve_api_key(scheme_name, scheme, auth_config)
+
+    return ResolvedAuth(
+        headers={},
+        warning=(
+            f"Security scheme '{scheme_name}' (type '{scheme_type}') is not "
+            f"supported in this version; skipping authentication for "
+            f"{endpoint.method.upper()} {endpoint.path}."
+        ),
+    )
+
+
+def _resolve_bearer(scheme_name, auth_config):
+    """Build a bearer Authorization header from configured credentials."""
+    bearer = auth_config.bearer
+    if bearer is None or not bearer.token:
+        return ResolvedAuth(
+            headers={},
+            warning=(
+                f"Scheme '{scheme_name}' requires a bearer token, but none is "
+                f"configured; generating without authentication. Add a "
+                f"[auth.bearer] section with a 'token' to enable it."
+            ),
+        )
+    return ResolvedAuth(
+        headers={"Authorization": f"Bearer {bearer.token}"}, warning=None
+    )
+
+
+def _resolve_basic(scheme_name, auth_config):
+    """Build a basic Authorization header from configured credentials."""
+    basic = auth_config.basic
+    if basic is None or not basic.username or not basic.password:
+        return ResolvedAuth(
+            headers={},
+            warning=(
+                f"Scheme '{scheme_name}' requires basic credentials, but the "
+                f"username and password are not both configured; generating "
+                f"without authentication. Add a [auth.basic] section with "
+                f"'username' and 'password' to enable it."
+            ),
+        )
+    raw = f"{basic.username}:{basic.password}".encode("utf-8")
+    encoded = base64.b64encode(raw).decode("ascii")
+    return ResolvedAuth(
+        headers={"Authorization": f"Basic {encoded}"}, warning=None
+    )
+
+
+def _resolve_api_key(scheme_name, scheme, auth_config):
+    """Build an API-key header, taking the header name from the spec scheme."""
+    api_key = auth_config.api_key
+    if api_key is None or not api_key.value:
+        return ResolvedAuth(
+            headers={},
+            warning=(
+                f"Scheme '{scheme_name}' requires an API key, but none is "
+                f"configured; generating without authentication. Add a "
+                f"[auth.api_key] section with a 'value' to enable it."
+            ),
+        )
+    header_name = scheme.get("name")
+    if not header_name:
+        return ResolvedAuth(
+            headers={},
+            warning=(
+                f"API-key scheme '{scheme_name}' does not declare a header "
+                f"name; skipping authentication for it."
+            ),
+        )
+    return ResolvedAuth(headers={header_name: api_key.value}, warning=None)

{swaggerforge-0.1.0 → swaggerforge-0.3.0}/src/swaggerforge/cli.py

@@ -1,6 +1,7 @@
 """Command-line interface for SwaggerForge."""
 
 import click
+from swaggerforge.config import load_config, ConfigError
 from swaggerforge.validator import load_and_validate, SpecValidationError
 from swaggerforge.parser import parse_spec, SpecParseError
 from swaggerforge.generator import generate_scenarios
@@ -23,17 +24,39 @@ def main():
 )
 @click.option(
     "--url",
-    required=True,
-    help="Base URL of the API to be tested.",
+    default=None,
+    help="Base URL of the API to be tested. "
+         "Required unless base_url is set in the config file.",
 )
 @click.option(
     "--output",
-    default="tests_generated",
+    default=None,
+    type=click.Path(),
+    help="Directory where generated test files will be written "
+         "[default: tests_generated].",
+)
+@click.option(
+    "--config",
+    "config_path",
+    default=None,
     type=click.Path(),
-    help="Directory where generated test files will be written.",
+    help="Path to a swaggerforge.toml config file "
+         "[default: ./swaggerforge.toml if present].",
 )
-def generate(spec, url, output):
+def generate(spec, url, output, config_path):
     """Generate pytest test files from an OpenAPI specification."""
+    try:
+        config = load_config(config_path)
+    except ConfigError as error:
+        raise click.ClickException(str(error))
+
+    url = url or config.base_url
+    if url is None:
+        raise click.ClickException(
+            "No base URL given: pass --url or set base_url in swaggerforge.toml."
+        )
+    output = output or config.output_dir or "tests_generated"
+
     click.echo(f"Reading specification: {spec}")
 
     try:
@@ -45,7 +68,8 @@ def generate(spec, url, output):
     click.echo(f"API title: {spec_dict['info']['title']}")
 
     try:
-        endpoints = parse_spec(spec)
+        parsed = parse_spec(spec)
+        endpoints = parsed.endpoints
     except SpecParseError as error:
         raise click.ClickException(str(error))
 
@@ -56,12 +80,22 @@ def generate(spec, url, output):
     click.echo(f"Generated {len(scenarios)} test scenarios.")
 
     try:
-        written = write_test_files(scenarios, url, output)
+        result = write_test_files(
+            scenarios,
+            url,
+            output,
+            config.timeout,
+            security_schemes=parsed.security_schemes,
+            auth_config=config.auth,
+        )
     except OSError as error:
         raise click.ClickException(
             f"Could not write test files to '{output}': {error}"
         )
 
-    click.echo(f"Wrote {len(written)} test file(s) to '{output}':")
-    for path in written:
+    for warning in result.warnings:
+        click.echo(f"Warning: {warning}")
+
+    click.echo(f"Wrote {len(result.written)} test file(s) to '{output}':")
+    for path in result.written:
         click.echo(f"  - {path}")