test: Setup E2E tests for user roles (#2220)

api.planx.uk/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "dependencies": {
     "@airbrake/node": "^2.1.8",
-    "@opensystemslab/planx-core": "git+https://github.com/theopensystemslab/planx-core#7e31b2e",
+    "@opensystemslab/planx-core": "git+https://github.com/theopensystemslab/planx-core#44e9ebe",
     "@types/isomorphic-fetch": "^0.0.36",
     "adm-zip": "^0.5.10",
     "aws-sdk": "^2.1441.0",

e2e/README.md

@@ -11,7 +11,7 @@ We use [Playwright](https://playwright.dev/docs/api/class-test) to run UI driven
 
 ## API driven tests
 
-We use [Gherkin](https://cucumber.io/docs/gherkin/reference) to run API tests where interactions are simulated via automated network requests.
+We use [Gherkin](https://cucumber.io/docs/gherkin/reference) to run API tests where interactions are simulated via automated network requests. For more details please see [our README here](https://github.com/theopensystemslab/planx-new/blob/main/e2e/tests/api-driven/README.md)).
 
 
 # Running Tests

e2e/tests/api-driven/README.md

@@ -0,0 +1,27 @@
+# API-Driven Tests
+
+This subfolder contains end-to-end (E2E) tests aimed at testing the logic of interactions between our services, without requiring a front-end interface to drive user interactions.
+
+These tests may require interaction with various services, such as Hasura and a PostgreSQL database, or a mocked third-party service such as Uniform or BOPS.
+
+## Stack
+
+- **Gherkin**: Gherkin is a language used for specifying structured test scenarios [(docs)](https://docs.cucumber.io/gherkin/reference/)
+- **Cucumber-JS**: Cucumber-JS is a JavaScript implementation of the Cucumber framework, allowing us to write and run behaviour-driven development (BDD) tests [(docs)](https://github.com/cucumber/cucumber-js)
+- **Node.js assert**: The `assert` module in Node.js is used for making assertions in our tests [(docs)](https://nodejs.org/api/assert.html). If we find this to be insufficient we could move to a richer assertation library such as Jest.
+
+## Basic setup for adding new tests
+
+To add new tests to this folder, follow these steps:
+
+1. Create a subfolder for each test scenario you want to test.
+
+2. Inside each test subfolder, include the following files:
+
+   - `<YOUR_FEATURE>.feature` file: This file contains the Gherkin syntax to describe the test scenario in a human-readable format. It outlines the steps and expected behaviour of the test.
+   - `helpers.ts` file: This file should contain utility functions and setup/cleanup logic for your test. At a minimum, it should include the following functions:
+
+     - `setup()`: This function sets up the necessary environment or configurations required for the test scenario.
+     - `cleanup()`: This function performs cleanup tasks after the test scenario is executed, such as resetting the environment to its initial state.
+
+   - `steps.ts` file: This file contains the step definitions for your Gherkin scenarios. Each step definition maps a step in the `.feature` file to a function that performs the corresponding action and assertion in your test. We aim to keep these steps as readable as possible, with the majority of the logic being contained within `helpers.ts`.

e2e/tests/api-driven/package.json

@@ -6,13 +6,16 @@
   },
   "dependencies": {
     "@cucumber/cucumber": "^9.3.0",
-    "@opensystemslab/planx-core": "git+https://github.com/theopensystemslab/planx-core#4e3d09f",
+    "@opensystemslab/planx-core": "git+https://github.com/theopensystemslab/planx-core#44e9ebe",
     "axios": "^1.4.0",
     "dotenv": "^16.3.1",
     "dotenv-expand": "^10.0.0",
+    "graphql-request": "^6.1.0",
+    "jsonwebtoken": "^9.0.2",
     "nock": "^13.3.1"
   },
   "devDependencies": {
+    "@types/lodash.zipobject": "^4.1.7",
     "@types/node": "18.16.1",
     "ts-node": "^10.9.1",
     "typescript": "^5.1.6"