Browser-test fixture: built-in /_browser/login-as sets bare session.userId / session.userEmail, no extension point for app session shape #2830

Activity

1. wheels-bot commented on May 28, 2026

   

   wheels-botBot

   on May 28, 2026

   Contributor

   More actions

   Wheels Bot — Triage

   Classified as framework-design (API/feature design question).
   Cross-framework research will follow shortly — Rails, Laravel, Django,
   and other modern frameworks will be consulted before any path forward
   is proposed.

   <!-- wheels-bot:triage:2830 -->
   <!-- wheels-bot:triage-class:framework-design -->
2. wheels-bot commented on May 28, 2026

   

   wheels-botBot

   on May 28, 2026

   Contributor

   More actions

   Wheels Bot — Cross-Framework Research

   Question

   The built-in /_browser/login-as fixture (BrowserTestLogin#create) hard-codes session.userId = 1 and session.userEmail = params.identifier. Real apps store richer session shapes (e.g. session.member = { id, email, firstName, lastName }). There's no extension point for apps that opt into loadBrowserTestFixtures = true to customize the fixture's session writes — today's only paths (don't opt in + write a parallel route, or patch the vendor tree) duplicate boilerplate or break on upgrade. How should the framework expose a clean override hook?

   How other frameworks handle this

   Framework	Naming	Surface	Trade-offs	Edge cases
   Rails (Devise/Warden)	sign_in(user) / login_as	In-process Warden helper; model hook serialize_into_session(record) controls session shape	Same call works in integration + system tests; out-of-process drivers need real HTTP	MFA bypassed; multi-scope namespacing; 4 KB cookie store cap
   Laravel (Dusk)	loginAs($userId, $guard?) browser; actingAs($user) feature	Built-in _dusk/login/{userId}/{guard?} HTTP route; SessionGuard::login() fires Illuminate\Auth\Events\Login, app subscribes via listener	One-liner; no callback on the route itself, enrichment rides the Login event	Multiple guards; email-as-id; MFA out of scope
   Django	Client.force_login(user, backend=None)	Writes three _auth_user_* session keys; fires user_logged_in signal; cookie-transplant for Selenium	Fast (bypasses password); signal is the canonical extension seam	Multi-backend explicit; cookie pattern undocumented but widespread
   Phoenix	log_in_user(conn, user)	Scaffolded into the app by mix phx.gen.auth (both MyAppAuth.log_in_user/3 and MyAppConnCase.log_in_user/2); framework ships no built-in endpoint	Maximum flexibility (app owns the function body); no shared contract; every app diverges	Token-based variant; sudo-mode opts; LiveView/Wallaby reuse the prepared conn
   Symfony (+1: closest PHP analogue, server-side session)	KernelBrowser::loginUser($user, $firewall='main', $tokenAttributes=[])	Direct session write of a serialized TestBrowserToken under _security_<firewall>; $tokenAttributes accepts ad-hoc enrichment	One line; does NOT fire LoginSuccessEvent so app listeners are bypassed in tests — widely-cited pain	Stateless firewalls need per-request injection; Panther needs cookie copy

   Dominant pattern

   All five frameworks converge on the same shape: framework writes a minimal default, app extends. They diverge sharply on the extension mechanism. Three of five (Rails, Django, Laravel) use event/signal listeners that fire from both real and test logins — clean composability with plugins, but it requires pub/sub infrastructure. Symfony does direct token-attribute injection per-call but bypasses its own event chain in tests (a known wart). Phoenix punts entirely with scaffold-the-helper-into-the-app, taking "let the app own the body" to its extreme. The user's suggestion (1) — settings-driven handler delegation — is the Phoenix endpoint dressed in Wheels' Controller##action convention; suggestion (2) is the Laravel/Django/Rails event approach.

   Recommended path for Wheels

   Ship the user's suggestion (1) as the canonical extension point. It matches Wheels' existing routing convention (to = "Controller##action" strings), stores nothing but a string in application.wheels (no Adobe-CF function-member crash, anti-pattern #2), reuses existing route dispatch and controller invocation, and the app's handler is just a normal controller with full access to params, session, model(), and inject(). The framework keeps env-gating and view rendering; the app provides the body. Suggestion (2)'s lifecycle hook is the cross-framework majority but requires event infrastructure Wheels doesn't currently have — defer it.

   // vendor/wheels/public/browser-fixtures/routes.cfm — read override at route-registration
   <cfscript>
   local.loginAsTarget = StructKeyExists(application.wheels, "browserLoginAsHandler")
       && Len(application.wheels.browserLoginAsHandler)
       ? application.wheels.browserLoginAsHandler
       : "BrowserTestLogin##create";
   
   mapper()
       .scope(path = "/_browser", middleware = ["wheels.middleware.BrowserTestFixtureGuard"])
           .get(name = "browserTestLoginAs", pattern = "/login-as", to = local.loginAsTarget)
           // ... other fixture routes ...
       .end()
   .end();
   </cfscript>
   
   // vendor/wheels/middleware/BrowserTestFixtureGuard.cfc — env-gate moves to middleware
   // so it still runs when the app's handler is mapped.
   component implements="wheels.middleware.MiddlewareInterface" {
       public any function handle(required struct request, required any next) {
           if (!ListFindNoCase("testing,development", application.wheels.environment)) {
               Throw(
                   type = "Wheels.BrowserTestSecurityError",
                   message = "/_browser/* endpoints are only available in testing/development"
               );
           }
           return arguments.next(arguments.request);
       }
   }
   
   // App usage — config/settings.cfm
   set(loadBrowserTestFixtures = true);
   set(browserLoginAsHandler = "AuthFixture##loginAs");
   
   // app/controllers/AuthFixture.cfc
   component extends="Controller" {
       function loginAs() {
           var member = model("Member").findOne(where = "email = '#params.identifier#'");
           if (IsObject(member)) {
               session.member = {
                   id: member.id,
                   email: member.email,
                   firstName: member.firstName,
                   lastName: member.lastName
               };
               session.isADAuth = (params.isAD ?: false);
           }
           renderText("ok");
       }
   }

   Lives in: vendor/wheels/public/browser-fixtures/routes.cfm (override read at route registration) + new vendor/wheels/middleware/BrowserTestFixtureGuard.cfc (env-gate extracted from the controller so it still applies under override).

   Composes with: existing Controller##action route targets, the DI container (inject() in config()), params / session, model finders, and any other controller filter. The app's handler is a normal Wheels controller.

   Cross-engine notes

   Clean. Setting holds a string ("AuthFixture##loginAs"), never a closure — avoids the Adobe CF application-scope function-member crash (CLAUDE.md anti-pattern #2). Override is read at route-registration time (single-threaded boot), so no runtime closure-capture concerns. No obj.map(), no obj["key"]() in closures, no <cfheader attributeCollection=arguments> patterns. Standard middleware + controller dispatch, both already validated across Lucee 5/6/7, Adobe 2018/2021/2023/2025, and BoxLang.

   Open questions

   • Should the framework also ship a lighter after-login enrichment callback (set(afterBrowserLoginAs = "AuthFixture##enrichSession")) that runs on top of framework defaults, for apps that want to add fields rather than replace the body? This is the Laravel/Django event-listener shape and composes better with plugins, but adds a second extension point.
   • Should the env-gate middleware apply to the whole /_browser/* scope (defense-in-depth, recommended) or only login-as (matches today's behavior)?
   • Setting name — browserLoginAsHandler (matches the URL segment) vs browserTestLoginAs (matches loadBrowserTestFixtures) vs browserLoginAs? Prefer the first for clarity.
   • Should the app's handler live in app/controllers/ (current convention) or a dedicated app/test-fixtures/controllers/ directory so it's visually quarantined? The loadBrowserTestFixtures gate prevents route registration in production, but the controller class file still ships.
   • Should the override also accept a DI service name (set(browserLoginAsHandler = "browserAuthService")) resolved via service(), for apps that want a non-controller object to handle this? Symmetric with Wheels' DI container conventions.

   Confidence: medium

   Three of five surveyed frameworks (Rails, Django, Laravel) use event/signal listeners as the canonical extension point — a pattern Wheels can't adopt without new pub/sub infrastructure. The handler-override approach (the user's preferred suggestion, well-precedented by Phoenix's scaffold model and Laravel's route-name-takeover escape hatch) is the cleanest fit for Wheels conventions, but it's a meaningful fork from the cross-framework majority — a human should weigh whether to also ship the event/callback variant for plugin composability.

   Sources

   • https://github.com/heartcombo/devise/blob/main/lib/devise/test/integration_helpers.rb
   • https://github.com/heartcombo/devise/blob/main/lib/devise/models/authenticatable.rb
   • https://laravel.com/docs/dusk#authentication
   • https://github.com/laravel/dusk/blob/master/src/DuskServiceProvider.php
   • https://github.com/laravel/dusk/blob/master/src/Http/Controllers/UserController.php
   • https://docs.djangoproject.com/en/stable/topics/testing/tools/#django.test.Client.force_login
   • https://docs.djangoproject.com/en/stable/ref/contrib/auth/#django.contrib.auth.signals.user_logged_in
   • https://hexdocs.pm/phoenix/Mix.Tasks.Phx.Gen.Auth.html
   • https://github.com/phoenixframework/phoenix/blob/main/priv/templates/phx.gen.auth/conn_case.exs.eex
   • https://symfony.com/doc/current/testing.html
   • https://github.com/symfony/symfony/blob/7.2/src/Symfony/Bundle/FrameworkBundle/KernelBrowser.php
3. wheels-bot commented on May 28, 2026

   

   wheels-botBot

   on May 28, 2026

   Contributor

   More actions

   Wheels Bot — Fix proposed

   Draft PR: #2832

   Spec: vendor/wheels/tests/specs/wheelstest/BrowserLoginAsHandlerSpec.cfc — failing → passing.
   Implementation: vendor/wheels/public/browser-fixtures/routes.cfm (reads application.wheels.browserLoginAsHandler, defaults to BrowserTestLogin##create), new vendor/wheels/middleware/BrowserTestFixtureGuard.cfc (env-gate on the /_browser scope), and vendor/wheels/public/browser-fixtures/controllers/BrowserTestLogin.cfc (drops the redundant in-controller env-gate now that the middleware owns it).

   Followed the cross-framework research's recommended path: a settings-driven to = "Controller##action" handler override. The Laravel/Django/Rails event-listener variant from the survey is deferred per the research's note that it would require pub/sub infrastructure Wheels doesn't currently have.

   A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.
4. bpamiri

   added 2 commits that reference this issue on Jun 4, 2026

   fix(test): escape '#' in BrowserLoginAsHandlerSpec describe label

   ...

   d57e4d8

   Merge branch 'develop' into fix/bot-2830-browser-test-fixture-built-i…

   ...

   b5fc2c5
5. bpamiri

   closed this as completedin #2832on Jun 4, 2026