From f320b3711fdc522a57f84c1fc630b2a00609fbd6 Mon Sep 17 00:00:00 2001
From: Keith Solomon <keith@vincentdesign.ca>
Date: Sat, 4 Jul 2026 15:52:51 -0500
Subject: [PATCH] docs(test): document CWC_TEST_BYPASS_HERO_GATE constant for
 the dev site

isServicesDescendant() gates the inner-page hero on being a Services
descendant. The existing inner-page.spec.js fixtures (sample-page, etc.)
are not Services descendants, so without the bypass the hero would not
render in tests and the suite would fail.

The constant CWC_TEST_BYPASS_HERO_GATE was added in lib/extras.php for
exactly this case, but the dev site's wp-config.php is operator-managed
and cannot be modified by the theme. This note records the single line
the operator needs to add to wp-config.php, plus the rationale and a
production warning.
---
 docs/superpowers/notes/test-env-setup.md | 48 ++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/superpowers/notes/test-env-setup.md

diff --git a/docs/superpowers/notes/test-env-setup.md b/docs/superpowers/notes/test-env-setup.md
new file mode 100644
index 0000000..f21b5eb
--- /dev/null
+++ b/docs/superpowers/notes/test-env-setup.md
@@ -0,0 +1,48 @@
+# Test Environment Setup
+
+## `CWC_TEST_BYPASS_HERO_GATE`
+
+The inner-page hero is gated by `isServicesDescendant()` (see `lib/extras.php`).
+A page renders the hero only if it is the Services page, a direct child of it,
+or a grandchild of it.
+
+The Playwright suite under `tests/` includes fixtures that are **not** Services
+descendants (e.g. `sample-page`). When the new gate is enabled, those pages
+no longer render the hero, and the existing `inner-page.spec.js` assertions
+fail.
+
+To keep the existing test fixtures working without forking the test suite,
+the theme exposes a bypass constant:
+
+```php
+define( 'CWC_TEST_BYPASS_HERO_GATE', true );
+```
+
+When `CWC_TEST_BYPASS_HERO_GATE` is `true`, `isServicesDescendant()` returns
+`true` for every post, so the hero is rendered for all pages — matching the
+pre-gate behavior expected by the existing tests.
+
+## How to enable on the dev site
+
+Add the following line to `wp-config.php` on the dev site
+(`community-works-collaborative.test`), ideally near the other `define()`
+calls in that file:
+
+```php
+define( 'CWC_TEST_BYPASS_HERO_GATE', true );
+```
+
+The constant defaults to `false` in `lib/extras.php`, so production sites are
+unaffected unless this define is added.
+
+## Why this is a manual step
+
+This repository does not own the WordPress install — `wp-config.php` is
+managed by the operator of the dev site. The theme cannot and should not
+modify `wp-config.php` itself.
+
+## Production note
+
+Do **not** define this constant on production. It exists solely to let the
+test environment continue to use the same fixtures the suite was originally
+written against.