Testing the API

This is all theory, although some of it is being put into practice on an internal project

At the moment the core of the API, under lib/sequencescape-api, is being tested with RSpec but this is not actually how it will be in the future. The intention is that JSON contracts will be used to not only check the behaviour of the code in this client library, but will also be made available for other client libraries to be built, as well as for testing the behaviour of the API on the server.

The intention is that a client application should be able to write Cucumber features that look something like this:

Scenario: Collecting the barcode
  Given the request and response for "a pending batch of 10 samples"
    And the request and response for "starting a batch of 10 samples"
    And the request and response for "updating the barcode to 100225674813"
   When I am on the barcode page
    And I fill in "Barcode" with "100225674813"
    And I press "Next"
   Then I should be on the information page
    And I should see "Barcode recorded"

The idea is that the first three steps, the ones that talk about request and response, will be loading files that describe the raw HTTP request and response, mocking the HTTP connections using Webmock to check the requests are both valid and made.

The raw files would look like this for a request:

GET /api/1/some_path HTTP/1.1
Accept: application/json
Cookie: COOKIE_FOR_SIGNON=value

Or for an update:

PUT /api/1/some_path HTTP/1.1
Accept: application/json
Content-Type: application/json
Cookie: COOKIE_FOR_SIGNON=value

{"root":{"attribute":"value"}}

And the response would be the equivalent raw HTTP response. Not all headers need to be included in either, just the crucial ones like Accept, Content-Type, Cookie and Location.

The step definitions and the raw HTTP request and response files will be made available through another project. In theory these steps could be translated to other languages and testing frameworks, enabling people to create client libraries using raw HTTP request and response files.

These can also be used to test the server side of the API, meaning that the interface between the client libraries and the server is defined once and used to test both.