Modules

Extend TestBox your way!
TestBox supports the concepts of modules just like how ColdBox has modules. They are self-contained packages that can extend the functionality of TestBox. They can listen to test creations, errors, failures, skippings and much more. To get started you can use the TestBox CLI to generate a module for you:
testbox generate module MyModule

Module Layout

A TestBox module layout is similar to a ColdBox Module layout. They have to be installed at /testbox/system/modules to be discovered and loaded and have one mandatory file: ModuleConfig.cfc which must exist in the root of the module folder.
+ testbox/system/modules
+ myModule
+ ModuleConfig.cfc
You can install TestBox modules from ForgeBox via the install command:
install id=module directory=testbox/system/modules

Differences With ColdBox Modules

  • There is no WireBox
  • There is no Routing
  • There is no Scheduling
  • There is no Interceptors
  • There is no Views
  • Inception works, but limited
  • No module dependencies, all modules are loaded in discovered order

ModuleConfig

This is the main descriptor file for your TestBox module.

Mandatory Callbacks

It must have three mandatory callbacks:
  • configure() - Configures the module for operation
  • onLoad() - When the module is now activated
  • onUnload() - When the module is deactivated
component{
function configure(){
}
function onLoad(){
}
function onUnload(){
}
}

Injected Properties

The following are the injected properties:
Property
Description
ModulePath
The module’s absolute path
ModuleMapping
The module’s invocation path
TestBox
The testbox reference
TestBoxVersion
The version of TestBox being used

Injected Methods

The following are injected methods:
Method
Description
getEnv()
Get an environment variable
getSystemSetting()
Get a Java system setting
getSystemProperty()
Get a Java system property
getJavaSystem()
Get the Java system class

Module Loading Failures

If a module fails to be activated, it will still be in the module registry but marked inactive via the active boolean key in its registry entry. You will also find the cause of the failure in the console logs and the key activationFailure of the module's registry entry.
writedump( testbox.getModuleRegistry() )
Not all ColdBox/CommandBox modules can be TestBox modules. Remember that TestBox modules are extremely lightweight and testing focused.

Testing Callbacks

This ModuleConfig can also listen to the following test life-cycle events. It will also receive several arguments to the call. Here are the common descriptions of the arguments
  • target - The bundle in question
  • testResults - The TestBox results object
  • suite - The suite descriptor
  • suiteStats - The stats for the running suite
  • exception - A ColdFusion exception
  • spec - The spec descriptor
  • specStats - The stats of the running spec
Callback
Arguments
onBundleStart()
  • target
  • testResults
onBundleEnd()
  • target
  • testResults
onSuiteStart()
  • target
  • testResults
  • suite
onSuiteEnd()
  • target
  • testResults
  • suite
onSuiteError()
  • exception
  • target
  • testResults
  • suite
onSuiteSkipped()
  • target
  • testResults
  • suite
onSpecStart()
  • target
  • testResults
  • suite
  • spec
onSpecEnd()
  • target
  • testResults
  • suite
  • spec
onSpecFailure()
  • exception
  • spec
  • specStats
  • suite
  • suiteStats
  • testResults
onSpecSkipped()
  • spec
  • specStats
  • suite
  • testResults
onSpecError()
  • exception
  • spec
  • specStats
  • suite
  • suiteSpecs
  • testResults

Manual Registration

You can also manually register and activate modules by using the registerAndActivate( invocationPath ) method of the TestBox object. All you have to do is pass the invocation path to your modules' root folder:
testbox.registerAndActivate( "tests.resources.modules.MyModule" )
That's it! It will register it and activate and be ready to listen.