From 9fa5a9eee05d922b46805e38be84953e422f2db5 Mon Sep 17 00:00:00 2001
From: Corbin Crutchley <git@crutchcorn.dev>
Date: Mon, 4 May 2026 06:30:29 -0700
Subject: [PATCH] chore: add react island strategy tests

---
 tests/specs/IslandClientStrategyReactSpec.cfc | 113 ++++++++++++
 ...ec.cfc => IslandClientStrategyVueSpec.cfc} |  10 +-
 tests/specs/IslandLoadStrategyReactSpec.cfc   | 162 ++++++++++++++++++
 ...Spec.cfc => IslandLoadStrategyVueSpec.cfc} |   9 +-
 4 files changed, 285 insertions(+), 9 deletions(-)
 create mode 100644 tests/specs/IslandClientStrategyReactSpec.cfc
 rename tests/specs/{IslandClientStrategySpec.cfc => IslandClientStrategyVueSpec.cfc} (93%)
 create mode 100644 tests/specs/IslandLoadStrategyReactSpec.cfc
 rename tests/specs/{IslandLoadStrategySpec.cfc => IslandLoadStrategyVueSpec.cfc} (94%)

diff --git a/tests/specs/IslandClientStrategyReactSpec.cfc b/tests/specs/IslandClientStrategyReactSpec.cfc
new file mode 100644
index 0000000..07f2c75
--- /dev/null
+++ b/tests/specs/IslandClientStrategyReactSpec.cfc
@@ -0,0 +1,113 @@
+/**
+ * Spec: <cf_Island framework={React} strategy="client">
+ *
+ * React parity of IslandClientStrategySpec. Island.cfm is framework-agnostic
+ * (it dispatches via the framework struct's .name / .clientEntry / .render /
+ * .ssrRender), so this spec proves the same client-strategy contract holds
+ * when a React-shaped struct is plugged in: no SSR call, no SSR HTML/CSS,
+ * empty mount div, boot script with the React client entry.
+ */
+component extends="testbox.system.BaseSpec" {
+
+	function beforeAll(){
+		application.coldspaConfig = {
+			"isDev":    true,
+			"debug":    false,
+			"vitePort": "5173",
+			"viteUrl":  "http://localhost:5173",
+			"ssrUrl":   "http://127.0.0.1:5174"
+		};
+	}
+
+	function run(){
+
+		describe( "cf_Island strategy=client (React)", function(){
+
+			beforeEach( function( currentSpec ){
+				variables.ssrCallCount = 0;
+
+				variables.mockReact = {
+					"name":        "React",
+					"clientEntry": "./coldspa/vite/clients/react-client.js",
+					"ssrRender":   function( componentGlobKey, props, slotHtml, namedSlots ){
+						variables.ssrCallCount++;
+						return { "html": "<p>SHOULD NOT APPEAR</p>", "css": "", "error": "" };
+					},
+					"render":      function( mountId, componentGlobKey, propsJson, resolvedClientEntry, optionsJson ){
+						return {
+							"imports": "import { mount } from '" & arguments.resolvedClientEntry & "';",
+							"body":    "mount('" & arguments.componentGlobKey & "', document.getElementById('" & arguments.mountId & "'), " & arguments.propsJson & ", " & arguments.optionsJson & ");"
+						};
+					}
+				};
+			} );
+
+			it( "skips SSR entirely (does not call framework.ssrRender)", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = { "msg": "hi" }, strategy = "client" );
+				expect( ssrCallCount ).toBe( 0, "ssrRender must not run when strategy=client" );
+				expect( html ).notToInclude( "SHOULD NOT APPEAR" );
+			} );
+
+			it( "emits an empty mount div tagged for React (no SSR HTML inside)", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = {}, strategy = "client" );
+				expect( html ).toMatch( '<div id="island-[a-f0-9]+" data-coldspa-island="React"></div>' );
+			} );
+
+			it( "does not emit any SSR style or link tags", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = {}, strategy = "client" );
+				expect( html ).notToInclude( "data-coldspa-ssr" );
+			} );
+
+			it( "does not emit a slot template when there are no slots", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = {}, strategy = "client" );
+				expect( html ).notToInclude( "<template" );
+				expect( html ).notToInclude( "data-coldspa-slot" );
+			} );
+
+			it( "emits a script module tag with the mount call importing the React client entry", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = { "msg": "hi" }, strategy = "client" );
+				expect( html ).toInclude( '<script type="module">' );
+				expect( html ).toInclude( "import { mount } from 'http://localhost:5173/coldspa/vite/clients/react-client.js';" );
+				expect( html ).toInclude( "mount('/Hello.jsx', document.getElementById(" );
+			} );
+
+			it( "serializes mount options with strategy:'client' and hasSlot:false", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = {}, strategy = "client" );
+				expect( html ).toMatch( '"strategy"\s*:\s*"client"' );
+				expect( html ).toMatch( '"hasSlot"\s*:\s*false' );
+			} );
+
+			it( "serializes the props the caller passed", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = { "msg": "hello world" }, strategy = "client" );
+				expect( html ).toInclude( '"msg":"hello world"' );
+			} );
+
+			it( "does NOT wrap the boot in requestIdleCallback or IntersectionObserver", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = {}, strategy = "client" );
+				expect( html ).notToInclude( "requestIdleCallback" );
+				expect( html ).notToInclude( "IntersectionObserver" );
+			} );
+
+		} );
+
+	}
+
+	private string function renderIsland(
+		required struct framework,
+		required string path,
+		struct props      = {},
+		string strategy   = "client"
+	){
+		var out = "";
+		savecontent variable="out" {
+			cf_Island(
+				framework = arguments.framework,
+				path      = arguments.path,
+				props     = arguments.props,
+				strategy  = arguments.strategy
+			);
+		}
+		return out;
+	}
+
+}
diff --git a/tests/specs/IslandClientStrategySpec.cfc b/tests/specs/IslandClientStrategyVueSpec.cfc
similarity index 93%
rename from tests/specs/IslandClientStrategySpec.cfc
rename to tests/specs/IslandClientStrategyVueSpec.cfc
index f8e668b..177afff 100644
--- a/tests/specs/IslandClientStrategySpec.cfc
+++ b/tests/specs/IslandClientStrategyVueSpec.cfc
@@ -1,13 +1,13 @@
 /**
- * Spec: <cf_Island> with strategy="client"
+ * Spec: <cf_Island framework={Vue} strategy="client">
  *
  * The "client" strategy is the no-SSR contract: Island.cfm must NOT call the
  * framework's ssrRender(), must NOT emit SSR HTML / CSS / link tags, and must
  * still emit a boot script that the client uses to mount the component.
  *
- * We use a mock framework struct so the spec is hermetic — no Vite, no SSR
- * sidecar, no network. The shape (name, clientEntry, render, ssrRender) is
- * the same one Vue.cfm / React.cfm produce.
+ * We use a mock framework struct shaped like the one Vue.cfm produces, so
+ * the spec is hermetic — no Vite, no SSR sidecar, no network. React parity
+ * for this contract lives in IslandClientStrategyReactSpec.cfc.
  */
 component extends="testbox.system.BaseSpec" {
 
@@ -25,7 +25,7 @@ component extends="testbox.system.BaseSpec" {
 
 	function run(){
 
-		describe( "cf_Island strategy=client", function(){
+		describe( "cf_Island strategy=client (Vue)", function(){
 
 			beforeEach( function( currentSpec ){
 				// Tracks whether the framework's ssrRender() was invoked.
diff --git a/tests/specs/IslandLoadStrategyReactSpec.cfc b/tests/specs/IslandLoadStrategyReactSpec.cfc
new file mode 100644
index 0000000..5a2f35f
--- /dev/null
+++ b/tests/specs/IslandLoadStrategyReactSpec.cfc
@@ -0,0 +1,162 @@
+/**
+ * Spec: <cf_Island framework={React} strategy="load">
+ *
+ * React parity of IslandLoadStrategySpec. Same SSR + immediate-hydration
+ * contract, exercised through a React-shaped mock framework struct so we
+ * confirm Island.cfm doesn't favor Vue anywhere (mount div tagged "React",
+ * React client entry imported in the boot script, JSX-style component path
+ * threaded through to ssrRender).
+ */
+component extends="testbox.system.BaseSpec" {
+
+	function beforeAll(){
+		application.coldspaConfig = {
+			"isDev":    true,
+			"debug":    false,
+			"vitePort": "5173",
+			"viteUrl":  "http://localhost:5173",
+			"ssrUrl":   "http://127.0.0.1:5174"
+		};
+	}
+
+	function run(){
+
+		describe( "cf_Island strategy=load (React)", function(){
+
+			beforeEach( function( currentSpec ){
+				variables.ssrCalls = [];
+
+				variables.mockReact = {
+					"name":        "React",
+					"clientEntry": "./coldspa/vite/clients/react-client.js",
+					"ssrRender":   function( componentGlobKey, props, slotHtml, namedSlots ){
+						arrayAppend( variables.ssrCalls, {
+							"componentGlobKey": arguments.componentGlobKey,
+							"props":            duplicate( arguments.props ),
+							"slotHtml":         arguments.slotHtml,
+							"namedSlots":       duplicate( arguments.namedSlots )
+						} );
+						return {
+							"html":  "<p data-from-ssr=""yes"">SSR rendered: " & ( arguments.props.msg ?: "" ) & "</p>",
+							"css":   ".coldspa-test{color:red}",
+							"error": ""
+						};
+					},
+					"render":      function( mountId, componentGlobKey, propsJson, resolvedClientEntry, optionsJson ){
+						return {
+							"imports": "import { mount } from '" & arguments.resolvedClientEntry & "';",
+							"body":    "mount('" & arguments.componentGlobKey & "', document.getElementById('" & arguments.mountId & "'), " & arguments.propsJson & ", " & arguments.optionsJson & ");"
+						};
+					}
+				};
+			} );
+
+			it( "calls framework.ssrRender exactly once with the component path, props, and empty slots", function(){
+				renderIsland( framework = mockReact, path = "./Hello.jsx", props = { "msg": "hi" } );
+				expect( arrayLen( ssrCalls ) ).toBe( 1 );
+				expect( ssrCalls[1].componentGlobKey ).toBe( "/Hello.jsx" );
+				expect( ssrCalls[1].props.msg ).toBe( "hi" );
+				expect( ssrCalls[1].slotHtml ).toBe( "" );
+				expect( structIsEmpty( ssrCalls[1].namedSlots ) ).toBeTrue();
+			} );
+
+			it( "injects the SSR HTML inside the React-tagged mount div", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = { "msg": "world" } );
+				expect( html ).toMatch( '<div id="island-[a-f0-9]+" data-coldspa-island="React"><p data-from-ssr="yes">SSR rendered: world</p></div>' );
+			} );
+
+			it( "emits the SSR CSS in a tagged style element", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = {} );
+				expect( html ).toMatch( '<style data-coldspa-ssr="island-[a-f0-9]+">\.coldspa-test\{color:red\}</style>' );
+			} );
+
+			it( "emits an immediate boot script importing the React client entry (no idle / observer wrappers)", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = {} );
+				expect( html ).toInclude( '<script type="module">' );
+				expect( html ).toInclude( "import { mount } from 'http://localhost:5173/coldspa/vite/clients/react-client.js';" );
+				expect( html ).toInclude( "mount('/Hello.jsx', document.getElementById(" );
+				expect( html ).notToInclude( "requestIdleCallback" );
+				expect( html ).notToInclude( "IntersectionObserver" );
+			} );
+
+			it( "serializes mount options with strategy=load and hasSlot=false (no slot content)", function(){
+				var html = renderIsland( framework = mockReact, path = "./Hello.jsx", props = {} );
+				expect( html ).toMatch( '"strategy"\s*:\s*"load"' );
+				expect( html ).toMatch( '"hasSlot"\s*:\s*false' );
+			} );
+
+			it( "passes default-slot HTML through to ssrRender and stashes it in a slot template", function(){
+				var html = "";
+				savecontent variable="html" {
+					cf_Island(
+						framework = mockReact,
+						path      = "./Hello.jsx",
+						props     = {},
+						strategy  = "load"
+					) {
+						writeOutput( "<span class=""hello"">slotted!</span>" );
+					}
+				}
+				expect( arrayLen( ssrCalls ) ).toBe( 1 );
+				expect( ssrCalls[1].slotHtml ).toInclude( "slotted!" );
+				expect( html ).toMatch( '<template id="slot-[a-f0-9]+" data-coldspa-slot="island-[a-f0-9]+">' );
+				expect( html ).toInclude( "slotted!" );
+				expect( html ).toMatch( '"hasSlot"\s*:\s*true' );
+			} );
+
+			it( "passes named slots through to ssrRender and emits one template per name", function(){
+				var html = "";
+				savecontent variable="html" {
+					cf_Island(
+						framework = mockReact,
+						path      = "./Hello.jsx",
+						props     = {},
+						strategy  = "load"
+					) {
+						cf_Slot( name = "header" ) {
+							writeOutput( "HEADER-CONTENT" );
+						}
+						cf_Slot( name = "footer" ) {
+							writeOutput( "FOOTER-CONTENT" );
+						}
+					}
+				}
+				expect( arrayLen( ssrCalls ) ).toBe( 1 );
+				expect( ssrCalls[1].namedSlots ).toHaveKey( "header" );
+				expect( ssrCalls[1].namedSlots ).toHaveKey( "footer" );
+				expect( ssrCalls[1].namedSlots.header ).toInclude( "HEADER-CONTENT" );
+				expect( ssrCalls[1].namedSlots.footer ).toInclude( "FOOTER-CONTENT" );
+				expect( html ).toMatch( '<template id="slot-[a-f0-9]+-header" data-coldspa-slot="island-[a-f0-9]+" data-coldspa-slot-name="header">HEADER-CONTENT</template>' );
+				expect( html ).toMatch( '<template id="slot-[a-f0-9]+-footer" data-coldspa-slot="island-[a-f0-9]+" data-coldspa-slot-name="footer">FOOTER-CONTENT</template>' );
+			} );
+
+			it( "uses the framework name in the data-coldspa-island attribute", function(){
+				// Swap the renderer name to prove it isn't hardcoded.
+				mockReact.name = "Vue";
+				var html = renderIsland( framework = mockReact, path = "./Hello.vue", props = {} );
+				expect( html ).toInclude( 'data-coldspa-island="Vue"' );
+			} );
+
+		} );
+
+	}
+
+	private string function renderIsland(
+		required struct framework,
+		required string path,
+		struct props      = {},
+		string strategy   = "load"
+	){
+		var out = "";
+		savecontent variable="out" {
+			cf_Island(
+				framework = arguments.framework,
+				path      = arguments.path,
+				props     = arguments.props,
+				strategy  = arguments.strategy
+			);
+		}
+		return out;
+	}
+
+}
diff --git a/tests/specs/IslandLoadStrategySpec.cfc b/tests/specs/IslandLoadStrategyVueSpec.cfc
similarity index 94%
rename from tests/specs/IslandLoadStrategySpec.cfc
rename to tests/specs/IslandLoadStrategyVueSpec.cfc
index c98f4d4..5b6570a 100644
--- a/tests/specs/IslandLoadStrategySpec.cfc
+++ b/tests/specs/IslandLoadStrategyVueSpec.cfc
@@ -1,5 +1,5 @@
 /**
- * Spec: <cf_Island> with strategy="load" (SSR + immediate hydration)
+ * Spec: <cf_Island framework={Vue} strategy="load"> (SSR + immediate hydration)
  *
  * The "load" strategy is the default. Island.cfm must:
  *   - call framework.ssrRender(componentPath, props, slotHtml, namedSlots)
@@ -13,8 +13,9 @@
  *     no IntersectionObserver wrapper)
  *   - serialize mount options with strategy="load"
  *
- * Like the client spec, this is hermetic: a mock framework struct stands
- * in for Vue/React so we don't depend on the SSR sidecar.
+ * Like the client spec, this is hermetic: a mock Vue-shaped framework struct
+ * stands in for the real renderer so we don't depend on the SSR sidecar.
+ * React parity for this contract lives in IslandLoadStrategyReactSpec.cfc.
  */
 component extends="testbox.system.BaseSpec" {
 
@@ -30,7 +31,7 @@ component extends="testbox.system.BaseSpec" {
 
 	function run(){
 
-		describe( "cf_Island strategy=load", function(){
+		describe( "cf_Island strategy=load (Vue)", function(){
 
 			beforeEach( function( currentSpec ){
 				// Tracks each call into the mock framework so we can assert
-- 
2.51.2