test runner: app test endpoint and runner.cfm break under subfolder installs

[bpamiri]

Surfaced while triaging discussion #2887 (mikegrogan). The runtime set(subpath=...) fix landed in 4.0.5 and works, but three testing-layer gaps remain for apps served from a subfolder / CommandBox multi-app topology. These are distinct from #3025 (a refactor-scoped fix for the web runner mutating live application.wheels, not the items below).

1. ?format=html on the app test endpoint silently returns JSON

vendor/wheels/tests/app-runner.cfm:117-131 — the html branch (which is also the no-format default) emits application/json, not an HTML report. The inline comment says this is deliberate ("for the app-runner we just emit the JSON in this branch too"). Only the core runner (vendor/wheels/tests/runner.cfm) falls through to html.cfm.

A user opening /wheels/app/tests?format=html in a browser reasonably expects the TestBox-style HTML report and instead gets raw JSON, with no documentation of the limitation.

• Either render a real HTML report for app tests, or document that /wheels/app/tests supports format=json|txt|junit only and html returns JSON by design.

2. runner.cfm hardcodes /wheels/tests/app-runner.cfm — breaks subfolder topologies

The shipped template cli/lucli/templates/app/tests/runner.cfm does <cfinclude template="/wheels/tests/app-runner.cfm">, which depends on the /wheels mapping resolving correctly. In a CommandBox multi-subfolder setup the mapping doesn't resolve the way it does for a single rooted app, so the include fails.

• Resolve the app-runner include relative to the app's subpath (reuse the set(subpath=...) / WHEELS_SUBPATH derivation) instead of an absolute /wheels/... path.

3. Testing guide over-states what wheels new scaffolds

web/sites/guides/src/content/docs/v4-0-0/testing/index.mdx:29,32,94 documents tests/specs/view/, tests/specs/browser/, and tests/TestRunner.cfc. The template (cli/lucli/templates/app/tests/) ships only specs/{controllers,functional,models}/ and no TestRunner.cfc. New users following the guide look for folders/files that don't exist.

• Reconcile the testing guide with the actual template contents (the template is the source of truth — either add the folders to the template or correct the docs).

---

Note: the reporter's CLI errors stem from running the outdated CommandBox/ForgeBox wheels-cli package (tracked at #3180/#3181), not a missing framework fix — wheels test --base-path shipped in PR #3028. That is being addressed directly in the discussion thread.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report mixes reproducible defects (items 1 & 2) with a docs reconciliation (item 3). Items 1 and 2 reproduce in isolation — verified against the source: vendor/wheels/tests/app-runner.cfm:117 emits application/json for the html/default branch, and cli/lucli/templates/app/tests/runner.cfm hardcodes <cfinclude template="/wheels/tests/app-runner.cfm">. Per triage rules, a mixed report with a bug reproducible in isolation classifies as bug.

Suspected layer

cli — the test-runner template and subpath derivation are CLI-owned (cli/lucli/templates/app/tests/runner.cfm, plus the WHEELS_SUBPATH / set(subpath=...) resolution that landed in 4.0.5). The framework-side test endpoint (vendor/wheels/tests/app-runner.cfm, runner.cfm) is also in scope. See .ai/wheels/testing/ for test-runner patterns.

Fix sketch

Three independent threads:

1. vendor/wheels/tests/app-runner.cfm:117-131 — the html/no-format branch returns JSON by design. Either render a real HTML report (fall through to html.cfm like the core runner.cfm does) or document that /wheels/app/tests supports format=json|txt|junit only and html returns JSON. This one carries a design choice (render vs document).
2. cli/lucli/templates/app/tests/runner.cfm — replace the absolute /wheels/tests/app-runner.cfm include with a subpath-relative resolution reusing the existing set(subpath=...) / WHEELS_SUBPATH derivation so CommandBox multi-subfolder topologies resolve.
3. web/sites/guides/src/content/docs/v4-0-0/testing/index.mdx:29,32,94 — the guide documents tests/specs/view/, tests/specs/browser/, and tests/TestRunner.cfc, none of which the template ships (it has only specs/controllers, specs/functional, and specs/models). Reconcile docs to template (template is source of truth).

Confidence: medium

Multi-part issue spanning three files across two layers; item 1 requires a design decision (render an HTML report vs. document the JSON-only limitation), so the fix shape is not fully mechanical.

<!-- wheels-bot:triage:3251 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3255

Spec: vendor/wheels/tests/specs/global/resolveSubpathIncludeSpec.cfc — failing → passing
Implementation: vendor/wheels/Global.cfc ($resolveSubpathInclude()), cli/lucli/templates/app/tests/runner.cfm

Scope: this addresses item 2 (the hardcoded /wheels/tests/app-runner.cfm include that breaks subfolder topologies). Items 1 (?format=html returning JSON — carries a render-vs-document design decision, no isolatable unit-test surface) and 3 (testing-guide reconciliation — docs, handled by bot-update-docs.yml) are deliberately deferred, so the PR uses Refs #3251 rather than Fixes to avoid auto-closing the tracking issue.

Note: the wheels CLI was not installed in the bot's authoring environment, so tools/test-local.sh could not be run locally. The change is verified by the failing-first spec (helper method absent pre-implementation), a manual trace of the pure path-join algorithm, and cross-engine review; the PR's CI gates run the authoritative suite.

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