Tutorial

To demonstrate typical usage of Brine, let’s write some tests against http://myjson.com/api (selected fairly arbitrarily from the list at https://github.com/toddmotto/public-apis).

Setting BRINE_ROOT_URL

Brine expects steps to use relative URLs. The feature files specify the behavior of an API (or multiple APIs), while the root of the define where to reach that API, so this should align with a natural separation of API behavior and location. More practically an API is likely to exist across various environments such as local, qa, stage, and production; having a parameterized root for the URLs eases switching between these while encouraging inter-environment consistency.

When all tests are to be run against the same root url, the value of the root can be specified with the environment variable BRINE_ROOT_URL. This can be set when running Cucumber with a command such as:

BRINE_ROOT_URL=https://api.myjson.com/ cucumber

or by any other means that populates the environment appropriately.

A personally preferred approach is to have per-environment make files and include the desired file(s) into the main make file with a line such as:

A Basic GET

Most tests will involve some form of issuing requests and performing assertions on the responses. Let’s start with a simple version of that pattern: testing the response status from a GET request.

Feature: Absent resources return 404s.

  Scenario: A request for a known missing resource.
    When a GET is sent to `/bins/brine-absent`
    Then the value of the response status is equal to `404`

A Write Request

For POST, PATCH, and PUT requests you’ll normally want to include a request body. To support this, additional data can be added to requests before they are sent.

Feature: A POST returns a 201.

  Scenario: A valid post.
    When the request body is assigned:
      """
      {"name": "boolean-setting",
       "value": true}
      """
    And a POST is sent to `/bins`
    Then the value of the response status is equal to `201`

See also

Steps

Request Construction

Test Response Properties

http://myjson.com/api returns the link to the created resource which is based off of a generated id. That means the exact response cannot be verified, but instead property based testing can be done to verify that the data is sane and therefore likely trustworthy. In this case we can check that the uri response child matches the expected pattern.

Feature: A POST returns a link to the created resource.

  Scenario: A valid post.
    When the request body is assigned:
      """
      {"name": "boolean-setting",
       "value": true}
      """
    And a POST is sent to `/bins`

    Then the value of the response status is equal to `201`
    And the value of the response body child `uri` is matching `/https://api.myjson.com/bins/\w+/`