djblets.webapi.testing.testcases¶

Test case support for full API testing.

This provides a useful mixin, WebAPITestCaseMixin, that can be mixed into a base test case for an API testing suite. This mixin provides a number of useful helpers for calling APIs and validating results, along with generating consistent docstrings.

class WebAPITestCaseMixin(methodName='runTest')[source]¶

Mixin for test cases for thoroughly testing APIs.

This helps with the testing of APIs by providing convenient methods for performing HTTP requests and checking their response payloads, redirects, mimetypes, and more.

Any test methods in a subclass that have the is_test_template flag set to True can include <URL> in their docstring. When the test is run, the <URL> will be replaced by the contents of the subclass’s sample_api_url.

WebAPITestCaseMixin is meant to be mixed into a new base class that all API test suites would inherit from. Subclasses must provide values for sample_api_url and error_mimetype.

sample_api_url = None[source]¶: The path to the resource, which may be placed into the docstring.

error_mimetype = None[source]¶: The mimetype representing an error for this API.

base_url = 'http://testserver'[source]¶: A fake base URL for API operations.

shortDescription()[source]¶

Return a description for a particular test.

If the test has the is_test_template attribute set, and contains <URL> in the docstring, the URL will be replaced by the contents of sample_api_url.

Returns: The description of the test.
Return type: unicode

api_get(*args, **kwargs)[source]¶

Perform and check a HTTP GET request, returning additional data.

This will perform the request to the resource and validate that all the results are what the caller expects.

This method is a wrapper around api_get_with_response(). See that method for the arguments.

Parameters

*args (tuple) – Positional arguments to pass to api_get_with_response().
**kwargs (dict) – Keyword arguments to pass to api_get_with_response().

Returns

The parsed payload data as a dictionary, if expected_json is True and the response isn’t a HTTP 302. Otherwise, the raw payload contents.

Return type

dict or bytes

api_get_with_response(path, data={}, **kwargs)[source]¶

Perform and check a HTTP GET request to an API resource.

This will perform the request to the resource and validate that all the results are what the caller expects.

Parameters

path (unicode) – The path to the resource to request.
data (object, optional) – The request query string.
*args (tuple) – Positional arguments to pass to api_call().
**kwargs (dict) – Keyword arguments to pass to api_call().

Returns

A 2-item tuple containing the parsed response and the original HttpResponse.

Return type

tuple

api_post(*args, **kwargs)[source]¶

Perform and check an HTTP POST to an API resource.

This will perform the request to the resource and validate that all the results are what the caller expects.

This method is a wrapper around api_post_with_response(). See that method for the arguments.

Parameters

*args (tuple) – Positional arguments to pass to api_post_with_response().
**kwargs (dict) – Keyword arguments to pass to api_post_with_response().

Returns

The parsed payload data as a dictionary, if expected_json is True and the response isn’t a HTTP 302. Otherwise, the raw payload contents.

Return type

dict or bytes

api_post_with_response(path, data={}, expected_status=201, **kwargs)[source]¶

Perform an HTTP POST to an API resource, returning additional data.

This works like api_post(), but returns the resulting payload and the original HttpResponse.

This will perform the request to the resource and validate that all the results are what the caller expects.

Parameters

path (unicode) – The path to the resource to request.
data (object, optional) – The request payload.
expected_status (int, optional) – The expected HTTP status.
*args (tuple) – Positional arguments to pass to api_call().
**kwargs (dict) – Keyword arguments to pass to api_call().

Returns

A 2-item tuple containing the parsed response and the original HttpResponse.

Return type

tuple

api_put(*args, **kwargs)[source]¶

Perform and check an HTTP PUT to an API resource.

This will perform the request to the resource and validate that all the results are what the caller expects.

This method is a wrapper around api_put_with_response(). See that method for the arguments.

Parameters

*args (tuple) – Positional arguments to pass to api_put_with_response().
**kwargs (dict) – Keyword arguments to pass to api_put_with_response().

Returns

The parsed payload data as a dictionary, if expected_json is True and the response isn’t a HTTP 302. Otherwise, the raw payload contents.

Return type

dict or bytes

api_put_with_response(path, data={}, content_type='multipart/form-data; boundary=BoUnDaRyStRiNg', **kwargs)[source]¶

Perform an HTTP PUT to an API resource, returning additional data.

This will perform the request to the resource and validate that all the results are what the caller expects.

Parameters

path (unicode) – The path to the resource to request.
data (object, optional) – The request payload.
*args (tuple) – Positional arguments to pass to api_call().
**kwargs (dict) – Keyword arguments to pass to api_call().

Returns

A 2-item tuple containing the parsed response and the original HttpResponse.

api_delete(*args, **kwargs)[source]¶

Perform and check an HTTP DELETE to an API resource.

This will perform the request to the resource and validate that all the results are what the caller expects.

This method is a wrapper around api_delete_with_response(). See that method for the arguments.

Parameters

*args (tuple) – Positional arguments to pass to api_delete_with_response().
**kwargs (dict) – Keyword arguments to pass to api_delete_with_response().

Returns

The HTTP response payload. This won’t have any content if the delete was successful.

Return type

bytes

api_delete_with_response(path, expected_status=204, **kwargs)[source]¶

Perform an HTTP DELETE to an API resource, returning additional data.

This will perform the request to the resource and validate that all the results are what the caller expects.

Parameters

path (unicode) – The path to the resource to request.
expected_status (int, optional) – The expected HTTP status.
*args (tuple) – Positional arguments to pass to api_call().
**kwargs (dict) – Keyword arguments to pass to api_call().

Returns

A 2-item tuple containing the parsed response and the original HttpResponse.

Return type

tuple

assertHttpOK(response, check_last_modified=False, check_etag=False)[source]¶

Assert that a response was OK and optionally has caching headers.

Parameters

response (django.http.HttpResponse) – The HTTP response from the API.
check_last_modified (bool) – If set, this will assert that the response has a Last-Modified header.
check_etag (bool) – If set, this will assert that the response has a ETag header.

assertHttpNotModified(response)[source]¶

Assert that the response was HTTP 304 Not Modified.

Parameters: response (django.http.HttpResponse) – The HTTP response from the API.

api_call(client_http_method, path, data=None, follow_redirects=False, expected_status=200, expected_redirects=[], expected_headers={}, expected_mimetype=None, expected_num_queries=None, expected_json=True, return_http_response=True, **extra)[source]¶

Perform an API call using a client API method.

This will invoke an API function with all the necessary parameters, and check the results for the expected values.

Parameters

api_func (callable) – The API function to call.
path (unicode) – The path to the resource to request.
data (dict, optional) – The data to pass in the request. For an HTTP GET, this will be used as a query string. For other requests, this will be the request body.
follow_redirects (bool, optional) – Whether to expect and follow redirects to another URL.
expected_status (int, optional) – The expected HTTP status.
expected_redirects (list of unicode, optional) – The list of expected redirects performed by the resource(s), in order.
expected_headers (dict, optional) – Expected HTTP headers and their values from the response.
expected_num_queries (int, optional) – The number of queries this API call is expected to make.
expected_mimetype (unicode, optional) – The expected mimetype for the response payload.
expected_json (bool) – Whether JSON-parsable content is expected in the response.
return_http_response (bool, optional) – Whether to return the HttpResponse as part of the result.
**extra (dict) – Extra data to pass to the client HTTP method.

Returns

By default, this returns the payload content, which may be a raw byte string result or a deserialized JSON body (depending on expected_json).

If passing return_http_response=True, this will return a tuple in the form of (payload_content, http_response), where http_response is the HttpResponse object.

Return type

object