doc: add more info on Broker and Tests

README.md

@@ -13,7 +13,7 @@ Running `npm start` in the root will run the OpenActive Test Suite, which is act
 
 # Usage
 
-Running `npm start` will orchestrate running the [Broker Microservice](./packages/openactive-broker-microservice/) and the [Integration Tests](./packages/openactive-integration-tests/) in order to test your Open Booking API implementation.
+Running `npm start` will orchestrate running the [Broker Microservice](./packages/openactive-broker-microservice/) and a one-off run of the [Integration Tests](./packages/openactive-integration-tests/) in order to test your Open Booking API implementation.
 
 Note that the implementation under test will need to implement the [OpenActive Test Interface](https://openactive.io/test-interface/) to run in controlled mode, and for selected tests.
 
@@ -403,6 +403,8 @@ The Test Suite Certificate should be updated upon each successfull CI run.
 
 In order to run the tests in random mode, the target Open Booking API implementation will need to have some Opportunity data pre-loaded. Use [Test Data Generator](./packages/openactive-integration-tests/test-data-generator/) to find out how much data is needed and in what configuration.
 
+It is recommeneded that, during developement of an Open Booking API, the test data is kept to a minimum, ie what is needed to pass the features under test. This allows the [Broker Microservice](./packages/openactive-broker-microservice/README.md) to complete its [Initial Harvest](./packages/openactive-broker-microservice/README.md#initial-harvest) quicker and allows the [Integration Tests](./packages/openactive-integration-tests/README.md) to run more quickly.
+
 ## Certification
 
 An OpenActive Conformance Certificate offers a mechanism by which implementing systems can prove their conformance to the OpenActive specifications. Test Suite can be configured to output a Conformance Certificate upon all tests passing.

packages/openactive-broker-microservice/README.md

@@ -13,6 +13,8 @@ Broker Microservice sits in front of a [Booking System](#booking-system-under-te
 
 It needs to be running, against a Booking System, in order for the [openactive-integration-tests](../openactive-integration-tests/) to run.
 
+The Broker can take some time to start up as it must harvest and validate data from the Booking System's feeds. The larger the Booking System's feeds, the longer it will take and the Integration Tests will not start until the Broker has finished harvesting (unless the `waitForHarvestCompletion` config is set to `false`, see [Configuration](#configuration-for-broker-within-config-node_env-json) below).
+
 ## Usage in separate terminal windows
 
 To run `openactive-broker-microservice` in separate terminal window to `openactive-integration-tests`, from repository root:

packages/openactive-integration-tests/README.md

@@ -1,6 +1,8 @@
 # openactive-integration-tests
 
-This Node.js script runs tests against the specified openactive-broker-microservice instance
+The Integration Tests are a component of the OpenActive Test Suite. They contain the collection of tests that are used to validate the Open Booking API implementation of a Booking System.
+
+They cannot be run standalone, but must be run in conjunction with the [Broker Microservice](../openactive-broker-microservice/README.md).
 
 ## Test coverage
 
@@ -13,6 +15,9 @@ The results of this test suite when run against the reference implementation can
 
 ## Usage in separate terminal windows
 
+It is sometimes useful to run `openactive-integration-tests` in a separate terminal window to `openactive-broker-microservice`.
+When running many tests, especially against larger feeds, it can be more helpful to run the Broker Microservice in a separate terminal window and run individual tests in the separate terminal window. Keeping the Broker running in the background allows test failures to be debugged and rerun without having to restart the Broker.
+
 To run `openactive-integration-tests` in separate terminal window to `openactive-broker-microservice`, from repository root:
 
 1. Ensure the [openactive-broker-microservice](../openactive-broker-microservice/) is running in another terminal window