[NDR-270] Add spec & APIM e2e tests (#859)

Author: megan-bower4

.gitignore

@@ -99,6 +99,7 @@ node_modules/
 .vscode/
 
 lambdas/tests/unit/helpers/data/pdf/tmp
+lambdas/tests/e2e/apim/*.pdf
 /lambdas/package_/
 
 # jupyter notebook files

Makefile

@@ -73,6 +73,9 @@ test-fhir-api-e2e: ## Runs FHIR API E2E tests. Usage: make test-fhir-api-e2e WOR
 	./scripts/test/run-e2e-fhir-api-tests.sh --workspace $(WORKSPACE)
 	rm -rf ./lambdas/mtls_env_certs/$(WORKSPACE)
 
+test-apim-e2e: ## Runs APIM E2E tests for National Document Repository FHIR R4 API against ndr-dev.
+	./scripts/test/run-apim-e2e-tests.sh
+
 test-api-e2e-snapshots:
 	cd ./lambdas && ./venv/bin/python3 -m pytest tests/e2e/api --ignore=tests/e2e/api/fhir --snapshot-update
 

README.md

@@ -8,6 +8,10 @@ Our Lambda function readme can be found [here](lambdas/README.md)
 
 Our React User Interface readme can be found [here](app/README.md)
 
+## End-to-End Tests Intro
+
+Our E2E test readme can be found [here](lambdas/tests/e2e/README.md). We have E2E tests for our FHIR endpoints and APIM setup.
+
 ## Installation
 
 - [Git](https://git-scm.com/)

apim/specification.yaml

@@ -7,9 +7,11 @@ There are 2 suites which separately test
 1. FHIR API endpoints using mTLS `lambdas/tests/e2e/api/fhir/` (routed to **PDM** usecase)
 2. API endpoints **not** using mTLS `lambdas/tests/e2e/api/` (routed to **Lloyd George** usecase)
 
+as well as APIM E2E tests `lambdas/tests/e2e/apim/`.
+
 ### 🔐 AWS Authentication
 
-You must be authenticated with AWS to run the tests. Use the following commands with a configured profile set up in ~/.aws/config to authenticate:
+You must be authenticated with AWS to run the api tests. Use the following commands with a configured profile set up in ~/.aws/config to authenticate:
 
 ```bash
 aws sso login --profile <your-aws-profile>
@@ -40,6 +42,8 @@ Make sure your AWS profile has access to the required resources.
 
 - `make test-api-e2e` — Runs the E2E tests without mTLS
 
+- `make test-apim-e2e` - Runs the APIM E2E tests
+
 ### Snapshots
 
 Snapshots reduce the amount of individual assertions by comparing pre and post an object e.g. a JSON returned from an API.
@@ -75,3 +79,60 @@ After updating your shell config, reload it:
 ```bash
 source ~/.zshrc   # or source ~/.bashrc
 ```
+
+## APIM E2E Tests
+
+The **APIM E2E tests** validate the full integration and behavior of the API Management layer within the system. These tests ensure that:
+
+- FHIR API endpoints (/DocumentReference) are correctly exposed and accessible via APIM.
+- mTLS authentication and authorization mechanisms are functioning as expected.
+- The routing and transformation logic configured in APIM behaves correctly.
+- The downstream services respond appropriately when accessed through APIM.
+
+### Running the Tests
+
+#### Authentication Requirement
+
+Before running the APIM E2E tests, you must generate a **Proxygen access token**. This token is required to authenticate requests against the APIM proxy.
+
+You can generate a temporary token using the `pytest-nhsd-apim` plugin
+
+```
+proxygen pytest-nhsd-apim get-token
+```
+
+Once generated, export the token to your shell environment so it's available during test execution. For example, in your `.zshrc` or `.bashrc` file:
+
+```
+export APIGEE_ACCESS_TOKEN=your_token_here
+```
+
+#### Executing
+
+To execute the APIM E2E tests, use the following Make command:
+
+```bash
+make test-apim-e2e
+```
+
+This command validates APIM functionality for the National Document Repository FHIR R4 API using the following configuration:
+
+```
+cd ./lambdas && ./venv/bin/python3 -m pytest tests/e2e/apim -vv \
+  --api-name=national-document-repository_FHIR_R4 \
+  --proxy-name=national-document-repository--internal-dev--national-document-repository_FHIR_R4
+```
+
+### Arguments
+
+- `api-name`: Specifies the name of the API being tested. In this case, it's the National Document Repository FHIR R4 API.
+- `proxy-name`: Indicates the APIM proxy configuration to use during testing. This ensures the tests target the correct APIM instance and environment.
+
+### Important Notes
+
+- Environment Configuration: Make sure your test environment is properly configured with access to APIM and any required secrets or credentials.
+
+  - You can test your proxygen set up via `proxygen instance list` and expect to see `national-document-repository_FHIR_R4` listed.
+    For more information on proxygen credentials see: https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?spaceKey=APM&title=Proxygen+CLI+user+guide
+
+- Dependencies: These tests rely on other services being up and running (e.g. backend API, databases). Ensure all dependencies are available before running the tests.

lambdas/tests/e2e/README.md

@@ -1,6 +1,5 @@
 import base64
 import io
-import uuid
 
 import pytest
 import requests
@@ -9,27 +8,13 @@
 from lambdas.tests.e2e.api.fhir.conftest import (
     MTLS_ENDPOINT,
     PDM_S3_BUCKET,
-    PDM_SNOMED,
     create_mtls_session,
 )
+from lambdas.tests.e2e.conftest import PDM_SNOMED
 
 pdm_data_helper = PdmDataHelper()
 
 
-def build_pdm_record(nhs_number="9912003071", data=None, doc_status=None, size=None):
-    """Helper to create a PDM record dictionary."""
-    record = {
-        "id": str(uuid.uuid4()),
-        "nhs_number": nhs_number,
-        "data": data or io.BytesIO(b"Sample PDF Content"),
-    }
-    if doc_status:
-        record["doc_status"] = doc_status
-    if size:
-        record["size"] = size
-    return record
-
-
 def get_document_reference(record_id):
     """Helper to perform GET request for DocumentReference."""
     url = f"https://{MTLS_ENDPOINT}/DocumentReference/{PDM_SNOMED}~{record_id}"
@@ -43,7 +28,7 @@ def get_document_reference(record_id):
 @pytest.mark.parametrize("file_size", [None, 10 * 1024 * 1024])
 def test_file_retrieval(test_data, file_size):
     """Test retrieval for small and large files."""
-    pdm_record = build_pdm_record(
+    pdm_record = pdm_data_helper.build_record(
         data=io.BytesIO(b"A" * file_size) if file_size else None,
         size=file_size * 1024 if file_size else None,
     )
@@ -93,7 +78,7 @@ def test_retrieve_edge_cases(
 
 
 def test_preliminary_file(test_data):
-    pdm_record = build_pdm_record(doc_status="preliminary")
+    pdm_record = pdm_data_helper.build_record(doc_status="preliminary")
     test_data.append(pdm_record)
     pdm_data_helper.create_metadata(pdm_record)
     pdm_data_helper.create_resource(pdm_record)
@@ -106,7 +91,7 @@ def test_preliminary_file(test_data):
 
 
 def test_forbidden_with_invalid_cert(test_data, temp_cert_and_key):
-    pdm_record = build_pdm_record()
+    pdm_record = pdm_data_helper.build_record()
     test_data.append(pdm_record)
     pdm_data_helper.create_metadata(pdm_record)
     pdm_data_helper.create_resource(pdm_record)

lambdas/tests/e2e/api/fhir/test_retrieve_document_fhir_api.py

@@ -1,32 +1,13 @@
-import io
-import uuid
-
 import pytest
 import requests
 
-from lambdas.tests.e2e.api.fhir.conftest import (
-    MTLS_ENDPOINT,
-    PDM_SNOMED,
-    create_mtls_session,
-)
-from lambdas.tests.e2e.conftest import APIM_ENDPOINT
+from lambdas.tests.e2e.api.fhir.conftest import MTLS_ENDPOINT, create_mtls_session
+from lambdas.tests.e2e.conftest import APIM_ENDPOINT, PDM_SNOMED
 from lambdas.tests.e2e.helpers.data_helper import PdmDataHelper
 
 pdm_data_helper = PdmDataHelper()
 
 
-def build_pdm_record(nhs_number="9912003071", data=None, doc_status=None):
-    """Helper to create a PDM record dictionary."""
-    record = {
-        "id": str(uuid.uuid4()),
-        "nhs_number": nhs_number,
-        "data": data or io.BytesIO(b"Sample PDF Content"),
-    }
-    if doc_status:
-        record["doc_status"] = doc_status
-    return record
-
-
 def search_document_reference(nhs_number):
     """Helper to perform search by NHS number."""
     url = (
@@ -45,7 +26,7 @@ def create_and_store_record(
     test_data, nhs_number="9912003071", doc_status: str | None = None
 ):
     """Helper to create metadata and resource for a record."""
-    record = build_pdm_record(nhs_number=nhs_number, doc_status=doc_status)
+    record = pdm_data_helper.build_record(nhs_number=nhs_number, doc_status=doc_status)
     test_data.append(record)
     pdm_data_helper.create_metadata(record)
     pdm_data_helper.create_resource(record)

lambdas/tests/e2e/api/fhir/test_search_patient_fhir_api.py

@@ -1,5 +1,4 @@
 import base64
-import json
 import logging
 import os
 
@@ -8,60 +7,13 @@
 
 from lambdas.tests.e2e.api.fhir.conftest import (
     MTLS_ENDPOINT,
-    PDM_SNOMED,
     create_mtls_session,
     fetch_with_retry_mtls,
 )
+from lambdas.tests.e2e.conftest import APIM_ENDPOINT, PDM_SNOMED
 from lambdas.tests.e2e.helpers.data_helper import PdmDataHelper
 
-
-def create_upload_payload(record):
-    """Helper to build DocumentReference payload."""
-    payload = {
-        "resourceType": "DocumentReference",
-        "type": {
-            "coding": [
-                {
-                    "system": "https://snomed.info/sct",
-                    "code": f"{PDM_SNOMED}",
-                    "display": "Confidential patient data",
-                }
-            ]
-        },
-        "subject": {
-            "identifier": {
-                "system": "https://fhir.nhs.uk/Id/nhs-number",
-                "value": record["nhs_number"],
-            }
-        },
-        "author": [
-            {
-                "identifier": {
-                    "system": "https://fhir.nhs.uk/Id/ods-organization-code",
-                    "value": record["ods"],
-                }
-            }
-        ],
-        "custodian": {
-            "identifier": {
-                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
-                "value": record["ods"],
-            }
-        },
-        "content": [
-            {
-                "attachment": {
-                    "creation": "2023-01-01",
-                    "contentType": "application/pdf",
-                    "language": "en-GB",
-                    "title": "1of1_record_[Paula Esme VESEY]_[9730153973]_[22-01-1960].pdf",
-                }
-            }
-        ],
-    }
-    if "data" in record:
-        payload["content"][0]["attachment"]["data"] = record["data"]
-    return json.dumps(payload)
+pdm_data_helper = PdmDataHelper()
 
 
 def upload_document(session, payload):
@@ -91,19 +43,21 @@ def test_create_document_base64(test_data):
     sample_pdf_path = os.path.join(os.path.dirname(__file__), "files", "dummy.pdf")
     with open(sample_pdf_path, "rb") as f:
         record["data"] = base64.b64encode(f.read()).decode("utf-8")
-    payload = create_upload_payload(record)
+    payload = pdm_data_helper.create_upload_payload(record)
 
     session = create_mtls_session()
     raw_upload_response = upload_document(session, payload)
     assert raw_upload_response.status_code == 200
+    record["id"] = raw_upload_response.json()["id"].split("~")[1]
+    test_data.append(record)
 
     # Validate attachment URL
     upload_response = raw_upload_response.json()
     attachment_url = upload_response["content"][0]["attachment"]["url"]
-    assert f"/DocumentReference/{PDM_SNOMED}~" in attachment_url
-
-    record["id"] = raw_upload_response.json()["id"].split("~")[1]
-    test_data.append(record)
+    assert (
+        f"https://{APIM_ENDPOINT}/national-document-repository/FHIR/R4/DocumentReference/{PDM_SNOMED}~"
+        in attachment_url
+    )
 
     def condition(response_json):
         logging.info(response_json)
@@ -128,7 +82,7 @@ def test_create_document_presign_fails():
     sample_pdf_path = os.path.join(os.path.dirname(__file__), "files", "big-dummy.pdf")
     with open(sample_pdf_path, "rb") as f:
         record["data"] = base64.b64encode(f.read()).decode("utf-8")
-    payload = create_upload_payload(record)
+    payload = pdm_data_helper.create_upload_payload(record)
 
     session = create_mtls_session()
     upload_response = upload_document(session, payload)
@@ -141,7 +95,7 @@ def test_create_document_virus(test_data):
         "ods": "H81109",
         "nhs_number": "9730154260",
     }
-    payload = create_upload_payload(record)
+    payload = pdm_data_helper.create_upload_payload(record)
     session = create_mtls_session()
 
     retrieve_response = upload_document(session, payload)
@@ -198,7 +152,7 @@ def test_search_edge_cases(
     sample_pdf_bytes = b"Sample PDF Content"
     record["data"] = base64.b64encode(sample_pdf_bytes).decode("utf-8")
 
-    payload = create_upload_payload(record)
+    payload = pdm_data_helper.create_upload_payload(record)
     session = create_mtls_session()
     response = upload_document(session, payload)
     assert response.status_code == expected_status
@@ -220,7 +174,7 @@ def test_forbidden_with_invalid_cert(temp_cert_and_key):
     sample_pdf_bytes = b"Sample PDF Content"
     record["data"] = base64.b64encode(sample_pdf_bytes).decode("utf-8")
 
-    payload = create_upload_payload(record)
+    payload = pdm_data_helper.create_upload_payload(record)
 
     # Use an invalid cert that is trusted by TLS but fails truststore validation
     cert_path, key_path = temp_cert_and_key
@@ -244,15 +198,15 @@ def test_create_document_saves_raw(test_data):
     sample_pdf_path = os.path.join(os.path.dirname(__file__), "files", "dummy.pdf")
     with open(sample_pdf_path, "rb") as f:
         record["data"] = base64.b64encode(f.read()).decode("utf-8")
-    payload = create_upload_payload(record)
+    payload = pdm_data_helper.create_upload_payload(record)
 
     session = create_mtls_session()
     raw_upload_response = upload_document(session, payload)
     assert raw_upload_response.status_code == 200
 
     json_response = raw_upload_response.json()
     record["id"] = json_response.get("id")
-    pdm_data_helper = PdmDataHelper()
+
     doc_ref = pdm_data_helper.retrieve_document_reference(record=record)
     assert "Item" in doc_ref
     assert "RawRequest" in doc_ref["Item"]

lambdas/tests/e2e/api/fhir/test_upload_document_fhir_api.py

@@ -0,0 +1,20 @@
+import os
+
+import pytest
+
+from lambdas.tests.e2e.helpers.data_helper import PdmDataHelper
+
+pdm_data_helper = PdmDataHelper()
+
+PDM_METADATA_TABLE = (
+    os.environ.get("PDM_METADATA_TABLE") or "ndr-dev_PDMDocumentMetadata"
+)
+PDM_S3_BUCKET = os.environ.get("PDM_S3_BUCKET") or "ndr-dev-pdm-document-store"
+
+
+@pytest.fixture
+def test_data():
+    test_records = []
+    yield test_records
+    for record in test_records:
+        pdm_data_helper.tidyup(record)