fix(test): BrowserTest reports unwired this.browser with browserDescribe() hint (#2782)

* fix(test): BrowserTest reports unwired this.browser with browserDescribe() hint

Plain describe() blocks inside BrowserTest subclasses left this.browser
as an empty string, so the first DSL call surfaced as
"function [visitUrl] does not exist in the String" — a misleading error
that hits every newcomer on iteration 1. Install an UnwiredBrowserGuard
sentinel at this.browser before browserDescribe() wires a real
BrowserClient (and after $endBrowserContext tears it down) so any method
call throws Wheels.BrowserTest.NotWired with a message naming
browserDescribe() as the fix.

Fixes #2778

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(web/guides): note Wheels.BrowserTest.NotWired when describe() used instead of browserDescribe()

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: wheels-bot[bot]

.ai/wheels/testing/browser-testing.md

@@ -59,6 +59,7 @@ bash tools/test-local.sh                    # skips browser specs if JARs missin
 
 ## Key gotchas
 
+- **`this.browser` is not wired in plain `describe()` blocks.** Calling any DSL method on `this.browser` outside a `browserDescribe()` block throws `Wheels.BrowserTest.NotWired` (message names `browserDescribe()` as the fix; `detail` names the method that was called). The sentinel `UnwiredBrowserGuard` is installed at construction and after each `$endBrowserContext()` teardown.
 - **`##` in selectors** — CFML requires `##` to emit literal `#`. `"##email"` → `"#email"` at runtime.
 - **`client` is a Lucee reserved scope.** `var client = ...` in a closure throws "client scope is not enabled". Use `var c = ...` or `var bc = ...`. (Generalized rule: see CLAUDE.md anti-pattern #11.)
 - **Data URLs work for most tests** — no server needed for ~95% of DSL coverage. Full HTTP integration (cookies, form submits, redirects) needs a running fixture app; that wiring is the same as Wheels Web app bootstrap (separate server + baseUrl).

CHANGELOG.md

@@ -22,6 +22,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ### Fixed
 
+- `wheels.wheelstest.BrowserTest` now throws a clear `Wheels.BrowserTest.NotWired` error — naming `browserDescribe()` as the fix — when a spec calls a DSL method on `this.browser` from a plain `describe()` block. Previously the uninitialized `this.browser` was an empty string, producing the misleading `function [visitUrl] does not exist in the String` on every newcomer's first BrowserTest spec. A sentinel `UnwiredBrowserGuard` is now installed at `this.browser` before `browserDescribe()` wires the real `BrowserClient` and after `$endBrowserContext()` tears it down
 - Linux `.deb` / `.rpm` packages double-nested the framework at `/opt/wheels/module/vendor/wheels/wheels/` instead of `/opt/wheels/module/vendor/wheels/`. `wheels-core-VER.zip` carries a top-level `wheels/` directory that `unzip` preserves; the nfpm `type: tree` rule then copied the entire `build/framework/` tree (wrapper and all) into the destination, leaving `Injector.cfc` one level too deep. Every fresh `wheels new` install on Ubuntu/Fedora then crashed on first request with `could not find component or class with name [wheels.Injector]`, cascading into the cryptic `The key [WO] does not exist.` error in `onError`. The brew formula handles this correctly via `(share/"wheels/framework/wheels").install Dir["*"]`; the Linux nfpm configs now pin `src` at `./build/framework/wheels/` to match. Regression spec at `vendor/wheels/tests/specs/cli/LinuxPackageStagingSpec.cfc` (#2773)
 - `onError` in the generated app template and demo `public/Application.cfc` now guards `application.wo` with `StructKeyExists(application, "wo")` after the recovery try/catch. When `new wheels.Injector(...)` fails during `onApplicationStart` (e.g. a stale `/wheels` mapping under Lucee Express 7), the original error is preserved via a minimal HTML fallback instead of cascading into the cryptic "The key [WO] does not exist" exception that hit "Your First 15 Minutes" tutorial users on fresh installs
 

vendor/wheels/tests/specs/wheelstest/BrowserTestNotWiredSpec.cfc

@@ -0,0 +1,36 @@
+/**
+ * Self-test for the unwired-this.browser guard. A BrowserTest subclass
+ * that uses plain describe() (instead of browserDescribe()) must surface
+ * a clear "use browserDescribe()" error when any method is invoked on
+ * this.browser — not "function [visitUrl] does not exist in the String".
+ */
+component extends="wheels.WheelsTest" {
+
+    function run() {
+        describe("BrowserTest unwired this.browser guard", () => {
+
+            it("throws Wheels.BrowserTest.NotWired when a DSL method is called before browserDescribe wiring", () => {
+                var spec = new wheels.wheelstest.BrowserTest();
+                expect(function() {
+                    spec.browser.visitUrl("data:text/html,<h1>Hi</h1>");
+                }).toThrow(type="Wheels.BrowserTest.NotWired");
+            });
+
+            it("error message names browserDescribe() so users see the fix", () => {
+                var spec = new wheels.wheelstest.BrowserTest();
+                var state = {message: "", detail: ""};
+
+                try {
+                    spec.browser.assertSee("anything");
+                } catch (Wheels.BrowserTest.NotWired e) {
+                    state.message = e.message;
+                    state.detail = e.detail;
+                }
+
+                expect(state.message).toInclude("browserDescribe");
+                expect(state.detail).toInclude("assertSee");
+            });
+
+        });
+    }
+}

vendor/wheels/wheelstest/BrowserTest.cfc

@@ -38,7 +38,11 @@ component extends="wheels.WheelsTest" {
     this.browserEngine = "chromium";
     this.browserViewport = "";  // empty = Playwright default; "mobile"/"tablet"/"desktop" or {width:N, height:N}
     this.browserScreenshotOnFailure = true;
-    this.browser = "";
+    // Sentinel: any method call on this.browser before browserDescribe() wires
+    // a real BrowserClient throws Wheels.BrowserTest.NotWired with a helpful
+    // message naming browserDescribe(), instead of the misleading
+    // "function [X] does not exist in the String".
+    this.browser = new wheels.wheelstest.UnwiredBrowserGuard();
     this.browserTestSkipped = false;
 
     variables.$launcher = "";
@@ -178,7 +182,7 @@ component extends="wheels.WheelsTest" {
             }
             variables.$context = "";
             variables.$page = "";
-            this.browser = "";
+            this.browser = new wheels.wheelstest.UnwiredBrowserGuard();
         }
     }
 
@@ -256,6 +260,7 @@ component extends="wheels.WheelsTest" {
     public void function $captureFailureArtifacts(required any spec) {
         if (!(this.browserScreenshotOnFailure ?: true)) return;
         if (!isObject(this.browser) || this.browserTestSkipped) return;
+        if (structKeyExists(this.browser, "$isUnwiredBrowserGuard")) return;
 
         try {
             var artifactDir = this.browserArtifactPath

vendor/wheels/wheelstest/UnwiredBrowserGuard.cfc

@@ -0,0 +1,26 @@
+/**
+ * Sentinel installed at `this.browser` before browserDescribe() wires a real
+ * BrowserClient. Any DSL method call (visitUrl, click, assertSee, ...) raises
+ * Wheels.BrowserTest.NotWired with a message that names the actual cause —
+ * the spec is using plain describe() inside a BrowserTest subclass — instead
+ * of the original misleading "function [X] does not exist in the String".
+ *
+ * Carries a flag `this.$isUnwiredBrowserGuard = true` so callers that need to
+ * distinguish the guard from a real BrowserClient can use structKeyExists()
+ * without invoking onMissingMethod.
+ */
+component {
+
+    this.$isUnwiredBrowserGuard = true;
+
+    public any function onMissingMethod(
+        required string missingMethodName,
+        required struct missingMethodArguments
+    ) {
+        throw(
+            type="Wheels.BrowserTest.NotWired",
+            message="this.browser is not wired. BrowserTest specs must use browserDescribe() blocks instead of describe() — the framework only populates this.browser inside browserDescribe() callbacks.",
+            detail="Attempted to call this.browser." & arguments.missingMethodName & "() outside a browserDescribe() block. Change describe(...) to browserDescribe(...) so the browser context is set up per `it` block, or do not access this.browser from this block."
+        );
+    }
+}

web/sites/guides/src/content/docs/v4-0-1-snapshot/testing/browser-tests.mdx

@@ -67,7 +67,7 @@ Two things to note in every browser spec:
 
 ## `browserDescribe` vs `describe`
 
-Regular `describe()` works inside a `BrowserTest` subclass — but every `it` inside it would share the same browser state, because `beforeEach`/`afterEach` aren't automatically wired. `browserDescribe()` wraps `describe()` with hooks that create a fresh Playwright `BrowserContext` and `Page` per `it`, then tear them down afterwards. Each test gets its own cookies, localStorage, and navigation history.
+Regular `describe()` works inside a `BrowserTest` subclass — but `this.browser` is **not wired** inside a plain `describe()` block. Calling any DSL method on it (for example, `this.browser.visitUrl(...)`) throws `Wheels.BrowserTest.NotWired` with a message that names `browserDescribe()` as the fix. If you see that error, change `describe(...)` to `browserDescribe(...)`. `browserDescribe()` wraps `describe()` with hooks that create a fresh Playwright `BrowserContext` and `Page` per `it`, then tear them down afterwards. Each test gets its own cookies, localStorage, and navigation history.
 
 ```cfm {test:compile} title="tests/specs/browser/IsolationSpec.cfc"
 component extends="wheels.wheelstest.BrowserTest" {