Merge branch 'master' into feature/workflows-readme

.github/workflows/code-tests.yml

@@ -14,10 +14,10 @@ jobs:
     steps:
     - name: Checkout OpenActive Test Suite
       uses: actions/checkout@v2
-    - name: Setup Node.js 14.x
+    - name: Setup Node.js 18.17.1
       uses: actions/setup-node@v1
       with:
-        node-version: 14.x
+        node-version: 18.17.1
     - name: Install OpenActive Test Suite
       run: npm install
     - name: Run Checks on the Code (Test the Tests!)

.github/workflows/create-data-model-pr.yaml

@@ -16,10 +16,10 @@ jobs:
           ref: master
           path: openactive-test-suite
 
-      - name: Setup Node.js 14.x
+      - name: Setup Node.js 18.17.1
         uses: actions/setup-node@v1
         with:
-          node-version: 14.x
+          node-version: 18.17.1
 
       - name: Update openactive-integration-tests with latest data-models and validators
         run: npm install @openactive/data-models@latest @openactive/data-model-validator@latest --save
@@ -48,6 +48,14 @@ jobs:
             automated pr
           draft: false
 
+      - name: Enable Pull Request Automerge
+        if: steps.cpr.outputs.pull-request-operation == 'created'
+        uses: peter-evans/enable-pull-request-automerge@v3
+        with:
+          token: ${{ secrets.PUBLIC_REPO_ACCESS_TOKEN }}
+          pull-request-number: ${{ steps.cpr.outputs.pull-request-number }}
+          merge-method: squash
+
       - name: Check outputs
         run: |
           echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"

.github/workflows/reference-implementation.yml

@@ -48,10 +48,10 @@ jobs:
       with:
         dotnet-version: 3.1.419
 
-    - name: Setup Node.js 14.x
+    - name: Setup Node.js 18.17.1
       uses: actions/setup-node@v1
       with:
-        node-version: 14.x
+        node-version: 18.17.1
 
     - name: Install OpenActive.Server.NET dependencies
       run: dotnet restore ./server/

.nvmrc

@@ -1 +1 @@
-v14.16.0
+v18.17.1

.vscode/launch.json

@@ -19,7 +19,7 @@
                 "<node_internals>/**"
             ],
             "type": "node",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "env": {
                 "NODE_APP_INSTANCE": "dev",
                 "NODE_CONFIG": "{\"integrationTests\": {\"useRandomOpportunities\": false}}"
@@ -40,7 +40,7 @@
                 "<node_internals>/**"
             ],
             "type": "node",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "env": {
                 "NODE_APP_INSTANCE": "dev",
                 "NODE_CONFIG": "{\"integrationTests\": {\"useRandomOpportunities\": true}}"
@@ -52,7 +52,7 @@
             "request": "launch",
             "cwd": "${workspaceFolder}/packages/openactive-integration-tests",
             "runtimeExecutable": "npm",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "runtimeArgs": ["run-script", "debug"],
             "env": {
                 "NODE_APP_INSTANCE": "dev",
@@ -66,7 +66,7 @@
             "request": "launch",
             "cwd": "${workspaceFolder}/packages/openactive-integration-tests",
             "runtimeExecutable": "npm",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "runtimeArgs": ["run-script", "debug"],
             "env": {
                 "NODE_APP_INSTANCE": "dev",
@@ -80,7 +80,7 @@
             "request": "launch",
             "cwd": "${workspaceFolder}/packages/openactive-integration-tests",
             "runtimeExecutable": "npm",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "runtimeArgs": ["run-script", "debug"],
             "env": {
                 "NODE_ENV": "dev",
@@ -91,18 +91,31 @@
             "name": "broker-microservice",
             "type": "node",
             "request": "launch",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "program": "${workspaceFolder}/packages/openactive-broker-microservice/app.js",
             "cwd": "${workspaceFolder}/packages/openactive-broker-microservice/",
             "env": {
               "NODE_APP_INSTANCE": "dev"
             },
         },
+        {
+            "name": "test-interface-criteria - unit tests",
+            "type": "node",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/packages/test-interface-criteria/",
+            "runtimeArgs": [
+              "--inspect-brk",
+              "node_modules/.bin/jest",
+              "--runInBand"
+              ],
+            "console": "integratedTerminal",
+            "internalConsoleOptions": "neverOpen"
+        },
         {
             "name": "validate-feeds",
             "type": "node",
             "request": "launch",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "program": "${workspaceFolder}/packages/openactive-broker-microservice/app.js",
             "cwd": "${workspaceFolder}/packages/openactive-broker-microservice/",
             "args": [
@@ -117,31 +130,31 @@
             "name": "test-data-generator",
             "type": "node",
             "request": "launch",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "program": "${workspaceFolder}/packages/openactive-integration-tests/test-data-generator/test-data-generator.js",
             "cwd": "${workspaceFolder}/packages/openactive-integration-tests/"
         },
         {
             "name": "certification-validator-microservice",
             "type": "node",
             "request": "launch",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "program": "${workspaceFolder}/packages/openactive-integration-tests/test/certification/certification-validator-microservice.js",
             "cwd": "${workspaceFolder}/packages/openactive-integration-tests/",
         },
         {
             "name": "doc-gen",
             "type": "node",
             "request": "launch",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "program": "${workspaceFolder}/packages/openactive-integration-tests/documentation/generator.js",
             "cwd": "${workspaceFolder}/packages/openactive-integration-tests/"
         },
         {
             "name": "combined",
             "type": "node",
             "request": "launch",
-            "runtimeVersion": "14.16.0",
+            "runtimeVersion": "18.17.1",
             "autoAttachChildProcesses": true,
             "program": "${workspaceFolder}/start.js",
             "env": {

CONTRIBUTING.md

@@ -61,3 +61,7 @@ For new features that affect test coverage, use a `coverage/*` branch in this re
 2. Ensure that documentation reflects the new changes.
 3. Check that CI tests pass before merging a Pull Request.
 4. Ensure that your Pull Request has at least one approval before merging.
+
+## Writing a new test
+
+See the [Integration Tests CONTRIBUTING.md](./packages/openactive-integration-tests/CONTRIBUTING.md) for guidance on writing a new test.

README.md

@@ -4,14 +4,16 @@ To join the conversation, we're on the [OpenActive Slack](https://slack.openacti
 
 The general aim of this project is to allow end to end testing of the various flows and failure states of the Open Booking API.
 
-Running `npm start` in the root will run the OpenActive Test Suite, which is actually comprised of three packages:
-* [OpenID Test Client](./packages/openactive-openid-test-client): this connects to the target Open Booking API's OpenID Provider. This allows the Broker and Integration tests to authorize with the implementation
-* [Broker Microservice](./packages/openactive-broker-microservice/): this sits in between the test suite and the target Open Booking API implementation. This allows the integration tests to watch for changes to the various RPDE feeds.
+Running `npm start` in the root will run the OpenActive Test Suite, which is actually comprised of these packages:
+
 * [Integration Tests](./packages/openactive-integration-tests): this performs automated tests against the API.
+* [Broker Microservice](./packages/openactive-broker-microservice/): this sits in between the test suite and the target Open Booking API implementation. This allows the integration tests to watch for changes to the various RPDE feeds.
+* [OpenID Client](./packages/openactive-openid-client), [OpenID Browser Automation](./packages/openactive-openid-browser-automation) and [OpenID Test CLI](./packages/openactive-openid-test-cli): together these connect to the target Open Booking API's OpenID Provider. This allows the Broker and Integration tests to authorize with the implementation
+* [Test Interface Criteria](./packages/test-interface-criteria/): this allows test suite to tailor specific opportunities to specific tests by implementing the [OpenActive Test Interface](https://openactive.io/test-interface/) Criteria.
 
 # Usage
 
-Running `npm start` will orchestrate running the [OpenID Test Client](./packages/openactive-openid-test-client/), [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 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.
 
@@ -31,25 +33,149 @@ Note that the above command only runs the "core" tests within the test suite, wh
 The hosted OpenActive Reference Implementation is running on a basic developer tier Azure instance with a burst quota, so it will not handle the load of a test suite run for all tests (hence `npm start -- core`); if the hosted application shuts down, simply wait 5 minutes and try again.
 
 ## Configuration
+
 In order to run the test suite against your own implementation, configure the test suite by creating a copy of [`config/default.json`](./config/default.json) named `config/{NODE_ENV}.json` (where `{NODE_ENV}` is the value of your `NODE_ENV` environment variable), including the following properties:
    - [`broker` microservice configuration](./packages/openactive-broker-microservice/#configuration-for-broker-within-confignode_envjson)
    - [`integrationTests` and `sellers` configuration](./packages/openactive-integration-tests/#configuration-for-integrationtests-within-confignode_envjson)
 
-The test suite uses the file `config/{NODE_ENV}.json` to override the settings in `default.json`. It is recommended that for development and deployment a such a new file is created instead of making changes to the `default.json` file, so that any new required settings that are added in future versions can be automatically updated in `default.json`.
+The test suite uses the file `config/{NODE_ENV}.json` to override the settings in `default.json`. For development and deployment create a new file instead of making changes to the `default.json` file, so that any new required settings that are added in future versions can be automatically updated in `default.json`.
+
+For more information about this use of `NODE_ENV` see this [documentation](https://github.com/lorenwest/node-config/wiki/Environment-Variables#node_env).
+
+By convention, much of the documentation assumes you to have created a `config/dev.json` file, which Test Suite will use when env var `NODE_ENV=dev`. But you can use any name you like, and have multiple configuration files for different environments.
+
+### Configuration for `sellers` within `./config/{NODE_ENV}`
+
+The `primary` Seller is used for all tests, and random opportunities used when `"useRandomOpportunities": true` are selected from this Seller. The `secondary` Seller is used only for [multiple-sellers](./test/features/core/multiple-sellers/README.md) tests.
+
+An example, using OpenID Connect Authentication:
+
+```json
+  "sellers": {
+    "primary": {
+      "@type": "Organization",
+      "@id": "https://reference-implementation.openactive.io/api/identifiers/sellers/0",
+      "authentication": {
+        "loginCredentials": {
+          "username": "test1",
+          "password": "test1"
+        }
+      },
+      "taxMode": "https://openactive.io/TaxGross",
+      "paymentReconciliationDetails": {
+        "name": "AcmeBroker Points",
+        "accountId": "SN1593",
+        "paymentProviderId": "STRIPE"
+      }
+    },
+    "secondary": {
+      "@type": "Person",
+      "@id": "https://reference-implementation.openactive.io/api/identifiers/sellers/1",
+      "authentication": {
+        "loginCredentials": {
+          "username": "test2",
+          "password": "test2"
+        }
+      },
+      "taxMode": "https://openactive.io/TaxNet"
+    }
+  }
+```
+
+Description of each field:
+
+* `authentication`: Check out the [**Configuration for Seller Authentication**](#configuration-for-seller-authentication) section.
+* `taxMode`: Which [Tax Mode](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#tax-mode) is used for this Seller.
+
+  **Note: If testing both Tax Modes, make sure that there is at least one Seller with each**. Alternatively, if not supporting multiple Sellers, you can run the Test Suite once with `"taxMode": "https://openactive.io/TaxNet"` and once with `"taxMode": "https://openactive.io/TaxGross"`. However, it is not currently possible to generate a certificate that covers both configurations unless multiple Sellers are supported.
+* `paymentReconciliationDetails`: If testing [Payment Reconciliation Detail Validation](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#payment-reconciliation-detail-validation), include the required payment reconciliation details here.
+
+### Configuration for Seller Authentication
+
+In order to make bookings for a specific Seller's Opportunity data, some kind of authentication is required to ensure that the caller is authorized to make bookings for that Seller.
+
+Test Suite allows for a few different options for Seller Authentication. This determines the data to put in the `authentication` field for each Seller:
 
-For more information see this [documentation](https://github.com/lorenwest/node-config/wiki/Environment-Variables#node_env).
+#### OpenID Connect
+
+[View Spec](https://openactive.io/open-booking-api/EditorsDraft/#openid-connect-booking-partner-authentication-for-multiple-seller-systems)
+
+You'll need the username/password that the Seller can use to log in to your OpenID Connect Provider.
+
+Example:
+
+```json
+  "sellers": {
+    "primary": {
+      // ...
+      "authentication": {
+        "loginCredentials": {
+          "username": "test1",
+          "password": "test1"
+        }
+      }
+    },
+```
+
+#### Request Headers
+
+Just a set of request HTTP headers which will be used to make booking requests. There are no restrictions on the `requestHeaders` that can be specified.
+
+Example:
+
+```json
+  "sellers": {
+    "primary": {
+      // ...
+      "authentication": {
+        "loginCredentials": null,
+        "requestHeaders": {
+          "X-OpenActive-Test-Client-Id": "booking-partner-1",
+          "X-OpenActive-Test-Seller-Id": "https://localhost:5001/api/identifiers/sellers/1"
+        }
+      }
+    },
+```
+
+#### Client Credentials
+
+[OAuth Client Credentials](https://oauth.net/2/grant-types/client-credentials/) are used to make booking requests.
+
+Example:
+
+```json
+  "sellers": {
+    "primary": {
+      // ...
+      "authentication": {
+        "loginCredentials": null,
+        "clientCredentials": {
+          "clientId": "clientid_XXX",
+          "clientSecret": "example"
+        }
+      }
+    },
+```
+
+This is different from the behaviour in the Client Credentials sub-section mentioned within the [OpenID Connect Booking Partner Authentication for Multiple Seller Systems](https://openactive.io/open-booking-api/EditorsDraft/#openid-connect-booking-partner-authentication-for-multiple-seller-systems) section in the spec as, in this case, Client Credentials are used to make booking requests for this Seller, rather than just to view the Booking Partner's Orders Feed.
 
 ## Installation
 
-Node.js version 14 or above is required.
+First, ensure that you have the correct Node.js version installed. We recommend managing this with [Node Version Manager (NVM)](https://github.com/nvm-sh/nvm). If you use NVM, switch to the correct version of Node.js with:
+
+```sh
+nvm use
+```
+
+Otherwise, get the correct version of Node.js from the [`.nvmrc`](./.nvmrc) file.
+
+Then, install the dependencies needed for all packages in the test suite:
 
 ```bash
 npm install
 ```
-
-This will install the dependencies needed for all packages in the test suite.
 
-For developers that are customising the installation, for use in e.g. Docker, the directory `./packages/test-interface-criteria` is a dependency, and so must be present during `npm install`.
+For developers that are customising the installation, for use in e.g. Docker, the directories `./packages/openactive-openid-browser-automation`, `./packages/openactive-openid-client`, `./packages/openactive-openid-test-cli`, `./packages/openactive-openid-test-client` and `./packages/test-interface-criteria` are dependencies, and so must be present during `npm install`.
 
 ## Running
 
@@ -140,3 +266,23 @@ In order to run the tests in random mode, the target Open Booking API implementa
 # Contributing
 
 - [Contributing to the project](./CONTRIBUTING.md)
+
+# Concepts
+
+## Booking Partner Authentication Strategy
+
+The method by which a [Booking Partner](https://openactive.io/open-booking-api/EditorsDraft/#dfn-booking-partner) authenticates with the Open Booking API implementation. There are a number of supported strategies, including OpenID Connect, HTTP Header, etc.
+
+Your impementation will need to support at least one Authentication Strategy for each of [**Orders Feed Authentication**](#orders-feed-authentication) and [**Booking Authentication**](#booking-authentication).
+
+### Orders Feed Authentication
+
+How a Booking Partner accesses the [Orders Feed](https://openactive.io/open-booking-api/EditorsDraft/#dfn-orders-feed) containing updates to Orders that they have created.
+
+For Test Suite, the selected Orders Feed Authentication Strategy is configured with the [`broker.bookingPartners` configuration property](./packages/openactive-broker-microservice/README.md#bookingpartners) and documentation on the supported strategies can be found there.
+
+### Booking Authentication
+
+How a Booking Partner accesses the booking endpoints (C1, C2, B, etc) for a specific Seller's data. This differs from [Orders Feed Authentication](#orders-feed-authentication) as it can be specified at the per-Seller level for Multiple Seller Systems (relevant feature: [`multiple-sellers`](packages/openactive-integration-tests/test/features/core/multiple-sellers/)).
+
+For Test Suite, the selected Booking Authentication Strategy is configured with the [`sellers` configuration property](#configuration-for-seller-authentication) and documentation on the supported strategies can be found there.

config/default.json

@@ -134,7 +134,8 @@
           }
         }
       }
-    }
+    },
+    "useShapeExpressions": false
   },
   "sellers": {
     "primary": {