A modern editor can enhance your testing experience. We recommend VSCode due to the extensive modules library. Here are the plugins we maintain for each platform.

VSCode Plugin

The VSCode plugin is the best way for you to interact with TestBox alongside the BoxLang plugin. It allows you to run tests, generate tests, navigate tests and much more.

Sublime Plugin

TestBox is fully compliant with MXUnit xUnit test cases. In order to leverage it you will need to create or override the /mxunit mapping and make it point to the /testbox/system/compat folder. That's it, everything should continue to work as expected.

Note you will still need TestBox to be in the web root, or have a /testbox mapping created even when using the MXUnit compat runner.

this.mappings[ "/mxunit" ] = expandPath( "/testbox/system/compat" );

After this, all your test code remains the same but it will execute through TestBox's xUnit runners. You can even execute them via the normal URL you are used to. If there is something that is not compatible, please let us know and we will fix it.

Expected Exceptions

We also support in the compatibility mode the expected exception MXUnit annotation: mxunit:expectedException and the expectException() methods. The expectException() method is not part of the assertion library, but instead is inherited from our BaseSpec.cfc.

Please refer to MXUnit's documentation on the annotation and method for expected exceptions, but it is supported with one caveat. The expectException() method can produce unwanted results if you are running your test specs in TestBox asynchronous mode since it stores state at the component level. Only synchronous mode is supported if you are using the expectException() method. The annotation can be used in both modes.

Framework

TestBox can be installed via CommandBox CLI as a development dependency in the root of your projects:

// Create a new project
mkdir myProject --cd

// latest stable version
box install testbox --saveDev

// latest bleeding edge
box install testbox@be --saveDev

The only requirement is that it be in either in the webroot or in a location where you create a /testbox mapping to it's folder.

System Requirements

• BoxLang 1+ Language (Our preference)

• CFML Engines: Lucee 5.x+ or ColdFusion 2018+

What's Included

Here is a table of what's included in the installation package which goes in /{project}/testbox

In the bx folder you will find specific BoxLang tools:

CFML Tools

In the cfml folder you will find specific BoxLang tools:

IDE Tooling

Now that you are installed, please set up your favorite IDE with our tooling extensions so it can make your testing experience more enjoyable.

TestBox CLI

TestBox comes with its own CLI for CommandBox. You can use it to generate tests, harnesses, and suites and also run executions from the CLI.

install testbox-cli

You will now have the testbox namesapce available to you, try it out

testbox help

Generating a Testing Harness

Once you install TestBox, you'll need a quick way to set up a testing harness in your project. The generate harness command will add a new /tests folder to your application with a few example tests to get you started.

testbox generate harness

/tests - The test harness generated

• /resources - Where you can place any kind of testing helpers, data, etc

• /specs - Where your test bundles can go

  • /unit

  • /integration

• Application.bx|cfc - Your test harness applilcation file. Controls life-cycle and application concerns.

• runner.bx|cfm - A web runner template that executes ALL your tests with tons of different options from a running web server.

• test.xml - An ANT task to do JUNIT testing.

You can then run your tests by executing the testbox run command in CommandBox or by visiting the web runner in the generated harness: http://localhost/tests/runner.cfm

testbox run --help

Generating Tests

You can also use the CLI to generate tests according to your style and also it detects if you are using BoxLang or a CFML engine.

testbox create bdd --help
testbox create unit --help

Language Generation

If you want to be explicit you can use the language id to set it to your preferred language for generation and usage. We recommend this so all CLI tooling can detect what language your project is in.

# For BoxLang Generation
package set language="boxlang"

# For CFML
package set language="cfml"