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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

259
docs/source/format.rst
View File

@ -1,120 +1,189 @@
.. highlight:: yaml
Test Format
===========
Gabbi tests are expressed in YAML containing an HTTP request and an
expected response. Each YAML file is an ordered sequence of requests.
A minimal YAML file for a single request is::
Gabbi tests are expressed in YAML as a series of HTTP requests with their
expected response::
tests:
- name: the name of a test
- name: retrieve root
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
:doc:`host` is. The test will pass if the status of the HTTP response
is ``200``.
.. _test-structure:
The ``tests`` sequence can contain as many requests as required.
Other top level keys are:
Test Structure
--------------
* ``fixtures``: A sequence of named :doc:`fixtures`.
* ``defaults``: A dictionary of local default values for the requests and
responses in the ``tests`` in this file. These override the global
defaults (explained below).
The top-level ``tests`` category contains an ordered sequence of test
declarations, each describing the expected response to a given request:
Each test can use the following structure. Only ``name`` and ``url``
are required. For examples see `the gabbi tests`_, :doc:`example`
and the `gabbi-demo`_ tutorial.
.. table:: metadata
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
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:
``desc`` An arbitrary string describing the test.
* ``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.
``verbose`` If ``True`` or ``all`` (synonymous), prints a defaults to
representation of the current request and ``False``
response to ``stdout``, including both headers
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
asynchronous request. Use with caution.
``skip`` A string message which if set will cause the test defaults to
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
statement by exchanging the ``url`` key for the actual method::
Note: When tests are generated dynamically, the ``TestCase`` name will include
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
url: /
.. table:: request parameters
corresponds to::
==================== ======================================== ============
Key Description Notes
==================== ======================================== ============
any uppercase string Any such key is considered an HTTP
method, with the corresponding value
expressing the URL.
PATCH: /
This is a shortcut combining ``method``
and ``url`` into a single statement::
Any uppercase key is considered an HTTP method, there is no pre-defined
list of approved methods.
GET: /index
The ``response_*`` items are examples of Response Handlers. Additional
handlers may be created by test authors for specific use cases. See
:doc:`handlers` for more information.
corresponds to::
method: GET
url: /index
``method`` The HTTP request method. defaults to
``GET``
``url`` The URL to request. This can either be a **required**
full path (e.g. "/index") or a fully
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
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
of examples and the `gabbi-demo`_ tutorial.
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
or javascript it will be encoded to UTF-8.
.. _the gabbi tests: https://github.com/cdent/gabbi/tree/master/gabbi/gabbits_intercept
.. _gabbi-demo: https://github.com/cdent/gabbi-demo