# Content Handlers

Content handlers are responsible for preparing request data and evaluating response data based on the content-type of the request and response. A content handler operates as follows:

- Structured YAML data provided via the `data` attribute is converted to a string or bytes sequence and used as request body.

- The response body (a string or sequence of bytes) is transformed into a content-type dependent structure and stored in an internal attribute named `response_data` that is:

  - used when evaluating the response body

  - used in `$RESPONSE[]` substitutions

By default, gabbi provides content handlers for JSON. In that content handler the `data` test key is converted from structured YAML into a JSON string. Response bodies are converted from a JSON string into a data structure in `response_data` that is used when evaluating `response_json_paths` entries in a test or doing JSONPath-based `$RESPONSE[]` substitutions.

A YAMLDiskLoadingJSONHandler has been added to extend the JSON handler. It works the same way as the JSON handler except for when evaluating the `response_json_paths` handle, data that is read from disk can be either in JSON or YAML format. The YAMLDiskLoadingJSONHandler is not enabled by default and must be added as shown in the Extensions section in order to be used in the tests.

Further content handlers can be added as extensions. Test authors may need these extensions for their own suites, or enterprising developers may wish to create and distribute extensions for others to use.

Note

One extension that is likely to be useful is a content handler that turns `data` into url-encoded form data suitable for POST and turns an HTML response into a DOM object.

## Extensions

Content handlers are an evolution of the response handler concept in earlier versions gabbi. To preserve backwards compatibility with existing response handlers, old style response handlers are still allowed, but new handlers should implement the content handler interface (described below).

Registering additional custom handlers is done by passing a subclass of `ContentHandler` to `build_tests()`:

    driver.build_tests(test_dir, loader, host=None,
                       intercept=simple_wsgi.SimpleWsgi,
                       content_handlers=[MyContentHandler])

If pytest is being used:

    driver.py_test_generator(test_dir, intercept=simple_wsgi.SimpleWsgi,
                             content_handlers=[MyContenHandler])

Gabbi provides an additional custom handler named YAMLDiskLoadingJSONHandler. This can be used for loading JSON and YAML files from disk when evaluating the `response_json_paths` handle.

Warning

YAMLDiskLoadingJSONHandler shares the same content-type as the default JSONHandler. When there are multiple handlers listed that accept the same content-type, the one that is earliest in the list will be used.

With `gabbi-run`, custom handlers can be loaded via the `--response-handler` option – see `load_response_handlers()` for details.

Note

The use of the `--response-handler` argument is done to preserve backwards compatibility and avoid excessive arguments. Both types of handler may be passed to the argument.

### Implementation Details

Creating a content handler requires subclassing `ContentHandler` and implementing several methods. These methods are described below, but inspecting `JSONHandler` will be instructive in highlighting required arguments and techniques.

To provide a `response_<something>` response-body evaluator a subclass must define:

- `test_key_suffix`: This, along with the prefix `response_`, forms the key used in the test structure. It is a class level string.

- `test_key_value`: The key’s default value, either an empty list (`[]`) or empty dict (`{}`). It is a class level value.

- `action`: An instance method which tests the expected values against the HTTP response - it is invoked for each entry, with the parameters depending on the default value. The arguments to `action` are (in order):

  - `self`: The current instance.

  - `test`: The currently active `HTTPTestCase`

  - `item`: The current entry if `test_key_value` is a list, otherwise the key half of the key/value pair at this entry.

  - `value`: `None` if `test_key_value` is a list, otherwise the value half of the key/value pair at this entry.

To translate request or response bodies to or from structured data a subclass must define an `accepts` method. This should return `True` if this class is willing to translate the provided content-type. During request processing it is given the value of the content-type header that will be sent in the request. During response processing it is given the value of the content-type header of the response. This makes it possible to handle different request and response bodies in the same handler, if desired. For example a handler might accept `application/x-www-form-urlencoded` and `text/html`.

If `accepts` is defined two additional static methods should be defined:

- `dumps`: Turn structured Python data from the `data` key in a test into a string or byte stream. The optional `test` param allows you to access the current test case which may help with manipulations for custom content handlers, e.g. `multipart/form-data` needs to add a `boundary` to the `Content-Type` header in order to mark the appropriate sections of the body.

- `loads`: Turn a string or byte stream in a response into a Python data structure. Gabbi will put this data on the `response_data` attribute on the test, where it can be used in the evaluations described above (in the `action` method) or in `$RESPONSE` handling. An example usage here would be to turn HTML into a DOM.

- `load_data_file`: Load data from disk into a Python data structure. Gabbi will call this method when `response_<something>` contains an item where the right hand side value starts with `<@`. The `test` param allows you to access the current test case and provides a load_data_file method which should be used because it verifies the data is loaded within the test diectory and returns the file source as a string. The `load_data_file` method was introduced to re-use the JSONHandler in order to support loading YAML files from disk through the implementation of an additional custom handler, see `YAMLDiskLoadingJSONHandler` for details.

Finally if a `replacer` class method is defined, then when a `$RESPONSE` substitution is encountered, `replacer` will be passed the `response_data` of the prior test and the argument within the `$RESPONSE`.

Please see the JSONHandler source for additional detail.