State

The Cicada state container is essentially a giant dictionary that gets tracks information generated in each test. You can set the test's inital state using a JSON file with the INITIAL_STATE_FILE setting.

Structure

The state container follows this structure:

{
    globals: {
      ...
    },
    test-name: {
        actions: {
            action-name: {
                results: [
                    {dictionary generated by runner}
                ],
                outputs: {
                    output-name: {value specified in test config}
                },
                asserts: {
                    assert-name: [
                        {
                            AssertResult
                        }
                    ]
                }
            },
            another-action-name: {...}
        },
        asserts: {
            assert-name: [
                {
                    AssertResult
                }
            ],
            another-action-name: [...]
        },
        summary: {
          description: Provided test description
          completed_cycles: Number of times all actions and asserts executed
          remaining_asserts: List of assert names that did not pass
          error: Reason test was ended early
          duration: Time in seconds to complete
        }
    },
    another-test-name: {
        ...
    }
}

Each test is added the the state container by ID. Under each test are the results of its actions and asserts as well as the summary of that test.

In addition, there is a special area called globals. This is used to hold config information that can be used in the test templates, such as from the initial state file.

Notice that the test-generated data is stored in lists. This can be changed to produce a single result (and overwrite the previous result) by setting the storeVersions parameter in actions, outputs, and asserts to false

Templates

The state container can be used in tests through a parameter called templates. The templates section will be rendered using Jinja2 and replaced into the config.

For example, let's say we wanted to make sure the API returns the Jeff that was created:

- name: check-jeff-added
  description: Checks that API returns new Jeff
  dependencies:
    - add-member
  runner: rest-runner
  asserts:
    - type: JSON
      template: >
        params:
          method: GET
          actionParams:
            url: http://api:8080/members/{{ state['add-member']['actions']['POST0']['results'][0]['body']['id'] }}
          expected:
            name: Jeff
            age: 25

When the action is run, this template will be rendered and the template section will be added to the assert config (ID may vary):

- name: check-jeff-added
  description: Checks that API returns new Jeff
  dependencies:
    - add-member
  runner: sql-runner
  asserts:
    - type: JSON
      params:
        method: GET
        actionParams:
          url: http://api:8080/members/123
        expected:
          name: Jeff
          age: 25

Besides the state container, the template also has access to the getenv function and the json library