swaggerforge 0.2.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swaggerforge
-Version: 0.2.0
+Version: 0.3.1
 Summary: Automatic pytest test generation from OpenAPI (Swagger) specifications
 Author: Viktor Pylypenko
 License-Expression: MIT
@@ -20,6 +20,8 @@ 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"
+Provides-Extra: oauth2
+Requires-Dist: requests-oauth2client>=1.6; extra == "oauth2"
 Dynamic: license-file
 
 # SwaggerForge
@@ -48,6 +50,9 @@ 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
+- Comprehensive authentication: bearer, basic, API key (header/query/cookie),
+  multiple-scheme AND/OR requirements, and OAuth2 / OpenID Connect (optional
+  extra), with environment-variable substitution for secrets
 
 ## Requirements
 
@@ -109,6 +114,84 @@ 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 configures
+the generated tests to authenticate. Credentials are supplied through the
+config file; the specification decides *which* scheme and *where* each value
+goes, and the config supplies the secret values.
+
+```toml
+# swaggerforge.toml
+[auth.bearer]
+token = "${API_TOKEN}"
+
+[auth.api_key]
+value = "${API_KEY}"
+
+[auth.basic]
+username = "${API_USER}"
+password = "${API_PASSWORD}"
+
+[auth.oauth2]
+client_id = "${OAUTH_CLIENT_ID}"
+client_secret = "${OAUTH_CLIENT_SECRET}"
+scope = "read write"
+```
+
+Generated tests build a session-scoped `requests.Session` that carries the
+resolved authentication, so every request is authenticated without repeating
+credentials per call.
+
+### Supported schemes
+
+| Config section  | OpenAPI scheme                              | How it is applied                                   |
+|-----------------|---------------------------------------------|-----------------------------------------------------|
+| `[auth.bearer]` | `http` bearer                               | `Authorization: Bearer <token>` header              |
+| `[auth.api_key]`| `apiKey` in header, query, or cookie        | the name and location declared by the specification |
+| `[auth.basic]`  | `http` basic                                | `Authorization: Basic <base64>` header              |
+| `[auth.oauth2]` | `oauth2` client credentials, `openIdConnect`| a token fetched at runtime (see below)              |
+
+For an API key, both the **name** and the **location** (header, query, or
+cookie) come from the specification; the config supplies only the secret
+`value`.
+
+### Multiple schemes
+
+OpenAPI can require several schemes at once (AND) or offer alternatives (OR).
+SwaggerForge honours both: it uses the first alternative whose credentials are
+fully configured, combining every scheme in an AND group. When endpoints in one
+file need different authentication, the differing ones override the session per
+request.
+
+### OAuth2 and OpenID Connect
+
+OAuth2 and OIDC support is an optional extra, installed with:
+
+```bash
+pip install swaggerforge[oauth2]
+```
+
+For the **client credentials** flow, generated tests fetch a fresh access
+token from the specification's `tokenUrl` at runtime (and refresh it on
+expiry), so no token is ever embedded at generation time. **OpenID Connect**
+schemes work the same way, discovering the token endpoint at runtime from the
+specification's `openIdConnectUrl`. Both need `client_id` and `client_secret`
+in `[auth.oauth2]`.
+
+Interactive flows (OAuth2 **authorization code**) require a human to log in
+through a browser and so cannot be fully automated. For these, SwaggerForge
+generates a clearly marked placeholder in the session fixture where you paste a
+token obtained manually.
+
+### Environment variables and missing credentials
+
+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. If a specification requires a scheme whose credentials are not
+configured, SwaggerForge prints a warning naming the scheme and generates the
+tests without that authentication rather than failing.
+
 ## How it works
 
 SwaggerForge runs a six-stage pipeline: the specification is validated, parsed
@@ -119,7 +202,10 @@ written to per-resource files.
 ## Limitations
 
 - Targets OpenAPI 3.x with JSON request bodies
-- Authentication is not yet handled (planned)
+- Authentication covers bearer, basic, API key (header/query/cookie), OAuth2
+  client credentials, and OpenID Connect; interactive OAuth2 flows
+  (authorization code) generate a placeholder for a manually obtained token,
+  as they require a browser-based login that cannot be automated
 - Boundary tests require the specification to declare numeric/length constraints
 
 ## License

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

@@ -24,6 +24,9 @@ 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
+- Comprehensive authentication: bearer, basic, API key (header/query/cookie),
+  multiple-scheme AND/OR requirements, and OAuth2 / OpenID Connect (optional
+  extra), with environment-variable substitution for secrets
 
 ## Requirements
 
@@ -85,6 +88,84 @@ 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 configures
+the generated tests to authenticate. Credentials are supplied through the
+config file; the specification decides *which* scheme and *where* each value
+goes, and the config supplies the secret values.
+
+```toml
+# swaggerforge.toml
+[auth.bearer]
+token = "${API_TOKEN}"
+
+[auth.api_key]
+value = "${API_KEY}"
+
+[auth.basic]
+username = "${API_USER}"
+password = "${API_PASSWORD}"
+
+[auth.oauth2]
+client_id = "${OAUTH_CLIENT_ID}"
+client_secret = "${OAUTH_CLIENT_SECRET}"
+scope = "read write"
+```
+
+Generated tests build a session-scoped `requests.Session` that carries the
+resolved authentication, so every request is authenticated without repeating
+credentials per call.
+
+### Supported schemes
+
+| Config section  | OpenAPI scheme                              | How it is applied                                   |
+|-----------------|---------------------------------------------|-----------------------------------------------------|
+| `[auth.bearer]` | `http` bearer                               | `Authorization: Bearer <token>` header              |
+| `[auth.api_key]`| `apiKey` in header, query, or cookie        | the name and location declared by the specification |
+| `[auth.basic]`  | `http` basic                                | `Authorization: Basic <base64>` header              |
+| `[auth.oauth2]` | `oauth2` client credentials, `openIdConnect`| a token fetched at runtime (see below)              |
+
+For an API key, both the **name** and the **location** (header, query, or
+cookie) come from the specification; the config supplies only the secret
+`value`.
+
+### Multiple schemes
+
+OpenAPI can require several schemes at once (AND) or offer alternatives (OR).
+SwaggerForge honours both: it uses the first alternative whose credentials are
+fully configured, combining every scheme in an AND group. When endpoints in one
+file need different authentication, the differing ones override the session per
+request.
+
+### OAuth2 and OpenID Connect
+
+OAuth2 and OIDC support is an optional extra, installed with:
+
+```bash
+pip install swaggerforge[oauth2]
+```
+
+For the **client credentials** flow, generated tests fetch a fresh access
+token from the specification's `tokenUrl` at runtime (and refresh it on
+expiry), so no token is ever embedded at generation time. **OpenID Connect**
+schemes work the same way, discovering the token endpoint at runtime from the
+specification's `openIdConnectUrl`. Both need `client_id` and `client_secret`
+in `[auth.oauth2]`.
+
+Interactive flows (OAuth2 **authorization code**) require a human to log in
+through a browser and so cannot be fully automated. For these, SwaggerForge
+generates a clearly marked placeholder in the session fixture where you paste a
+token obtained manually.
+
+### Environment variables and missing credentials
+
+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. If a specification requires a scheme whose credentials are not
+configured, SwaggerForge prints a warning naming the scheme and generates the
+tests without that authentication rather than failing.
+
 ## How it works
 
 SwaggerForge runs a six-stage pipeline: the specification is validated, parsed
@@ -95,7 +176,10 @@ written to per-resource files.
 ## Limitations
 
 - Targets OpenAPI 3.x with JSON request bodies
-- Authentication is not yet handled (planned)
+- Authentication covers bearer, basic, API key (header/query/cookie), OAuth2
+  client credentials, and OpenID Connect; interactive OAuth2 flows
+  (authorization code) generate a placeholder for a manually obtained token,
+  as they require a browser-based login that cannot be automated
 - Boundary tests require the specification to declare numeric/length constraints
 
 ## License

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swaggerforge"
-version = "0.2.0"
+version = "0.3.1"
 description = "Automatic pytest test generation from OpenAPI (Swagger) specifications"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -39,3 +39,4 @@ testpaths = ["tests"]
 
 [project.optional-dependencies]
 dev = ["pytest>=9.0", "flake8>=7.0", "pytest-cov>=7.0", "tox>=4.0"]
+oauth2 = ["requests-oauth2client>=1.6"]

swaggerforge-0.3.1/src/swaggerforge/auth.py

@@ -0,0 +1,274 @@
+"""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 OAuth2Fixture(NamedTuple):
+    """The parameters needed to generate an OAuth2 client-credentials fixture.
+
+    Exactly one of ``token_url`` (a direct clientCredentials token endpoint
+    from the spec) or ``discovery_url`` (an OpenID Connect discovery
+    endpoint, resolved at runtime) is set. The client credentials and
+    optional scope come from the configuration. The generated test fetches
+    a token at runtime rather than embedding one.
+    """
+
+    token_url: str | None = None
+    client_id: str = ""
+    client_secret: str = ""
+    discovery_url: str | None = None
+    scope: str | None = None
+
+
+class ResolvedAuth(NamedTuple):
+    """The outcome of resolving auth for one endpoint.
+
+    ``headers``, ``query_params`` and ``cookies`` hold the static
+    authentication values to inject, by location (each empty when it does
+    not apply). ``oauth2`` carries the parameters for a runtime
+    token-fetching fixture, or None. ``warning`` is a human-readable
+    message when a declared scheme was skipped, or None otherwise.
+    """
+
+    headers: dict = {}
+    query_params: dict = {}
+    cookies: dict = {}
+    oauth2: OAuth2Fixture | None = None
+    manual_auth: str | None = None
+    warning: str | None = None
+
+
+_NO_AUTH = ResolvedAuth(headers={}, warning=None)
+
+
+def resolve_auth(endpoint, security_schemes, auth_config):
+    """Resolve authentication for a single endpoint.
+
+    The endpoint's security is a list of alternatives (OR); each
+    alternative is a list of scheme names that must all be satisfied
+    together (AND). The first alternative whose schemes are all
+    resolvable is used, merging every scheme's contribution. If no
+    alternative is fully satisfiable, generation proceeds without
+    authentication and a warning is returned.
+
+    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 values to inject and an optional warning.
+    """
+    if not endpoint.security:
+        return _NO_AUTH
+
+    for alternative in endpoint.security:
+        merged = _resolve_alternative(alternative, security_schemes, auth_config)
+        if merged is not None:
+            if merged.manual_auth is not None and merged.warning is None:
+                merged = merged._replace(
+                    warning=(
+                        f"Scheme '{merged.manual_auth}' uses an interactive "
+                        f"OAuth2 flow that cannot be automated; a placeholder "
+                        f"token is generated for you to complete manually."
+                    )
+                )
+            return merged
+
+    scheme_names = sorted(
+        {name for alternative in endpoint.security for name in alternative}
+    )
+    listed = ", ".join(scheme_names) if scheme_names else "the declared schemes"
+    return ResolvedAuth(
+        warning=(
+            f"Could not satisfy security requirement(s) [{listed}] with the "
+            f"configured credentials; affected endpoints are generated "
+            f"without authentication."
+        ),
+    )
+
+
+def _resolve_alternative(alternative, security_schemes, auth_config):
+    """Resolve one AND group, merging all schemes, or None if unsatisfiable.
+
+    An empty alternative (an empty security requirement in the spec) means
+    authentication is optional and resolves to no auth.
+    """
+    headers = {}
+    query_params = {}
+    cookies = {}
+    oauth2 = None
+    manual_auth = None
+    for scheme_name in alternative:
+        contribution = _resolve_scheme(
+            scheme_name, security_schemes, auth_config
+        )
+        if contribution is None:
+            return None
+        (
+            scheme_headers,
+            scheme_query,
+            scheme_cookies,
+            scheme_oauth2,
+            scheme_manual,
+        ) = contribution
+        headers.update(scheme_headers)
+        query_params.update(scheme_query)
+        cookies.update(scheme_cookies)
+        if scheme_oauth2 is not None:
+            oauth2 = scheme_oauth2
+        if scheme_manual is not None:
+            manual_auth = scheme_manual
+
+    return ResolvedAuth(
+        headers=headers,
+        query_params=query_params,
+        cookies=cookies,
+        oauth2=oauth2,
+        manual_auth=manual_auth,
+    )
+
+
+def _resolve_scheme(scheme_name, security_schemes, auth_config):
+    """Resolve one scheme to a (headers, query_params, cookies, oauth2) tuple.
+
+    Returns None when the scheme is undefined, unsupported, or its
+    credentials are not configured - signalling that the enclosing
+    alternative cannot be satisfied.
+    """
+    scheme = security_schemes.get(scheme_name)
+    if scheme is None:
+        return None
+
+    scheme_type = scheme.get("type")
+
+    if scheme_type == "oauth2":
+        return _resolve_oauth2(scheme_name, scheme, auth_config)
+    if scheme_type == "openIdConnect":
+        return _resolve_oidc(scheme, auth_config)
+    if scheme_type == "http":
+        http_scheme = scheme.get("scheme", "").lower()
+        if http_scheme == "bearer":
+            return _resolve_bearer(auth_config)
+        if http_scheme == "basic":
+            return _resolve_basic(auth_config)
+    if scheme_type == "apiKey" and scheme.get("in") in (
+        "header",
+        "query",
+        "cookie",
+    ):
+        return _resolve_api_key(scheme, auth_config)
+
+    return None
+
+
+def _resolve_bearer(auth_config):
+    """Return a bearer Authorization header, or None if unconfigured."""
+    bearer = auth_config.bearer
+    if bearer is None or not bearer.token:
+        return None
+    return ({"Authorization": f"Bearer {bearer.token}"}, {}, {}, None, None)
+
+
+def _resolve_basic(auth_config):
+    """Return a basic Authorization header, or None if unconfigured."""
+    basic = auth_config.basic
+    if basic is None or not basic.username or not basic.password:
+        return None
+    raw = f"{basic.username}:{basic.password}".encode("utf-8")
+    encoded = base64.b64encode(raw).decode("ascii")
+    return ({"Authorization": f"Basic {encoded}"}, {}, {}, None, None)
+
+
+def _resolve_api_key(scheme, auth_config):
+    """Return an API-key contribution by location, or None if unconfigured.
+
+    The key's name and location come from the spec scheme; the config
+    supplies only the value.
+    """
+    api_key = auth_config.api_key
+    if api_key is None or not api_key.value:
+        return None
+    key_name = scheme.get("name")
+    if not key_name:
+        return None
+
+    location = scheme.get("in")
+    if location == "query":
+        return ({}, {key_name: api_key.value}, {}, None, None)
+    if location == "cookie":
+        return ({}, {}, {key_name: api_key.value}, None, None)
+    return ({key_name: api_key.value}, {}, {}, None, None)
+
+
+def _resolve_oauth2(scheme_name, scheme, auth_config):
+    """Resolve an oauth2 scheme.
+
+    The clientCredentials flow is fully automated (it needs the spec's
+    tokenUrl and the configured client id and secret). When only an
+    interactive flow such as authorizationCode is offered, it cannot be
+    automated, so a manual stub naming the scheme is produced for the user
+    to complete. Purely interactive-only flows with no authorizationCode
+    (implicit, password) are not supported and make the alternative
+    unsatisfiable.
+    """
+    flows = scheme.get("flows", {})
+
+    client_credentials = flows.get("clientCredentials")
+    if client_credentials is not None:
+        token_url = client_credentials.get("tokenUrl")
+        oauth2 = auth_config.oauth2
+        if (
+            token_url
+            and oauth2 is not None
+            and oauth2.client_id
+            and oauth2.client_secret
+        ):
+            fixture = OAuth2Fixture(
+                token_url=token_url,
+                client_id=oauth2.client_id,
+                client_secret=oauth2.client_secret,
+                scope=oauth2.scope,
+            )
+            return ({}, {}, {}, fixture, None)
+
+    if "authorizationCode" in flows:
+        return ({}, {}, {}, None, scheme_name)
+
+    return None
+
+
+def _resolve_oidc(scheme, auth_config):
+    """Resolve an openIdConnect scheme to a discovery-based OAuth2 fixture.
+
+    The generated test performs OpenID Connect discovery at runtime using
+    the scheme's openIdConnectUrl, then obtains a token via the client
+    credentials grant. It therefore needs configured client credentials;
+    without them the scheme is not satisfiable.
+    """
+    discovery_url = scheme.get("openIdConnectUrl")
+    if not discovery_url:
+        return None
+
+    oauth2 = auth_config.oauth2
+    if oauth2 is None or not oauth2.client_id or not oauth2.client_secret:
+        return None
+
+    fixture = OAuth2Fixture(
+        discovery_url=discovery_url,
+        client_id=oauth2.client_id,
+        client_secret=oauth2.client_secret,
+        scope=oauth2.scope,
+    )
+    return ({}, {}, {}, fixture, None)

{swaggerforge-0.2.0 → swaggerforge-0.3.1}/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}")