From 793785a34d5550cebc16d2b2b30289565936d88a Mon Sep 17 00:00:00 2001
From: Simon Clark <simon@starmerclark.com>
Date: Tue, 5 May 2026 08:44:31 +0100
Subject: [PATCH 1/2] docs: TestingBase conventions section in
 patterns/testing.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Captures real-world findings from the netro pilot (first workspace
adoption of TestingBase) so future Claude sessions don't repeat them.

Five conventions added — each one bit during the pilot:

- run_host_script wraps the script as a function body; print() goes
  to Indigo's event log, not subprocess stdout. Use `return` instead.
  (Upstream's own utils.py:get_install_folder is the canonical example.)
- Plugin state isn't on the HTTP API. Indigo's /v2/api/indigo.<endpoint>
  exposes only devices/variables/actionGroups/controlPages/logs/
  triggers/schedules. Plugin queries (isEnabled, isRunning) go through
  the IOM via run_host_script + indigo.server.getPlugin().
- /usr/local/indigo/ ships as drwxrwx--- root:wheel on fresh 2025.2
  installs. Regular users can't traverse it; sudo chmod 0755 fixes.
- New reflectors need an Indigo Server restart before they're live.
  Until then httpx gets the public indigodomo.com "Not Found" page.
- Local IWS is HTTP-only on port 8176. Upstream's ENV_TEMPLATE default
  of https://localhost:8176 produces SSL handshake timeouts.

Also adds a clear pointer to TestingBase upstream as the authoritative
source for TestingBase usage (separate from /indigo:dev which is the
authoritative source for the Indigo plugin SDK). Conflating the two
caused real time-loss in the pilot — explicit guidance prevents that
for the next adoption.

Bump 1.9.1 -> 1.9.2 (patch, pure docs augmentation).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json     |  2 +-
 .claude-plugin/plugin.json          |  2 +-
 docs/plugin-dev/patterns/testing.md | 68 ++++++++++++++++++++++++++++-
 3 files changed, 69 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 692fe0f..ae8f407 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -8,7 +8,7 @@
       "name": "indigo",
       "source": "./",
       "description": "Indigo home automation development toolkit \u2014 plugin development, API integration, and control page building",
-      "version": "1.9.3",
+      "version": "1.9.4",
       "repository": "https://github.com/simons-plugins/indigo-claude-plugin",
       "license": "MIT",
       "keywords": [
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 5e93bd7..260caca 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "indigo",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "description": "Indigo home automation development toolkit \u2014 plugin development, API integration, and control page building",
   "repository": "https://github.com/simons-plugins/indigo-claude-plugin"
 }
diff --git a/docs/plugin-dev/patterns/testing.md b/docs/plugin-dev/patterns/testing.md
index 7d1825c..8e7d46f 100644
--- a/docs/plugin-dev/patterns/testing.md
+++ b/docs/plugin-dev/patterns/testing.md
@@ -127,8 +127,74 @@ Use both for any non-trivial plugin: A on every commit, B before each release.
 
 ---
 
+## TestingBase conventions worth knowing
+
+The upstream [TestingBase repo](https://github.com/IndigoDomotics/TestingBase) is the authoritative source for TestingBase usage — its `README.md` and `example_test_xml_files.py` document the public API. `/indigo:dev` covers Indigo plugin SDK questions; for TestingBase-specific questions, read upstream first.
+
+A few conventions that aren't intuitive and have bitten downstream consumers:
+
+### `run_host_script` uses `return`, not `print`
+
+`tests/shared/utils.py:run_host_script(script)` wraps `indigo-host -e <script>`. Indigo wraps your script as a function body; `print()` goes to Indigo's event log, not the subprocess stdout. Use `return` to send a value back:
+
+```python
+# WRONG — print goes to event log, run_host_script returns ""
+script = "print(indigo.server.getInstallFolderPath())"
+
+# RIGHT — return value comes back via stdout
+script = "return indigo.server.getInstallFolderPath()"
+```
+
+Upstream's own `tests/shared/utils.py:get_install_folder` uses the same `return` convention. Result is always a string — JSON-encode and decode if you need richer types.
+
+### Plugin state is not on the HTTP API — use the IOM
+
+Indigo's HTTP API (`/v2/api/indigo.<endpoint>`) only knows about `devices`, `variables`, `actionGroups`, `controlPages`, `logs`, `triggers`, `schedules`. There is no `indigo.plugins` endpoint. Plugin state queries (`isEnabled`, `isRunning`, `isInstalled`) go through the IOM via `run_host_script`:
+
+```python
+from shared import APIBase
+from shared.utils import run_host_script
+
+class TestPluginLoaded(APIBase):
+    def test_loaded(self):
+        script = (
+            f"plugin = indigo.server.getPlugin('{self.plugin_id}')\n"
+            f"if plugin is None:\n"
+            f"    return 'state=missing'\n"
+            f"return f'state=found|enabled={{plugin.isEnabled()}}|running={{plugin.isRunning()}}'\n"
+        )
+        result = run_host_script(script)
+        self.assertIn("enabled=True", result, f"indigo-host returned: {result!r}")
+```
+
+The plugin object's API (`isInstalled()`, `isEnabled()`, `isRunning()`, plus several properties) is documented in `/indigo:dev` → `docs/plugin-dev/api/iom/command-namespaces.md` under "Plugin Object Access". That's the SDK side; this section covers how to *invoke* it from a TestingBase test.
+
+### `/usr/local/indigo/` must be traversable by your user
+
+A fresh Indigo 2025.2 install sets `drwxrwx---  root:wheel` on `/usr/local/indigo/`, which means a regular user can't even traverse into the directory to execute `indigo-host` or `indigo-restart-plugin`. Symptom: `PermissionError: [Errno 13] Permission denied: '/usr/local/indigo/indigo-host'` raised from `subprocess.run` inside `setUpClass`.
+
+Fix once on each developer machine:
+
+```bash
+sudo chmod 0755 /usr/local/indigo/   # makes the dir traversable + listable
+```
+
+The binaries inside stay `0770 root:admin` so only admin-group users can run them. macOS primary users are in `admin` by default.
+
+### Reflector setup needs an Indigo Server restart
+
+If `URL_PREFIX` points at a brand-new reflector (e.g. `https://yourname.indigodomo.net`), the reflector address resolves immediately but indigodomo.com's reflector service shows "Reflector Not Found" until Indigo Server is restarted with the reflector configured. Symptom: `httpx` returns HTTP 200 with the public indigodomo.com error page (HTML, not JSON). Fix: restart Indigo Server after enabling the reflector.
+
+### Local IWS is HTTP, not HTTPS
+
+`URL_PREFIX=https://localhost:8176` gives an SSL handshake timeout — local Indigo Web Server is HTTP-only by default. Use `http://localhost:8176` for direct local testing, or a reflector for HTTPS. The upstream `ENV_TEMPLATE` shows `https://localhost:8176` as the default, which is misleading for local-only setups.
+
+---
+
 ## References
 
-- TestingBase upstream: https://github.com/IndigoDomotics/TestingBase
+- TestingBase upstream (authoritative for TestingBase): https://github.com/IndigoDomotics/TestingBase
+- TestingBase upstream `example_test_xml_files.py`: shows the canonical `ValidateXmlFile` patterns
 - Plugin HTTP API (consumed by Pattern B): see `/indigo:api`
 - Plugin lifecycle (what you'd typically test): see `concepts/plugin-lifecycle.md`
+- Plugin Object Access (the IOM surface for plugin queries): see `docs/plugin-dev/api/iom/command-namespaces.md` — "Plugin Object Access" section

From 892f8ac5934305ee9ebad1678939d5b6a4ee7c51 Mon Sep 17 00:00:00 2001
From: Simon Clark <simon@starmerclark.com>
Date: Tue, 5 May 2026 08:50:13 +0100
Subject: [PATCH 2/2] docs: separate upstream conventions from pilot
 field-notes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR review feedback: my first version conflated TestingBase upstream-
documented conventions with empirical findings from the netro pilot.
Restructure to make provenance explicit:

**Upstream conventions** (verified against upstream README):
1. run_host_script uses return, not print — quotes the upstream README
   directly ("return whatever value the script returns"), with code
   contrast.
2. Plugin state via IOM — quotes upstream's "useful for testing
   functions in the IOM that don't have a corresponding API method",
   plus Indigo's own authoritative endpoint list.

**Setup notes** (from real-world adoption, NOT upstream docs):
3. /usr/local/indigo/ perms — clearly framed as a finding from a
   specific fresh install; whether universal is unclear; most users
   won't hit it.
4. Reflector setup needs server restart — clearly framed as an Indigo
   Server quirk, not a TestingBase issue.
5. URL_PREFIX must match server config — REWRITTEN. The previous
   "local IWS is HTTP" claim was too absolute. Indigo can be
   configured to force HTTPS on local; the right URL_PREFIX is
   whatever your specific server is configured to accept. Three
   sub-cases documented (HTTP localhost, force-HTTPS, Reflector).

Honest provenance prevents future readers from assuming the field
notes are upstream-sanctioned. Item 5's rewrite specifically corrects
an over-confident claim that didn't account for server configuration.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/plugin-dev/patterns/testing.md | 58 ++++++++++++++++++++---------
 1 file changed, 40 insertions(+), 18 deletions(-)

diff --git a/docs/plugin-dev/patterns/testing.md b/docs/plugin-dev/patterns/testing.md
index 8e7d46f..d6e8b20 100644
--- a/docs/plugin-dev/patterns/testing.md
+++ b/docs/plugin-dev/patterns/testing.md
@@ -127,15 +127,19 @@ Use both for any non-trivial plugin: A on every commit, B before each release.
 
 ---
 
-## TestingBase conventions worth knowing
+## TestingBase conventions (from upstream docs)
 
-The upstream [TestingBase repo](https://github.com/IndigoDomotics/TestingBase) is the authoritative source for TestingBase usage — its `README.md` and `example_test_xml_files.py` document the public API. `/indigo:dev` covers Indigo plugin SDK questions; for TestingBase-specific questions, read upstream first.
+The upstream [TestingBase repo](https://github.com/IndigoDomotics/TestingBase) is the **authoritative source for TestingBase usage** — its `README.md` and `example_test_xml_files.py` document the public API. `/indigo:dev` covers Indigo plugin SDK questions; for TestingBase-specific questions, read upstream first.
 
-A few conventions that aren't intuitive and have bitten downstream consumers:
+Two conventions from upstream that aren't intuitive at first read:
 
 ### `run_host_script` uses `return`, not `print`
 
-`tests/shared/utils.py:run_host_script(script)` wraps `indigo-host -e <script>`. Indigo wraps your script as a function body; `print()` goes to Indigo's event log, not the subprocess stdout. Use `return` to send a value back:
+Per upstream README:
+
+> `run_host_script(script: str) -> str` — this will accept an Indigo Python script, run it against the IPH, and **return whatever value the script returns**.
+
+Indigo wraps your script as a function body; `print()` inside it goes to Indigo's event log, not the subprocess stdout. Use `return` to send a value back:
 
 ```python
 # WRONG — print goes to event log, run_host_script returns ""
@@ -145,11 +149,13 @@ script = "print(indigo.server.getInstallFolderPath())"
 script = "return indigo.server.getInstallFolderPath()"
 ```
 
-Upstream's own `tests/shared/utils.py:get_install_folder` uses the same `return` convention. Result is always a string — JSON-encode and decode if you need richer types.
+Upstream's own `tests/shared/utils.py:get_install_folder` uses the same `return` convention. Result is always a string — JSON-encode in the script and decode in the test if you need richer types.
 
 ### Plugin state is not on the HTTP API — use the IOM
 
-Indigo's HTTP API (`/v2/api/indigo.<endpoint>`) only knows about `devices`, `variables`, `actionGroups`, `controlPages`, `logs`, `triggers`, `schedules`. There is no `indigo.plugins` endpoint. Plugin state queries (`isEnabled`, `isRunning`, `isInstalled`) go through the IOM via `run_host_script`:
+Per upstream README, `run_host_script` is *"useful for testing functions in the IOM that don't have a corresponding API method"*. Plugin state is one such case.
+
+Indigo's HTTP API (`/v2/api/indigo.<endpoint>`) only exposes `devices`, `variables`, `actionGroups`, `controlPages`, `logs`, `triggers`, `schedules` — Indigo itself returns this list when you hit an invalid endpoint. There is no `indigo.plugins` endpoint. To query `isEnabled`, `isRunning`, or `isInstalled`, go through the IOM:
 
 ```python
 from shared import APIBase
@@ -167,34 +173,50 @@ class TestPluginLoaded(APIBase):
         self.assertIn("enabled=True", result, f"indigo-host returned: {result!r}")
 ```
 
-The plugin object's API (`isInstalled()`, `isEnabled()`, `isRunning()`, plus several properties) is documented in `/indigo:dev` → `docs/plugin-dev/api/iom/command-namespaces.md` under "Plugin Object Access". That's the SDK side; this section covers how to *invoke* it from a TestingBase test.
+The plugin object's API (`isInstalled()`, `isEnabled()`, `isRunning()`, plus several properties) is in `/indigo:dev` → `docs/plugin-dev/api/iom/command-namespaces.md` under "Plugin Object Access". That's the SDK side; this section is about how to *invoke* it from a TestingBase test.
+
+---
+
+## Setup notes (from real-world adoption, not upstream docs)
 
-### `/usr/local/indigo/` must be traversable by your user
+These aren't in TestingBase's documentation — they're observations from this workspace's first adoption. Treat them as field notes; your environment may differ.
 
-A fresh Indigo 2025.2 install sets `drwxrwx---  root:wheel` on `/usr/local/indigo/`, which means a regular user can't even traverse into the directory to execute `indigo-host` or `indigo-restart-plugin`. Symptom: `PermissionError: [Errno 13] Permission denied: '/usr/local/indigo/indigo-host'` raised from `subprocess.run` inside `setUpClass`.
+### `/usr/local/indigo/` perms can block your user from executing `indigo-host`
 
-Fix once on each developer machine:
+On at least one fresh install of Indigo 2025.2 we saw `/usr/local/indigo/` shipped as `drwxrwx--- root:wheel`. A regular user (not in `wheel`) can't even traverse into the directory to execute `indigo-host`. Symptom: `PermissionError: [Errno 13] Permission denied: '/usr/local/indigo/indigo-host'` raised from `subprocess.run` inside `setUpClass`, before any test code runs.
+
+If you hit this, the one-time fix is:
 
 ```bash
 sudo chmod 0755 /usr/local/indigo/   # makes the dir traversable + listable
 ```
 
-The binaries inside stay `0770 root:admin` so only admin-group users can run them. macOS primary users are in `admin` by default.
+The binaries inside stay `0770 root:admin` so only admin-group users can run them. macOS primary users are in `admin` by default. Whether this perm pattern is universal across all 2025.2 installs or installer-state-dependent is unclear — most users will never hit this since they won't be freshly setting up a developer machine. Documenting the fix here for the few who do.
+
+### "Reflector Not Found" from a fresh reflector → restart Indigo Server
+
+When you configure a new reflector in Indigo's preferences, the reflector address resolves immediately on the internet, but indigodomo.com's reflector service won't recognise it as live until Indigo Server is restarted. Until then, `httpx` returns HTTP 200 with the public indigodomo.com "Indigo Reflector Not Found" HTML error page. The test will fail with assertion errors that look like JSON-parse failures.
+
+Fix: restart Indigo Server after enabling the reflector. Same applies if you change the reflector subdomain.
+
+This is an Indigo Server quirk, not a TestingBase issue — but worth knowing because the failure mode is confusing (the test sees a 200, not a 404).
 
-### Reflector setup needs an Indigo Server restart
+### `URL_PREFIX` must match your Indigo Server's HTTPS configuration
 
-If `URL_PREFIX` points at a brand-new reflector (e.g. `https://yourname.indigodomo.net`), the reflector address resolves immediately but indigodomo.com's reflector service shows "Reflector Not Found" until Indigo Server is restarted with the reflector configured. Symptom: `httpx` returns HTTP 200 with the public indigodomo.com error page (HTML, not JSON). Fix: restart Indigo Server after enabling the reflector.
+The upstream `ENV_TEMPLATE` shows `shared.URL_PREFIX=https://localhost:8176` as the default. Whether that's correct depends on how your Indigo Server is configured:
 
-### Local IWS is HTTP, not HTTPS
+- **If Indigo allows HTTP on localhost** (the typical out-of-box setup): use `http://localhost:8176`. The default `https://` form will give an SSL handshake timeout because the local IWS isn't terminating TLS.
+- **If you've enabled "force HTTPS" in Indigo's Server preferences**, or you're hitting a Reflector: use `https://...`.
+- **If you're using a Reflector** (e.g. `https://yourname.indigodomo.net`): always `https://`.
 
-`URL_PREFIX=https://localhost:8176` gives an SSL handshake timeout — local Indigo Web Server is HTTP-only by default. Use `http://localhost:8176` for direct local testing, or a reflector for HTTPS. The upstream `ENV_TEMPLATE` shows `https://localhost:8176` as the default, which is misleading for local-only setups.
+The right `URL_PREFIX` is whatever protocol your specific server is configured to accept — check Indigo's Server preferences if unsure. Match it; the upstream default is reasonable for the Reflector case but assumes a particular config for localhost.
 
 ---
 
 ## References
 
-- TestingBase upstream (authoritative for TestingBase): https://github.com/IndigoDomotics/TestingBase
-- TestingBase upstream `example_test_xml_files.py`: shows the canonical `ValidateXmlFile` patterns
+- TestingBase upstream (authoritative for TestingBase usage): https://github.com/IndigoDomotics/TestingBase
+- TestingBase upstream `example_test_xml_files.py`: canonical `ValidateXmlFile` patterns
 - Plugin HTTP API (consumed by Pattern B): see `/indigo:api`
 - Plugin lifecycle (what you'd typically test): see `concepts/plugin-lifecycle.md`
-- Plugin Object Access (the IOM surface for plugin queries): see `docs/plugin-dev/api/iom/command-namespaces.md` — "Plugin Object Access" section
+- Plugin Object Access (the IOM surface for plugin queries): `docs/plugin-dev/api/iom/command-namespaces.md` — "Plugin Object Access" section