tests

docs/README.md

@@ -22,6 +22,7 @@ PHPUnit, PHPStan (tests + scanned `Model/`), and PHPCS run from the repo root af
 | [scripts.md](scripts.md) | Node scripts, nginx helpers, probes |
 | [troubleshooting.md](troubleshooting.md) | Common failures and fixes |
 | [gitea-act-runner-labels.md](gitea-act-runner-labels.md) | Add `ubuntu-latest` (Docker) labels to an existing Gitea act_runner |
+| [phpunit-tier4-deferred.md](phpunit-tier4-deferred.md) | Classes not covered by off-Magento PHPUnit (integration / Magento app) |
 
 ## Deeper dives (in the module tree)
 

docs/phpunit-tier4-deferred.md

@@ -0,0 +1,21 @@
+# Tier 4: not covered by off-Magento PHPUnit
+
+The workspace [`composer.json`](../composer.json) does not install `magento/framework` from Packagist (private `repo.magento.com` is required). Unit tests therefore use **minimal Magento stubs** under [`Magesail/Test/Stubs/Magento/`](../Magesail/Test/Stubs/Magento/) for PSR-4 types.
+
+The following production classes are **not** exercised by the repository’s PHPUnit suite. They need either **refactoring** (extract pure services + seams) or **Magento integration / functional tests** inside a full Magento project (`dev/tests/integration` or MFTF):
+
+| Class | Reason |
+|-------|--------|
+| Controllers under `MageSail/Controller/Adminhtml/**` | `Action`, `Context`, ACL, sessions, HTTP stack |
+| Blocks under `MageSail/Block/Adminhtml/**` | Layout, `Block` base, helpers |
+| `MageSail/Cron/DailyMonitor.php` | Cron + DI graph + side effects |
+| `MageSail/Setup/Patch/Data/GrantMagesailMenuAcl.php` | `ModuleDataSetupInterface`, ACL resources |
+| `MageSail/Model/TunnelManager.php` | Large orchestration, Node, config, registry |
+| `MageSail/Model/NginxGlobalMapManager.php` | Filesystem, nginx, permissions |
+| `MageSail/Model/TunnelStoreProvisioner.php` | Store API, websites, side effects |
+| `MageSail/Model/MagesailLog.php` | `ResourceConnection`, DB |
+| `MageSail/Model/Config/Backend/MonitorCronExpr.php` | Extends `Config\Value`, cron validation in Magento stack |
+
+**Recommended next step:** In a Magento 2 app that already requires `magesail/magesail`, add integration tests that bootstrap the framework and cover critical paths (tunnel create, map save, cron).
+
+**Optional:** Add `@group magento-integration` tests in this repo that `markTestSkipped()` with a message pointing here, so the 1-1 file layout can exist without running in CI until a harness exists.