rbtools.testing.api.transport¶

API transports for unit tests.

New in version 3.1.

Classes

URLMapTransport(url[, username, password, ...])

API transport for defining and querying URL maps of responses.

class rbtools.testing.api.transport.URLMapTransport(url, username=None, password=None, cache_location=None, in_memory_cache=False, **kwargs)[source]¶

Bases: Transport

API transport for defining and querying URL maps of responses.

This transport allows unit tests to define the URLs they want to test against, mapping URLS and HTTP methods to groups of payloads and headers, and HTTP status codes.

By default, this provides a handful of pre-built URLs:

/api/
/api/info/
/api/repositories/
/api/review-requests/

Unit tests can define any additional resources they need through the following functions:

add_item_url()
add_list_url()

Any defined URLs can be modified by changing entries anywhere in the urls dictionary. These changes will not persist to other unit tests.

API capabilities can also be changed be modifying capabilities.

If unit tests need URLs that are not already defined on this transport, it may be worth contributing helper functions to this class, in order to ensure consistency (see the implementation of add_repository_url() for details).

New in version 3.1.

api_calls¶

A list of API calls that have been made. Each is a dictionary containing:

Keys:

method (unicode) – The HTTP method.
path (unicode) – The API path, relative to the root of the server.

Type:

list of dict

cache_location¶

The cache location configured when constructing the transport or when calling enable_cache().

Type:: unicode

cache_in_memory¶

The cache-in-memory flag configured when constructing the transport or when calling enable_cache().

Type:: bool

capabilities¶

The dictionary of capabilities to simulate being returned from the API. This can be modified as needed by unit tests.

Type:: dict

list_item_payloads¶

A mapping of relative list URLs to lists of item payloads that should be returned when accessing that list resource.

Note that list resources must be registered through add_list_url().

Type:: dict

logged_in¶

Whether the user is logged in.

This will be set to True if a username and password are provided during construction, or if login() is called.

Type:: bool

login_credentials¶

A dictionary of login credentials.

This will be set to a dictionary with username and password keys if a username and password are provided during construction, or if login() is called. Otherwise it will be None.

Type:: dict

payload_factory¶

The payload factory used to construct resource object and response payloads. This can be used when calling add_item_url() or add_list_url().

Type:: rbtools.testing.api.payloads.PayloadFactory

transport_kwargs¶

Additional keyword arguments passed during construction.

Type:: dict

urls¶

The mapping of URLs to response information. This is in the following form:

urls = {
    '/api/.../[?...]': {
        '<HTTP method>': {
            'headers': {
                'Content-Type': '...',
                ...,
            },
            'http_status': ...,
            'payload': {
                'stat': '...',
                ...,
            },
        },
        ...
    },
    ...
}

Anything in this tree can be freely modified by unit tests. Changes will not persist across tests.

Type:: dict

__init__(url, username=None, password=None, cache_location=None, in_memory_cache=False, **kwargs)[source]¶

Initialize the transport.

Parameters:

url (unicode) – The URL to the root of the server. This must end with /.
username (unicode, optional) – An optional username to simulate logging in with. If set, password is required.
password (unicode, optional) – An optional password to simulate logging in with. This is ignored if username is not set.
cache_location (unicode, optional) – An optional cache location to set. This only affects cache_location and will otherwise be ignored.
in_memory_cache (bool, optional) – Whether to use an in-memory cache. This only affects cache_in_memory and will otherwise be ignored.
**kwargs (dict) – Additional keyword arguments passed to the transport. These will be stored in transport_kwargs.

add_url(url, mimetype, method='GET', http_status=200, headers={}, payload={}, link_expansion_types={}, extra_node_state={})[source]¶

Add a URL mapping to a payload.

Parameters:

url (unicode) – The URL for the resource. This can include or omit a query string, as needed (exact query strings have higher precedence than not having a query string).
mimetype (unicode) – The mimetype for the response.
method (unicode, optional) – The HTTP method that the payload will map to.
http_status (int, optional, optional) – The HTTP status code of the response.
headers (dict, optional, optional) – Any custom headers to provide in the response.
payload (dict or bytes, optional) – The payload data. This can be a dictionary of deserialized API results, or it can be a byte string of content.
link_expansion_types (dict, optional) – A mapping of links to rbtools.testing.api.payloads. LinkExpansionType values to help determine how to expand links.
extra_node_state (dict, optional) – Extra state to store along with the registered URL node.

Responses:

dict: The results of the add operation, for further tracking or processing.

Keys:

method (unicode):: The registered HTTP method.
url (unicode):: The normalized registered URL used to store the mapping.
node (dict):: The registered dictionary that the URL and method maps to, for modification.

add_item_url(url, payload, item_key=None, in_list_urls=[], link_expansion_types={}, **kwargs)[source]¶

Add a URL for an item or singleton resource.

Parameters:

url (unicode) – The URL for the resource. This can include or omit a query string, as needed (exact query strings have higher precedence than not having a query string).
payload (dict) – The object payload to provide in the response payload.
item_key (unicode, optional) – The item key used to map to the object’s payload in the response payload. If None, the object payload will be merged into the response payload.
in_list_urls (list of unicode) – Any URLs for list resources that should contain this item in list responses.
link_expansion_types (dict, optional) – A mapping of links to rbtools.testing.api.payloads. LinkExpansionType values to help determine how to expand links.
**kwargs (dict) – Additional keyword arguments for the registration. See add_url() for details.

Responses:: dict: The results of the add operation, for further tracking or processing. See the return type for add_url() for details.

add_list_url(url, list_key, item_mimetype, headers={}, **kwargs)[source]¶

Add a URL for a list resource.

The payload will be computed dynamically as needed, listing items registered in list_item_payloads.

Parameters:

url (unicode) – The URL for the resource. This can include or omit a query string, as needed (exact query strings have higher precedence than not having a query string).
list_key (unicode) – The key used to map to the list of item payloads in the response payload.
item_mimetype (unicode) – The mimetype for items in the list.
headers (dict, optional) – Any custom headers to provide in the response.
**kwargs (dict) – Additional keyword arguments for the registration. See add_url() for details.

Responses:: dict: The results of the add operation, for further tracking or processing. See the return type for add_url() for details.

add_error_url(url, error_code, error_message, payload_extra=None, http_status=400, **kwargs)[source]¶

Add a URL for an error response.

Parameters:

url (unicode) – The URL that triggers the error. This can include or omit a query string, as needed (exact query strings have higher precedence than not having a query string).
error_code (int) – The API error code.
error_message (unicode) – The API error message.
payload_extra (dict, optional) – Additional data to provide in the root of the error payload.
http_status (int, optional) – The HTTP status code for the error.
**kwargs (dict) – Additional keyword arguments for the registration. See add_url() for details.

Responses:: dict: The results of the add operation, for further tracking or processing. See the return type for add_url() for details.

add_repository_urls(repository_id=1, info_payload=None, **kwargs)[source]¶

Add URLs for a repository.

This will add a URL for a repository item resource and register it in the corresponding list resource.

A repository info URL is also registered, returning either a specified repository-specific info payload or a suitable error.

Parameters:

repository_id (int, optional) – The ID of the repository being added to the API.
info_payload (dict, optional) – Any payload data for the info/ URL. If None, then an error payload will be registered instead.
**kwargs (dict) – Additional keyword arguments for the repository payload. See rbtools.testing.api.payloads.PayloadFactory. make_repository_object_data() for details.

Returns:

A dictionary of add_url() results for the two URLs.

Keys:

repositories_info_url_info (dict) – The result of the repository info URL registration.
repositories_url_info (dict) – The result of the repository URL registration.

Return type:

dict

add_review_request_url(**kwargs)[source]¶

Add URLs for a review request.

This will add a URL for a review request item resource and register it in the corresponding list resource.

Parameters:: **kwargs (dict) – Keyword arguments for the review request payload. See rbtools.testing.api.payloads.PayloadFactory. make_review_request_object_data() for details.
Returns:: The results of the add operation, for further tracking or processing. See the return type for add_url() for details.
Return type:: dict

add_review_request_draft_url(**kwargs)[source]¶

Add URLs for a review request draft.

This will add a URL for a review request draft resource.

Parameters:: **kwargs (dict) – Keyword arguments for the review request draft payload. See rbtools.testing.api.payloads.PayloadFactory. make_review_request_draft_object_data() for details.
Returns:: The results of the add operation, for further tracking or processing. See the return type for add_url() for details.
Return type:: dict

add_session_url(**kwargs)[source]¶

Add URLs for a user session.

Parameters:: **kwargs (dict) – Keyword arguments for the session payload. See rbtools.testing.api.payloads.PayloadFactory. make_session_object_data() for details.
Returns:: The results of the add operation, for further tracking or processing. See the return type for add_url() for details.
Return type:: dict

add_user_url(**kwargs)[source]¶

Add URLs for a user resource.

Parameters:: **kwargs (dict) – Keyword arguments for the user payload. See rbtools.testing.api.payloads.PayloadFactory. make_user_object_data() for details.
Returns:: The results of the add operation, for further tracking or processing. See the return type for add_url() for details.
Return type:: dict

get_root()[source]¶

Perform a simulated HTTP GET on the root API.

Returns:: The resulting root resource.
Return type:: rbtools.api.resource.RootResource

get_path(path, *args, **kwargs)[source]¶

Perform a simulated HTTP GET on the given relative path.

Parameters:

path (unicode) – The path relative to the root of the server.
*args (tuple, unused) – Unused positional arguments.
**kwargs (dict) – Additional query arguments used to build a query string.

Returns:

The resulting resource or error.

Return type:

rbtools.api.resource.Resource or rbtools.api.errors.APIError

get_url(url, *args, **kwargs)[source]¶

Perform a simulated HTTP GET on the given absolute URL.

Parameters:

url (unicode) – The absolute URL.
*args (tuple, unused) – Unused positional arguments.
**kwargs (dict) – Additional query arguments used to build a query string.

Returns:

The resulting resource or error.

Return type:

rbtools.api.resource.Resource or rbtools.api.errors.APIError

login(username: Optional[str] = None, password: Optional[str] = None, api_token: Optional[str] = None, *args, **kwargs) → None[source]¶

This will simply set the logged_in and login_credentials login state.

Changed in version 5.0: Added an optional api_token parameter and made the username and password parameters optional to allow logging in with either a username and password or API token.

Parameters:

username (str, optional) – The username to log in with.
password (str, optional) – The password to log in with.
api_token (str, optional) – The API token to log in with.
*args (tuple, unused) – Unused positional arguments.
**kwargs (dict, unused) – Unused keyword arguments.

logout()[source]¶

Log out of the server.

This will simply clear the logged_in and login_credentials login state.

execute_request_method(method, *args, **kwargs)[source]¶

Execute a method and process the resulting HttpRequest.

Parameters:

method (callable) – The method to call to generate the HTTP request.
*args (tuple) – Positional arguments to pass to the method.
**kwargs (dict) – Keyword arguments to pass to the method.

Returns:

The resulting resource or error.

Return type:

rbtools.api.resource.Resource or rbtools.api.errors.APIError

enable_cache(cache_location=None, in_memory=False)[source]¶

Enable the HTTP cache.

This will simply set the cache_location and cache_in_memory attributes.

Parameters:

cache_location (unicode, optional) – The cache location to set.
in_memory (bool, optional) – The cache-in-memory flag to set.

disable_cache() → None[source]¶: Disable the HTTP cache.

New in version 5.0.

handle_api_path(path, method)[source]¶

Handle a request to an API path.

This will log the request attempt for debugging purposes, look up the appropriate response, and return it if found.

Any missing URL or method mappings will result in an assertion error.

Parameters:

path (unicode) – The path or URL the API request was made to.
method (unicode) – The HTTP method being performed.

Returns:

The resulting resource or error.

This may also return None for DELETE requests.

Return type:

rbtools.api.resource.Resource or rbtools.api.errors.APIError