robotframework-openapitools 0.4.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

OpenApiLibCore/parameter_utils.py

@@ -0,0 +1,97 @@
+"""
+Module holding the functions to support mapping between Python-safe parameter
+names and the original names in the parsed OpenApi Specification document.
+"""
+
+from typing import Generator
+
+from OpenApiLibCore.models import ParameterObject, PathItemObject
+
+PARAMETER_REGISTRY: dict[str, str] = {
+    "body": "body",
+}
+
+
+def get_oas_name_from_safe_name(safe_name: str) -> str:
+    oas_name = PARAMETER_REGISTRY.get(safe_name)
+    if not oas_name:
+        raise ValueError(f"No entry for '{safe_name}' registered {PARAMETER_REGISTRY}.")
+    return oas_name
+
+
+def get_safe_name_for_oas_name(oas_name: str) -> str:
+    if _is_python_safe(oas_name):
+        PARAMETER_REGISTRY[oas_name] = oas_name
+        return oas_name
+
+    safe_name = convert_string_to_python_identifier(oas_name)
+
+    if safe_name not in PARAMETER_REGISTRY:
+        PARAMETER_REGISTRY[safe_name] = oas_name
+        return safe_name
+
+    registered_oas_name = PARAMETER_REGISTRY[safe_name]
+    if registered_oas_name == oas_name:
+        return safe_name
+    # We're dealing with multiple oas_names that convert to the same safe_name.
+    # To resolve this, a more verbose safe_name is generated. This is less user-friendly
+    # but necessary to ensure an one-to-one mapping.
+    verbose_safe_name = convert_string_to_python_identifier(oas_name, verbose=True)
+    if verbose_safe_name not in PARAMETER_REGISTRY:
+        PARAMETER_REGISTRY[verbose_safe_name] = oas_name
+    return verbose_safe_name
+
+
+def _is_python_safe(name: str) -> bool:
+    return name.isidentifier()
+
+
+def convert_string_to_python_identifier(string: str, verbose: bool = False) -> str:
+    def _convert_string_to_python_identifier() -> Generator[str, None, None]:
+        string_iterator = iter(string)
+
+        # The first character must be A-z or _
+        first_character = next(string_iterator, "_")
+        if first_character.isalpha() or first_character == "_":
+            yield first_character
+        elif first_character.isnumeric():
+            yield "_" + first_character
+        elif not verbose:
+            yield "_"
+        else:
+            ascii_code = ord(first_character)
+            yield f"_{ascii_code}_"
+        # Further characters must be A-z, 0-9 or _
+        for character in string_iterator:
+            if character.isalnum() or character == "_":
+                yield character
+            elif not verbose:
+                yield "_"
+            else:
+                ascii_code = ord(character)
+                yield f"_{ascii_code}_"
+
+    if _is_python_safe(string):
+        return string
+
+    converted_string = "".join(_convert_string_to_python_identifier())
+    if not _is_python_safe(converted_string):
+        raise ValueError(f"Failed to convert '{string}' to Python identifier.")
+    return converted_string
+
+
+def register_path_parameters(paths_data: dict[str, PathItemObject]) -> None:
+    def _register_path_parameter(parameter_object: ParameterObject) -> None:
+        if parameter_object.in_ == "path":
+            _ = get_safe_name_for_oas_name(parameter_object.name)
+
+    for path_item in paths_data.values():
+        if parameters := path_item.parameters:
+            for parameter in path_item.parameters:
+                _register_path_parameter(parameter_object=parameter)
+
+        operations = path_item.get_operations()
+        for operation in operations.values():
+            if parameters := operation.parameters:
+                for parameter in parameters:
+                    _register_path_parameter(parameter_object=parameter)

OpenApiLibCore/path_functions.py

@@ -0,0 +1,215 @@
+"""Module holding the functions related to paths and urls."""
+
+import json as _json
+from itertools import zip_longest
+from random import choice
+from typing import Any
+
+from requests import Response
+from robot.libraries.BuiltIn import BuiltIn
+
+from OpenApiLibCore.models import OpenApiObject
+from OpenApiLibCore.protocols import GetIdPropertyNameType, GetPathDtoClassType
+from OpenApiLibCore.request_data import RequestData
+
+run_keyword = BuiltIn().run_keyword
+
+
+def match_parts(parts: list[str], spec_parts: list[str]) -> bool:
+    for part, spec_part in zip_longest(parts, spec_parts, fillvalue="Filler"):
+        if part == "Filler" or spec_part == "Filler":
+            return False
+        if part != spec_part and not spec_part.startswith("{"):
+            return False
+    return True
+
+
+def get_parametrized_path(path: str, openapi_spec: OpenApiObject) -> str:
+    path_parts = path.split("/")
+    # if the last part is empty, the path has a trailing `/` that
+    # should be ignored during matching
+    if path_parts[-1] == "":
+        _ = path_parts.pop(-1)
+
+    spec_paths: list[str] = list(openapi_spec.paths.keys())
+
+    candidates: list[str] = []
+
+    for spec_path in spec_paths:
+        spec_path_parts = spec_path.split("/")
+        # ignore trailing `/` the same way as for path_parts
+        if spec_path_parts[-1] == "":
+            _ = spec_path_parts.pop(-1)
+        if match_parts(path_parts, spec_path_parts):
+            candidates.append(spec_path)
+
+    if not candidates:
+        raise ValueError(f"{path} not found in paths section of the OpenAPI document.")
+
+    if len(candidates) == 1:
+        return candidates[0]
+    # Multiple matches can happen in APIs with overloaded paths, e.g.
+    # /users/me
+    # /users/${user_id}
+    # In this case, find the closest (or exact) match
+    exact_match = [c for c in candidates if c == path]
+    if exact_match:
+        return exact_match[0]
+    # TODO: Implement a decision mechanism when real-world examples become available
+    # In the face of ambiguity, refuse the temptation to guess.
+    raise ValueError(f"{path} matched to multiple paths: {candidates}")
+
+
+def get_valid_url(
+    path: str,
+    base_url: str,
+    get_path_dto_class: GetPathDtoClassType,
+    openapi_spec: OpenApiObject,
+) -> str:
+    try:
+        # path can be partially resolved or provided by a PathPropertiesConstraint
+        parametrized_path = get_parametrized_path(path=path, openapi_spec=openapi_spec)
+        _ = openapi_spec.paths[parametrized_path]
+    except KeyError:
+        raise ValueError(
+            f"{path} not found in paths section of the OpenAPI document."
+        ) from None
+    dto_class = get_path_dto_class(path=path)
+    relations = dto_class.get_path_relations()
+    paths = [p.path for p in relations]
+    if paths:
+        url = f"{base_url}{choice(paths)}"
+        return url
+    path_parts = list(path.split("/"))
+    for index, part in enumerate(path_parts):
+        if part.startswith("{") and part.endswith("}"):
+            type_path_parts = path_parts[slice(index)]
+            type_path = "/".join(type_path_parts)
+            existing_id: str | int | float = run_keyword(
+                "get_valid_id_for_path", type_path
+            )
+            path_parts[index] = str(existing_id)
+    resolved_path = "/".join(path_parts)
+    url = f"{base_url}{resolved_path}"
+    return url
+
+
+def get_valid_id_for_path(
+    path: str,
+    get_id_property_name: GetIdPropertyNameType,
+) -> str | int:
+    url: str = run_keyword("get_valid_url", path)
+    # Try to create a new resource to prevent conflicts caused by
+    # operations performed on the same resource by other test cases
+    request_data: RequestData = run_keyword("get_request_data", path, "post")
+
+    response: Response = run_keyword(
+        "authorized_request",
+        url,
+        "post",
+        request_data.get_required_params(),
+        request_data.get_required_headers(),
+        request_data.get_required_properties_dict(),
+    )
+
+    id_property, id_transformer = get_id_property_name(path=path)
+
+    if not response.ok:
+        # If a new resource cannot be created using POST, try to retrieve a
+        # valid id using a GET request.
+        try:
+            valid_id = choice(run_keyword("get_ids_from_url", url))
+            return id_transformer(valid_id)
+        except Exception as exception:
+            raise AssertionError(
+                f"Failed to get a valid id using GET on {url}"
+            ) from exception
+
+    response_data = response.json()
+    if prepared_body := response.request.body:
+        if isinstance(prepared_body, bytes):
+            send_json = _json.loads(prepared_body.decode("UTF-8"))
+        else:
+            send_json = _json.loads(prepared_body)
+    else:
+        send_json = None
+
+    # no support for retrieving an id from an array returned on a POST request
+    if isinstance(response_data, list):
+        raise NotImplementedError(
+            f"Unexpected response body for POST request: expected an object but "
+            f"received an array ({response_data})"
+        )
+
+    # POST on /resource_type/{id}/array_item/ will return the updated {id} resource
+    # instead of a newly created resource. In this case, the send_json must be
+    # in the array of the 'array_item' property on {id}
+    send_path: str = response.request.path_url
+    response_href: str = response_data.get("href", "")
+    if response_href and (send_path not in response_href) and send_json:
+        try:
+            property_to_check = send_path.replace(response_href, "")[1:]
+            item_list: list[dict[str, Any]] = response_data[property_to_check]
+            # Use the (mandatory) id to get the POSTed resource from the list
+            [valid_id] = [
+                item[id_property]
+                for item in item_list
+                if item[id_property] == send_json[id_property]
+            ]
+        except Exception as exception:
+            raise AssertionError(
+                f"Failed to get a valid id from {response_href}"
+            ) from exception
+    else:
+        try:
+            valid_id = response_data[id_property]
+        except KeyError:
+            raise AssertionError(
+                f"Failed to get a valid id from {response_data}"
+            ) from None
+    return id_transformer(valid_id)
+
+
+def get_ids_from_url(
+    url: str,
+    get_id_property_name: GetIdPropertyNameType,
+) -> list[str]:
+    path: str = run_keyword("get_parameterized_path_from_url", url)
+    request_data: RequestData = run_keyword("get_request_data", path, "get")
+    response = run_keyword(
+        "authorized_request",
+        url,
+        "get",
+        request_data.get_required_params(),
+        request_data.get_required_headers(),
+    )
+    response.raise_for_status()
+    response_data: dict[str, Any] | list[dict[str, Any]] = response.json()
+
+    # determine the property name to use
+    mapping = get_id_property_name(path=path)
+    if isinstance(mapping, str):
+        id_property = mapping
+    else:
+        id_property, _ = mapping
+
+    if isinstance(response_data, list):
+        valid_ids: list[str] = [item[id_property] for item in response_data]
+        return valid_ids
+    # if the response is an object (dict), check if it's hal+json
+    if embedded := response_data.get("_embedded"):
+        # there should be 1 item in the dict that has a value that's a list
+        for value in embedded.values():
+            if isinstance(value, list):
+                valid_ids = [item[id_property] for item in value]
+                return valid_ids
+    if (valid_id := response_data.get(id_property)) is not None:
+        return [valid_id]
+    valid_ids = [item[id_property] for item in response_data["items"]]
+    return valid_ids
+
+
+def substitute_path_parameters(path: str, substitution_dict: dict[str, str]) -> str:
+    for path_parameter, substitution_value in substitution_dict.items():
+        path = path.replace("{" + path_parameter + "}", str(substitution_value))
+    return path

OpenApiLibCore/path_invalidation.py

@@ -0,0 +1,42 @@
+"""Module holding functions related to invalidation of paths and urls."""
+
+from random import choice
+from uuid import uuid4
+
+from robot.libraries.BuiltIn import BuiltIn
+
+from OpenApiLibCore.protocols import GetPathDtoClassType
+
+run_keyword = BuiltIn().run_keyword
+
+
+def get_invalidated_url(
+    valid_url: str,
+    path: str,
+    base_url: str,
+    get_path_dto_class: GetPathDtoClassType,
+    expected_status_code: int,
+) -> str:
+    dto_class = get_path_dto_class(path=path)
+    relations = dto_class.get_path_relations()
+    paths = [
+        p.invalid_value
+        for p in relations
+        if p.invalid_value_error_code == expected_status_code
+    ]
+    if paths:
+        url = f"{base_url}{choice(paths)}"
+        return url
+    parameterized_path: str = run_keyword("get_parameterized_path_from_url", valid_url)
+    parameterized_url = base_url + parameterized_path
+    valid_url_parts = list(reversed(valid_url.split("/")))
+    parameterized_parts = reversed(parameterized_url.split("/"))
+    for index, (parameterized_part, _) in enumerate(
+        zip(parameterized_parts, valid_url_parts)
+    ):
+        if parameterized_part.startswith("{") and parameterized_part.endswith("}"):
+            valid_url_parts[index] = uuid4().hex
+            valid_url_parts.reverse()
+            invalid_url = "/".join(valid_url_parts)
+            return invalid_url
+    raise ValueError(f"{parameterized_path} could not be invalidated.")

OpenApiLibCore/protocols.py

@@ -0,0 +1,38 @@
+"""A module holding Protcols."""
+
+from typing import Callable, Protocol, Type
+
+from openapi_core.contrib.requests import (
+    RequestsOpenAPIRequest,
+    RequestsOpenAPIResponse,
+)
+
+from OpenApiLibCore.dto_base import Dto
+
+
+class ResponseValidatorType(Protocol):
+    def __call__(
+        self, request: RequestsOpenAPIRequest, response: RequestsOpenAPIResponse
+    ) -> None: ...  # pragma: no cover
+
+
+class GetDtoClassType(Protocol):
+    def __init__(self, mappings_module_name: str) -> None: ...  # pragma: no cover
+
+    def __call__(self, path: str, method: str) -> Type[Dto]: ...  # pragma: no cover
+
+
+class GetIdPropertyNameType(Protocol):
+    def __init__(self, mappings_module_name: str) -> None: ...  # pragma: no cover
+
+    def __call__(
+        self, path: str
+    ) -> tuple[
+        str, Callable[[str], str] | Callable[[int], int]
+    ]: ...  # pragma: no cover
+
+
+class GetPathDtoClassType(Protocol):
+    def __init__(self, mappings_module_name: str) -> None: ...  # pragma: no cover
+
+    def __call__(self, path: str) -> Type[Dto]: ...  # pragma: no cover

OpenApiLibCore/request_data.py

@@ -0,0 +1,246 @@
+"""Module holding the classes used to manage request data."""
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+from functools import cached_property
+from random import sample
+from typing import Any
+
+from OpenApiLibCore.annotations import JSON
+from OpenApiLibCore.dto_base import Dto
+from OpenApiLibCore.dto_utils import DefaultDto
+from OpenApiLibCore.models import (
+    ObjectSchema,
+    ParameterObject,
+    ResolvedSchemaObjectTypes,
+    UnionTypeSchema,
+)
+
+
+@dataclass
+class RequestValues:
+    """Helper class to hold parameter values needed to make a request."""
+
+    url: str
+    method: str
+    params: dict[str, JSON] = field(default_factory=dict)
+    headers: dict[str, JSON] = field(default_factory=dict)
+    json_data: dict[str, JSON] = field(default_factory=dict)
+
+    def override_body_value(self, name: str, value: JSON) -> None:
+        if name in self.json_data:
+            self.json_data[name] = value
+
+    def override_header_value(self, name: str, value: JSON) -> None:
+        if name in self.headers:
+            self.headers[name] = value
+
+    def override_param_value(self, name: str, value: JSON) -> None:
+        if name in self.params:
+            self.params[name] = str(value)
+
+    def override_request_value(self, name: str, value: JSON) -> None:
+        self.override_body_value(name=name, value=value)
+        self.override_header_value(name=name, value=value)
+        self.override_param_value(name=name, value=value)
+
+    def remove_parameters(self, parameters: list[str]) -> None:
+        for parameter in parameters:
+            _ = self.params.pop(parameter, None)
+            _ = self.headers.pop(parameter, None)
+            _ = self.json_data.pop(parameter, None)
+
+
+@dataclass
+class RequestData:
+    """Helper class to manage parameters used when making requests."""
+
+    dto: Dto | DefaultDto = field(default_factory=DefaultDto)
+    body_schema: ObjectSchema | None = None
+    parameters: list[ParameterObject] = field(default_factory=list)
+    params: dict[str, JSON] = field(default_factory=dict)
+    headers: dict[str, JSON] = field(default_factory=dict)
+    has_body: bool = True
+
+    def __post_init__(self) -> None:
+        # prevent modification by reference
+        self.params = deepcopy(self.params)
+        self.headers = deepcopy(self.headers)
+
+    @property
+    def has_optional_properties(self) -> bool:
+        """Whether or not the dto data (json data) contains optional properties."""
+
+        def is_required_property(property_name: str) -> bool:
+            return property_name in self.required_property_names
+
+        properties = (self.dto.as_dict()).keys()
+        return not all(map(is_required_property, properties))
+
+    @property
+    def required_property_names(self) -> list[str]:
+        if self.body_schema:
+            return self.body_schema.required
+        return []
+
+    @property
+    def has_optional_params(self) -> bool:
+        """Whether or not any of the query parameters are optional."""
+
+        def is_optional_param(query_param: str) -> bool:
+            optional_params = [
+                p.name for p in self.parameters if p.in_ == "query" and not p.required
+            ]
+            return query_param in optional_params
+
+        return any(map(is_optional_param, self.params))
+
+    @cached_property
+    def params_that_can_be_invalidated(self) -> set[str]:
+        """
+        The query parameters that can be invalidated by violating data
+        restrictions, data type or by not providing them in a request.
+        """
+        result = set()
+        params = [h for h in self.parameters if h.in_ == "query"]
+        for param in params:
+            # required params can be omitted to invalidate a request
+            if param.required:
+                result.add(param.name)
+                continue
+
+            if param.schema_ is None:
+                continue
+
+            possible_schemas: list[ResolvedSchemaObjectTypes] = []
+            if isinstance(param.schema_, UnionTypeSchema):
+                possible_schemas = param.schema_.resolved_schemas
+            else:
+                possible_schemas = [param.schema_]
+
+            for param_schema in possible_schemas:
+                if param_schema.can_be_invalidated:
+                    result.add(param.name)
+
+        return result
+
+    @property
+    def has_optional_headers(self) -> bool:
+        """Whether or not any of the headers are optional."""
+
+        def is_optional_header(header: str) -> bool:
+            optional_headers = [
+                p.name for p in self.parameters if p.in_ == "header" and not p.required
+            ]
+            return header in optional_headers
+
+        return any(map(is_optional_header, self.headers))
+
+    @cached_property
+    def headers_that_can_be_invalidated(self) -> set[str]:
+        """
+        The header parameters that can be invalidated by violating data
+        restrictions or by not providing them in a request.
+        """
+        result = set()
+        headers = [h for h in self.parameters if h.in_ == "header"]
+        for header in headers:
+            # required headers can be omitted to invalidate a request
+            if header.required:
+                result.add(header.name)
+                continue
+
+            if header.schema_ is None:
+                continue
+
+            possible_schemas: list[ResolvedSchemaObjectTypes] = []
+            if isinstance(header.schema_, UnionTypeSchema):
+                possible_schemas = header.schema_.resolved_schemas
+            else:
+                possible_schemas = [header.schema_]
+
+            for param_schema in possible_schemas:
+                if param_schema.can_be_invalidated:
+                    result.add(header.name)
+
+        return result
+
+    def get_required_properties_dict(self) -> dict[str, Any]:
+        """Get the json-compatible dto data containing only the required properties."""
+        relations = self.dto.get_relations()
+        mandatory_properties = [
+            relation.property_name
+            for relation in relations
+            if getattr(relation, "treat_as_mandatory", False)
+        ]
+        required_properties = self.body_schema.required if self.body_schema else []
+        required_properties.extend(mandatory_properties)
+
+        required_properties_dict: dict[str, Any] = {}
+        for key, value in (self.dto.as_dict()).items():
+            if key in required_properties:
+                required_properties_dict[key] = value
+        return required_properties_dict
+
+    def get_minimal_body_dict(self) -> dict[str, Any]:
+        required_properties_dict = self.get_required_properties_dict()
+
+        min_properties = 0
+        if self.body_schema and self.body_schema.minProperties is not None:
+            min_properties = self.body_schema.minProperties
+
+        number_of_optional_properties_to_add = min_properties - len(
+            required_properties_dict
+        )
+
+        if number_of_optional_properties_to_add < 1:
+            return required_properties_dict
+
+        optional_properties_dict = {
+            k: v
+            for k, v in self.dto.as_dict().items()
+            if k not in required_properties_dict
+        }
+        optional_properties_to_keep = sample(
+            sorted(optional_properties_dict), number_of_optional_properties_to_add
+        )
+        optional_properties_dict = {
+            k: v
+            for k, v in optional_properties_dict.items()
+            if k in optional_properties_to_keep
+        }
+
+        return {**required_properties_dict, **optional_properties_dict}
+
+    def get_required_params(self) -> dict[str, JSON]:
+        """Get the params dict containing only the required query parameters."""
+        return {
+            k: v for k, v in self.params.items() if k in self.required_parameter_names
+        }
+
+    def get_required_headers(self) -> dict[str, JSON]:
+        """Get the headers dict containing only the required headers."""
+        return {
+            k: v for k, v in self.headers.items() if k in self.required_parameter_names
+        }
+
+    @property
+    def required_parameter_names(self) -> list[str]:
+        """
+        The names of the mandatory parameters, including the parameters configured to be
+        treated as mandatory using a PropertyValueConstraint.
+        """
+        relations = self.dto.get_parameter_relations()
+        mandatory_property_names = [
+            relation.property_name
+            for relation in relations
+            if getattr(relation, "treat_as_mandatory", False)
+        ]
+        parameter_names = [p.name for p in self.parameters]
+        mandatory_parameters = [
+            p for p in mandatory_property_names if p in parameter_names
+        ]
+
+        required_parameters = [p.name for p in self.parameters if p.required]
+        required_parameters.extend(mandatory_parameters)
+        return required_parameters

OpenApiLibCore/resource_relations.py

@@ -0,0 +1,55 @@
+"""Module holding the functions related to relations between resources."""
+
+from requests import Response
+from robot.api import logger
+from robot.libraries.BuiltIn import BuiltIn
+
+import OpenApiLibCore.path_functions as _path_functions
+from OpenApiLibCore.dto_base import IdReference
+from OpenApiLibCore.models import OpenApiObject
+from OpenApiLibCore.request_data import RequestData
+
+run_keyword = BuiltIn().run_keyword
+
+
+def ensure_in_use(
+    url: str,
+    base_url: str,
+    openapi_spec: OpenApiObject,
+    resource_relation: IdReference,
+) -> None:
+    resource_id = ""
+
+    path = url.replace(base_url, "")
+    path_parts = path.split("/")
+    parameterized_path = _path_functions.get_parametrized_path(
+        path=path, openapi_spec=openapi_spec
+    )
+    parameterized_path_parts = parameterized_path.split("/")
+    for part, param_part in zip(
+        reversed(path_parts), reversed(parameterized_path_parts)
+    ):
+        if param_part.endswith("}"):
+            resource_id = part
+            break
+    if not resource_id:
+        raise ValueError(f"The provided url ({url}) does not contain an id.")
+    request_data: RequestData = run_keyword(
+        "get_request_data", resource_relation.post_path, "post"
+    )
+    json_data = request_data.dto.as_dict()
+    json_data[resource_relation.property_name] = resource_id
+    post_url: str = run_keyword("get_valid_url", resource_relation.post_path)
+    response: Response = run_keyword(
+        "authorized_request",
+        post_url,
+        "post",
+        request_data.params,
+        request_data.headers,
+        json_data,
+    )
+    if not response.ok:
+        logger.debug(
+            f"POST on {post_url} with json {json_data} failed: {response.json()}"
+        )
+        response.raise_for_status()