swaggerforge 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swaggerforge
-Version: 0.3.1
+Version: 0.4.0
 Summary: Automatic pytest test generation from OpenAPI (Swagger) specifications
 Author: Viktor Pylypenko
 License-Expression: MIT
@@ -43,12 +43,18 @@ established test-design techniques.
     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
+  - **Nonexistent resource** >>> requests a resource that was created and then
+    deleted, so its absence is guaranteed (or, when the API offers no delete,
+    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
+- Stateful tests: operations on an existing resource run against one the test
+  creates itself and removes afterwards, instead of a guessed identifier
+- Valid request data built from the specification's own examples, defaults,
+  enums and constraints
 - Deterministic output: the same specification always produces identical tests
-- Generated files use session-scoped pytest fixtures and run with no manual edits
+- Generated files use 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
@@ -192,12 +198,79 @@ 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.
 
+## Stateful tests
+
+Endpoints that act on an existing resource - `GET`, `PUT`, `PATCH` or
+`DELETE` on `/pets/{petId}` - need a resource that really exists. SwaggerForge
+detects the operation that creates it and generates fixtures that create the
+resource before a test and remove it afterwards.
+
+A create operation is recognised by REST convention: a `POST` on a collection
+path (`/pets`) produces resources addressed by that path plus one parameter
+(`/pets/{petId}`). The new resource's identifier is taken from the response
+field named like the path parameter, or else from `id`. When the
+specification declares explicit OpenAPI `links`, they take priority.
+
+For each such resource, generated files contain two fixtures:
+
+- `created_<resource>` creates the resource, yields its identifier (read from
+  the response body, or from the `Location` header) and deletes it after the
+  test
+- `deleted_<resource>` creates the resource and deletes it immediately, giving
+  the nonexistent-resource test an identifier that is guaranteed not to exist
+
+```python
+@pytest.fixture
+def created_pet(base_url, api_session):
+    response = api_session.post(f"{base_url}/pet", json={'id': uuid.uuid4().int >> 80, 'name': 'doggie', 'photoUrls': ['string']})
+    assert response.status_code in [200], (
+        f"Creating pet failed: "
+        f"{response.status_code} {response.text}"
+    )
+    resource_id = _extract_id(response, 'id')
+    yield resource_id
+    try:
+        api_session.delete(f"{base_url}/pet/{resource_id}")
+    except requests.RequestException:
+        pass
+
+
+def test_get_pet_by_id_success(base_url, api_session, created_pet):
+    """GET /pet/{petId} - positive scenario"""
+    response = api_session.get(f"{base_url}/pet/{created_pet}")
+    assert response.status_code in [200]
+```
+
+*(Abridged from a file generated for the Swagger Petstore specification.)*
+
+Every scenario on such an endpoint uses the created resource - negative
+scenarios included, so a 404 for a missing resource cannot hide the 400 a
+validation test expects. A top-level `id` in the create request is sent as a
+fresh unique value on every run, so tests never share or collide on one
+resource; whether the server keeps that value or assigns its own, the fixture
+reads the actual identifier from the response. The generated files themselves
+stay identical for the same specification - only the runtime data varies.
+
+Endpoints without a recognisable create operation are generated exactly as
+before, with example identifiers.
+
+## Request data
+
+Request bodies and parameters are built deterministically from the
+specification, without random data. For each value, the first available
+source is used: `const`, then `example` (or the first of `examples`), then
+`default`, then the first `enum` member, and finally a placeholder matching
+the declared type and format (for example `user@example.com` for an `email`).
+Placeholder strings are fitted to `minLength` and `maxLength`. Properties
+marked `readOnly` are left out of requests, as OpenAPI prescribes.
+
 ## 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.
+based on test-design techniques - with dependencies between operations
+inferred, so stateful scenarios can share created resources - rendered into
+pytest code via templates, and written to per-resource files.
 
 ## Limitations
 
@@ -207,6 +280,19 @@ written to per-resource files.
   (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
+- Stateful tests cover single-level resources (a collection and its items);
+  nested chains such as `/owners/{ownerId}/pets/{petId}` keep example
+  identifiers, and only `links` passing a top-level response field by
+  `operationId` are used
+- APIs that soft-delete (a deleted resource still answers 200) fail the
+  nonexistent-resource test - a reflection of the API's semantics
+- Resource fixtures use the file's session authentication; a create operation
+  that needs different credentials than the file's default is not overridden
+- Only a top-level field named `id` is treated as a server-side surrogate key;
+  a differently named one is sent with its example value
+- An identifier read from a `Location` header arrives as a string
+- The create operation's own positive test does not remove the resource it
+  creates
 
 ## License
 

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

@@ -17,12 +17,18 @@ established test-design techniques.
     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
+  - **Nonexistent resource** >>> requests a resource that was created and then
+    deleted, so its absence is guaranteed (or, when the API offers no delete,
+    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
+- Stateful tests: operations on an existing resource run against one the test
+  creates itself and removes afterwards, instead of a guessed identifier
+- Valid request data built from the specification's own examples, defaults,
+  enums and constraints
 - Deterministic output: the same specification always produces identical tests
-- Generated files use session-scoped pytest fixtures and run with no manual edits
+- Generated files use 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
@@ -166,12 +172,79 @@ 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.
 
+## Stateful tests
+
+Endpoints that act on an existing resource - `GET`, `PUT`, `PATCH` or
+`DELETE` on `/pets/{petId}` - need a resource that really exists. SwaggerForge
+detects the operation that creates it and generates fixtures that create the
+resource before a test and remove it afterwards.
+
+A create operation is recognised by REST convention: a `POST` on a collection
+path (`/pets`) produces resources addressed by that path plus one parameter
+(`/pets/{petId}`). The new resource's identifier is taken from the response
+field named like the path parameter, or else from `id`. When the
+specification declares explicit OpenAPI `links`, they take priority.
+
+For each such resource, generated files contain two fixtures:
+
+- `created_<resource>` creates the resource, yields its identifier (read from
+  the response body, or from the `Location` header) and deletes it after the
+  test
+- `deleted_<resource>` creates the resource and deletes it immediately, giving
+  the nonexistent-resource test an identifier that is guaranteed not to exist
+
+```python
+@pytest.fixture
+def created_pet(base_url, api_session):
+    response = api_session.post(f"{base_url}/pet", json={'id': uuid.uuid4().int >> 80, 'name': 'doggie', 'photoUrls': ['string']})
+    assert response.status_code in [200], (
+        f"Creating pet failed: "
+        f"{response.status_code} {response.text}"
+    )
+    resource_id = _extract_id(response, 'id')
+    yield resource_id
+    try:
+        api_session.delete(f"{base_url}/pet/{resource_id}")
+    except requests.RequestException:
+        pass
+
+
+def test_get_pet_by_id_success(base_url, api_session, created_pet):
+    """GET /pet/{petId} - positive scenario"""
+    response = api_session.get(f"{base_url}/pet/{created_pet}")
+    assert response.status_code in [200]
+```
+
+*(Abridged from a file generated for the Swagger Petstore specification.)*
+
+Every scenario on such an endpoint uses the created resource - negative
+scenarios included, so a 404 for a missing resource cannot hide the 400 a
+validation test expects. A top-level `id` in the create request is sent as a
+fresh unique value on every run, so tests never share or collide on one
+resource; whether the server keeps that value or assigns its own, the fixture
+reads the actual identifier from the response. The generated files themselves
+stay identical for the same specification - only the runtime data varies.
+
+Endpoints without a recognisable create operation are generated exactly as
+before, with example identifiers.
+
+## Request data
+
+Request bodies and parameters are built deterministically from the
+specification, without random data. For each value, the first available
+source is used: `const`, then `example` (or the first of `examples`), then
+`default`, then the first `enum` member, and finally a placeholder matching
+the declared type and format (for example `user@example.com` for an `email`).
+Placeholder strings are fitted to `minLength` and `maxLength`. Properties
+marked `readOnly` are left out of requests, as OpenAPI prescribes.
+
 ## 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.
+based on test-design techniques - with dependencies between operations
+inferred, so stateful scenarios can share created resources - rendered into
+pytest code via templates, and written to per-resource files.
 
 ## Limitations
 
@@ -181,6 +254,19 @@ written to per-resource files.
   (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
+- Stateful tests cover single-level resources (a collection and its items);
+  nested chains such as `/owners/{ownerId}/pets/{petId}` keep example
+  identifiers, and only `links` passing a top-level response field by
+  `operationId` are used
+- APIs that soft-delete (a deleted resource still answers 200) fail the
+  nonexistent-resource test - a reflection of the API's semantics
+- Resource fixtures use the file's session authentication; a create operation
+  that needs different credentials than the file's default is not overridden
+- Only a top-level field named `id` is treated as a server-side surrogate key;
+  a differently named one is sent with its example value
+- An identifier read from a `Location` header arrives as a string
+- The create operation's own positive test does not remove the resource it
+  creates
 
 ## License
 

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

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

swaggerforge-0.4.0/src/swaggerforge/dependencies.py

@@ -0,0 +1,129 @@
+"""Inference of resource dependencies between OpenAPI operations.
+
+Identifies create operations whose responses yield identifiers consumed by
+operations on the corresponding item path. Explicit OpenAPI links on the
+create's response take priority; otherwise inference follows the REST convention
+that a POST on a collection path creates a resource addressed by the
+collection path plus one path parameter. Only single-level relationships
+are inferred; a POST on a path that already contains a parameter is not
+treated as a producer.
+"""
+
+import re
+
+from swaggerforge.models import ResourceProducer
+
+# matches a path segment consisting of exactly one parameter, e.g. "{petId}"
+_PARAM_SEGMENT = re.compile(r"^\{([^{}/]+)\}$")
+
+# finds every path parameter in a path, e.g. "/items/{itemId}" -> ["itemId"]
+_PATH_PARAMS = re.compile(r"\{([^{}/]+)\}")
+
+
+def find_producers(endpoints):
+    """Infer resource producers from a list of endpoints.
+
+    Args:
+        endpoints: A list of Endpoint objects from the parser.
+
+    Returns:
+        A list of ResourceProducer objects, in specification order.
+    """
+    by_path = {}
+    by_operation = {}
+    for endpoint in endpoints:
+        by_path.setdefault(endpoint.path, {})[endpoint.method] = endpoint
+        if endpoint.operation_id:
+            by_operation[endpoint.operation_id] = endpoint
+
+    producers = []
+    for path, methods in by_path.items():
+        create = methods.get("post")
+        if create is None or "{" in path:
+            continue
+        producer = (
+            _producer_from_links(path, create, by_path, by_operation)
+            or _producer_for(path, create, by_path)
+        )
+        if producer is not None:
+            producers.append(producer)
+    return producers
+
+
+def _producer_from_links(collection_path, create, by_path, by_operation):
+    """Build a producer from the create's explicit OpenAPI links, or None.
+
+    A link is usable when its target operation exists and its path has
+    exactly one path parameter, which the link supplies from the response
+    body. Explicit links are the specification's own statement of the
+    relationship, so they take priority over path inference.
+    """
+    for target_id, parameters in create.links.items():
+        target = by_operation.get(target_id)
+        if target is None:
+            continue
+        params = _PATH_PARAMS.findall(target.path)
+        if len(params) != 1 or params[0] not in parameters:
+            continue
+        param = params[0]
+        return ResourceProducer(
+            resource=_resource_name(collection_path),
+            create=create,
+            item_path=target.path,
+            path_param=param,
+            id_field=parameters[param],
+            delete=by_path.get(target.path, {}).get("delete"),
+        )
+    return None
+
+
+def _producer_for(collection_path, create, by_path):
+    """Build the producer for a collection POST, or None if none applies."""
+    for path, methods in by_path.items():
+        param = _single_param_child(collection_path, path)
+        if param is None:
+            continue
+        id_field = _id_field(create.response_schema, param)
+        if id_field is None:
+            continue
+        return ResourceProducer(
+            resource=_resource_name(collection_path),
+            create=create,
+            item_path=path,
+            path_param=param,
+            id_field=id_field,
+            delete=methods.get("delete"),
+        )
+    return None
+
+
+def _single_param_child(parent, path):
+    """Return the parameter name if path is parent plus one parameter."""
+    prefix = parent.rstrip("/") + "/"
+    if not path.startswith(prefix):
+        return None
+    match = _PARAM_SEGMENT.match(path[len(prefix):])
+    return match.group(1) if match else None
+
+
+def _id_field(response_schema, param):
+    """Pick the response field holding the identifier.
+
+    A field named exactly like the path parameter wins; otherwise a field
+    named 'id' is used. Returns None when neither exists.
+    """
+    if not isinstance(response_schema, dict):
+        return None
+    properties = response_schema.get("properties", {})
+    if param in properties:
+        return param
+    if "id" in properties:
+        return "id"
+    return None
+
+
+def _resource_name(collection_path):
+    """Derive a fixture-safe resource name from the last path segment."""
+    segment = collection_path.rstrip("/").rsplit("/", 1)[-1]
+    name = re.sub(r"[^a-zA-Z0-9_]", "_", segment).lower()
+    return name or "resource"