Add local instructions in tests/README.md

Author: paulbalandan

tests/README.md

@@ -108,6 +108,48 @@ You can run the tests without running the live database and the live cache tests
 ./phpunit --exclude-group DatabaseLive --exclude-group CacheLive
 ```
 
+## Verifying Random Test Execution Order
+
+To help detect hidden test inter-dependencies, you can run component tests in random order using:
+
+```console
+.github/scripts/run-random-tests.sh
+```
+
+This script reads enabled components from `.github/scripts/random-tests-config.txt` and runs each
+component under `tests/system/` with PHPUnit random ordering.
+
+Common examples:
+
+```console
+# Run all configured components once
+.github/scripts/run-random-tests.sh
+
+# Run all configured components 10 times
+.github/scripts/run-random-tests.sh --repeat 10
+
+# Run one component 10 times
+.github/scripts/run-random-tests.sh --component CLI --repeat 10
+
+# Limit parallel jobs and suppress debug lines
+.github/scripts/run-random-tests.sh --max-jobs 4 --quiet
+```
+
+Short-option equivalents:
+
+```console
+# Run all configured components 10 times
+.github/scripts/run-random-tests.sh -r 10
+
+# Run one component 10 times
+.github/scripts/run-random-tests.sh -c CLI -r 10
+
+# Limit parallel jobs and suppress debug lines
+.github/scripts/run-random-tests.sh -n 4 -q
+```
+
+Failure diagnostics and execution-order logs are written to `build/random-tests/`.
+
 ## Generating Code Coverage
 
 The coverage reports are generated by default after the execution of tests. These reports