Documentation tidy up

dlzhry2nhs · dlzhry2nhs · commit 7f354d55c3db · 2026-01-20T17:17:21.000Z
diff --git a/README.md b/README.md
@@ -52,10 +52,9 @@ See https://nhsd-confluence.digital.nhs.uk/display/APM/Glossary.
 
 ### Tests
 
-| Folder      | Description                                                                          |
-| ----------- | ------------------------------------------------------------------------------------ |
-| `e2e`       | End-to-end tests executed during PR pipelines.                                       |
-| `e2e_batch` | E2E tests specifically for batch-related functionality, also run in the PR pipeline. |
+| Folder           | Description                                                                   |
+| ---------------- | ----------------------------------------------------------------------------- |
+| `e2e_automation` | End-to-end tests executed during PR pipelines using the pytest-bdd framework. |
 
 ---
 
@@ -143,7 +142,7 @@ Steps:
 
 ### Setting up a virtual environment with poetry
 
-The steps below must be performed in each Lambda function folder and e2e folder to ensure the environment is correctly configured.
+The steps below must be performed in each Lambda function folder and e2e_automation folder to ensure the environment is correctly configured.
 
 For detailed instructions on running individual Lambdas, refer to the README.md files located inside each respective Lambda folder.
 
diff --git a/sonar-project.properties b/sonar-project.properties
@@ -3,7 +3,7 @@ sonar.projectKey=NHSDigital_immunisation-fhir-api
 sonar.organization=nhsdigital
 sonar.host.url=https://sonarcloud.io
 sonar.python.version=3.11
-sonar.exclusions=**/e2e/**,**/e2e_batch/**,**/devtools/**,**/proxies/**,**/utilities/scripts/**,**/infrastructure/account/**,**/infrastructure/instance/**,**/infrastructure/grafana/**,**/terraform_aws_backup/**,**/tests/**
+sonar.exclusions=**/devtools/**,**/proxies/**,**/utilities/scripts/**,**/infrastructure/account/**,**/infrastructure/instance/**,**/infrastructure/grafana/**,**/terraform_aws_backup/**,**/tests/**
 sonar.coverage.exclusions=lambdas/shared/src/common/models/batch_constants.py
 sonar.python.coverage.reportPaths=backend-coverage.xml,delta-coverage.xml,ack-lambda-coverage.xml,filenameprocessor-coverage.xml,recordforwarder-coverage.xml,recordprocessor-coverage.xml,mesh_processor-coverage.xml,redis_sync-coverage.xml,mns_subscription-coverage.xml,id_sync-coverage.xml,shared-coverage.xml,batchprocessorfilter-coverage.xml
 sonar.cpd.exclusions=**/Dockerfile
diff --git a/tests/e2e_automation/.env.example.dynamic b/tests/e2e_automation/.env.example.dynamic
@@ -1,24 +1,24 @@
+# Do not change these 3 values. We always use internal-dev for dynamic mock auth in all APIM Apigee non-prod environments
 auth_url=https://internal-dev.api.service.nhs.uk/oauth2-mock/authorize
 token_url=https://internal-dev.api.service.nhs.uk/oauth2-mock/token
 callback_url=https://oauth.pstmn.io/v1/callback
+
 # Obtain value from dev/testing team
 STATUS_API_KEY=
+username=
+scope=
 
-username=aal3
-scope=nhs-cis2
-
-# Internal-dev PR environment
+# Set all the below values based on the environment you are testing e.g. pr-xxx, internal-dev, internal-qa
 baseUrl=https://internal-dev.api.service.nhs.uk/immunisation-fhir-api/FHIR/R4-pr-123
 aws_token_refresh=False
-aws_profile_name=345594581768_DEV-IMMS-Devops
+aws_profile_name={your-aws-profile}
 
 S3_env=pr-123
-# LOCAL_RUN_WITHOUT_S3_UPLOAD = True
 LOCAL_RUN_FILE_NAME=HPV_Vaccinations_v5_V0V8L_20251111T16304982.csv
 AWS_DOMAIN_NAME=pr-123.imms.dev.vds.platform.nhs.uk
 
 PROXY_NAME=immunisation-fhir-api-pr-123
 # See README for details on how to obtain this
 APIGEE_ACCESS_TOKEN={use-the-apigee-get-token-utility}
 APIGEE_USERNAME={your-apigee-developer-email}
-APIGEE_ENVIRONMENT={the-relevant-apigee-env}  # E.g. internal-dev, internal-qa
+APIGEE_ENVIRONMENT={the-relevant-apigee-env}# E.g. internal-dev, internal-qa
diff --git a/tests/e2e_automation/.env.example.static b/tests/e2e_automation/.env.example.static
@@ -1,14 +1,19 @@
-username=joebloggs
-scope=nhs-xyz
-aws_token_refresh= True
-########## INT env 
+aws_token_refresh=True
+USE_STATIC_APPS=True
+
+########## INT env variables
 # baseUrl=https://int.api.service.nhs.uk/immunisation-fhir-api/FHIR/R4
 # auth_url=https://int.api.service.nhs.uk/oauth2-mock/authorize
 # token_url=https://int.api.service.nhs.uk/oauth2-mock/token
 # callback_url=https://oauth.pstmn.io/v1/callback
 # S3_env=int
 # aws_profile_name={your-aws-profile}
+# PROXY_NAME=immunisation-fhir-api-int
 ## Id/Secret values - please contact Dev or Test team to get these values
+# username=
+# scope=
+# STATUS_API_KEY=
+# AWS_DOMAIN_NAME=
 # Postman_Auth_client_Id=
 # Postman_Auth_client_Secret=
 # RAVS_client_Id=
@@ -23,14 +28,18 @@ aws_token_refresh= True
 # TPP_client_Secret=
 # MEDICUS_client_Id=
 # MEDICUS_client_Secret=
-########## Internal-QA env
+
+########## Internal-QA env variables
 baseUrl=https://internal-qa.api.service.nhs.uk/immunisation-fhir-api/FHIR/R4
 auth_url=https://internal-qa.api.service.nhs.uk/oauth2-mock/authorize
 token_url=https://internal-qa.api.service.nhs.uk/oauth2-mock/token
 callback_url=https://oauth.pstmn.io/v1/callback
 S3_env=internal-qa
 aws_profile_name={your-aws-profile}
+PROXY_NAME=immunisation-fhir-api-internal-qa
 ## Id/Secret values - please contact Dev or Test team to get these values
+username=
+scope=
 STATUS_API_KEY=
 AWS_DOMAIN_NAME=
 Postman_Auth_client_Id=
diff --git a/tests/e2e_automation/Makefile b/tests/e2e_automation/Makefile
@@ -1,7 +1,7 @@
 -include .env
 
 cmd = poetry run pytest
-
+# Add sandbox, add to README
 test:
 	$(cmd)
 
@@ -17,5 +17,8 @@ test-batch-smoke:
 test-batch-full:
 	$(cmd) features/batchTests -m functional
 
+test-sandbox:
+	$(cmd) features -m sandbox
+
 collect-only:
 	$(cmd) --collect-only
diff --git a/tests/e2e_automation/README.md b/tests/e2e_automation/README.md
@@ -4,81 +4,58 @@ This directory contains End-to-end Automation Tests for the Immunisation FHIR AP
 
 ## Setting up e2e_automation tests to run locally
 
-Update README with the changes to use get_token
-
 1. Follow the instructions in the root level README.md to setup the [dependencies](../../README.md#environment-setup) and create a [virtual environment](../../README.md#setting-up-a-virtual-environment-with-poetry) for this folder (`e2e_automation`).
+2. Run `poetry install --no-root` to install dependencies.
+3. Ensure you are authenticated with AWS in your terminal, using your preferred method.
+4. Choose which approach you wish to use: static apps or temporary apps. Temporary apps are the recommended way to go as
+   they are spun up and torn down on each test run, therefore requiring fewer env vars and less operational overhead. Skip
+   to the relevant section below depending on which approach you are going to use.
 
-2. Add values to the .env file.
-
-    For an example of a template .env file, see [.env.example](./.env.example).
-
-    The following values should be added:
-
-    ```
-    aws_token_refresh=True
-    baseUrl=https://internal-qa.api.service.nhs.uk/immunisation-fhir-api/FHIR/R4
-    auth_url=https://internal-qa.api.service.nhs.uk/oauth2-mock/authorize
-    token_url=https://internal-qa.api.service.nhs.uk/oauth2-mock/token
-    callback_url=https://oauth.pstmn.io/v1/callback
-    S3_env=internal-qa
-    aws_profile_name={your-profile}
-    ```
-
-3. Add login and secret values to the .env file.
-
-    **Please contact the Imms FHIR API Test team to get these values.**
-
-    The following values should be added:
-
-    ```
-    username
-    scope
-    STATUS_API_KEY
-    AWS_DOMAIN_NAME
-    Postman_Auth_client_Id
-    Postman_Auth_client_Secret
-    RAVS_client_Id
-    RAVS_client_Secret
-    MAVIS_client_Id
-    MAVIS_client_Secret
-    EMIS_client_Id
-    EMIS_client_Secret
-    SONAR_client_Id
-    SONAR_client_Secret
-    TPP_client_Id
-    TPP_client_Secret
-    MEDICUS_client_Id
-    MEDICUS_client_Secret
-    ```
-
-4. Run `poetry install --no-root` to install dependencies.
-
-5. The `Makefile` in this directory provides the following commands:
+## Setup when using on demand apps
 
-- `make test` - run all tests (may take some time)
-- `make test-api-full` - run API tests
-- `make test-api-smoke` - run API smoke tests only (quicker)
-- `make test-batch-full` - run Batch tests
-- `make test-batch-smoke` - run Batch smoke tests only (quicker)
-- `make collect-only` - check that all tests are discovered
+**NOTE:** this approach cannot be used in INT. Both INT and PROD (we do not test here) belong to the APIM Apigee prod
+organisation so there is no support for creating apps on the fly.
 
-## Running e2e_automation tests against PR environments
+**Background:** this approach uses the Apigee API to create and teardown applications during a test run. This is the
+approach used in the pipeline for all APIM non-prod environments: internal-dev, internal-qa, pr and so forth.
 
-Need to update this in PR and explain how to use static apps if desired locally.
+1. Configure your .env file with the required values.
 
-The environment variables define a client ID and client secret for each of the Apigee test apps we use in static
-environments such as `internal-dev`, `internal-qa` and so on.
+    The [.env.example.dynamic](./.env.example.dynamic) template defines all the values you will need and explains how
+    to obtain them. Most will be simple enough, based on the environment you wish to test. However, there is the
+    `STATUS_API_KEY` which you will need to ask the testers or tech lead for, and `APIGEE_ACCESS_TOKEN` which is outlined
+    below.
 
-However, creating pull requests will spin up a dynamic Apigee proxy and AWS backend which lives for the duration of the PR.
-To minimise admin overhead, the automation tests create dynamic applications for the duration of a test run rather than
-us having to manually create new apps each time we produce a pull request.
+2. [Install](https://docs.apigee.com/api-platform/system-administration/auth-tools#install) and run the Apigee [get_token](https://docs.apigee.com/api-platform/system-administration/using-gettoken) tool to obtain an access token.
+3. Set this value against the `APIGEE_ACCESS_TOKEN` variable in your .env file.
+4. Finally, use the Makefile to run your desired suite of tests.
 
-These tests are run seamlessly in the pipeline. But if you are doing some local changes and want to test against your
-PR environment, please follow these pre-requisites to get it working:
+Note: the `get_token` tool is only supported in Linux environments, so if you are using a Windows environment, you will
+at least need to run the operation in WSL to obtain the access token.
 
-1. [Install](https://docs.apigee.com/api-platform/system-administration/auth-tools#install) and run the Apigee [get_token](https://docs.apigee.com/api-platform/system-administration/using-gettoken) tool to obtain an access token.
-2. Set this value against the `APIGEE_ACCESS_TOKEN` in your .env file.
-3. Finally, use the [.env.example.pr](./.env.example.pr) as your baseline for your .env file and fill all of the required values.
+## Setup when using static apps
 
-Note: the `get_token` tool is only supported in Linux environments, so if you are using a Windows environment, you will
-at least need to run the operation in WSL to obtain the access token.
+**NOTE:** you must use this approach in INT.
+
+1. Configure your .env file with the required values.
+
+    The [.env.example.static](./.env.example.static) template defines all the values you will need and explains how
+    to obtain them. A lot more configuration is required as you will need to obtain all the `{Supplier}_client_Id` and
+    `{Supplier}_client_Secret` values for the static apps in your target environment.
+
+2. Finally, use the Makefile to run your desired suite of tests.
+
+## Test commands
+
+The `Makefile` in this directory provides the following commands:
+
+- `make test` - run all tests (may take some time)
+- `make test-api-full` - run API tests
+- `make test-api-smoke` - run API smoke tests only (quicker)
+- `make test-batch-full` - run Batch tests
+- `make test-batch-smoke` - run Batch smoke tests only (quicker)
+- `make test-sandbox` - run lightweight tests for the sandbox i.e. just checks /\_ping and /\_status
+- `make collect-only` - check that all tests are discovered
+
+If you want even more granular control, you can run `poetry run pytest features -m` followed by the given suite you
+want to run e.g. `Delete_Feature`, `Create_Batch_Feature` and so on.
diff --git a/tests/e2e_automation/utilities/apigee/apigee_env_helpers.py b/tests/e2e_automation/utilities/apigee/apigee_env_helpers.py
@@ -34,7 +34,7 @@ def use_temp_apigee_apps() -> bool:
     if get_proxy_name() == INT_PROXY_NAME:
         return False
 
-    return os.getenv("USE_STATIC_APPS", "false") != "true"
+    return os.getenv("USE_STATIC_APPS", "False") != "True"
 
 
 def is_pr_env() -> bool:
