From 48d3bc40bafe9c983cb08b0d9d5aafb71bd49cdc Mon Sep 17 00:00:00 2001
From: diroussel <dir@bjss.com>
Date: Thu, 23 Apr 2026 16:55:01 +0100
Subject: [PATCH] Add local workflow testing support and miscellaneous
 improvements

- Document steps to run GitHub Actions workflows locally using `act` in `CONTRIBUTING.md`.
- Update `.gitignore` to exclude `.cache/` directory used by `act`.
- Add `act` version to `.tool-versions` for consistency.
- Introduce `workflow_dispatch` trigger and conditional parsing for `act` in `test_v2.yml`.
- Extend `package.json` with commands for local workflow testing (`test:workflow:local` and architecture-specific variants).
---
 .github/workflows/test_v2.yml |  3 +++
 .gitignore                    |  3 ++-
 .tool-versions                |  3 ++-
 CONTRIBUTING.md               | 18 ++++++++++++++++++
 package.json                  |  5 ++++-
 5 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/test_v2.yml b/.github/workflows/test_v2.yml
index a0a5cf9e..69e56db4 100644
--- a/.github/workflows/test_v2.yml
+++ b/.github/workflows/test_v2.yml
@@ -1,6 +1,7 @@
 name: Test Transfer Artefact V2
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - main
@@ -19,6 +20,7 @@ jobs:
     services:
       floci:
         image: hectorvent/floci:latest
+        options: --workdir /app
         ports:
           - 4566:4566
 
@@ -85,6 +87,7 @@ jobs:
         run: npm run test
 
       - name: SonarQube Scan
+        if: ${{ !env.ACT }}
         uses: SonarSource/sonarqube-scan-action@fd88b7d7ccbaefd23d8f36f73b59db7a3d246602 # v6.0.0
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
diff --git a/.gitignore b/.gitignore
index 6e213c0a..01729ea6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 .idea/
+.cache/
 node_modules/
 lib/
 __tests__/_temp/
-coverage
\ No newline at end of file
+coverage
diff --git a/.tool-versions b/.tool-versions
index 14f3ec61..1387850d 100644
--- a/.tool-versions
+++ b/.tool-versions
@@ -1 +1,2 @@
-nodejs 24.13.0
\ No newline at end of file
+nodejs 24.13.0
+act  0.2.87
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d73d76a8..7f1b747e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -35,6 +35,24 @@ Artifact related issues will be tracked in this repository so please do not open
 9. Push to your fork and [submit a pull request][pr]
 10. Pat your self on the back and wait for your pull request to be reviewed and merged.
 
+## Run the integration workflow locally
+
+The repository keeps the GitHub Actions integration coverage in `.github/workflows/test_v2.yml`.
+You can run that workflow locally with [`act`](https://nektosact.com/):
+
+1. Install the tool versions from `.tool-versions`, for example with `mise install`
+2. Start Docker Desktop, or another Docker Engine API compatible runtime
+3. Run `npm run test:workflow:local`
+
+Notes:
+
+- The local command uses `workflow_dispatch`, so it works from any branch.
+- `act` caches data under `.cache/` by default in this repository-local command, so it does not need to manage a separate cache directory in your home folder.
+- The SonarQube step is skipped automatically when the workflow is running under `act`.
+- The default local command lets `act` use the host architecture. That means Apple Silicon machines will use `linux/arm64` by default, while most Windows developers running WSL on x86_64 will use `linux/amd64`.
+- If you need to force a specific architecture, use `npm run test:workflow:local:arm64` or `npm run test:workflow:local:amd64`.
+- The first run may take a while because `act` will pull `catthehacker/ubuntu:full-latest`, which is intentionally closer to a GitHub-hosted runner than the smaller default image.
+
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:
 
 - Write tests.
diff --git a/package.json b/package.json
index 24be426e..f572dd0e 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,10 @@
     "format": "prettier --write .",
     "format-check": "prettier --check .",
     "lint": "eslint .",
-    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --config jest.config.js --testTimeout 10000"
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --config jest.config.js --testTimeout 10000",
+    "test:workflow:local": "XDG_CACHE_HOME=${XDG_CACHE_HOME:-$PWD/.cache} act workflow_dispatch -W .github/workflows/test_v2.yml -j test -P ubuntu-latest=catthehacker/ubuntu:full-latest",
+    "test:workflow:local:arm64": "npm run test:workflow:local -- --container-architecture linux/arm64",
+    "test:workflow:local:amd64": "npm run test:workflow:local -- --container-architecture linux/amd64"
   },
   "repository": {
     "type": "git",