Merge pull request #16 from ColdBox/claude/bx-playwright-research-plan-ddfqpm

Browser testing skills: TestBox BrowserSpec and ColdBox BrowserTestCase

Author: lmajano

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "ColdBox skills for Claude Code — handlers, routing, REST APIs, interceptors, testing, security, ORM, WireBox DI, CacheBox, and LogBox",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "pluginRoot": "."
   },
   "plugins": [
@@ -17,7 +17,7 @@
         "repo": "ColdBox/skills"
       },
       "description": "ColdBox skills for Claude Code — handlers, routing, REST APIs, interceptors, testing, security, ORM, WireBox DI, CacheBox, and LogBox",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "author": {
         "name": "Ortus Solutions",
         "email": "info@ortussolutions.com"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "coldbox-agent-skills",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "ColdBox skills for Claude Code — handlers, routing, REST APIs, interceptors, testing, security, ORM, WireBox DI, CacheBox, LogBox, and ContentBox CMS",
   "author": {
     "name": "Ortus Solutions",

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "coldbox-agent-skills",
   "displayName": "ColdBox Skills",
   "description": "ColdBox skills for Cursor — handlers, routing, REST APIs, interceptors, testing, security, ORM, WireBox DI, CacheBox, LogBox, and ContentBox CMS.",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "Ortus Solutions",
     "url": "https://www.ortussolutions.com"

.grok-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "coldbox-agent-skills",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "ColdBox skills for Grok — handlers, routing, REST APIs, interceptors, testing, security, ORM, WireBox DI, CacheBox, LogBox, and ContentBox CMS.",
   "author": {
     "name": "Ortus Solutions",

README.md

@@ -112,28 +112,30 @@ The [`.claude-plugin/plugin.json`](./.claude-plugin/plugin.json) registers these
 
 | Skill | What It Covers |
 |---|---|
-| [`testing-base-classes`](./coldbox/testing-base-classes/SKILL.md) | Testing class hierarchy, annotations (appMapping, configMapping, unloadColdBox), test harness setup, when to use each base class |
+| [`testing-base-classes`](./coldbox/testing-base-classes/SKILL.md) | Testing class hierarchy, annotations (appMapping, configMapping, unloadColdBox), test harness setup, when to use each base class, including `BrowserTestCase` |
 | [`testing-handler`](./coldbox/testing-handler/SKILL.md) | Handler testing with `execute()`, rc/prc assertions, view selection, renderData, relocations, mock injection, BaseHandlerTest isolation |
 | [`testing-integration`](./coldbox/testing-integration/SKILL.md) | Full virtual-app integration tests, lifecycle management, route testing, database rollback, custom matchers |
 | [`testing-http-methods`](./coldbox/testing-http-methods/SKILL.md) | `get()`, `post()`, `put()`, `patch()`, `delete()`, `request()` simulation, headers, JSON bodies, `toHaveStatus()`, `toHaveInvalidData()` |
 | [`testing-model`](./coldbox/testing-model/SKILL.md) | BaseModelTest, the `model` variable, mockLogger/mockLogBox/mockCacheBox/mockWireBox, mocking collaborators, init() patterns |
 | [`testing-interceptor`](./coldbox/testing-interceptor/SKILL.md) | BaseInterceptorTest, the `interceptor` variable, mockController/mockRequestService/mockFlash, configProperties, announce point testing |
+| [`testing-browser`](./coldbox/testing-browser/SKILL.md) | `BrowserTestCase` browser tests (BoxLang + bx-playwright): `browse()`, `routeURL()`/`visitRoute()`/`assertRouteIs()`, `loginAs()`/`logout()` with the BrowserTesting module and its security model, app server setup, CI |
 
 ### `testbox` — Comprehensive TestBox Skills
 
 | Skill | What It Covers |
 |---|---|
-| [`bdd`](./testbox/bdd/SKILL.md) | BDD suites with describe/it, Gherkin-style given/when/then, lifecycle hooks, focused/skipped specs, nested suites, labels |
-| [`unit`](./testbox/unit/SKILL.md) | xUnit-style tests (testXxx), setup/teardown, `$assert` object, Arrange-Act-Assert pattern |
+| [`bdd`](./testbox/bdd/SKILL.md) | BDD suites with describe/it, Gherkin-style given/when/then, lifecycle hooks, focused/skipped specs, nested suites, labels, spec `retries`, `attach()` |
+| [`unit`](./testbox/unit/SKILL.md) | xUnit-style tests (testXxx), setup/teardown, `$assert` object, Arrange-Act-Assert pattern, `retries` method annotation |
 | [`assertions`](./testbox/assertions/SKILL.md) | `$assert` object, isTrue/isEqual/includes/isEmpty/throws/between/match, custom assertion functions, BoxLang dynamic assertion methods |
-| [`expectations`](./testbox/expectations/SKILL.md) | Fluent `expect()`, all matchers (toBe/toBeTrue/toHaveKey/toThrow/toMatch), `not` operator, `expectAll()` over collections, custom matchers |
+| [`expectations`](./testbox/expectations/SKILL.md) | Fluent `expect()`, all matchers (toBe/toBeTrue/toHaveKey/toThrow/toMatch), `not` operator, `expectAll()` over collections, custom matchers, browser matchers pointer |
 | [`mockbox`](./testbox/mockbox/SKILL.md) | MockBox mocks/stubs/spies, `$()` stubbing, `$args/$results/$throws`, call-count verification, `$callLog`, `querySim`, `$spy` |
 | [`cbmockdata`](./testbox/cbmockdata/SKILL.md) | Generating fake data (age, email, name, uuid, lorem, etc.), arrays of objects, nested objects, custom supplier closures |
-| [`runners`](./testbox/runners/SKILL.md) | CommandBox CLI runner, BoxLang CLI, HTML runner, programmatic TestBox, watcher mode, streaming runner, all CLI flags |
-| [`reporters`](./testbox/reporters/SKILL.md) | ANTJunit/Console/Doc/JSON/JUnit/Min/Simple/Text/XML reporters, reporter options, custom IReporter implementations |
+| [`runners`](./testbox/runners/SKILL.md) | CommandBox CLI runner, BoxLang CLI, HTML runner, programmatic TestBox, watcher mode, streaming runner, all CLI flags including `--retries`, `--failed` and `--web-server` |
+| [`reporters`](./testbox/reporters/SKILL.md) | ANTJunit/Console/Doc/JSON/JUnit/Min/Simple/Text/XML reporters, reporter options, spec attachments and attempts, custom IReporter implementations |
 | [`listeners`](./testbox/listeners/SKILL.md) | Run listeners (onBundleStart/End, onSuiteStart/End, onSpecStart/End), progress indicators, custom loggers, live dashboards |
 | [`testing-fixtures`](./testbox/testing-fixtures/SKILL.md) | Fixture factories, test data builders, shared fixture files, cbMockData integration, setup/teardown strategies |
 | [`testing-coverage`](./testbox/testing-coverage/SKILL.md) | Code coverage setup, coverage reporting, CI integration, TestBox coverage options, improving coverage of untested paths |
+| [`browser-testing`](./testbox/browser-testing/SKILL.md) | `BrowserSpec` browser tests on BoxLang with bx-playwright: `browse()`, annotations, the 9 browser matchers, automatic attachments, `attach()`, retries, `--failed`, `--web-server`, CI, debugging traces |
 
 ### `security` — Security and Authentication Skills
 
@@ -270,7 +272,7 @@ The bundled [`.mcp.json`](./.mcp.json) includes Ortus documentation MCP endpoint
 | Path | Purpose |
 |---|---|
 | [`coldbox/`](./coldbox/) | Core ColdBox framework skills, testing patterns, and database migration workflows |
-| [`testbox/`](./testbox/) | Comprehensive TestBox skills (BDD, xUnit, MockBox, runners, reporters) |
+| [`testbox/`](./testbox/) | Comprehensive TestBox skills (BDD, xUnit, MockBox, runners, reporters, browser testing) |
 | [`security/`](./security/) | Authentication, authorization, CSRF, SSO, passkeys |
 | [`wirebox/`](./wirebox/) | WireBox dependency injection |
 | [`cachebox/`](./cachebox/) | CacheBox standalone caching |

coldbox/testing-base-classes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coldbox-testing-base-classes
-description: "Use this skill to understand which ColdBox testing base class to extend for a given test type, configure test bundle annotations (appMapping, configMapping, unloadColdBox, loadColdBox, coldboxAppKey), set up the tests/ harness (Application.cfc, folder structure), or choose between integration testing (BaseTestCase), isolated handler testing (BaseHandlerTest), model unit testing (BaseModelTest), and interceptor unit testing (BaseInterceptorTest)."
+description: "Use this skill to understand which ColdBox testing base class to extend for a given test type, configure test bundle annotations (appMapping, configMapping, unloadColdBox, loadColdBox, coldboxAppKey), set up the tests/ harness (Application.cfc, folder structure), or choose between integration testing (BaseTestCase), isolated handler testing (BaseHandlerTest), model unit testing (BaseModelTest), interceptor unit testing (BaseInterceptorTest), and real-browser testing of the running app (BrowserTestCase, BoxLang + bx-playwright)."
 applyTo: "**/*.{bx,bxm,cfc,cfm,cfml}"
 ---
 
@@ -13,7 +13,8 @@ testbox.system.BaseSpec
  └── coldbox.system.testing.BaseTestCase
       ├── coldbox.system.testing.BaseHandlerTest
       ├── coldbox.system.testing.BaseModelTest
-      └── coldbox.system.testing.BaseInterceptorTest
+      ├── coldbox.system.testing.BaseInterceptorTest
+      └── coldbox.system.testing.BrowserTestCase   (BoxLang only, ColdBox 8.3+)
 ```
 
 ---
@@ -26,6 +27,7 @@ testbox.system.BaseSpec
 | Handler CFC in complete isolation (no app load) | `BaseHandlerTest` |
 | A model/service/ORM entity in isolation | `BaseModelTest` |
 | An interceptor CFC in isolation | `BaseInterceptorTest` |
+| User journeys in a real browser against the running app (forms, JavaScript, sessions, named routes, `loginAs()`) | `BrowserTestCase` (see `coldbox-testing-browser`) |
 | Any CFML/BX component with no ColdBox app | `BaseSpec` (TestBox) |
 
 ---
@@ -237,6 +239,27 @@ class extends="coldbox.system.testing.BaseInterceptorTest"
 
 ---
 
+## BrowserTestCase (Real Browser)
+
+`BrowserTestCase` (BoxLang only, needs bx-playwright and TestBox 7.2+) still loads the app virtually like `BaseTestCase`, and drives a real browser against your **running** server. Extra annotations: `baseURL` (the running app) and `browserProfile` (bx-playwright profiles). It adds `browse()`, the TestBox browser matchers, and the ColdBox helpers `routeURL()`, `visitRoute()`, `assertRouteIs()`, `loginAs()` and `logout()`. Without bx-playwright its browser specs are skipped, not failed. Full guide: the [`coldbox-testing-browser`](../testing-browser/SKILL.md) skill.
+
+```boxlang
+class extends="coldbox.system.testing.BrowserTestCase" appMapping="/root" baseURL="http://127.0.0.1:8080" {
+    function run() {
+        describe( "Users", () => {
+            it( "shows a user", () => {
+                browse( ( page ) => {
+                    visitRoute( page, "users.show", { id : 5 } )
+                    expect( page ).toSee( "User 5" )
+                } )
+            } )
+        } )
+    }
+}
+```
+
+---
+
 ## Custom TestBox Matchers (ColdBox adds)
 
 | Matcher | Used on | Description |