CommandBox Runner

By installing the CommandBox TestBox CLI you can access our CommandBox runner. The CommandBox runner leverages HTTP(S) to test against any running server. By default it reads your box.json for a testbox.runner entry, or falls back to /tests/runner.cfm.

testbox run
testbox run directory="tests.specs" outputFormats="json,junit,html"
testbox run runner="http://myremoteapp.com/tests/runner.cfm"

Runner Options

If you type testbox run --help you can see all the arguments you can set for running your tests. However, please note that you can also pre-set them in your box.json under the testbox entry:

"testbox":{
    "bundles":"",
    "directory":"tests.specs",
    "excludes":"",
    "labels":"",
    "options":{},
    "recurse":true,
    "reporter":"",
    "runner":[
        {
            "default":""
        }
    ],
    "testBundles":"",
    "testSpecs":"",
    "testSuites":"",
    "verbose":true,
    "watchDelay":500,
    "watchPaths":"**.cfc"
},

Runner URL

You can also set up the default runner URL in your box.json and it will be used for you. Setting the URL is a one-time operation.

package set testbox.runner="http://localhost:8080/tests/runner.cfm"
testbox run

You can also use a relative path and CommandBox will look up the host and port from your server settings.

package set testbox.runner="/tests/runner.cfm"
testbox run

The default runner URL of the testbox run command is /tests/runner.cfm so there's actually no need to even configure it if you're using the default convention location for your runner.

Multiple Runner URLs

You can define multiple URLs for your runners by using a JSON array of objects. Each key will be a nice identifier you can use via the runner=key argument in the command.

"testbox" : {
    "runner" : [
        { "core"   : "http://localhost/tests/runner.cfm" },
        { "api" : "http://localhost/api/tests/runner.cfm" }
    ]
}

Then you can just pass in the name:

testbox run runner="core"

More Commands:

package set testbox.runner="[ { default : 'http://localhost/tests/runner.cfm' } ]" --append
package show testbox.runner
testbox run default

Watcher

The CLI also comes with a code watcher and runner. It will watch any paths for you, and if it detects any changes, it will run the tests you want.

testbox watch help

In order for this command to work, you need to have started your server and configured the URL to the test runner in your box.json.

package set testbox.runner=http://localhost:8080/tests/runner.cfm
server start
testbox watch

You can also control what files to watch.

testbox watch **.bx

If you need more control over what tests run and their output, you can set additional options in your box.json which will be picked up automatically by testbox run when it fires.

package set testbox.verbose=false
package set testbox.labels=foo
package set testbox.testSuites=bar
package set testbox.watchDelay=1000
package set testbox.watchPaths=/models/**.bx

This command will run in the foreground until you stop it. When you are ready to shut down the watcher, press Ctrl+C.

🌊 Streaming (Real-Time Results)

The --streaming flag taps into the new StreamingRunner to deliver each spec result to your terminal in real time via Server-Sent Events (SSE) — no waiting for the full suite to finish.

testbox run --streaming

Pair with --verbose to include all passing specs in the live feed (by default only failures and skipped specs persist after the run):

testbox run --streaming --verbose

Streaming works best with BoxLang, but can be used with CFML engines that support SSE as well. See Streaming Runner for the underlying API.