swaggerforge 0.1.0__py3-none-any.whl

swaggerforge/cli.py

@@ -0,0 +1,67 @@
+"""Command-line interface for SwaggerForge."""
+
+import click
+from swaggerforge.validator import load_and_validate, SpecValidationError
+from swaggerforge.parser import parse_spec, SpecParseError
+from swaggerforge.generator import generate_scenarios
+from swaggerforge.output import write_test_files
+
+
+@click.group()
+@click.version_option()
+def main():
+    """SwaggerForge generate pytest tests from OpenAPI specifications."""
+    pass
+
+
+@main.command()
+@click.option(
+    "--spec",
+    required=True,
+    type=click.Path(exists=True),
+    help="Path to the OpenAPI specification file (JSON or YAML).",
+)
+@click.option(
+    "--url",
+    required=True,
+    help="Base URL of the API to be tested.",
+)
+@click.option(
+    "--output",
+    default="tests_generated",
+    type=click.Path(),
+    help="Directory where generated test files will be written.",
+)
+def generate(spec, url, output):
+    """Generate pytest test files from an OpenAPI specification."""
+    click.echo(f"Reading specification: {spec}")
+
+    try:
+        spec_dict = load_and_validate(spec)
+    except SpecValidationError as error:
+        raise click.ClickException(str(error))
+
+    click.echo("Specification is valid.")
+    click.echo(f"API title: {spec_dict['info']['title']}")
+
+    try:
+        endpoints = parse_spec(spec)
+    except SpecParseError as error:
+        raise click.ClickException(str(error))
+
+    tags = sorted({endpoint.tag for endpoint in endpoints})
+    click.echo(f"Found {len(endpoints)} endpoints across {len(tags)} resources: {', '.join(tags)}")
+
+    scenarios = generate_scenarios(endpoints)
+    click.echo(f"Generated {len(scenarios)} test scenarios.")
+
+    try:
+        written = write_test_files(scenarios, url, output)
+    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:
+        click.echo(f"  - {path}")

swaggerforge/generator.py

@@ -0,0 +1,441 @@
+"""Generation of test scenarios from parsed OpenAPI endpoints.
+
+This module turns the internal endpoint model into concrete test scenarios.
+Its first building block is a deterministic example-value generator that
+produces valid sample values from a JSON schema.
+"""
+
+from swaggerforge.models import TestScenario
+
+
+def example_value(schema):
+    """Produce a deterministic example value conforming to a JSON schema.
+
+    The same schema always yields the same value, which is required for
+    reproducible test generation (WNF11).
+
+    Args:
+        schema: A resolved JSON schema fragment (a dictionary).
+
+    Returns:
+        A Python value (str, int, float, bool, list, or dict) valid under
+        the schema.
+    """
+    if not isinstance(schema, dict):
+        return None
+
+    enum = schema.get("enum")
+    if enum:
+        return enum[0]
+
+    schema_type = schema.get("type")
+
+    if schema_type == "string":
+        return _example_string(schema)
+    if schema_type == "integer":
+        return _example_integer(schema)
+    if schema_type == "number":
+        return _example_integer(schema)
+    if schema_type == "boolean":
+        return True
+    if schema_type == "array":
+        item_schema = schema.get("items", {})
+        return [example_value(item_schema)]
+    if schema_type == "object":
+        return _example_object(schema)
+
+    return None
+
+
+def _example_integer(schema):
+    """Return a valid integer, respecting 'minimum' if present."""
+    minimum = schema.get("minimum")
+    if minimum is not None:
+        return minimum
+    return 0
+
+
+# deterministic values for common string formats
+_STRING_FORMATS = {
+    "date-time": "2024-01-01T00:00:00Z",
+    "date": "2024-01-01",
+    "email": "user@example.com",
+    "uuid": "00000000-0000-0000-0000-000000000000",
+    "uri": "https://example.com",
+}
+
+
+def _example_string(schema):
+    """Return a string value, honoring a recognized 'format' if present."""
+    string_format = schema.get("format")
+    return _STRING_FORMATS.get(string_format, "string")
+
+
+def _example_object(schema):
+    """Build a dict with an example value for each declared property."""
+    result = {}
+    properties = schema.get("properties", {})
+    for name, prop_schema in properties.items():
+        result[name] = example_value(prop_schema)
+    return result
+
+
+def generate_positive_scenario(endpoint):
+    """Build a positive (happy-path) test scenario for an endpoint.
+
+    Sends a valid request conforming to the schema and expects a 2xx
+    response code, following the equivalence-partitioning technique for
+    the valid input class.
+
+    Args:
+        endpoint: The Endpoint to generate a scenario for.
+
+    Returns:
+        A single-element list containing the positive-case TestScenario.
+    """
+    request_body = None
+    if endpoint.request_body is not None:
+        request_body = example_value(endpoint.request_body)
+
+    return [TestScenario(
+        endpoint=endpoint,
+        name="success",
+        scenario_type="positive",
+        description=f"{endpoint.method.upper()} {endpoint.path} - positive scenario",
+        path_params=_example_path_params(endpoint),
+        query_params=_example_query_params(endpoint),
+        request_body=request_body,
+        expected_status=_success_codes(endpoint),
+    )]
+
+
+def _success_codes(endpoint):
+    """Return the 2xx response codes declared for an endpoint."""
+    return [code for code in endpoint.responses if code.startswith("2")]
+
+
+def _example_path_params(endpoint):
+    """Build example values for an endpoint's path parameters."""
+    params = {}
+    for param in endpoint.parameters:
+        if param.location == "path":
+            params[param.name] = example_value(param.schema)
+    return params
+
+
+def _example_query_params(endpoint):
+    """Build example values for an endpoint's required query parameters."""
+    params = {}
+    for param in endpoint.parameters:
+        if param.location == "query" and param.required:
+            params[param.name] = example_value(param.schema)
+    return params
+
+
+def generate_missing_field_scenario(endpoint):
+    """Build a negative scenario that omits a required field from the body.
+
+    Takes a valid request body and removes the first required field,
+    following the equivalence-partitioning technique for the invalid
+    input class.
+
+    Args:
+        endpoint: The Endpoint to generate a scenario for.
+
+    Returns:
+        A single-element list with the missing-field TestScenario, or an
+        empty list if the endpoint has no request body with required fields.
+    """
+    if endpoint.request_body is None:
+        return []
+
+    required_fields = endpoint.request_body.get("required", [])
+    if not required_fields:
+        return []
+
+    field_to_remove = required_fields[0]
+
+    body = example_value(endpoint.request_body)
+    body.pop(field_to_remove, None)
+
+    return [TestScenario(
+        endpoint=endpoint,
+        name=f"missing_{field_to_remove}",
+        scenario_type="negative",
+        description=(
+            f"{endpoint.method.upper()} {endpoint.path} - "
+            f"missing required field '{field_to_remove}' (expects 400)"
+        ),
+        path_params=_example_path_params(endpoint),
+        query_params=_example_query_params(endpoint),
+        request_body=body,
+        expected_status=["400"],
+    )]
+
+
+# A deterministic, unlikely-to-exist identifier used for "resource not found" tests.
+NONEXISTENT_INT_ID = 999999999
+NONEXISTENT_STR_ID = "nonexistent-id-000000"
+
+
+def generate_nonexistent_scenario(endpoint):
+    """Build a negative scenario requesting a resource that does not exist.
+
+    Applies to endpoints with a path parameter (a resource identifier).
+    Uses a deterministic, unlikely identifier and expects a 404 response.
+    This is a best-effort heuristic: the spec describes the API's shape,
+    not its data, so the absence of the resource cannot be guaranteed.
+
+    Args:
+        endpoint: The Endpoint to generate a scenario for.
+
+    Returns:
+        A single-element list with the not-found TestScenario, or an empty
+        list if the endpoint has no path parameter.
+    """
+    path_params = {}
+    has_path_param = False
+    for param in endpoint.parameters:
+        if param.location == "path":
+            has_path_param = True
+            path_params[param.name] = _nonexistent_value(param.schema)
+
+    if not has_path_param:
+        return []
+
+    expected = "404"
+
+    return [TestScenario(
+        endpoint=endpoint,
+        name="nonexistent",
+        scenario_type="negative",
+        description=(
+            f"{endpoint.method.upper()} {endpoint.path} - "
+            f"nonexistent resource (expects 404)"
+        ),
+        path_params=path_params,
+        query_params=_example_query_params(endpoint),
+        request_body=None,
+        expected_status=[expected],
+    )]
+
+
+def generate_wrong_type_scenario(endpoint):
+    """Build a negative scenario sending a wrong-typed field in the body.
+
+    Takes a valid request body and replaces the first numeric field with a
+    string value, violating the declared type. Expects a 400 or 422
+    response.
+
+    Args:
+        endpoint: The Endpoint to generate a scenario for.
+
+    Returns:
+        A single-element list with the wrong-type TestScenario, or an empty
+        list if the body has no numeric field to corrupt.
+    """
+    if endpoint.request_body is None:
+        return []
+
+    properties = endpoint.request_body.get("properties", {})
+    field_to_corrupt = _first_numeric_field(properties)
+    if field_to_corrupt is None:
+        return []
+
+    body = example_value(endpoint.request_body)
+    body[field_to_corrupt] = "not_a_number"
+
+    return [TestScenario(
+        endpoint=endpoint,
+        name=f"wrong_type_{field_to_corrupt}",
+        scenario_type="negative",
+        description=(
+            f"{endpoint.method.upper()} {endpoint.path} - "
+            f"wrong type for field '{field_to_corrupt}' (expects 400 or 422)"
+        ),
+        path_params=_example_path_params(endpoint),
+        query_params=_example_query_params(endpoint),
+        request_body=body,
+        expected_status=["400", "422"],
+    )]
+
+
+def generate_boundary_scenarios(endpoint):
+    """Build boundary-value scenarios for an endpoint's constrained fields.
+
+    Applies Boundary Value Analysis: for each body field that declares
+    numeric (minimum/maximum) or string-length (minLength/maxLength)
+    constraints, generates scenarios at and just beyond each edge. Valid
+    edges expect a 2xx response; out-of-range values expect 400 or 422.
+
+    Args:
+        endpoint: The Endpoint to generate scenarios for.
+
+    Returns:
+        A list of TestScenario objects (empty if no constrained fields).
+    """
+    if endpoint.request_body is None:
+        return []
+
+    scenarios = []
+    properties = endpoint.request_body.get("properties", {})
+    for field_name, field_schema in properties.items():
+        if not isinstance(field_schema, dict):
+            continue
+        for value, is_valid, label in _boundary_cases(field_schema):
+            scenarios.append(
+                _make_boundary_scenario(endpoint, field_name, value, is_valid, label)
+            )
+    return scenarios
+
+
+def generate_boolean_scenarios(endpoint):
+    """Build scenarios exercising both values of each boolean body field.
+
+    For every boolean field in the request body, generates two scenarios -
+    one sending True and one sending False - since both are valid values an
+    API should accept. This gives coverage of logical parameters (WF12).
+
+    Args:
+        endpoint: The Endpoint to generate scenarios for.
+
+    Returns:
+        A list of TestScenario objects (empty if no boolean fields).
+    """
+    if endpoint.request_body is None:
+        return []
+
+    scenarios = []
+    properties = endpoint.request_body.get("properties", {})
+    for field_name, field_schema in properties.items():
+        if not isinstance(field_schema, dict):
+            continue
+        if field_schema.get("type") != "boolean":
+            continue
+        for value in (True, False):
+            scenarios.append(
+                _make_boolean_scenario(endpoint, field_name, value)
+            )
+    return scenarios
+
+
+def _make_boolean_scenario(endpoint, field_name, value):
+    """Construct one boolean TestScenario for a field set to True or False."""
+    body = example_value(endpoint.request_body)
+    body[field_name] = value
+
+    return TestScenario(
+        endpoint=endpoint,
+        name=f"boolean_{field_name}_{str(value).lower()}",
+        scenario_type="boolean",
+        description=(
+            f"{endpoint.method.upper()} {endpoint.path} - "
+            f"boolean field '{field_name}' = {str(value).lower()}"
+        ),
+        path_params=_example_path_params(endpoint),
+        query_params=_example_query_params(endpoint),
+        request_body=body,
+        expected_status=_success_codes(endpoint) or ["200"],
+    )
+
+
+def _boundary_cases(field_schema):
+    """Return (value, is_valid, label) tuples for a field's declared boundaries."""
+    field_type = field_schema.get("type")
+    if field_type in ("integer", "number"):
+        return _numeric_boundary_cases(field_schema)
+    if field_type == "string":
+        return _string_boundary_cases(field_schema)
+    return []
+
+
+def _numeric_boundary_cases(field_schema):
+    """Boundary cases for a numeric field with minimum/maximum."""
+    cases = []
+    minimum = field_schema.get("minimum")
+    maximum = field_schema.get("maximum")
+    if minimum is not None:
+        cases.append((minimum - 1, False, "below_min"))
+        cases.append((minimum, True, "at_min"))
+    if maximum is not None:
+        cases.append((maximum, True, "at_max"))
+        cases.append((maximum + 1, False, "above_max"))
+    return cases
+
+
+def _string_boundary_cases(field_schema):
+    """Boundary cases for a string field with minLength/maxLength."""
+    cases = []
+    min_length = field_schema.get("minLength")
+    max_length = field_schema.get("maxLength")
+    if min_length is not None and min_length > 0:
+        cases.append(("x" * (min_length - 1), False, "below_min_length"))
+        cases.append(("x" * min_length, True, "at_min_length"))
+    if max_length is not None:
+        cases.append(("x" * max_length, True, "at_max_length"))
+        cases.append(("x" * (max_length + 1), False, "above_max_length"))
+    return cases
+
+
+def _make_boundary_scenario(endpoint, field_name, value, is_valid, label):
+    """Construct one boundary TestScenario for a field set to a given value."""
+    body = example_value(endpoint.request_body)
+    body[field_name] = value
+
+    if is_valid:
+        expected = _success_codes(endpoint) or ["200"]
+    else:
+        expected = ["400", "422"]
+
+    return TestScenario(
+        endpoint=endpoint,
+        name=f"boundary_{field_name}_{label}",
+        scenario_type="boundary",
+        description=(
+            f"{endpoint.method.upper()} {endpoint.path} - "
+            f"boundary value for '{field_name}' ({label})"
+        ),
+        path_params=_example_path_params(endpoint),
+        query_params=_example_query_params(endpoint),
+        request_body=body,
+        expected_status=expected,
+    )
+
+
+def _first_numeric_field(properties):
+    """Return the name of the first integer/number property, or None."""
+    for name, prop_schema in properties.items():
+        if isinstance(prop_schema, dict) and prop_schema.get("type") in ("integer", "number"):
+            return name
+    return None
+
+
+def _nonexistent_value(schema):
+    """Return a deterministic, unlikely identifier matching the schema type."""
+    if schema.get("type") == "integer":
+        return NONEXISTENT_INT_ID
+    return NONEXISTENT_STR_ID
+
+
+def generate_scenarios(endpoints):
+    """Generate all applicable test scenarios for a list of endpoints.
+
+    Runs every scenario generator over each endpoint. Every generator
+    returns a (possibly empty) list of scenarios, so the results are simply
+    flattened into one list.
+
+    Args:
+        endpoints: A list of Endpoint objects.
+
+    Returns:
+        A list of TestScenario objects.
+    """
+    scenarios = []
+    for endpoint in endpoints:
+        scenarios.extend(generate_positive_scenario(endpoint))
+        scenarios.extend(generate_missing_field_scenario(endpoint))
+        scenarios.extend(generate_nonexistent_scenario(endpoint))
+        scenarios.extend(generate_wrong_type_scenario(endpoint))
+        scenarios.extend(generate_boundary_scenarios(endpoint))
+        scenarios.extend(generate_boolean_scenarios(endpoint))
+    return scenarios

swaggerforge/models.py

@@ -0,0 +1,46 @@
+"""Internal data model for SwaggerForge.
+
+These dataclasses represent the structured form of an OpenAPI specification
+used internally by the library. The Parser produces them from a raw
+specification; the Generator and Template modules consume them.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Parameter:
+    """A single operation parameter (path, query, or header)."""
+
+    name: str
+    location: str
+    required: bool
+    schema: dict = field(default_factory=dict)
+
+
+@dataclass
+class Endpoint:
+    """A single API operation: one HTTP method on one path."""
+
+    path: str
+    method: str
+    tag: str
+    operation_id: str
+    parameters: list[Parameter] = field(default_factory=list)
+    request_body: dict | None = None
+    responses: list[str] = field(default_factory=list)
+    response_schema: dict | None = None
+
+
+@dataclass
+class TestScenario:
+    """A single generated test case for one endpoint."""
+
+    endpoint: Endpoint
+    name: str
+    scenario_type: str
+    description: str
+    path_params: dict = field(default_factory=dict)
+    query_params: dict = field(default_factory=dict)
+    request_body: dict | None = None
+    expected_status: list[str] = field(default_factory=list)

swaggerforge/output.py

@@ -0,0 +1,53 @@
+"""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 swaggerforge.template import render_test_file
+
+
+def write_test_files(scenarios, base_url, output_dir):
+    """Group scenarios by tag, render them, and write one file per tag.
+
+    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.
+
+    Returns:
+        A sorted list of paths to the files that were written.
+    """
+    grouped = _group_by_tag(scenarios)
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    written = []
+    for tag in sorted(grouped):
+        filename = f"test_{_sanitize(tag)}.py"
+        file_path = output_path / filename
+        content = render_test_file(filename, base_url, grouped[tag])
+        file_path.write_text(content, encoding="utf-8")
+        written.append(str(file_path))
+
+    return written
+
+
+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)

swaggerforge/parser.py

@@ -0,0 +1,108 @@
+"""Parsing of OpenAPI specifications into the internal data model.
+
+This module reads an OpenAPI specification, resolves any $ref references,
+and extracts a structured list of endpoints grouped by resource tag.
+"""
+
+from prance import ResolvingParser
+
+from swaggerforge.models import Endpoint, Parameter
+
+# HTTP methods that represent operations we generate tests for.
+HTTP_METHODS = ("get", "post", "put", "patch", "delete")
+
+
+class SpecParseError(Exception):
+    """Raised when the specification cannot be parsed into the data model."""
+    pass
+
+
+def parse_spec(spec_path):
+    """Parse an OpenAPI specification into a list of endpoints.
+
+    Args:
+        spec_path: Path to the OpenAPI specification file (JSON or YAML).
+
+    Returns:
+        A list of Endpoint objects extracted from the specification.
+
+    Raises:
+        SpecParseError: If the specification cannot be parsed.
+    """
+    try:
+        parser = ResolvingParser(spec_path, backend="openapi-spec-validator")
+        spec = parser.specification
+    except Exception as error:
+        raise SpecParseError(
+            f"Could not parse specification '{spec_path}': {error}"
+        )
+
+    endpoints = []
+
+    paths = spec.get("paths", {})
+    for path, path_item in paths.items():
+        for method in HTTP_METHODS:
+            operation = path_item.get(method)
+            if operation is None:
+                continue
+
+            endpoint = Endpoint(
+                path=path,
+                method=method,
+                tag=_extract_tag(operation),
+                operation_id=operation.get("operationId", ""),
+                parameters=_extract_parameters(operation),
+                request_body=_extract_request_body(operation),
+                responses=list(operation.get("responses", {}).keys()),
+                response_schema=_extract_response_schema(operation),
+            )
+            endpoints.append(endpoint)
+
+    return endpoints
+
+
+def _extract_tag(operation):
+    """Return the first tag of an operation, or 'default' if none."""
+    tags = operation.get("tags", [])
+    if tags:
+        return tags[0]
+    return "default"
+
+
+def _extract_parameters(operation):
+    """Build a list of Parameter objects from an operation."""
+    parameters = []
+    for param in operation.get("parameters", []):
+        parameters.append(
+            Parameter(
+                name=param.get("name", ""),
+                location=param.get("in", ""),
+                required=param.get("required", False),
+                schema=param.get("schema", {}),
+            )
+        )
+    return parameters
+
+
+def _extract_request_body(operation):
+    """Return the resolved JSON request body schema, or None."""
+    request_body = operation.get("requestBody")
+    if request_body is None:
+        return None
+    content = request_body.get("content", {})
+    json_content = content.get("application/json")
+    if json_content is None:
+        return None
+    return json_content.get("schema")
+
+
+def _extract_response_schema(operation):
+    """Return the resolved JSON schema of the success (2xx) response, or None."""
+    responses = operation.get("responses", {})
+    for code, response in responses.items():
+        if code.startswith("2"):
+            content = response.get("content", {})
+            json_content = content.get("application/json")
+            if json_content is not None:
+                return json_content.get("schema")
+    return None

swaggerforge/template.py

@@ -0,0 +1,116 @@
+"""Rendering of test scenarios into pytest source code.
+
+This module turns TestScenario objects into the text of a pytest test
+file, using a Jinja2 template. All computation (building function names,
+request calls, and literals) happens here; the template only places the
+pre-computed values.
+"""
+
+from jinja2 import Environment, PackageLoader
+
+_env = Environment(
+    loader=PackageLoader("swaggerforge"),
+    trim_blocks=True,
+    lstrip_blocks=True,
+    keep_trailing_newline=True,
+    autoescape=False,
+)
+
+
+def render_test_file(filename, base_url, scenarios):
+    """Render a list of scenarios into the text of a pytest test file.
+
+    Args:
+        filename: The name of the file being generated (e.g. 'test_pet.py').
+        base_url: The base URL of the API under test.
+        scenarios: A list of TestScenario objects for one resource tag.
+
+    Returns:
+        The rendered file content as a string.
+    """
+    template = _env.get_template("test_file.py.j2")
+    rendered_scenarios = [_prepare_scenario(s) for s in scenarios]
+    return template.render(
+        filename=filename,
+        base_url=base_url,
+        scenarios=rendered_scenarios,
+    )
+
+
+def _prepare_scenario(scenario):
+    """Pre-compute all values the template needs for one scenario."""
+    return {
+        "function_name": build_function_name(scenario),
+        "docstring": scenario.description,
+        "request_call": build_request_call(scenario),
+        "expected_status": _status_codes_literal(scenario),
+        "response_schema": _response_schema_literal(scenario),
+    }
+
+
+def build_function_name(scenario):
+    """Build a unique pytest function name for a scenario.
+
+    Uses the operationId (unique per operation in OpenAPI) when available,
+    falling back to a method-and-path-derived identifier otherwise.
+    """
+    endpoint = scenario.endpoint
+    if endpoint.operation_id:
+        base = _to_snake_case(endpoint.operation_id)
+    else:
+        base = _path_to_identifier(endpoint.method, endpoint.path)
+    return f"test_{base}_{scenario.name}"
+
+
+def _to_snake_case(operation_id):
+    """Convert a camelCase operationId to snake_case (e.g. getPetById -> get_pet_by_id)."""
+    result = []
+    for char in operation_id:
+        if char.isupper():
+            result.append("_")
+            result.append(char.lower())
+        else:
+            result.append(char)
+    return "".join(result).strip("_")
+
+
+def _path_to_identifier(method, path):
+    """Build an identifier from method and path when no operationId exists."""
+    cleaned = path.replace("/", "_").replace("{", "").replace("}", "")
+    cleaned = cleaned.strip("_")
+    return f"{method}_{cleaned}"
+
+
+def build_request_call(scenario):
+    """Assemble the full requests.<method>(...) call as a string."""
+    endpoint = scenario.endpoint
+    url = _build_url(endpoint.path, scenario.path_params)
+
+    parts = [f'f"{{base_url}}{url}"']
+    if scenario.query_params:
+        parts.append(f"params={scenario.query_params!r}")
+    if scenario.request_body is not None:
+        parts.append(f"json={scenario.request_body!r}")
+
+    args = ", ".join(parts)
+    return f"requests.{endpoint.method}({args})"
+
+
+def _build_url(path, path_params):
+    """Substitute path parameter values into a path template."""
+    result = path
+    for name, value in path_params.items():
+        result = result.replace("{" + name + "}", str(value))
+    return result
+
+
+def _status_codes_literal(scenario):
+    """Return the expected status codes as a list of ints, e.g. [200, 201]."""
+    return [int(code) for code in scenario.expected_status]
+
+
+def _response_schema_literal(scenario):
+    """Return the response schema for positive scenarios, else None."""
+    if scenario.scenario_type == "positive":
+        return scenario.endpoint.response_schema
+    return None

swaggerforge/templates/test_file.py.j2

@@ -0,0 +1,24 @@
+{# Template for a generated pytest test file (one per resource tag). #}
+{# Receives: tag, base_url, and a list of pre-rendered scenario dicts. #}
+# {{ filename }}
+# Generated by SwaggerForge - do not edit manually.
+import pytest
+import requests
+import jsonschema
+
+
+@pytest.fixture(scope="session")
+def base_url():
+    return "{{ base_url }}"
+
+{% for scenario in scenarios %}
+
+def {{ scenario.function_name }}(base_url):
+    """{{ scenario.docstring }}"""
+    response = {{ scenario.request_call }}
+    assert response.status_code in {{ scenario.expected_status }}
+{% if scenario.response_schema %}
+    schema = {{ scenario.response_schema }}
+    jsonschema.validate(instance=response.json(), schema=schema)
+{% endif %}
+{% endfor %}

swaggerforge/validator.py

@@ -0,0 +1,44 @@
+"""Validation of OpenAPI specification files.
+
+This module is responsible for reading an OpenAPI specification from disk
+and verifying that it is structurally valid before any further processing.
+"""
+
+from openapi_spec_validator import validate
+from openapi_spec_validator.readers import read_from_filename
+from openapi_spec_validator.validation.exceptions import OpenAPIValidationError
+
+
+class SpecValidationError(Exception):
+    """Raised when an OpenAPI specification is invalid or cannot be read."""
+    pass
+
+
+def load_and_validate(spec_path):
+    """Read and validate an OpenAPI specification file.
+
+    Args:
+        spec_path: Path to the OpenAPI specification file (JSON or YAML).
+
+    Returns:
+        The validated specification as a dictionary.
+
+    Raises:
+        SpecValidationError: If the file cannot be read or is not a valid
+            OpenAPI specification.
+    """
+    try:
+        spec_dict, base_uri = read_from_filename(spec_path)
+    except Exception as error:
+        raise SpecValidationError(
+            f"Could not read specification file '{spec_path}': {error}"
+        )
+
+    try:
+        validate(spec_dict)
+    except OpenAPIValidationError as error:
+        raise SpecValidationError(
+            f"Invalid OpenAPI specification '{spec_path}': {error.message}"
+        )
+
+    return spec_dict

swaggerforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: swaggerforge
+Version: 0.1.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-core>=0.18
+Requires-Dist: openapi-spec-validator>=0.7
+Requires-Dist: jinja2>=3.0
+Requires-Dist: requests>=2.28
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: flake8>=7.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
+
+## 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)*       |
+| `--output` | Directory for the generated test files             | `tests_generated`  |
+
+## 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.

swaggerforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+swaggerforge/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swaggerforge/__main__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swaggerforge/cli.py,sha256=wJSm4NuITUncwgQTwbbpYx1KiNXtKu94y4aU-Oxwv6E,2048
+swaggerforge/generator.py,sha256=B7Jj9Uq-yx02n41v0boUIH8eINz4cnfHb3flmSx25c0,14979
+swaggerforge/models.py,sha256=rlPOYSqcZFsn8glUCG4T5Mi3XFl8BvWoEAW-tXYQrbY,1263
+swaggerforge/output.py,sha256=t_0Dms4-2Gp96Swo15VAs3Mfc87OODFzh8Ee_1zJTcA,1662
+swaggerforge/parser.py,sha256=r4vUzafeq6KCbIpVJec5QEB4FaOt_HBXsOXqsfwJ7_A,3545
+swaggerforge/template.py,sha256=sy6yH7xqcUFVIsrffu5iteOvemheFxdvT26CwNMqaSo,3920
+swaggerforge/validator.py,sha256=Cyn6uhC5O8Poihm_HsSZ-yk2TtSAWgPsg1wNI6Ek_F8,1373
+swaggerforge/templates/test_file.py.j2,sha256=zkJS2WlzmnRcHDVj3ovBRZzp56BKDK1Ba903Vefb_oQ,754
+swaggerforge-0.1.0.dist-info/licenses/LICENSE,sha256=xEuAv8EHV44TLaTEgveWUaVa_iXumSw-UY8kBHhqpTg,1092
+swaggerforge-0.1.0.dist-info/METADATA,sha256=QYYLgV3TBl3Ln6EQeHUyLtbJA3p1HX9uPcIYFBYsUy8,3543
+swaggerforge-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+swaggerforge-0.1.0.dist-info/entry_points.txt,sha256=KVzakVZtrieiY8HgXo_RVyZlTQUBfyJPB_jiUtuIZ6c,55
+swaggerforge-0.1.0.dist-info/top_level.txt,sha256=ytRVBaDXndBGnlln9nkkxmYeIoHygfuV2-IO11mxnd4,13
+swaggerforge-0.1.0.dist-info/RECORD,,

swaggerforge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

swaggerforge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+swaggerforge = swaggerforge.cli:main

swaggerforge-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viktor Pylypenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swaggerforge-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+swaggerforge