NPA-5247: Use Portman to Generate Postman Collection (#22)

## 🧾 Ticket Link

https://nhsd-jira.digital.nhs.uk/browse/NPA-5247

---

## 📄 Description/Summary of Changes

<!-- Describe the changes made in this PR. Include the
purpose/scope/impact/context of the changes -->

- Generates Postman Collection using Portman with `make
postman-generate-collection`
- Add GitHub action to test sandbox environment
  - Action runs as part of PR checks on PR sandbox environment
- Added docs on generating a Postman Collection  

---

## 🧪 Developer Testing Carried Out

<!-- Describe what tests (automated/unit/manual etc.) have been done for
the ticket. Include: -->
<!-- - Any tests added/updated -->
<!-- - Evidence that each acceptance criterion from the Jira ticket is
met -->

- Automated Sandbox testing
---

## ✅ Developer Checklist

<!-- To be completed by the developer -->

- [x] I have set the PR title to follow the format: `NPA-XXXX:
<short-description>`
- [x] My branch name follows the convention:
`<type>/NPA-XXXX/<short-description>`
- [x] My commit messages follow the template: `NPA-XXXX:
<short-description>`
- [x] I have updated the documentation accordingly
- [x] I have set assignees and added appropriate labels

---

## 👀 Reviewer Checklist

<!-- To be completed by the reviewer -->

- [ ] Changes meet the acceptance criteria of the Jira ticket
- [ ] Code is able to be merged (no conflicts and adheres to coding
standards)
- [ ] Sufficient test evidence is provided (manual and/or automated)

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [x] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

---------

Co-authored-by: Ellie Bound <175816742+ellie-bound1-NHSD@users.noreply.github.com>

Author: JackPlowman

.editorconfig

@@ -19,3 +19,6 @@ indent_size = 4
 
 [{Makefile,*.mk,go.mod,go.sum,*.go,.gitmodules}]
 indent_style = tab
+
+[postman/postman_collection.json]
+insert_final_newline = unset

.github/actions/compile-spec/action.yaml

@@ -0,0 +1,21 @@
+name: "Run Postman Collection"
+description: Run Postman collection with Newman
+
+inputs:
+  SANDBOX_BASE_URL:
+    description: The base URL for the sandbox environment (e.g., https://sandbox.api.service.nhs.uk/im1-pfs-auth/)
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install Node.js
+      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      with:
+        node-version: "24"
+    - name: Install NPM packages
+      run: npm install
+      shell: bash
+    - name: Run Postman Collection
+      run: make postman-test-pr-environment
+      shell: bash

.github/actions/run-postman-collection/action.yaml

@@ -10,12 +10,12 @@ updates:
       - ".github/actions/check-github-actions"
       - ".github/actions/check-markdown-format"
       - ".github/actions/check-uv-lock"
-      - ".github/actions/compile-spec"
       - ".github/actions/create-lines-of-code-report"
       - ".github/actions/perform-static-analysis"
       - ".github/actions/prettier-checks"
       - ".github/actions/ruff-checks"
       - ".github/actions/ruff-format"
+      - ".github/actions/run-postman-collection"
       - ".github/actions/run-unit-tests"
       - ".github/actions/scan-dependencies"
       - ".github/actions/scan-secrets"

.github/dependabot.yaml

@@ -50,3 +50,19 @@ jobs:
       PROXYGEN_CLIENT_ID: ${{ secrets.PROXYGEN_CLIENT_ID }}
       PROXYGEN_KEY_ID: ${{ secrets.PROXYGEN_KEY_ID }}
       PROXYGEN_PRIVATE_KEY: ${{ secrets.PROXYGEN_PRIVATE_KEY }}
+
+  run-postman-collection:
+    name: "Run Postman Collection"
+    runs-on: ubuntu-latest
+    needs: deploy-dev-sandbox
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Run Postman Collection
+        uses: ./.github/actions/run-postman-collection
+        env:
+          SANDBOX_BASE_URL: ${{ needs.deploy-dev-sandbox.outputs.environment_url }}

.github/workflows/pull-request-checks.yml

@@ -24,6 +24,11 @@ on:
         required: true
         type: string
 
+    outputs:
+      environment_url:
+        description: "The URL of the deployed environment"
+        value: ${{ jobs.deploy-environment.outputs.environment_url }}
+
     secrets:
       PROXYGEN_CLIENT_ID:
         required: true
@@ -90,8 +95,16 @@ jobs:
     needs: build-and-push-container
     environment:
       name: ${{ inputs.environment }}
-      url: https://${{ inputs.environment }}.api.platform.nhs.uk/${{ inputs.additional_path && format('im1-pfs-auth-{0}', inputs.additional_path) || 'im1-pfs-auth' }}
+      url: ${{ steps.deploy-environment-url.outputs.environment_url }}
+    outputs:
+      environment_url: ${{ steps.deploy-environment-url.outputs.environment_url }}
     steps:
+      - name: "Output PROXYGEN_URL_PATH"
+        run: echo "PROXYGEN_URL_PATH=${{ inputs.additional_path && format('im1-pfs-auth-{0}', inputs.additional_path) || 'im1-pfs-auth' }}" >> $GITHUB_ENV
+      - name: "Output Environment URL"
+        id: deploy-environment-url
+        run: echo "ENVIRONMENT_URL=https://${{ inputs.environment }}.api.service.nhs.uk/$PROXYGEN_URL_PATH" >> $GITHUB_OUTPUT
+
       - name: "Checkout code"
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
@@ -105,12 +118,11 @@ jobs:
           PROXYGEN_CLIENT_ID: ${{ secrets.PROXYGEN_CLIENT_ID }}
           PROXYGEN_KEY_ID: ${{ secrets.PROXYGEN_KEY_ID }}
           PROXYGEN_PRIVATE_KEY: ${{ secrets.PROXYGEN_PRIVATE_KEY }}
-
       - name: Deploy environment
         run: make deploy-ci
         env:
           ENVIRONMENT: ${{ inputs.environment }}
-          PROXYGEN_URL_PATH: ${{ inputs.additional_path && format('im1-pfs-auth-{0}', inputs.additional_path) || 'im1-pfs-auth' }}
+          PROXYGEN_URL_PATH: ${{ env.PROXYGEN_URL_PATH }}
 
       - name: "Check Deployment"
         run: cat specification/x-nhsd-apim/x-nhsd-apim.generated.yaml

.github/workflows/reusable-deploy.yml

@@ -1,3 +1,12 @@
+# ----------------
+# Custom
+# ----------------
+specification/im1-pfs-auth-api.portman.generated.yaml
+# Portman temp directory
+tmp/
+# ----------------
+# Python .gitignore - https://github.com/github/gitignore/blob/main/Python.gitignore
+# ----------------
 .scannerwork
 *cloc*report*.json
 *sbom*report*.json
@@ -10,6 +19,7 @@
 
 sandbox/pyproject.toml
 sandbox/uv.lock
+specification/assets/*.json
 
 ### This is the Github Python.gitignore https://github.com/github/gitignore/blob/main/Python.gitignore
 # Byte-compiled / optimized / DLL files
@@ -216,7 +226,9 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 
-### This is the Github Node.gitignore https://github.com/github/gitignore/blob/main/Node.gitignore
+# ----------------
+# Node .gitignore - https://github.com/github/gitignore/blob/main/Node.gitignore
+# ----------------
 # Logs
 logs
 *.log

.gitignore

@@ -0,0 +1 @@
+postman/postman_collection.json

.prettierignore

@@ -5,7 +5,9 @@ vale 3.12.0
 gitleaks 8.28.0
 python 3.13.5
 actionlint 1.7.7
-uv 0.8.3
+uv 0.8.5
+node 24.5
+npm 11.5
 
 # ==============================================================================
 # The section below is reserved for Docker image versions.

.tool-versions

@@ -78,6 +78,25 @@ spec-compile:
 	mkdir -p build
 	npm run spec-compile
 
+# ==============================================================================
+# Postman Commands
+# ==============================================================================
+
+# Generate Postman collection from OpenAPI specification
+postman-generate-collection:
+	yq 'del(.x-nhsd-apim)' specification/im1-pfs-auth-api.yaml > specification/im1-pfs-auth-api.portman.generated.yaml
+	npx portman --cliOptionsFile portman/portman-cli.json
+
+# Run Postman tests using Newman
+postman-test:
+	npx newman run postman/postman_collection.json $(NEWMAN_ARGS)
+
+# Run Postman Tests
+postman-test-pr-environment:
+# Mandatory arguments:
+# SANDBOX_BASE_URL: The base URL for the sandbox environment (e.g., https://sandbox.api.service.nhs.uk/im1-pfs-auth/)
+	@make postman-test NEWMAN_ARGS="--env-var baseUrl=$(SANDBOX_BASE_URL)"
+
 # ==============================================================================
 # App Commands
 # ==============================================================================