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

OpenApiLibCore/parameter_utils.py

@@ -0,0 +1,91 @@
+"""
+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.annotations import JSON
+
+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, dict[str, JSON]]) -> None:
+    for operations_data in paths_data.values():
+        for method_data in operations_data.values():
+            parameters_data: list[dict[str, str]] = method_data.get("parameters", [])
+            path_parameter_names = [
+                p["name"] for p in parameters_data if p["in"] == "path"
+            ]
+            for name in path_parameter_names:
+                _ = get_safe_name_for_oas_name(name)

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.dto_base import PathPropertiesConstraint
+from OpenApiLibCore.protocols import GetDtoClassType, GetIdPropertyNameType
+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: dict[str, Any]) -> 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] = {**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_dto_class: GetDtoClassType,
+    openapi_spec: dict[str, Any],
+) -> 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_dto_class(path=path, method="get")
+    relations = dto_class.get_relations()
+    paths = [p.path for p in relations if isinstance(p, PathPropertiesConstraint)]
+    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,44 @@
+"""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.dto_base import PathPropertiesConstraint
+from OpenApiLibCore.protocols import GetDtoClassType
+
+run_keyword = BuiltIn().run_keyword
+
+
+def get_invalidated_url(
+    valid_url: str,
+    path: str,
+    base_url: str,
+    get_dto_class: GetDtoClassType,
+    expected_status_code: int,
+) -> str:
+    dto_class = get_dto_class(path=path, method="get")
+    relations = dto_class.get_relations()
+    paths = [
+        p.invalid_value
+        for p in relations
+        if isinstance(p, PathPropertiesConstraint)
+        and 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,30 @@
+"""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: ...
+
+
+class GetDtoClassType(Protocol):
+    def __init__(self, mappings_module_name: str) -> None: ...
+
+    def __call__(self, path: str, method: str) -> Type[Dto]: ...
+
+
+class GetIdPropertyNameType(Protocol):
+    def __init__(self, mappings_module_name: str) -> None: ...
+
+    def __call__(
+        self, path: str
+    ) -> tuple[str, Callable[[str], str] | Callable[[int], int]]: ...

OpenApiLibCore/request_data.py

@@ -0,0 +1,281 @@
+"""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.dto_base import (
+    Dto,
+    resolve_schema,
+)
+from OpenApiLibCore.dto_utils import DefaultDto
+
+
+@dataclass
+class RequestValues:
+    """Helper class to hold parameter values needed to make a request."""
+
+    url: str
+    method: str
+    params: dict[str, Any] = field(default_factory=dict)
+    headers: dict[str, str] = field(default_factory=dict)
+    json_data: dict[str, Any] = field(default_factory=dict)
+
+    def override_body_value(self, name: str, value: Any) -> None:
+        if name in self.json_data:
+            self.json_data[name] = value
+
+    def override_header_value(self, name: str, value: Any) -> None:
+        if name in self.headers:
+            self.headers[name] = value
+
+    def override_param_value(self, name: str, value: str) -> None:
+        if name in self.params:
+            self.params[name] = str(value)
+
+    def override_request_value(self, name: str, value: Any) -> 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)
+    dto_schema: dict[str, Any] = field(default_factory=dict)
+    parameters: list[dict[str, Any]] = field(default_factory=list)
+    params: dict[str, Any] = field(default_factory=dict)
+    headers: dict[str, Any] = field(default_factory=dict)
+    has_body: bool = True
+
+    def __post_init__(self) -> None:
+        # prevent modification by reference
+        self.dto_schema = deepcopy(self.dto_schema)
+        self.parameters = deepcopy(self.parameters)
+        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.dto_schema.get("required", [])
+
+        properties = (self.dto.as_dict()).keys()
+        return not all(map(is_required_property, properties))
+
+    @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.get("name")
+                for p in self.parameters
+                if p.get("in") == "query" and not p.get("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.get("in") == "query"]
+        for param in params:
+            # required params can be omitted to invalidate a request
+            if param["required"]:
+                result.add(param["name"])
+                continue
+
+            schema = resolve_schema(param["schema"])
+            if schema.get("type", None):
+                param_types = [schema]
+            else:
+                param_types = schema["types"]
+            for param_type in param_types:
+                # any basic non-string type except "null" can be invalidated by
+                # replacing it with a string
+                if param_type["type"] not in ["string", "array", "object", "null"]:
+                    result.add(param["name"])
+                    continue
+                # enums, strings and arrays with boundaries can be invalidated
+                if set(param_type.keys()).intersection(
+                    {
+                        "enum",
+                        "minLength",
+                        "maxLength",
+                        "minItems",
+                        "maxItems",
+                    }
+                ):
+                    result.add(param["name"])
+                    continue
+                # an array of basic non-string type can be invalidated by replacing the
+                # items in the array with strings
+                if param_type["type"] == "array" and param_type["items"][
+                    "type"
+                ] not in [
+                    "string",
+                    "array",
+                    "object",
+                    "null",
+                ]:
+                    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.get("name")
+                for p in self.parameters
+                if p.get("in") == "header" and not p.get("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.get("in") == "header"]
+        for header in headers:
+            # required headers can be omitted to invalidate a request
+            if header["required"]:
+                result.add(header["name"])
+                continue
+
+            schema = resolve_schema(header["schema"])
+            if schema.get("type", None):
+                header_types = [schema]
+            else:
+                header_types = schema["types"]
+            for header_type in header_types:
+                # any basic non-string type except "null" can be invalidated by
+                # replacing it with a string
+                if header_type["type"] not in ["string", "array", "object", "null"]:
+                    result.add(header["name"])
+                    continue
+                # enums, strings and arrays with boundaries can be invalidated
+                if set(header_type.keys()).intersection(
+                    {
+                        "enum",
+                        "minLength",
+                        "maxLength",
+                        "minItems",
+                        "maxItems",
+                    }
+                ):
+                    result.add(header["name"])
+                    continue
+                # an array of basic non-string type can be invalidated by replacing the
+                # items in the array with strings
+                if header_type["type"] == "array" and header_type["items"][
+                    "type"
+                ] not in [
+                    "string",
+                    "array",
+                    "object",
+                    "null",
+                ]:
+                    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: list[str] = self.dto_schema.get("required", [])
+        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 = self.dto_schema.get("minProperties", 0)
+        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, str]:
+        """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, str]:
+        """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.get("required")]
+        required_parameters.extend(mandatory_parameters)
+        return required_parameters