openstack/deb-python-gabbi
Code Issues Proposed changes

Merge pull request #92 from cdent/format-docs

Browse Source 
reorganized test format documentation
This commit is contained in:
Chris Dent 2015-09-28 16:53:17 +01:00
commit 51b6e879b4
1 changed files with 165 additions and 94 deletions

257
docs/source/format.rst

@ -1,120 +1,189 @@
.. highlight:: yaml
Test Format Test Format
=========== ===========
Gabbi tests are expressed in YAML containing an HTTP request and an Gabbi tests are expressed in YAML as a series of HTTP requests with their
expected response. Each YAML file is an ordered sequence of requests. expected response::
A minimal YAML file for a single request is::
tests: tests:
- name: the name of a test - name: retrieve root
GET: / GET: /
status: 200
This is :ref:`short <method-shortcut>` for:: This will trigger a ``GET`` request to ``/`` on the configured :doc:`host`. The
test will pass if the response's status code is ``200``.
tests:
- name: the name of a test
method: GET
url: /
This will make a ``GET`` request to ``/`` on whatever the configured .. _test-structure:
:doc:`host` is. The test will pass if the status of the HTTP response
is ``200``.
The ``tests`` sequence can contain as many requests as required. Test Structure
Other top level keys are: --------------
* ``fixtures``: A sequence of named :doc:`fixtures`. The top-level ``tests`` category contains an ordered sequence of test
* ``defaults``: A dictionary of local default values for the requests and declarations, each describing the expected response to a given request:
responses in the ``tests`` in this file. These override the global
defaults (explained below).
Each test can use the following structure. Only ``name`` and ``url`` .. table:: metadata
are required. For examples see `the gabbi tests`_, :doc:`example`
and the `gabbi-demo`_ tutorial.
Many of these items allow substitutions (explained below). =========== ================================================= ============
Key Description Notes
=========== ================================================= ============
``name`` The test's name. Must be unique within a file. **required**
* ``name``: The name of the test. Must be unique in this file. When ``desc`` An arbitrary string describing the test.
tests are dynamically generated the ``TestCase`` name will include
this name, lowercased with spaces transformed to ``_``. In at least
some test runners this will allow you to select and filter on test
name. **Required**
* ``desc``: An arbitrary string describing this test. This is perhaps
redundant as YAML allows comments. However it's here in case other
tooling might use it.
* ``url``: The URL to request. This can either be a full path or a
fully qualified URL (with host and scheme). If not qualified the
test builder will be responsible for determining host and scheme.
**Required**
* ``query_parameters``: An optional dictionary of query parameters
that will be added to the ``url`` as query string. If the ``url``
already contains a set of query parameters, those wil be extended.
See :doc:`example` for a demonstration of how the data is structured.
* ``method``: The request method to use. Defaults to ``GET``.
* ``status``: The expected response status code. The default is
``200``. If necessary you may indicate multiple response codes
separated by ``||`` (e.g. ``302 || 301``). Avoid this if possible as
it indicates there is ambiguity in your tests or your API. Ambiguity
is bad.
* ``ssl``: Make this request use SSL? Defaults to ``False``. This only
comes into play if the ``url`` does not provide a scheme (see
:doc:`host` for more info).
* ``verbose``: If ``True`` print a representation of the current
request and response, including both headers and body to ``stdout``.
If set to ``headers`` or ``body`` then only the corresponding part
of the request and response will be displayed. ``all`` is a
synonym for ``True``. If the output is a tty, colors will be used.
See :class:`~gabbi.httpclient.VerboseHttp` for more details. Defaults
to ``False``.
* ``redirects``: If ``True`` automatically follow redirects. Defaults
to ``False``.
* ``request_headers``: A dictionary of key-value pairs representing
request header names and values. These will be added to the
constructed request.
* ``data``: A representation to pass as the body of a request. If you
use this you should set ``content-type`` in ``request_headers`` to
something meaningful. See `Data`_ below for more details.
* ``skip``: A string message which if set will cause the test to be
skipped with the provided message.
* ``xfail``: If ``True`` expect this test to fail but run it anyway.
* ``response_headers``: A dictionary of key-value pairs representing
expected response headers. If the value of a header is wrapped in
``/``, it will be treated as a raw regular expression string.
* ``response_strings``: A sequence of string fragments expected to be
in the response body.
* ``response_json_paths``: A dictionary of JSONPath rules paired with
expected matches. Using this rule requires that the content being
sent from the server is content-type ``application/json`` or is
a content-type derived from JSON and thus includes ``+json`` in
the content-type value.
* ``poll``: A dictionary of two keys:
* ``count``: An integer stating the number of times to attempt ``verbose`` If ``True`` or ``all`` (synonymous), prints a defaults to
this test before giving up. representation of the current request and ``False``
* ``delay``: A floating point number of seconds to delay between response to ``stdout``, including both headers
attemmpts. and body. If set to ``headers`` or ``body``, only
the corresponding part of the request and
response will be printed. If the output is a TTY,
colors will be used. See
:class:`~gabbi.httpclient.VerboseHttp` for
details.
This makes it possible to poll for a resource created via an ``skip`` A string message which if set will cause the test defaults to
asynchronous request. Use with caution. to be skipped with the provided message. ``False``
.. _method-shortcut: ``xfail`` Determines whether to expect this test to fail.
Note that the test will be run anyway.
=========== ================================================= ============
Note that it's possible to combine ``method`` and ``url`` into a single Note: When tests are generated dynamically, the ``TestCase`` name will include
statement by exchanging the ``url`` key for the actual method:: the respective test's ``name``, lowercased with spaces transformed to ``_``. In
at least some test runners this will allow you to select and filter on test
name.
method: PATCH .. table:: request parameters
url: /
==================== ======================================== ============
Key Description Notes
==================== ======================================== ============
any uppercase string Any such key is considered an HTTP
method, with the corresponding value
expressing the URL.
This is a shortcut combining ``method``
and ``url`` into a single statement::
GET: /index
corresponds to:: corresponds to::
PATCH: / method: GET
url: /index
Any uppercase key is considered an HTTP method, there is no pre-defined ``method`` The HTTP request method. defaults to
list of approved methods. ``GET``
The ``response_*`` items are examples of Response Handlers. Additional ``url`` The URL to request. This can either be a **required**
handlers may be created by test authors for specific use cases. See full path (e.g. "/index") or a fully
:doc:`handlers` for more information. qualified URL (i.e. including host and
scheme, e.g.
"http://example.org/index") - see
:doc:`host` for details.
``request_headers`` A dictionary of key-value pairs
representing request header names and
values. These will be added to the
constructed request.
``query_parameters`` A dictionary of query parameters that
will be added to the ``url`` as query
string. If that URL already contains a
set of query parameters, those wil be
extended. See :doc:`example` for a
demonstration of how the data is
structured.
``data`` A representation to pass as the body of
a request. Note that ``content-type`` in
``request_headers`` should also be set -
see `Data`_ for details.
``redirects`` If ``True``, redirects will defaults to
automatically be followed. ``False``
``ssl`` Determines whether the request uses SSL defaults to
(i.e. HTTPS). Note that the ``url``'s ``False``
scheme takes precedence if present - see
:doc:`host` for details.
==================== ======================================== ============
.. table:: response expectations
======================= ===================================== ============
Key Description Notes
======================= ===================================== ============
``status`` The expected response status code. defaults to
Multiple acceptable response codes ``200``
may be provided, separated by ``||``
(e.g. ``302 || 301`` - note, however,
that this indicates ambiguity, which
is generally undesirable).
``response_headers`` A dictionary of key-value pairs
representing expected response header
names and values. If a header's value
is wrapped in ``/.../``, it will be
treated as a regular expression.
``response_strings`` A list of string fragments expected
to be present in the response body.
``response_json_paths`` A dictionary of JSONPath rules paired
with expected matches. Using this
rule requires that the content being
sent from the server is JSON (i.e. a
content type of ``application/json``
or containing ``+json``)
``poll`` A dictionary of two keys:
* ``count``: An integer stating the
number of times to attempt this
test before giving up.
* ``delay``: A floating point number
of seconds to delay between
attemmpts.
This makes it possible to poll for a
resource created via an asynchronous
request. Use with caution.
======================= ===================================== ============
Note that many of these items allow substitutions (explained below).
Default values for a file's ``tests`` may be provided via the top-level
``defaults`` category. These take precedence over the global defaults
(explained below).
For examples see `the gabbi tests`_, :doc:`example` and the `gabbi-demo`_
tutorial.
.. _fixtures:
Fixtures
--------
The top-level ``fixtures`` category contains a sequence of named
:doc:`fixtures`.
.. _response-handlers:
Response Handlers
-----------------
``response_*`` keys are examples of Response Handlers. Custom handlers may be
created by test authors for specific use cases. See :doc:`handlers` for more
information.
Substitution
------------
There are a number of magical variables that can be used to make There are a number of magical variables that can be used to make
reference to the state of a current test or the one just prior. These reference to the state of a current test or the one just prior. These
@ -158,6 +227,7 @@ gabbi itself, `the gabbi tests`_ are a good source of examples on how
to use the functionality. See also :doc:`example` for a collection to use the functionality. See also :doc:`example` for a collection
of examples and the `gabbi-demo`_ tutorial. of examples and the `gabbi-demo`_ tutorial.
Data Data
---- ----
@ -174,5 +244,6 @@ reasonable content-type is set for the data as this will control if any
encoding is done of the resulting string value. If it is text, json, xml encoding is done of the resulting string value. If it is text, json, xml
or javascript it will be encoded to UTF-8. or javascript it will be encoded to UTF-8.
.. _the gabbi tests: https://github.com/cdent/gabbi/tree/master/gabbi/gabbits_intercept .. _the gabbi tests: https://github.com/cdent/gabbi/tree/master/gabbi/gabbits_intercept
.. _gabbi-demo: https://github.com/cdent/gabbi-demo .. _gabbi-demo: https://github.com/cdent/gabbi-demo