TESTBOX-453: Fix BoxLang CLI runner misreading its own path as a bundle argument by lmajano · Pull Request #201 · Ortus-Solutions/TestBox

lmajano · 2026-08-29T01:36:09Z

Description

./testbox/run --verbose --stream (the BoxLang CLI runner) fails immediately, before any test spec runs, with:

[ERROR] [EXCEPTION] The requested class [.../testbox/system/runners/BoxLangRunner.bx] has not been located in the [bx] resolver.
ortus.boxlang.runtime.types.exceptions.ClassNotFoundBoxLangException: ...
	at ortus.boxlang.runtime.loader.ClassLocator.load(ClassLocator.java:587)
	at ortus.boxlang.runtime.bifs.global.system.GetClassMetadata._invoke(GetClassMetadata.java:66)
	...
	at boxgenerated.boxclass.testbox.system.Testbox$cfc.invokeFunction_runRaw(.../TestBox.cfc:454)
	...
	at boxgenerated.boxclass...Boxlangrunner$bx.invokeFunction_main(.../BoxLangRunner.bx:219)
	at ortus.boxlang.runtime.BoxRuntime.executeClass(BoxRuntime.java:1466)
	at ortus.boxlang.runtime.BoxRunner._main(BoxRunner.java:255)

This surfaced downstream in ortus-boxlang/bx-sites CI on ubuntu-latest, reported as intermittent (~1/3 of runs) against BoxLang engine build v1.17.0+58.

Root cause: On the affected BoxLang build, server.cli.parsed.positionals always includes the entry-point script's own invocation path as its first entry (an argv[0]-style leak), regardless of whether boxlang was invoked with a relative or absolute path. BoxLangRunner.bx's CLI handling assumed any non-empty positionals meant the user passed a bundle name positionally:

if( positional.len() ) {
    initArgs.bundles = positional[ 1 ]
    initArgs.directory = {}
}

Since positionals is never actually empty on this engine build, an ordinary ./testbox/run --verbose --stream invocation (no bundle argument) has positional[1] equal to the runner's own script path, so TestBox is told to test its own runner file as a "bundle" — which then fails to resolve as a class in TestBox.cfc's bundle-discovery loop.

I reproduced this locally 100% of the time (installed BoxLang v1.17.0+58 via the quick installer and built a scratch project mirroring bx-sites), traced it with instrumentation, and confirmed the fix resolves it under both relative and absolute boxlang invocation, with 8/8 consecutive green runs afterward.

Fix: filter server.cli.parsed.positionals to drop any entry that resolves (relative to server.cli.executionPath, following symlinks) to the currently-executing script, before treating what remains as a genuine user-supplied bundle argument.

Jira Issues

https://ortussolutions.atlassian.net/browse/TESTBOX-453

Type of change

Bug Fix

Checklist

My code follows the style guidelines of this project cfformat
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes

Note: this fix touches the CLI runner's argument parsing, which isn't exercised by TestBox's existing test suite (that runs against CFML engine web servers, not the BoxLang CLI entry point) — verification here was a manual local repro against the actual BoxLang engine build, described above and in the linked Jira issue.

Generated by Claude Code

The `run` launcher resolved its own directory to an absolute path before invoking `boxlang`, so BoxLangRunner.bx was executed via an absolute filesystem path. BoxLang 1.17.0 hardened path resolution to force absolute-looking paths through mappings/webroot instead of the OS filesystem, which intermittently broke the entry point's own self-resolution later in the run (surfacing as a ClassNotFoundBoxLangException during TestBox's bundle discovery) on CI runners invoking `./testbox/run`. Passing boxlang a relative path avoids exercising that code path, and leaves server.cli.executionPath pointing at the caller's working directory as before.

Installed BoxLang v1.17.0+58 (the exact engine build from the CI failure reports) and reproduced the crash locally with a scratch project mirroring bx-sites' setup. Instrumented TestBox.cfc and BoxLangRunner.bx to trace the failure and found the real cause: `server.cli.parsed.positionals` on this engine build always includes the entry-point script's own invocation path as its first entry (effectively an argv[0] leak), regardless of whether boxlang was invoked with a relative or absolute path. BoxLangRunner.bx's `if( positional.len() ) { initArgs.bundles = positional[1] }` therefore always treats a plain `./testbox/run --verbose --stream` invocation (no bundle argument) as if the user had passed the runner's own path as a bundle to test, which then fails GetClassMetadata() resolution downstream in TestBox.cfc's bundle-discovery loop with the reported ClassNotFoundBoxLangException. This supersedes the previous commit on this branch, which changed `run` to pass a relative path under the theory that BoxLang 1.17.0's include-path hardening was responsible. That was disproven by testing: the crash reproduces identically with a relative invocation, and the real fix below resolves it under both relative and absolute invocation. `run` is reverted to its original form. Fix: filter `server.cli.parsed.positionals` to drop any entry that resolves (relative to the invocation directory, following symlinks) to this same script, before treating what remains as a user-supplied bundle argument. Verified locally: 8/8 consecutive green runs via `./testbox/run --stream`, and explicit `run my.bundle`-style invocations still work correctly.

github-actions · 2026-08-29T01:37:42Z