From c21d5b8e74be1d4c977771b5908bedc458f3b67e Mon Sep 17 00:00:00 2001
From: Thomas Vincent <thomasvincent@gmail.com>
Date: Mon, 17 Aug 2026 15:07:34 -0700
Subject: [PATCH] docs: document the Pest testing workflow

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
---
 .../{php-unit-tests.yml => pest-tests.yml}    |  0
 README.md                                     |  8 ++++
 docs/TESTING.md                               | 47 +++++++++++++++++++
 3 files changed, 55 insertions(+)
 rename .github/workflows/{php-unit-tests.yml => pest-tests.yml} (100%)
 create mode 100644 docs/TESTING.md

diff --git a/.github/workflows/php-unit-tests.yml b/.github/workflows/pest-tests.yml
similarity index 100%
rename from .github/workflows/php-unit-tests.yml
rename to .github/workflows/pest-tests.yml
diff --git a/README.md b/README.md
index 46310dce..6f470e84 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,14 @@ different sources.  These forks of thold are not necessarily compatible with the
 current version of Cacti's thold plugin.  Please be aware of this when
 installing thold for the first time.
 
+## Development and testing
+
+Thold's unit suite runs with [Pest](https://pestphp.com/) and the Composer
+toolchain supplied by Cacti.  The plugin intentionally does not maintain its
+own `composer.json`, `composer.lock`, or vendor directory.  See
+[Testing and contributing](docs/TESTING.md) for the supported local workflow,
+test layout, and pull request checks.
+
 ## Authors
 
 The thold plugin has been in development for well over a decade with increasing
diff --git a/docs/TESTING.md b/docs/TESTING.md
new file mode 100644
index 00000000..edbb0e04
--- /dev/null
+++ b/docs/TESTING.md
@@ -0,0 +1,47 @@
+# Testing and contributing
+
+Thold uses Pest for unit tests and Cacti's Composer toolchain for dependencies.
+Keeping one toolchain avoids a second dependency graph inside the plugin and
+ensures local tests exercise the same versions used by Cacti.
+
+## Repository policy
+
+- Write new unit and regression tests as Pest tests under `tests/Unit`.
+- Do not add a plugin-local `composer.json`, `composer.lock`, or `vendor`
+  directory.
+- Keep `phpunit.xml`. Pest reads this compatibility configuration for bootstrap,
+  suite, and coverage settings; its filename does not mean PHPUnit is run
+  directly.
+- Run the complete unit suite before opening or updating a pull request.
+
+## Run the tests locally
+
+Place the plugin at `plugins/thold` in a Cacti checkout whose Composer
+dependencies are installed, then run from the Cacti root:
+
+```console
+composer test -- --configuration=plugins/thold/phpunit.xml plugins/thold/tests/Unit
+```
+
+To run one test file while developing:
+
+```console
+composer test -- --configuration=plugins/thold/phpunit.xml plugins/thold/tests/Unit/TholdRpnCdefTest.php
+```
+
+The pull request workflow is the reproducible reference environment. It builds
+Cacti's pinned Docker test image, mounts Thold into a pinned Cacti runtime, runs
+PHP linting, runs Pest with coverage, and requires full coverage of lines added
+by a pull request. Review `.github/workflows/pest-tests.yml` when reproducing
+the exact CI commands or pinned Cacti revisions.
+
+## Pull request checklist
+
+Before pushing a branch:
+
+1. Run the Pest suite and any focused tests for the changed behavior.
+2. Confirm every changed PHP file passes the Cacti Composer lint script.
+3. Confirm `composer.json`, `composer.lock`, `vendor`, and generated coverage
+   output are not included in the diff.
+4. Rebase or update the branch against the current target branch and resolve
+   conflicts before requesting review.