# gabbi Package

## `case` Module

A single HTTP request represented as a subclass of `testtools.TestCase`

The test case encapsulates the request headers and body and expected response headers and body. When the test is run an HTTP request is made using urllib3. Assertions are made against the response.

class `gabbi.case.``HTTPTestCase`(*args, **kwargs)

  Bases: `testtools.testcase.TestCase`

  Encapsulate a single HTTP request as a TestCase.

  If the test is a member of a sequence of requests, ensure that prior tests are run.

  To keep the test harness happy we need to make sure the setUp and tearDown are only run once.

  `assert_in_or_print_output`(expected, iterable)

    Assert the iterable contains expected or print some output.

    If the output is long, it is limited by either GABBI_MAX_CHARS_OUTPUT in the environment or the MAX_CHARS_OUTPUT constant.

  `base_test` = {'data': '', 'desc': '', 'method': 'GET', 'name': '', 'poll': {}, 'query_parameters': {}, 'redirects': False, 'request_headers': {}, 'skip': '', 'ssl': False, 'status': '200', 'url': '', 'use_prior_test': True, 'verbose': False, 'xfail': False}
  `get_content_handler`(content_type)

    Determine the content handler for this media type.

  `load_data_file`(filename)

    Read a file from the current test directory.

  `replace_template`(message, escape_regex=False)

    Replace magic strings in message.

  `run`(result=None)

    Store the current result handler on this test.

  `setUp`()
  `tearDown`()
  `test_request`()

    Run this request if it has not yet run.

    If there is a prior test in the sequence, run it first.

`gabbi.case.``potentialFailure`(func)

  Decorate a test method that is expected to fail if ‘xfail’ is true.

## `driver` Module

## `suitemaker` Module

The code that creates a suite of tests.

The key piece of code is `test_suite_from_dict()`. It produces a `gabbi.suite.GabbiSuite` containing one or more `gabbi.case.HTTPTestCase`.

class `gabbi.suitemaker.``TestBuilder`

  Bases: `type`

  Metaclass to munge a dynamically created test.

  `required_attributes` = {'has_run': False}

class `gabbi.suitemaker.``TestMaker`(test_base_name, test_defaults, test_directory, fixture_classes, loader, host, port, intercept, prefix, response_handlers, content_handlers, test_loader_name=None, inner_fixtures=None)

  Bases: `object`

  A class for encapsulating test invariants.

  All of the tests in a single gabbi file have invariants which are provided when creating each HTTPTestCase. It is not useful to pass these around when making each test case. So they are wrapped in this class which then has make_one_test called multiple times to generate all the tests in the suite.

  `make_one_test`(test_dict, prior_test)

    Create one single HTTPTestCase.

    The returned HTTPTestCase is added to the TestSuite currently being built (one per YAML file).

`gabbi.suitemaker.``test_suite_from_dict`(loader, test_base_name, suite_dict, test_directory, host, port, fixture_module, intercept, prefix='', handlers=None, test_loader_name=None, inner_fixtures=None)

  Generate a GabbiSuite from a dict represent a list of tests.

  The dict takes the form:

  Parameters:

  - fixtures – An optional list of fixture classes that this suite can use.
  - defaults – An optional dictionary of default values to be used in each test.
  - tests – A list of individual tests, themselves each being a dictionary. See `gabbi.case.BASE_TEST`.

`gabbi.suitemaker.``test_update`(orig_dict, new_dict)

  Modify test in place to update with new data.

## `fixture` Module

Manage fixtures for gabbi at the test suite level.

class `gabbi.fixture.``GabbiFixture`

  Bases: `object`

  A context manager that operates as a fixture.

  Subclasses must implement `start_fixture` and `stop_fixture`, each of which contain the logic for stopping and starting whatever the fixture is. What a fixture is is left as an exercise for the implementor.

  These context managers will be nested so any actual work needs to happen in `start_fixture` and `stop_fixture` and not in `__init__`. Otherwise exception handling will not work properly.

  `start_fixture`()

    Implement the actual workings of starting the fixture here.

  `stop_fixture`()

    Implement the actual workings of stopping the fixture here.

exception `gabbi.fixture.``GabbiFixtureError`

  Bases: `exceptions.Exception`

  Generic exception for GabbiFixture.

class `gabbi.fixture.``SkipAllFixture`

  Bases: `gabbi.fixture.GabbiFixture`

  A fixture that skips all the tests in the current suite.

  `start_fixture`()

`gabbi.fixture.``nest`(*args, **kwds)

  Nest a series of fixtures.

  This is duplicated from `nested` in the stdlib, which has been deprecated because of issues with how exceptions are difficult to handle during `__init__`. Gabbi needs to nest an unknown number of fixtures dynamically, so the `with` syntax that replaces `nested` will not work.

## `handlers` Module

Package for response and content handlers that process the body of a response in various ways.

### `handlers.base` Module

Base classes for response and content handlers.

class `gabbi.handlers.base.``ContentHandler`

  Bases: `gabbi.handlers.base.ResponseHandler`

  A subclass of ResponseHandlers that adds content handling.

  static `accepts`(content_type)

    Return True if this handler can handler this type.

  static `dumps`(data, pretty=False, test=None)

    Return structured data as a string.

    If pretty is true, prettify.

  static `loads`(data)

    Create structured (Python) data from a stream.

  classmethod `replacer`(response_data, path)

    Return the string that is replacing RESPONSE.

class `gabbi.handlers.base.``ResponseHandler`

  Bases: `object`

  Add functionality for making assertions about an HTTP response.

  A subclass may implement two methods: `action` and `preprocess`.

  `preprocess` takes one argument, the `TestCase`. It is called exactly once for each test before looping across the assertions. It is used, rarely, to copy the `test.output` into a useful form (such as a parsed DOM).

  `action` takes two or three arguments. If `test_key_value` is a list `action` is called with the test case and a single list item. If `test_key_value` is a dict then `action` is called with the test case and a key and value pair.

  `action`(test, item, value=None)

    Test an individual entry for this response handler.

    If the entry is a key value pair the key is in item and the value in value. Otherwise the entry is considered a single item from a list.

  `preprocess`(test)

    Do any pre-single-test preprocessing.

  `test_key_suffix` = ''
  `test_key_value` = []

### `handlers.core` Module

Core response handlers.

class `gabbi.handlers.core.``ForbiddenHeadersResponseHandler`

  Bases: `gabbi.handlers.base.ResponseHandler`

  Test that listed headers are not in the response.

  `action`(test, forbidden, value=None)
  `test_key_suffix` = 'forbidden_headers'
  `test_key_value` = []

class `gabbi.handlers.core.``HeadersResponseHandler`

  Bases: `gabbi.handlers.base.ResponseHandler`

  Compare expected headers with actual headers.

  If a header value is wrapped in `/` it is treated as a raw regular expression.

  Headers values are always treated as strings.

  `action`(test, header, value=None)
  `test_key_suffix` = 'headers'
  `test_key_value` = {}

class `gabbi.handlers.core.``StringResponseHandler`

  Bases: `gabbi.handlers.base.ResponseHandler`

  Test for matching strings in the the response body.

  `action`(test, expected, value=None)
  `test_key_suffix` = 'strings'
  `test_key_value` = []

### `handlers.jsonhandler` Module

JSON-related content handling.

class `gabbi.handlers.jsonhandler.``JSONHandler`

  Bases: `gabbi.handlers.base.ContentHandler`

  A ContentHandler for JSON

  - Structured test `data` is turned into JSON when request content-type is JSON.
  - Response bodies that are JSON strings are made into Python data on the test `response_data` attribute when the response content-type is JSON.
  - A `response_json_paths` response handler is added.
  - JSONPaths in $RESPONSE substitutions are supported.
  static `accepts`(content_type)
  `action`(test, path, value=None)

    Test json_paths against json data.

  static `dumps`(data, pretty=False, test=None)
  static `extract_json_path_value`(data, path)

    Extract the value at JSON Path path from the data.

    The input data is a Python datastructure, not a JSON string.

  static `loads`(data)
  classmethod `replacer`(response_data, match)
  `test_key_suffix` = 'json_paths'
  `test_key_value` = {}

## `suite` Module

A TestSuite for containing gabbi tests.

This suite has two features: the contained tests are ordered and there are suite-level fixtures that operate as context managers.

class `gabbi.suite.``GabbiSuite`(tests=())

  Bases: `unittest.suite.TestSuite`

  A TestSuite with fixtures.

  The suite wraps the tests with a set of nested context managers that operate as fixtures.

  If a fixture raises unittest.case.SkipTest during setup, all the tests in this suite will be skipped.

  `run`(result, debug=False)

    Override TestSuite run to start suite-level fixtures.

    To avoid exception confusion, use a null Fixture when there are no fixtures.

  `start`(result, tests)

    Start fixtures when using pytest.

  `stop`()

    Stop fixtures when using pytest.

`gabbi.suite.``noop`(*args)

  A noop method used to disable collected tests.

## `runner` Module

## `reporter` Module

## `utils` Module

Utility functions grab bag.

`gabbi.utils.``create_url`(base_url, host, port=None, prefix='', ssl=False)

  Given pieces of a path-based url, return a fully qualified url.

`gabbi.utils.``decode_response_content`(header_dict, content)

  Decode content to a proper string.

`gabbi.utils.``extract_content_type`(header_dict, default='application/binary')

  Extract parsed content-type from headers.

`gabbi.utils.``get_colorizer`(stream)

  Return a function to colorize a string.

  Only if stream is a tty .

`gabbi.utils.``host_info_from_target`(target, prefix=None)

  Turn url or host:port and target into test destination.

`gabbi.utils.``load_yaml`(handle=None, yaml_file=None, safe=True)

  Read and parse any YAML file or filehandle.

  Let exceptions flow where they may.

  If no file or handle is provided, read from STDIN.

`gabbi.utils.``not_binary`(content_type)

  Decide if something is content we’d like to treat as a string.

`gabbi.utils.``parse_content_type`(content_type, default_charset='utf-8')

  Parse content type value for media type and charset.

## `exception` Module

Gabbi specific exceptions.

exception `gabbi.exception.``GabbiFormatError`

  Bases: `exceptions.ValueError`

  An exception to encapsulate poorly formed test data.

exception `gabbi.exception.``GabbiSyntaxWarning`

  Bases: `exceptions.SyntaxWarning`

  A warning about syntax that is not desirable.

## `httpclient` Module

Subclass of Http class for verbosity.

class `gabbi.httpclient.``Http`(num_pools=10, headers=None, **connection_pool_kw)

  Bases: `urllib3.poolmanager.PoolManager`

  A subclass of the urllib3.PoolManager to munge the data.

  This transforms the response to look more like what httplib2 provided when it was used as the httpclient.

  `request`(absolute_uri, method, body, headers, redirect)

class `gabbi.httpclient.``VerboseHttp`(**kwargs)

  Bases: `gabbi.httpclient.Http`

  A subclass of Http that verbosely reports on activity.

  If the output is a tty or `GABBI_FORCE_COLOR` is set in the environment, then output will be colorized according to `COLORMAP`.

  Output can include request and response headers, request and response body content (if of a printable content-type), or both.

  The color of the output has reasonable defaults. These may be overridden by setting the following environment variables

  - GABBI_CAPTION_COLOR
  - GABBI_HEADER_COLOR
  - GABBI_REQUEST_COLOR
  - GABBI_STATUS_COLOR

  to any of: BLACK RED GREEN YELLOW BLUE MAGENTA CYAN WHITE

  `COLORMAP` = {'caption': 'BLUE', 'header': 'YELLOW', 'request': 'CYAN', 'status': 'CYAN'}
  `HEADER_BLACKLIST` = ['status', 'reason']
  `REQUEST_PREFIX` = '>'
  `RESPONSE_PREFIX` = '<'
  `request`(absolute_uri, method, body, headers, redirect)

    Display request parameters before requesting.

`gabbi.httpclient.``get_http`(verbose=False, caption='')

  Return an Http class for making requests.

## `json_parser` Module

Keep one single global jsonpath parser.

`gabbi.json_parser.``parse`(path)

  Parse a JSONPath expression use the global parser.