Scenario Structure

Let’s take a look at the structure of verification scenario.

Here is a scenario example.

label: Scenario example
default:
  request:
    path: /path
  response:
    status_code: 200
when:
  - describe: .base_url
    should:
      contain_string: localhost
cases:
  - label: A simple example
    request: /path/to/foo?bar=baz
    response:
      status_code: 200
      body:
        describe: .foo
        should:
          equal: bar
  - label: A Little Complicated
    enabled: true
    wait: 3 minutes
    request:
      method: POST
      path: /path/to/foo
      headers:
        user-agent: custom-value
      params:
        key1: value
        key2:
          - value1
          - value2
      body:
        type: urlencoded
        data:
          foo: bar
    response:
      status_code:
        - be_greater_than_or_equal_to: 200
        - be_less_than: 400
      headers:
        - describe: ."content-type"
          should:
            equal_to: application/xml
        - describe:
            jq: ."content-length"
            cast_to: int
          should:
            be_greater_than: 100
      body:
        - describe:
            xpath: /html/body/h1
          should:
            - start_with: x
            - end_with: y

Scenario

A “scenario” is the basic unit of verification process. A scenario contains some “cases”, which are basically run serially. Scenarios can be nested by using “subscenarios.”

Key	Type	Default	Description
label	String	null	A label of this scenario.
cases	List[Case]	[]	Test cases.
subscenarios	List[Scenario]	[]	Nested scenarios.
ordered	Boolean	true	Mark the cases is ordered or not. When false, cases can be run concurrently. See Concurrent running for more information.
default	Case	{}	Default of this scenario. See Default Test for more information.
when	List[Description]	[]	Run this scenario only when the context satisfies these description. See Context for more information.
parameters	List[Parameter]	null	Parameters to make parameterized test. See Parameterized Test for more information.

Minimally, a scenario should contain label and cases.

label: The label of this scenario
cases:
  - ...
  - ...

Only the top level YAML value can be a list, which will be flattened even if it is nested.

- label: The label of the 1st scenario
  cases:
    - ...
- - label: The label of the 2nd scenario
    cases:
      - ...
  - label: The label of the 3rd scenario
    cases:
      - ...

Only the top level YAML value can also be a YAML stream, which has zero or more documents.

---
label: The label of the 1st scenario
cases:
  - ...
---
- label: The label of the 2nd scenario
  cases:
    - ...
- label: The label of the 3rd scenario
  cases:
    - ...

Case

A “case” is the basic unit of verification, which executes a request and verify its response.

Key	Type	Default	Description
label	String	null	A label of this case.
request	Request	The default request	The request to be executed in this case.
response	ResponseDescription	The default response description	The response description of this case.
enabled	Boolean	true	Whether this case is enabled. See Ignore cases for more information.
when	List[Description]	[]	Run this case only when the context satisfies these description. See Context for more information.
wait	Duration	null	The waiting time before this case is run.

You can use default values to simplify cases. See Default Test for more information.

Request

Normally, a “request” is described in a form of a dictionary. When given only a string, that is equivalent to {path: it}.

Key	Type	Default	Description
method	String	GET	An HTTP method, which must be in GET, POST, PUT or DELETE.
path	String	''	A request path
headers	Map[String, String]	{}	The headers as a map of names to values.
params	URLParameters	{}	The URL parameters for the query string.
body	RequestBody	null	The request body.

Note

A request path can also contain query parameters like /path?foo=bar&spam=ham.

URLParameters

When given URL parameters as a string, then it is regarded as a raw query string.

# Requests /path?foo=bar&foo=baz&spam=ham%26eggs
request:
  path: /path
  params: foo=bar&foo=baz&spam=ham%26eggs

When given URL parameters as a dictionary, then it is regarded as a map of keys to values and the query string is built with it.

# Requests /path?foo=bar&foo=baz&spam=ham%26eggs
request:
  path: /path
  params:
    foo:  # a value list is available.
      - bar
      - baz
      - null  # `null` is ignored
    spam: ham&eggs

Note

Allowed types for the parameter values are integer, float, string, timestamp and null (ignored). A timestamp value is converted into IS0 8601 format.

RequestBody

Key	Type	Default	Description
type	String	urlencoded	The request body type, which is urlencoded or json.
data	Depends on the type	Depends on the type	The request body data.

When the type is urlencoded, the data are URLParameters and built into a URL-encoded value such that HTML forms send. When the type is json, the data are built into JSON. The typical Content-type header will be set automatically.

ResponseDescription

Key	Type	Default	Description
status_code	List[Predicate]	[]	Predicates that match a status code as an integer value. See Status code for more information.
headers	List[Description]	{}	Descriptions that describe the response headers. See Headers for more information.
body	List[Description]	null	Descriptions that describe the response body.

Status code

When given a number, that is equivalent to {"equal": it}.

Headers

Response headers are converted to be a JSON that is a map of names to values and can be described as a JSON (e.g. ."content-type"). Note that Names are lower-cased to normalize.

Description

Key	Type	Default	Description
describe	Extraction	Required	An extraction to get the described value.
should	List[Predicate]	{}	Predicates that match the described value.
as	String	null	The name of this value. The extracted value is stored in Context as this name when given.

Predicate

A Predicate is a Matcher (can be extended in the future).

Parameter

A “parameter” is a parameter in parameterized tests. See Parameterized Test for more information.

Key	Type	Default	Description
label	String	null	Label of this parameter.
args	Map	{}	An argument map of argument names to their values.