From 4a8ff280ba18de660c1e2b3ff7266c4cc5fb3446 Mon Sep 17 00:00:00 2001 From: FND Date: Sat, 26 Sep 2015 12:29:14 +0200 Subject: [PATCH] Reorganize test format documentation previously keys were documented as a lengthy list in seemingly arbitrary order - in contrast, this structure promises to be more comprehensible (and less daunting), plus table layout should improve readability and scannability by providing some visual consistency note that this inevitably led to various editorial changes --- docs/source/format.rst | 259 ++++++++++++++++++++++++++--------------- 1 file changed, 165 insertions(+), 94 deletions(-) diff --git a/docs/source/format.rst b/docs/source/format.rst index 1fd80a6..cd1829a 100644 --- a/docs/source/format.rst +++ b/docs/source/format.rst @@ -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 ` 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