Gabbi tests are expressed as YAML containing an HTTP request and an expected response. Each YAML file is an ordered sequence of requests. The bare minimum YAML file for a single request is::
tests:
- name: the name of a test
url: /
This will make a request to / on whatever the configured Target Host is. The test will pass if the status of the HTTP response is 200.
The tests key can contain as many requests, in sequence, as required. Other top level keys are:
Each test can use the following structure. Only name and url are required. For examples see the gabbi tests. Most of these allow substitutions (explained below).
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 are replaced with real values during test processing. They are processed in the order given.
All of these variables may be used in all of the following fields:
With these variables it ought to be possible to traverse an API without any explicit statements about the URLs being used. If you need a replacement on a field that is not currently supported please raise an issue or provide a patch.
As all of these features needed to be tested in the development of gabbi itself, the gabbi tests are a good source of examples on how to use the functionality.
The data key has some special handing to allow for a bit more flexibility when doing a POST or PUT. If the value is not a string (that is, it is a sequence or structure) it is treated as a datastructure which is turned into a JSON string. If the value is a string that begins with <@ then the rest of the string is treated as a file to be loaded from the same directory as the YAML file. If the the value is an undecorated string, that’s the value.
When reading from a file care should be taken to ensure that a 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.