Overview

The OpenActive Test Suite consists of two projects:

• ​openactive-broker-microservice - harvests feeds and provides an interface to extract specific items from the feeds.

• ​openactive-integration-tests - a suite of Jest integration tests that exercise an Open Booking API implementation.

Step 1: Install the test suite

Clone the test suite repository locally, and install its dependencies.

​Node.js version 12 or above is required.

git clone [email protected]:openactive/openactive-test-suite.git
cd openactive-test-suite
npm install

You can check that the test suite works in your local environment by running it against the hosted OpenActive Reference Implementation, simply by using the default configuration:

npm start

Step 2: Configure features

The list of Open Booking API features supported by the test suite can be found in the Test Suite Feature Coverage page.

For each optional feature, assess whether or not your implementation will include this.

Configure the test suite accordingly, as detailed in the reference documentation, for example:

./packages/openactive-integration-tests/config/default.json (extract)
 "implementedFeatures": {
    "opportunity-feed": true,
    "dataset-site": true,
    "availability-check": true,
    ...
  }

Step 3: Configure Opportunity Types

Set up the Opportunity Types that your booking system will support, as detailed in the reference documentation. The test suite will only attempt to book opportunity types that are configured here, for example:

./packages/openactive-integration-tests/config/default.json (extract)
  "bookableOpportunityTypesInScope": {
    "ScheduledSession": true,
    "FacilityUseSlot": false,
    "IndividualFacilityUseSlot": false,
    "CourseInstance": false,
    "CourseInstanceSubEvent": false,
    "HeadlineEvent": false,
    "HeadlineEventSubEvent": false,
    "Event": false,
    "OnDemandEvent": false
  },

Step 4: Choose Controlled vs Random testing mode

Choose which testing strategy to use. You can always start with one and switch to the other later.

Random mode

./packages/openactive-integration-tests/config/default.json (extract)
  "useRandomOpportunities": true

Selects random opportunities from the feeds that match the prerequisite criteria for each test, to book opportunities that already exist in the booking system

If using random mode, you must ensure that enough opportunities exist that cover the required criteria for all features that you are implementing. See the features list for a summary of how many opportunities are required for each criteria to test a specific feature. Please note that opportunities are not reused between tests within the same run of the test suite.

It is often straightforward to use Random mode for the more general features such as those in the core category. More specific features, that have more selective criteria for their opportunities, generally benefit from using Controlled mode.

Controlled mode

./packages/openactive-integration-tests/config/default.json (extract)
  "useRandomOpportunities": false

Automatically creates new opportunities in the booking system before each test run.

In order to enable controlled testing, you must implement the OpenActive Test Interface within your booking system. This interface allows the test suite to create opportunities that conform to specific criteria.

Your implementation of the OpenActive Test Interface itself can be tested using the test-interface feature.

The testDatasetIdentifier setting is used in all calls in the test interface. It allows any test data that was created with this identifier to be cleared before a new test run begins.

Step 5: Configure Sellers and Booking Authentication

The test suite will making all bookings under a specific primary Seller provided in the configuration, using the authentication request headers provided for that Seller.

If your booking system only supports a single seller, only the “primary” seller is required. If your booking system supports multiple sellers, the “secondary” seller must also be set to support the “multiple-sellers” tests.

See the reference documentation for more information.

./packages/openactive-integration-tests/config/default.json (extract)
  "sellers": {
    "primary": {
      "@type": "Organization",
      "@id": "https://bookingsystemreferenceimplementation.azurewebsites.net/api/identifiers/sellers/0",
      "requestHeaders": {
        "X-OpenActive-Test-Client-Id": "test",
        "X-OpenActive-Test-Seller-Id": "https://bookingsystemreferenceimplementation.azurewebsites.net/api/identifiers/sellers/0"
      }
    },
    "secondary": {
      "@type": "Person",
      "@id": "https://bookingsystemreferenceimplementation.azurewebsites.net/api/identifiers/sellers/1"
    }
  }

Step 6: Configure Orders Feed Authentication

Configure the broker microservice with the authentication headers required for the Orders Feed.

Note such authentication must not be specific to any particular seller.

./packages/openactive-broker-microservice/config/default.json (extract)
  "ordersFeedRequestHeaders": {
    "X-OpenActive-Test-Client-Id": "test"
  }

Step 7: Configure Dataset Site

The datasetSiteUrl must be set to the local dataset site URL of your booking system. If you have not yet implemented a dataset site, details for creating it can be found here.

In addition to the standard dataset site, the JSON-LD of the page must include the accessService property, as specified in the reference documentation. Note that the endpointURL within the accessService is most important, and must refer to your local Open Booking API Base URI.

./packages/openactive-broker-microservice/config/default.json (extract)
  "datasetSiteUrl": "https://bookingsystemreferenceimplementation.azurewebsites.net/openactive",

Step 8: Run the test suite

Option 1: Single console window

With your booking system running, execute the following command in the rootopenactive-test-suite directory:

npm start

This will automatically start the microservice, run the integration tests, then kill the microservice. The output from the microservice and integration tests will be combined in the console.

Individual features or tests can be run in isolation using the following commands, for example:

npm start -- --runInBand test/features/core/test-interface/

npm start -- --runInBand test/features/core/test-interface/implemented/create-opportunity-test.js

Option 2: Two separate console windows

Start the Microservice

With your booking system running, execute the following command in the openactive-broker-microservice directory:

npm start

This will start to harvest the feeds from your running application.

Run the Integration Tests

With both your booking system and openactive-broker-microservice running, execute the following command in the openactive-integration-tests directory, to execute all configured tests:

npm start

This will execute tests against your booking system, using the openactive-broker-microservice as an intermediary.

Individual features or tests can be run in isolation using the following commands, for example:

npm start -- --runInBand test/features/core/test-interface/

npm start -- --runInBand test/features/core/test-interface/implemented/create-opportunity-test.js 

Reading the test results and debugging

The openactive-integration-tests writes log files into the ./output/ directory for each test in Markdown format, so you can see the endpoints that have been called, with both the requests sent and responses received.

To understand the requests and responses, please see the explanation in the Open Booking API specification, along with the more detailed sequence diagram and example requests and responses.

If you don't have an IDE that supports Markdown natively, use a Google Chrome extension to read the output Markdown files, as described here.

A reference version of passing test results is also available for comparison, complete with full model requests and responses for each test:

• ​Output in 'Random' mode, when "useRandomOpportunities": true​

• ​Output in 'Controlled' mode, when "useRandomOpportunities": false​

Continuous Integration

For continuous integration environments run npm start in the rootopenactive-test-suite directory. This will automatically start the microservice, run the integration tests, then kill the microservice.

This always overrides the configuration option "waitForHarvestCompletion": true , to ensure the harvester is up-to-date with the feeds before the tests begin.

A sample CI script is available, and more details can be found here.

You can see CI in action within the test suite itself, which runs CI against the reference implementation.