# gabbi Package

## `case` Module

A single HTTP request represented as a subclass of `unittest.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 httpx. Assertions are made against the response.

class gabbi.case.HTTPTestCase(methodName='runTest')

  Bases: `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 = {'cert_validate': True, 'data': '', 'desc': '', 'disable_response_handler': False, 'http_version': 1, 'method': 'GET', 'name': '', 'poll': {}, 'query_parameters': {}, 'redirects': False, 'request_headers': {}, 'skip': '', 'ssl': False, 'status': '200', 'timeout': 30, '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()

    Hook method for setting up the test fixture before exercising it.

  shortDescription()

    Returns a one-line description of the test, or None if no description has been provided.

    The default implementation of this method returns the first line of the specified test method’s docstring.

  tearDown()

    Hook method for deconstructing the test fixture after testing it.

  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

Generate HTTP tests from YAML files

Each HTTP request is its own TestCase and can be requested to be run in isolation from other tests. If it is a member of a sequence of requests, prior requests will be run.

A sequence is represented by an ordered list in a single YAML file.

Each sequence becomes a TestSuite.

An entire directory of YAML files is a TestSuite of TestSuites.

gabbi.driver.build_tests(path, loader, host=None, port=8001, intercept=None, test_loader_name=None, fixture_module=None, response_handlers=None, content_handlers=None, prefix='', require_ssl=False, cert_validate=True, url=None, inner_fixtures=None, verbose=False, use_prior_test=True, safe_yaml=True)

  Read YAML files from a directory to create tests.

  Each YAML file represents a list of HTTP requests.

  Parameters:

    - path – The directory where yaml files are located.

    - loader – The TestLoader.

    - host – The host to test against. Do not use with `intercept`.

    - port – The port to test against. Used with `host`.

    - intercept – WSGI app factory for the httpx.WSGITransport used by the httpclient.

    - test_loader_name – Base name for test classes. Use this to align the naming of the tests with other tests in a system.

    - fixture_module – Python module containing fixture classes.

    - response_handers – `ResponseHandler` classes.

    - content_handlers (List of ContentHandler classes.) – ContentHandler classes.

    - prefix – A URL prefix for all URLs that are not fully qualified.

    - url – A full URL to test against. Replaces host, port and prefix.

    - require_ssl – If `True`, make all tests default to using SSL.

    - inner_fixtures (List of classes with setUp and cleanUp methods to be used as fixtures.) – A list of `Fixtures` to use with each individual test request.

    - verbose – If `True` or `'all'`, make tests verbose by default `'headers'` and `'body'` are also accepted.

    - use_prior_test – If `True`, uses prior test to create ordered sequence of tests

    - safe_yaml – If `True`, recognizes only standard YAML tags and not Python object

    - cert_validate – If `False` ssl server certificate will be ignored, further it will not be validated if provided (set cert_reqs=CERT_NONE to the Http object)

  Return type:

    TestSuite containing multiple TestSuites (one for each YAML file).

gabbi.driver.py_test_generator(test_dir, host=None, port=8001, intercept=None, prefix='', test_loader_name=None, fixture_module=None, response_handlers=None, content_handlers=None, require_ssl=False, url=None, metafunc=None, use_prior_test=True, inner_fixtures=None, safe_yaml=True, cert_validate=True)

  Generate tests cases for py.test

  This uses build_tests to create TestCases and then yields them in a way that pytest can handle.

  test_loader_name is required!

gabbi.driver.test_pytest(test, result)

gabbi.driver.test_suite_from_yaml(loader, test_base_name, test_yaml, test_directory, host, port, fixture_module, intercept, prefix='')

  Legacy wrapper retained for backwards compatibility.

## `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(name, bases, attributes)

  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: `Exception`

  Generic exception for GabbiFixture.

class gabbi.fixture.SkipAllFixture

  Bases: `GabbiFixture`

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

  start_fixture()

    Implement the actual workings of starting the fixture here.

gabbi.fixture.nest(fixtures)

  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: `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 load_data_file(test, file_path)

    Return the string content of the file specified by the file_path.

  static loads(data)

    Create structured (Python) data from a stream.

    If there is a failure decoding then the handler should repackage the error as a gabbi.exception.GabbiDataLoadError.

  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.

  is_regex(value)

    Check if the value is formatted to looks like a regular expression.

    Meaning it starts and ends with “/”.

  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: `ResponseHandler`

  Test that listed headers are not in the response.

  action(test, forbidden, 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.

  test_key_suffix = 'forbidden_headers'
  test_key_value = []

class gabbi.handlers.core.HeadersResponseHandler

  Bases: `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 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.

  test_key_suffix = 'headers'
  test_key_value = {}

class gabbi.handlers.core.StringResponseHandler

  Bases: `ResponseHandler`

  Test for matching strings in the the response body.

  action(test, expected, 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.

  test_key_suffix = 'strings'
  test_key_value = []

### `handlers.jsonhandler` Module

JSON-related content handling.

class gabbi.handlers.jsonhandler.JSONHandler

  Bases: `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)

    Return True if this handler can handler this type.

  action(test, path, value=None)

    Test json_paths against json data.

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

    Return structured data as a string.

    If pretty is true, prettify.

  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 load_data_file(test, file_path)

    Return the string content of the file specified by the file_path.

  static loads(data)

    Create structured (Python) data from a stream.

    If there is a failure decoding then the handler should repackage the error as a gabbi.exception.GabbiDataLoadError.

  classmethod replacer(response_data, match)

    Return the string that is replacing RESPONSE.

  test_key_suffix = 'json_paths'
  test_key_value = {}

### `handlers.yaml_disk_loading_jsonhandler` Module

JSON-related content handling with YAML data disk loading.

class gabbi.handlers.yaml_disk_loading_jsonhandler.YAMLDiskLoadingJSONHandler

  Bases: `JSONHandler`

  A ContentHandler for JSON responses that loads YAML from disk

  - 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. Data read from disk during this handle will be loaded with the yaml.safe_load method to support both JSON and YAML data sources from disk.

  - JSONPaths in $RESPONSE substitutions are supported.

  static load_data_file(test, file_path)

    Return the string content of the file specified by the file_path.

## `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: `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=None)

    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

Implementation of a command-line runner for gabbi files (AKA suites).

gabbi.runner.extract_file_paths(argv)

  Extract file paths from the command-line.

  File path arguments follow a – end-of-options delimiter, if any.

gabbi.runner.initialize_handlers(response_handlers, local_handlers)

gabbi.runner.load_response_handlers(import_path)

  Load and return custom response handlers from the import path.

  The import path references either a specific response handler class (“package.module:class”) or a module that contains one or more response handler classes (“package.module”).

  For the latter, the module is expected to contain a `gabbi_response_handlers` object, which is either a list of response handler classes or a function returning such a list.

gabbi.runner.run()

  Run simple tests from STDIN.

  This command provides a way to run a set of tests encoded in YAML that is provided on STDIN. No fixtures are supported, so this is primarily designed for use with real running services.

  Host and port information may be provided in three different ways:

  - In the URL value of the tests.

  - In a host or host:port argument on the command line.

  - In a URL on the command line.

  An example run might looks like this:

      gabbi-run example.com:9999 < mytest.yaml

  or:

      gabbi-run http://example.com:999 < mytest.yaml

  It is also possible to provide a URL prefix which can be useful if the target application might be mounted in different locations. An example:

      gabbi-run example.com:9999 /mountpoint < mytest.yaml

  or:

      gabbi-run http://example.com:9999/mountpoint < mytest.yaml

  Use -x or –failfast to abort after the first error or failure:

      gabbi-run -x example.com:9999 /mountpoint < mytest.yaml

  Use -v or –verbose with a value of all, headers or body to turn on verbosity for all tests being run.

  Multiple files may be named as arguments, separated from other arguments by a `--`. Each file will be run as a separate test suite:

      gabbi-run http://example.com -- /path/to/x.yaml /path/to/y.yaml

  Output is formatted as unittest summary information. Use -q or –quiet to silence that output.

  Use `-r` or `--response-handler` to load a custom response or content handler for use with tests.

  Use `-l` to load response handlers relative to the current working directory.

  For example, to load a handler named `HTMLHandler` from the `handlers.html` module relative to the current directory:

  > gabbi-run -l -r handlers.html:HTMLHandler http://example.com < my.yaml

gabbi.runner.run_suite(handle, handler_objects, host, port, prefix, force_ssl=False, failfast=False, data_dir='.', verbosity=False, name='input', safe_yaml=True, quiet=False, cert_validate=True)

  Run the tests from the YAML in handle.

## `reporter` Module

TestRunner and TestResult for gabbi-run.

class gabbi.reporter.ConciseTestResult(stream, descriptions, verbosity)

  Bases: `TextTestResult`

  A TextTestResult with simple but useful output.

  If the output is a tty or GABBI_FORCE_COLOR is set in the environment, output will be colorized.

  addError(test, err)

    Called when an error has occurred. ‘err’ is a tuple of values as returned by sys.exc_info().

  addExpectedFailure(test, err)

    Called when an expected failure/error occurred.

  addFailure(test, err)

    Called when an error has occurred. ‘err’ is a tuple of values as returned by sys.exc_info().

  addSkip(test, reason)

    Called when a test is skipped.

  addSuccess(test)

    Called when a test has completed successfully

  addUnexpectedSuccess(test)

    Called when a test was expected to fail, but succeed.

  getDescription(test)
  printErrorList(flavor, errors)
  startTest(test)

    Called when the given test is about to be run

class gabbi.reporter.ConciseTestRunner(stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False, durations=None)

  Bases: `TextTestRunner`

  A TextTestRunner that uses ConciseTestResult for reporting results.

  resultclass

    alias of `ConciseTestResult`

class gabbi.reporter.PyTestResult(stream=None, descriptions=None, verbosity=None)

  Bases: `TestResult`

  Wrap a test result to allow it to work with pytest.

  The main behaviors here are:

  - to turn what had been exceptions back into exceptions

  - use pytest’s skip and xfail methods

  addError(test, err)

    Called when an error has occurred. ‘err’ is a tuple of values as returned by sys.exc_info().

  addExpectedFailure(test, err)

    Called when an expected failure/error occurred.

  addFailure(test, err)

    Called when an error has occurred. ‘err’ is a tuple of values as returned by sys.exc_info().

  addSkip(test, reason)

    Called when a test is skipped.

## `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.GabbiDataLoadError

  Bases: `ValueError`

  An exception to alert when data streams cannot be loaded.

exception gabbi.exception.GabbiFormatError

  Bases: `ValueError`

  An exception to encapsulate poorly formed test data.

exception gabbi.exception.GabbiSyntaxWarning

  Bases: `SyntaxWarning`

  A warning about syntax that is not desirable.

## `httpclient` Module

class gabbi.httpclient.Http(**kwargs)

  Bases: `object`

  A class to munge the HTTP response.

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

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

class gabbi.httpclient.VerboseHttp(**kwargs)

  Bases: `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', 'http_protocol_version']
  REQUEST_PREFIX = '>'
  RESPONSE_PREFIX = '<'
  request(absolute_uri, method, body, headers, redirect, timeout)

    Display request parameters before requesting.

gabbi.httpclient.get_http(verbose=False, caption='', cert_validate=True, hostname=None, intercept=None, prefix='', timeout=30, version=1)

  Return an `Http` class for making requests.

## `json_parser` Module