swaggerforge 0.2.0__tar.gz → 0.3.0__tar.gz

{swaggerforge-0.2.0/src/swaggerforge.egg-info → swaggerforge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swaggerforge
-Version: 0.2.0
+Version: 0.3.0
 Summary: Automatic pytest test generation from OpenAPI (Swagger) specifications
 Author: Viktor Pylypenko
 License-Expression: MIT
@@ -48,6 +48,8 @@ established test-design techniques.
 - 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
 
@@ -109,6 +111,46 @@ 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
@@ -119,7 +161,8 @@ written to per-resource files.
 ## Limitations
 
 - Targets OpenAPI 3.x with JSON request bodies
-- Authentication is not yet handled (planned)
+- 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

{swaggerforge-0.2.0 → swaggerforge-0.3.0}/README.md

@@ -24,6 +24,8 @@ established test-design techniques.
 - 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
 
@@ -85,6 +87,46 @@ 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
@@ -95,7 +137,8 @@ written to per-resource files.
 ## Limitations
 
 - Targets OpenAPI 3.x with JSON request bodies
-- Authentication is not yet handled (planned)
+- 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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swaggerforge"
-version = "0.2.0"
+version = "0.3.0"
 description = "Automatic pytest test generation from OpenAPI (Swagger) specifications"
 readme = "README.md"
 requires-python = ">=3.10"

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.2.0 → swaggerforge-0.3.0}/src/swaggerforge/cli.py

@@ -68,7 +68,8 @@ def generate(spec, url, output, config_path):
     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))
 
@@ -79,12 +80,22 @@ def generate(spec, url, output, config_path):
     click.echo(f"Generated {len(scenarios)} test scenarios.")
 
     try:
-        written = write_test_files(scenarios, url, output, config.timeout)
+        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}")

swaggerforge-0.3.0/src/swaggerforge/config.py

@@ -0,0 +1,206 @@
+"""Loading of user configuration from a swaggerforge.toml file.
+
+This module reads optional user configuration for the generator. An
+explicitly given path must exist and parse; an auto-discovered file
+(./swaggerforge.toml in the working directory) may be absent, in which
+case an empty configuration is returned.
+"""
+
+import os
+import re
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:
+    import tomli as tomllib  # Python 3.10 backport
+
+DEFAULT_CONFIG_FILENAME = "swaggerforge.toml"
+
+_KNOWN_KEYS = {
+    "timeout": int,
+    "output_dir": str,
+    "base_url": str,
+}
+
+
+class ConfigError(Exception):
+    """Raised when a config file is missing (if explicitly requested) or invalid."""
+
+
+@dataclass
+class BearerAuth:
+    """Bearer-token credentials for the API under test."""
+    token: str | None = None
+
+
+@dataclass
+class ApiKeyAuth:
+    """API-key credentials: the secret value (header name comes from the spec)."""
+    value: str | None = None
+
+
+@dataclass
+class BasicAuth:
+    """HTTP basic-auth credentials."""
+    username: str | None = None
+    password: str | None = None
+
+
+@dataclass
+class AuthConfig:
+    """Authentication credentials, keyed by scheme kind. All optional."""
+    bearer: BearerAuth | None = None
+    api_key: ApiKeyAuth | None = None
+    basic: BasicAuth | None = None
+
+
+@dataclass
+class Config:
+    """User configuration loaded from swaggerforge.toml.
+
+    A field value of None means the setting was not present in the file.
+    """
+    timeout: int | None = None
+    output_dir: str | None = None
+    base_url: str | None = None
+    auth: AuthConfig = field(default_factory=AuthConfig)
+
+
+def load_config(config_path=None):
+    """Load configuration from a swaggerforge.toml file.
+
+    Args:
+        config_path: Explicit path to a config file. If given, the file
+            must exist and parse; otherwise ./swaggerforge.toml is
+            auto-discovered, and its absence yields an empty Config.
+
+    Returns:
+        A Config object with values from the file, or an empty Config
+        when no file was found during auto-discovery.
+
+    Raises:
+        ConfigError: If an explicitly given file is missing, if any file
+            contains invalid TOML, or if it contains unknown keys or
+            values of the wrong type.
+    """
+    if config_path is not None:
+        path = Path(config_path)
+        if not path.is_file():
+            raise ConfigError(f"Config file not found: '{config_path}'")
+    else:
+        path = Path(DEFAULT_CONFIG_FILENAME)
+        if not path.is_file():
+            return Config()
+
+    try:
+        raw = path.read_bytes()
+        # utf-8-sig strips a leading UTF-8 BOM if present (common on
+        # Windows) and is identical to utf-8 otherwise.
+        data = tomllib.loads(raw.decode("utf-8-sig"))
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigError(f"Invalid config file '{path}': {error}")
+    except UnicodeDecodeError:
+        raise ConfigError(
+            f"Invalid config file '{path}': not valid UTF-8 "
+            f"(TOML files must be UTF-8 encoded; on Windows, beware that "
+            f"PowerShell redirection may create UTF-16 files)"
+        )
+
+    return _validate(data, path)
+
+
+_AUTH_SCHEMES = {
+    "bearer": BearerAuth,
+    "api_key": ApiKeyAuth,
+    "basic": BasicAuth,
+}
+
+
+def _validate(data, path):
+    """Check keys and value types, returning a populated Config."""
+    top_level = {key: value for key, value in data.items() if key != "auth"}
+
+    unknown = set(top_level) - set(_KNOWN_KEYS)
+    if unknown:
+        names = ", ".join(sorted(unknown))
+        raise ConfigError(f"Unknown key(s) in config file '{path}': {names}")
+
+    for key, expected_type in _KNOWN_KEYS.items():
+        if key not in top_level:
+            continue
+        value = top_level[key]
+        # bool is a subclass of int in Python; reject it for timeout.
+        if isinstance(value, bool) or not isinstance(value, expected_type):
+            raise ConfigError(
+                f"Invalid value for '{key}' in config file '{path}': "
+                f"expected {expected_type.__name__}, got {type(value).__name__}"
+            )
+
+    auth = _validate_auth(data.get("auth", {}), path)
+    return Config(auth=auth, **top_level)
+
+
+# Matches ${VAR} where VAR is a valid environment-variable name. The
+# ${VAR|default} and bare $VAR forms are deliberately not supported.
+_ENV_VAR_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def _substitute_env_vars(value, scheme, key, path):
+    """Replace every ${VAR} in a string with the environment value.
+
+    Raises ConfigError if a referenced variable is not set.
+    """
+    def replace(match):
+        var_name = match.group(1)
+        if var_name not in os.environ:
+            raise ConfigError(
+                f"Environment variable '{var_name}' referenced in "
+                f"[auth.{scheme}] ('{key}') of config file '{path}' is not set."
+            )
+        return os.environ[var_name]
+
+    return _ENV_VAR_PATTERN.sub(replace, value)
+
+
+def _validate_auth(auth_data, path):
+    """Build and validate an AuthConfig from the [auth] section."""
+    unknown = set(auth_data) - set(_AUTH_SCHEMES)
+    if unknown:
+        names = ", ".join(sorted(unknown))
+        raise ConfigError(
+            f"Unknown auth scheme(s) in config file '{path}': {names}"
+        )
+
+    kwargs = {}
+    for scheme, scheme_class in _AUTH_SCHEMES.items():
+        if scheme not in auth_data:
+            continue
+        kwargs[scheme] = _build_auth_scheme(
+            scheme, scheme_class, auth_data[scheme], path
+        )
+
+    return AuthConfig(**kwargs)
+
+
+def _build_auth_scheme(scheme, scheme_class, section, path):
+    """Validate one auth sub-table and build its dataclass."""
+    valid_fields = {f.name for f in fields(scheme_class)}
+    unknown = set(section) - valid_fields
+    if unknown:
+        names = ", ".join(sorted(unknown))
+        raise ConfigError(
+            f"Unknown key(s) in [auth.{scheme}] in config file '{path}': {names}"
+        )
+
+    resolved = {}
+    for key, value in section.items():
+        if not isinstance(value, str):
+            raise ConfigError(
+                f"Invalid value for '{key}' in [auth.{scheme}] in config file "
+                f"'{path}': expected str, got {type(value).__name__}"
+            )
+        resolved[key] = _substitute_env_vars(value, scheme, key, path)
+
+    return scheme_class(**resolved)

{swaggerforge-0.2.0 → swaggerforge-0.3.0}/src/swaggerforge/models.py

@@ -30,6 +30,7 @@ class Endpoint:
     request_body: dict | None = None
     responses: list[str] = field(default_factory=list)
     response_schema: dict | None = None
+    security: list[str] = field(default_factory=list)
 
 
 @dataclass

swaggerforge-0.3.0/src/swaggerforge/output.py

@@ -0,0 +1,91 @@
+"""Writing generated test files to disk.
+
+This module groups scenarios by resource tag, renders each group into a
+pytest file, and writes the files into the output directory. It only ever
+writes into the output directory and never modifies the input
+specification (WNF08).
+"""
+
+import re
+from pathlib import Path
+from typing import NamedTuple
+
+from swaggerforge.auth import resolve_auth
+from swaggerforge.config import AuthConfig
+from swaggerforge.template import render_test_file
+
+
+class WriteResult(NamedTuple):
+    """The result of writing test files: the paths written and any warnings."""
+
+    written: list
+    warnings: list
+
+
+def write_test_files(
+    scenarios,
+    base_url,
+    output_dir,
+    timeout=None,
+    security_schemes=None,
+    auth_config=None,
+):
+    """Group scenarios by tag, render them, and write one file per tag.
+
+    Authentication is resolved per file from the tag group's first
+    endpoint (file-level auth); a scheme that cannot be applied is
+    reported as a warning rather than stopping generation.
+
+    Args:
+        scenarios: A list of TestScenario objects.
+        base_url: The base URL of the API under test.
+        output_dir: Directory where the test files will be written.
+        timeout: Optional request timeout embedded in generated calls.
+        security_schemes: The specification's securitySchemes definitions.
+        auth_config: The AuthConfig carrying user-supplied credentials.
+
+    Returns:
+        A WriteResult with the sorted list of written paths and a list of
+        de-duplicated warnings raised while resolving authentication.
+    """
+    if security_schemes is None:
+        security_schemes = {}
+    if auth_config is None:
+        auth_config = AuthConfig()
+
+    grouped = _group_by_tag(scenarios)
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    written = []
+    warnings = []
+    for tag in sorted(grouped):
+        group = grouped[tag]
+        representative = group[0].endpoint
+        resolved = resolve_auth(representative, security_schemes, auth_config)
+        if resolved.warning and resolved.warning not in warnings:
+            warnings.append(resolved.warning)
+
+        filename = f"test_{_sanitize(tag)}.py"
+        file_path = output_path / filename
+        content = render_test_file(
+            filename, base_url, group, timeout, resolved.headers
+        )
+        file_path.write_text(content, encoding="utf-8")
+        written.append(str(file_path))
+
+    return WriteResult(written=written, warnings=warnings)
+
+
+def _group_by_tag(scenarios):
+    """Group scenarios into a dict keyed by their endpoint's tag."""
+    grouped = {}
+    for scenario in scenarios:
+        tag = scenario.endpoint.tag
+        grouped.setdefault(tag, []).append(scenario)
+    return grouped
+
+
+def _sanitize(tag):
+    """Replace characters not valid in a filename with underscores."""
+    return re.sub(r"[^a-zA-Z0-9_]", "_", tag)