TestBox BDD v5.x

class{

  function run(){
  	describe( "My calculator features", () => {
	
		beforeEach( () => {
			variables.calc = new Calculator()
		} )
			
		// Using expectations library
		it( "can add", () => {
			expect( calc.add(1,1) ).toBe( 2 )
		} )
		
		// Using assert library
		test( "it can multiply", () => {
			assertIsEqual( calc.multiply(2,2), 4 )
		} )
	} )
  }

}

/**
 * My calculator features
 */
class{

	property calc;
	
	function setup(){
	    calc = new Calculator()
	}
	
	// Function name includes the word 'test'
	// Using expectations library
	function testAdd(){
	    expect( calc.add(1,1) ).toBe( 2 )
	}
		
	// Any name, but with a test annotation
	// Using assertions library
	@test
	function itCanMultiply(){
	    $assert.isEqual( calc.multiply(2,2), 4 )
	}
}

component{

  function run(){
  	describe( "My calculator features", () => {
	
		beforeEach( () => {
			variables.calc = new Calculator()
		} );
			
		// Using expectations library
		it( "can add", () => {
			expect( calc.add(1,1) ).toBe( 2 )
		} );
		
		// Using assert library
		test( "it can multiply", () => {
			$assert.isEqual( calc.multiply(2,2), 4 )
		} );
	} );
  }

}

/**
 * My calculator features
 */
component{
	
	property calc;
	
	function setup(){
	    calc = new Calculator()
	}
	
	// Function name includes the word 'test'
	// Using expectations library
	function testAdd(){
	    expect( calc.add(1,1) ).toBe( 2 )
	}
		
	// Any name, but with a test annotation
	// Using assertions library
	function itCanMultiply() test{
	    $assert.isEqual( calc.multiply(2,2), 4 )
	}
}

Features At A Glance

Here is a simple listing of features TestBox brings to the table:

• BDD style or xUnit style testing

• Testing life-cycle methods

• Mocking data library for mocking JSON/complex data and relationships

• Ability to extend and create custom test runners and reporters

• Extensible reporters, bundled with tons of them:

  • JSON

  • XML

  • JUnit XML

  • Text

  • Console

  • Simple HTML

  • Min - Minimalistic Heaven

  • Raw

  • CommandBox

• Asynchronous testing

• Multi-suite capabilities

• Test skipping

• Test labels and tagging

• Testing debug output stream

• Much more!

Versioning

<major>.<minor>.<patch>

And constructed with the following guidelines:

• bumpBreaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bump the minor (and resets the patch)

• Bug fixes and misc changes bump the patch

License

• Copyright by Ortus Solutions, Corp

• TestBox is a registered trademark by Ortus Solutions, Corp

Discussion & Help

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, don't read it, it's not for you.

Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. - Romans 5:5

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc.

BoxLang, ColdBox, CommandBox, FORGEBOX, TestBox, ContentBox, and Ortus Solutions are all trademarks and copyrights of Ortus Solutions, Corp.

Notice of Liability

The information in this book is distributed “as is” without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity concerning loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software, and resources described in it.

Contributing

Charitable Proceeds

Shalom Children's Home

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education, and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador who either has no families or have been abandoned. This is a good earth to seed and plant.

Luis Fernando Majano Lainez

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

• He has a geek love for circuits, microcontrollers and overall embedded systems.

• He has of late (during old age) become a fan of running and bike riding with his family.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” Proverbs 3:5

Contributors

Jorge Emilio Reyes Bendeck

Jorge started working as project manager and business developer at Ortus Solutions, Corp. in 2013, . At Ortus he fell in love with software development and now enjoys taking part on software development projects and software documentation! He is a fellow Cristian who loves to play the guitar, worship and rejoice in the Lord!

Therefore, if anyone is in Christ, the new creation has come: The old has gone, the new is here! 2 Corinthians 5:17

Improvement

In this section, you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions, use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 5.x - May 2023

Version 4.x - April 2020

In this release, we have dropped support for legacy CFML engines and introduced the ability to mock data and relationships and build JSON documents.

Version 3.x

Version 2.x

This version spawned off with over 8 minor releases. We focused on taking TestBox 1 to yet a high level. Much more attention to detail and introducing modern paradigms like given-when-then. Multiple interception points, async executions, and ability to chain methods.

Version 1.x

This was our first major version of TestBox. We had completely migrated from MXUnit, and it introduced BDD to the ColdFusion (CFML) world.

New Feature

Bug

Improvement

Framework

// 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

• 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"

5.3.1 - September 13, 2023

Fixed

5.3.0 - August 1, 2023

New Features

Bugs

TestBox 5.x series is a major bump in our library. Here are the major areas of improvement and the full release notes.

Engine Support

We have dropped Adobe 2016 support and added support for Adobe 2023 and Lucee 6+

Batch Test Coverage Reporting

Due to memory limitations in CI environments, larger codebases cannot run all tests as a single testbox run command. Instead, specs are run in a methodical folder-by-folder sequence, separating the testbox run out over many requests and thus working around the Out-Of-Memory exceptions.

While this works, it prevents accurate code coverage reporting since only a small portion of the tests are executed during any request. The generated code coverage report only shows a tiny fraction of the coverage - say, 2% - and not the whole picture

TestBox 5 introduces a CoverageReporter component which

1. Runs on every TestBox code coverage execution

2. Loads any previous coverage data from a JSON file

3. Combines the previous coverage data with the current execution's coverage data (file by file and line by line)

4. Persists the COMBINED coverage data to a JSON file.

5. Returns the COMBINED coverage data for the CoverageBrowser.cfc to build as an HTML report

When setting url.isBatched=true and executing the batched test runner, the code coverage report will grow with each sequential testbox run command.

Method Spies!

MockBox now supports a $spy( method ) method that allows you to spy on methods with all the call log goodness but without removing all the methods. Every other method remains intact, and the actual spied method remains active. We decorate it to track its calls and return data via the $callLog() method.

Example of CUT:

void function doSomething(foo){
  // some code here then...
  local.foo = variables.collaborator.callMe(local.foo);
  variables.collaborator.whatever(local.foo);
}

Example Test:

function test_it(){
  local.mocked = createMock( "com.foo. collaborator" )
    .$spy( "callMe" )
    .$spy( "whatever" );
  variables.CUT.$property( "collaborator", "variables", local.mocked );
  assertEquals( 1, local.mocked.$count( "callMe" ) );
  assertEquals( 1, local.mocked.$count( "whatever" ) );
}

Performance Improvements

We have focused on this release to lazy load everything as much as possible to allow for much better testing performance. Check it out!

Skip it! Skip it -> Good!

You can now use the skip( message ) method to skip any spec or suite a-la-carte instead of as an argument to the function definitions. This lets you programmatically skip certain specs and suites and pass a nice message.

it( "can do something", () => {
    ...
    if( condition ){
        skip( "Condition is true, skipping spec" )
    }
    ...
} )

Release Notes

Fixed

Improvements

Added

In our test harness we include an ANT runner (test.xml) that will be able to execute your tests via ANT.

It can also leverage our ANTJunit reporter to use the junitreport task to produce JUnit compliant reports as well.

Now you can run the commands

BoxLang

The BoxLang language allows you to run your scripts via the CLI or the browser if you have a web server attached to your project.

// Run all the specs in the tests.specs directory and subdirectories
r = new testbox.system.TestBox( directory="tests.specs" )
println( r.run() )

// Run all the specs in the tests.specs directory ONLY
r = new testbox.system.TestBox(
		directory={
            mapping="tets.specs",
            recurse=false
      } )
println( r.run() )

// Run all the specs in the tests.specs directory and subdirectories using
// a custom lambda filter
r = new testbox.system.TestBox(
      	directory={
            mapping : "tets.specs",
            filter : path -> findNoCase( "test", arguments.path ) ? true : false
      }) >
println( r.run() )

// Run all the specs in the tests.specs directory and subdirectories using
// a custom lambda filter and create a JSON report
r = new testbox.system.TestBox(
      	directory={
            mapping="tets.specs",
            filter : path -> findNoCase( "test", arguments.path ) ? true : false
      }) >
fileWrite( 'testreports.json', r.run() )
println( "JSON report created" )

If you want to run it in the CLI, then just use:

boxlang run.bxs

If you want to run it via the web server, place it in your /tests/ folder and run it

http://localhost/tests/run.bxs

CFML

CFML engines only allow you to run tests via the browser. So create your script, place it in your web accessible /tests folder and run it.

<cfset r = new testbox.system.TestBox( directory="tests.specs" ) >
<cfoutput>#r.run()#</cfoutput>

<cfset r = new testbox.system.TestBox(
      directory={
            mapping="tets.specs",
            recurse=false
      }) >
<cfoutput>#r.run()#</cfoutput>

<cfset r = new testbox.system.TestBox(
      directory={
            mapping="tets.specs",
            recurse=true,
            filter=function(path){
                  return ( findNoCase( "test", arguments.path ) ? true : false );
            }
      }) >
<cfoutput>#r.run()#</cfoutput>

<cfset r = new testbox.system.TestBox(
      directory={
            mapping="tets.specs",
            recurse=true,
            filter=function(path){
                  return ( findNoCase( "test", arguments.path ) ? true : false );
            }
      }) >
<cfset fileWrite( 'testreports.json', r.run() )>

Styles

In TestBox you can write your tests in two different styles or approaches.

BDD (Behavior Driven Development)

BDD stands for behavior-driven development and is highly based on creating specifications and expectations of results in a readable DSL (Domain Specific Language). You are not focusing on a specific unit and method to test, but on functionality, features and more. This can encompass not only unit but also integration testing. You have several methods that you can use in order to denote functionality and specifications:

• describe()

• feature()

• story()

• given(), when(), then()

• it() or test()

describe( "My calculator features", () => {
	
	beforeEach( () => {
		variables.calc = new Calculator()
	} )
		
	// Using expectations library
	it( "can add", () => {
		expect( calc.add(1,1) ).toBe( 2 )
	} )
	
	// Using assert library
	test( "it can multiply", () => {
		$assert.isEqual( calc.multiply(2,2), 4 )
	} )
} )

xUnit (Test Driven Development)

xUnit style of testing is the more traditional TDD or test-driven development approach where you create a test case bundle class that matches the software under test, and for each method in the SUT, you create a test method in the test bundle class.

@DisplayName "My calculator features"
class{

	property calc;
	
	function setup(){
		calc = new Calculator()
	}
	
	// Function name includes the word 'test'
	// Using expectations library
	function testAdd(){
		expect( calc.add(1,1) ).toBe( 2 )
	}
		
	// Any name, but with a test annotation
	// Using assertions library
	@DisplayName "It can multiply two operands"
	@test
	function itCanMultiply(){
		$assert.isEqual( calc.multiply(2,2), 4 )
	}
}

Assertions & Expectations

We also give you two ways to do assertions:

// Assertions
assert( expression, "custom message" )

// Expectations
expect( structKeyExists( handler, "mixinTest" ) ).toBeTrue();
expect( structKeyExists( handler, "repeatThis" ) ).toBeTrue();
expect( structKeyExists( handler, "add" ) ).toBeTrue();
expect( target.$callLog().relocate[ 1 ].url ).toInclude( "dashboard" );

Life-Cycles

beforeEach( function( currentSpec ){
    setup();
    target = prepareMock( getInstance( "coldbox.system.FrameworkSupertype" ) );
} );

afterEach( function( currentSpec ){
    getCache( "template" ).clearAll();
    variables.scheduler.shutdown();
} );


function beforeAll() {
	super.beforeAll();
	
	// Login User
	variables.loggedInData = loginUser();
	
	variables.loggedInUserId = variables.loggedInData.user.getUserId();
	
	variables.testTimeOffEmployeeId = qb
		.select( "FK_userId" )
		.from( "timeOff" )
		.where( "requestType", "vacation" )
		.first()
		.FK_userId;
}

function afterAll() {
	variables.userService.clearCaches()
}

function setup() {
	super.setup();

	if ( !isNull( request.testUserData ) ) {
		getRequestContext().setValue( "x-auth-token", request.testUserData.token.access_token );
	}

	return;
}

function tearDown(){
	request.clear()
}

function beforeTests() {
	
	// Login User
	variables.loggedInData = loginUser();
	
	variables.loggedInUserId = variables.loggedInData.user.getUserId();
	
	variables.testTimeOffEmployeeId = qb
		.select( "FK_userId" )
		.from( "timeOff" )
		.where( "requestType", "vacation" )
		.first()
		.FK_userId;
}

function afterTests() {
	variables.userService.clearCaches()
}

Utilities

TestBox will also offer different utilities:

• Debug output to a debug buffer

• Mock classes, methods and properties

• Extension data mocking and JSON mocking

• Logging facilities

Runners

You can also execute your tests via the CLI, IDE or the web server.

Reports

TestBox can produce many different types of reports for your test executions:

• CLI / Console Output

• VSCode Output

• JSON

• XML

• JUNIT

• TAP

• HTML

• DOC

• Your own

Here is a few samples:

class{

  function run(){
  	describe( "My calculator features", () => {
	
		beforeEach( () => {
			variables.calc = new Calculator()
		} )
			
		// Using expectations library
		it( "can add", () => {
			expect( calc.add(1,1) ).toBe( 2 )
		} )
		
		// Using assert library
		test( "it can multiply", () => {
			$assert.isEqual( calc.multiply(2,2), 4 )
		} )
	} )
  }

}

/**
 * My calculator features
 */
class{

	property calc;
	
	function setup(){
		calc = new Calculator()
	}
	
	// Function name includes the word 'test'
	// Using expectations library
	function testAdd(){
		expect( calc.add(1,1) ).toBe( 2 )
	}
		
	// Any name, but with a test annotation
	// Using assertions library
	@test
	function itCanMultiply(){
		$assert.isEqual( calc.multiply(2,2), 4 )
	}
}

component{

  function run(){
  	describe( "My calculator features", () => {
	
		beforeEach( () => {
			variables.calc = new Calculator()
		} );
			
		// Using expectations library
		it( "can add", () => {
			expect( calc.add(1,1) ).toBe( 2 )
		} );
		
		// Using assert library
		test( "it can multiply", () => {
			$assert.isEqual( calc.multiply(2,2), 4 )
		} );
	} );
  }

}

/**
 * My calculator features
 */
component{
	
	property calc;
	
	function setup(){
		calc = new Calculator()
	}
	
	// Function name includes the word 'test'
	// Using expectations library
	function testAdd(){
		expect( calc.add(1,1) ).toBe( 2 )
	}
		
	// Any name, but with a test annotation
	// Using assertions library
	function itCanMultiply() test{
		$assert.isEqual( calc.multiply(2,2), 4 )
	}
}

Useful Resources

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 ships with a global runner that can be used to run pretty much anything. You can customize it or place it wherever you need it. You can find it in your distribution under:

• BoxLang: /testbox/bx/test-browser

• CFML: /testbox/cfml/test-browser

This is a mini web application to help you run bundles, directory, specs and more.

BDD stands for Behavioral Driven Development. It is a software development process that aims to improve collaboration between developers, testers, and business stakeholders. BDD involves creating automated tests that are based on the expected behavior of the software, rather than just testing individual code components. This approach helps ensure that the software meets the desired functionality and is easier to maintain and update in the future.

In traditional xUnit, you focused on every component's method individually. In BDD, we will focus on a feature or story to complete, which could include testing many different components to satisfy the criteria. TestBox allows us to create these types of texts with human-readable functions matching our features/stories and expectations.

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.

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.

TestBox ships with a new BoxLang CLI runner for Linux/Mac and Windows. This will allow you to execute your tests from the CLI and, in the future, via VSCode easily and extremely fast. It can also execute and stream the executions so you can see the testing progress when running in verbose mode. The runner can also execute specs/tests that are written in CFML or BoxLang in the BoxLang runtime.

BoxLang allows you to not only build web applications, but CLI, serverless, Android, etc. You can use this runner to test each environment. However, please note that if you will be doing web server testing from the CLI only, you will need to install the web support module into the Operating System runtime.

Web Server Testing

If you want to test from the CLI your web application with no web server, then you will need to install the bx-web-support module into the CLI. Remember that BoxLang is multi-runtime, and you not only can build web applications but CLI or OS based applications.

This will add web support to the CLI (BIFS, components, etc.) and a mock HTTP server so you can do full life-cycle testing from the CLI like if running your app in a web server. This runner does not require a web server to function, thus if you are building a web app, you will need this module if you still want to continue to execute your tests in the CLI Runtime.

Script Locations

The scripts are located in the following directory: /testbox/bin from the TestBox installation package.

• run - For Linux/Mac

• run.bat - For Windows

This is the entry point for executing tests at the CLI level. Please note that the test execution does NOT involve a web server. This is for pure CLI testing.

Examples:

The runner must be run from the root of your BoxLang project:

Mac/Linux

Windows Examples:

Execution Options

• --bundles A list of test bundles to run, defaults to *, ex: path.to.bundle1,path.to.bundle2, . Mutually exclusive with --directory

• --bundles-pattern A pattern to match test bundles defaults to "*Spec*.cfc|*Test*.cfc|*Spec*.bx|*Test*.bx"

• --directory A list of directories to look for tests to execute. Please use dot-notation, not absolute notation. Mutually exclusive with --bundles. Ex: tests.specs Defaults to tests.specs

• --recurse : Recurse into subdirectories, defaults to true

• --eager-failure : Fail fast, defaults to false

• --verbose : Verbose output defaults to false. This will stream the output of the status of the tests as they run.

• --runner-options: A JSON struct literal of options to pass into the test runner. Ex: {"verbose"=true}

Reporting Options

• --reporter The reporter to use.

• --reportpath : The path to write the report file, defaults to the /tests/results folder by convention

• --properties-summary : Generate a properties file with the summary of the test results, defaults to true.

• --properties-filename : The name of the properties file to generate defaults to TEST.properties

• --write-report : Write the report to a file in the report path folder, defaults to true

• --write-json-report : Write the report as JSON alongside the requested report, defaults to false

• --write-visualizer : Write the visualizer to a file in the report path folder, defaults to false

Filtering Options

• --labels : A list of labels to run, defaults to *

• --excludes : A list of labels to exclude, defaults to empty

• --filter-bundles : A list of bundles to filter by, defaults to *

• --filter-suites : A list of suites to filter by, defaults to *

• --filter-specs : A list of test names or spec names to filter by, defaults to *

TestBox tests can be run from different sources from what we call Runners. These can be from different sources:

• CLI

  • TestBox CLI (Powered by CommandBox)

  • BoxLang Scripts

  • NodeJS

• Web Server

  • Runner

  • TestBundle Directly

• Custom

Your test harness already includes the web runner: runner.bx or runner.cfm. You can execute that directly in your browser to get the results or run it via the CLI: testbox run. We invite you to explore the different runners available to you.

Custom Runners

However, you can create your own custom runners as long as you instantiate the TestBox class and execute one of it's runnable methods. The main execution methods are:

run()

Here are the arguments you can use for initializing TestBox or executing the run() method

• The bundles argument which can be a single CFC path or an array of CFC paths or a directory argument so it can go and discover the test bundles from that directory.

• The reporter argument can be a core reporter name like: json,xml,junit,raw,simple,dots,tap,min,etc or it can be an instance of a reporter CFC.

• You can execute the runners from any cfm template or any CFC or any URL, that is up to you.

• /tests - The test harness

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

  • /specs - Where your test bundles can go

  • 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 will be creating test classes inside the /tests/specs folders. The class can extend our base class: testbox.system.BaseSpec or not. If you do, then the tests will be faster, executable directly from a web server and you will get IDE introspection. However, TestBox doesn't enforce the inheritance.

My First Test

Typically test bundles are suffixed with the word Test or Spec, such as MyServiceSpec.bx or UserServiceTest.cfc

The CLI can assist you when creating new bundles:

Now you can run your tests via the browser (http://localhost:port/tests/runner.cfm)

or via the CLI testbox run

Optional Inheritance

At runtime we provide the inheritance via mixins so you don't have to worry about it. However, if you want to declare the inheritance you can do so and this will give you the following benefits:

• Some IDEs will be able to give you introspection for methods and properties

• You will be able to use the HTML runner by executing directly the runRemote method on the CFC Bundle

• Your tests will run faster

Injected Variables

At runtime, TestBox will inject several public variables into your testing bundle to help you with your testing.

• $mockbox : A reference to MockBox

• $assert : A reference to our Assertions library

• $utility : A utility CFC

• $customMatchers : A collection of custom matchers registered

• $exceptionAnnotation : The annotation used to discover expected exceptions, defaults to expectedException

• $testID : A unique identifier for the test bundle

• $debugBuffer : The debugging buffer stream

Injected/Inherited Methods

Wether you inherit or not, your bundles will have a plethora of methods that will help you in your testing adeventure. Here is a link to the API Docs for the BaseSpec class:

Quick Assertion Methods

Extension Methods

Environment Methods

These methods assist you with identifying environment conditions.

Java Environment

You can use the getEnv() to get access to our Environment utility object. From there you can use the following methods:

Utility Methods

These methods are here to help you during the testing process. Every bundle also get's a debug buffer attached to its running results. This is where you as the developer can send pretty much any variable (simple or complex) and attach it to the debug buffer. This will then be presented acordingly in the test reporters or facilities.

Mocking Methods

TestBox is bundles with two amazing mocking facilities:

• MockBox - Mocks objects and stubs

BDD Methods

Every test harness comes with a runner.bx or runner.cfm in the root of the tests folder. This is called the web runner and is executable via the web server you are running your application on. This will execute all the tests by convention found in the tests/specs folder.

http://localhost/tests/runner.cfm

You can open that file and customize it as you see fit. Here is an example of such a file:

<!--- Executes all tests in the 'specs' folder with simple reporter by default --->
<bx:param name="url.reporter" 			default="simple">
<bx:param name="url.directory" 			default="tests.specs">
<bx:param name="url.recurse" 			default="true" type="boolean">
<bx:param name="url.bundles" 			default="">
<bx:param name="url.labels" 			 default="">
<bx:param name="url.excludes" 			 default="">
<bx:param name="url.reportpath" 		 default="#expandPath( "/tests/results" )#">
<bx:param name="url.propertiesFilename"  default="TEST.properties">
<bx:param name="url.propertiesSummary"	default="false" type="boolean">
<bx:param name="url.editor" 			  default="vscode">
<bx:param name="url.bundlesPattern" 	 default="*Spec*.cfc|*Test*.cfc|*Spec*.bx|*Test*.bx">

<!--- Code Coverage requires FusionReactor --->
<bx:param name="url.coverageEnabled"			default="false">
<bx:param name="url.coveragePathToCapture"		default="#expandPath( '/root' )#">
<bx:param name="url.coverageWhitelist"			  default="">
<bx:param name="url.coverageBlacklist"			  default="/testbox,/coldbox,/tests,/modules,Application.cfc,/index.cfm,Application.bx,/index.bxm">
<!---<bx:param name="url.coverageBrowserOutputDir"		default="#expandPath( '/tests/results/coverageReport' )#">--->
<!---<bx:param name="url.coverageSonarQubeXMLOutputPath"	default="#expandPath( '/tests/results/SonarQubeCoverage.xml' )#">--->
<!--- Enable batched code coverage reporter, useful for large test bundles which require spreading over multiple testbox run commands. --->
<!--- <bx:param name="url.isBatched"						default="false"> --->

<!--- Include the TestBox HTML Runner --->
<bx:include template="/testbox/system/runners/HTMLRunner.cfm" >

Test Bundle Execution

If you make your test bundle class inherit from our testbox.system.BaseSpec class, you will be able to execute the class directly via the URL:

// BoxLang
http://localhost/tests/specs/MyFirstTest.bx?method=runRemote

// CFML
http://localhost/tests/specs/MyFirstTest.cfc?method=runRemote

Arguments

All the arguments found in the runner are available as well in a direct bundle execution:

• labels: The labels to apply to the execution

• testMethod : A list or array of xunit test names that will be executed ONLY!

• testSuites : A list or array of suite names that are the ones that will be executed ONLY!

• testSpecs : A list or array of test names that are the ones that will be executed ONLY!

• reporter : The type of reporter to run the test with

// BoxLang
http://localhost/tests/specs/MyFirstTest.bx?method=runRemote&reporter=text

// CFML
http://localhost/tests/specs/MyFirstTest.cfc?method=runRemote&reporter=text

To see all the running options run the following in your CLI shell:

testbox run help

testbox run directory="tests.specs" outputFormats="json,junit,html"

testbox run runner="http://myremoteapp.com/tests/runner.cfm"

It can also produce reports for you in JSON, HTML, and JUNIT.

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 **.cfc

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/**.cfc

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

Expectations are self-concatenated strings that evaluate an actual value to an expected value or condition. These are initiated by the global TestBox method called expect() which takes in a value called the actual value or expectAll() which takes in an array or struct which will be the actual value. It is concatenated in our expectations DSL with a matcher function that will most likely take in an expected value or condition to test. You can also concatenate the matchers and do multiple evaluations on a single actual value.

Matchers

Each matcher implements a comparison or evaluation of the actual value and an expected value or condition. It is responsible for either passing or failing this evaluation and reporting it to TestBox. Each matcher also has a negative counterpart assertion by just prefixing the call to the matcher with a not expression.

function run(){

     describe("The 'toBe' matcher evaluates equality", function(){
          it("and has a positive case", function(){
               expect( true ).toBe( true );
          });

          it("and has a negative case", function(){
               expect( false ).notToBe( true );
          });
     });

     describe("Collection expectations", function(){
        it( "can be done easily with TestBox", function(){
            expectAll( {a:2,b:4,c:6} ).toSatisfy( function(x){ return 0 == x%2; });
        });
    });

}

Included Matchers

describe("Some Included TestBox Matchers:", function() {

     describe("The 'toBe' matcher", function() {
          it("works for simple values", function() {
               coldbox = 1;
               expect( coldbox )
                    .toBe( 1 )
                    .notToBe( 5 );
          });

          it("works for complex values too (arrays,structs,queries,objects)", function() {
               expect( [1,2] ).toBe( [1,2] );
               expect( { name="luis", awesome=true} ).toBe( { awesome=true, name="luis" } );
               expect( this ).toBe( this );
               expect( queryNew("") ).toBe( queryNew("") );
          });
     });

     it("The 'toBeWithCase' matches strings with case equality", function() {
          expect( 'hello' )
               .toBeWithCase( 'hello' )
               .notToBeWithCase( 'HELLO' );
     });

     it("The 'toBeTrue' and 'toBeFalse' matchers are used for boolean operations", function() {
          coldbox_rocks = true;
          expect( coldbox_rocks ).toBeTrue();
          expect( !coldbox_rocks ).toBeFalse();
     });

     it("The 'toBeNull' expects null values", function() {
          foo = "bar";
          expect( javaCast("null", "") ).toBeNull();
          expect( foo ).notToBeNull();
     });

     it("The 'toBeInstanceOf' expects the object to be of the same class or inheritance or implementation", function() {
          expect( new coldbox.system.Assertions ).toBeInstanceOf( 'coldbox.system.Assertions' );
          expect( this ).notToBeInstanceOf( 'coldbox.system.MockBox' );
     });

     it("The 'toMatch' matcher is for regular expressions with case sensitivity", function() {
          message = 'foo man choo';

          expect( message )
               .toMatch( '^foo' )
               .toMatch( '(man)' )
               .notToMatch( 'superman' );
     });

     it("The 'toMatchNoCase' matcher is for regular expressions with no case sensitivity", function() {
          message = 'foo man choo';

          expect( message )
               .toMatchNoCase( '^FOO' )
               .toMatchNoCase( '(MAN)' )
               .notToMatchNoCase( 'SuperMan' );
     });

     describe("The 'toBeTypeOf' matcher evaluates using the CF isValid() function", function() {
          it("works with direct calls", function() {
               expect( [1,2] ).toBeTypeOf( 'Array' );
               expect( { name="luis", awesome=true} ).toBeTypeOf( 'struct' );
               expect( this ).toBeTypeOf( 'component' );
               expect( '03/01/1990' ).toBeTypeOf( 'usdate' );
          });

          it("works with dynamic calls as well", function() {
               expect( [1,2] ).toBeArray();
               expect( { name="luis", awesome=true} ).toBeStruct();
               expect( this ).toBeComponent();
               expect( '03/01/1990' ).toBeUsDate();
          });
     });

     it("The 'toBeEmpty' checks emptyness of simple or complex values", function() {
          expect( [] ).toBeEmpty();
          expect( { name="luis", awesome=true} ).notToBeEmpty();
          expect( '' ).toBeEmpty();
     });

     it("The 'toHaveLength' checks size of simple or complex values", function() {
          expect( [] ).toHaveLength( 0 );
          expect( { name="luis", awesome=true} ).toHaveLength( 2 );
          expect( 'Hello' ).toHaveLength( 5 );
     });

     it("The 'toHaveKey' checks for existence of keys in structs", function() {
          expect( { name="luis", awesome=true} ).toHaveKey( 'name' );
     });

     it("The 'toHaveDeepKey' checks for existence of keys anywhere in structs", function() {
          expect( { name="luis", { age=35, awesome=true } } ).toHaveDeepKey( 'age' );
     });

     it("The 'toThrow' checks if the actual call fails", function() {
          expect( function(){
               new calculator().divide( 40, 0 );
          }).toThrow();

          expect( function(){
               new calculator().divide( 40, 0 );
          }).toThrow( regex="zero" );
     });

});

Custom Matchers

TestBox ships with a test browser that is highly configurable to whatever URL accessible path you want. It will then show you a test browser where you can navigate and execute not only individual tests, but also directory suites as well.

• BoxLang: /testbox/bx/test-browser

• CFML: /testbox/cfml/test-browser

It is also a mini web application that can be configured to whatever root folder you desire. It will read the runners and tests from that folder and present a GUI that you can use to navigate the test folders and execute them easily.

TestBox relies on the fact of creating testing bundles which are basically CFCs. A bundle CFC will hold all the suites and specs a TestBox runner will execute and produce reports on. Don't worry, we will cover what's a suite and a spec as well. Usually they will have a name that ends with *Spec or *Test.

This bundle CFC can contain 2 life-cycle functions and a single run() function where you will write your test suites and specs.

Life-Cycle Methods

The beforeAll() and afterAll() methods are called life-cycle methods. They will execute once before the run() function and once after the run() function. This is a great way to do any global setup or tear down in your tests.

Execution

The run() function receives the TestBox testResults object as a reference and testbox as a reference as well. This way you can have metadata and access to what will be reported to users in a reporter. You can also use it to decorate the results or store much more information that reports can pick up later. You also have access to the testbox class so you can see how the test is supposed to execute, what labels was it passed, directories, options, etc.

This is more of an approach than an actual specifc runner. This approach shows you that you can create a script file in BoxLang (bxs) or in CFML (cfs|cfm) that can in turn execute any test bundle(s) with many many runnable configurations.

BoxLang

The BoxLang language allows you to run your scripts via the CLI or the browser if you have a web server attached to your project.

If you want to run it in the CLI, then just use:

If you want to run it via the web server, place it in your /tests/ folder and run it

CFML

CFML engines only allow you to run tests via the browser. So create your script, place it in your web accessible /tests folder and run it.

You can use node to install as well into your projects.

npm install -g testbox-runner

Configuration

Create a config file called .testbox-runnerrc in the root of your web project.

{
	"runner": "http://localhost/testbox/system/runners/HTMLRunner.cfm",
	"directory": "/tests/specs",
	"recurse": true
}

Then use the CLI command to run whatever you configured.

testbox-runner

You can also specify a specific configuration file:

testbox-runner --config /path/to/config/file.json

Command Line Arguments

Simply run the utility and pass the above configuration options prefixed with --.

Example

testbox-runner 
    --runner http://localhost/testbox/system/runners/HTMLRunner.cfm 
    --directory /tests 
    --recurse true

Feature: Box Size
    In order to know what size box I need
    As a distribution manager
    I want to know the volume of the box

    Scenario: Get box volume
        Given I have entered a width of 20
        And a height of 30
        And a depth of 40
        When I run the calculation
        Then the result should be 24000

TestBox provides you with feature(), scenario() and story() wrappers for describe() blocks. As such we can write our requirements in test form like so:

feature( "Box Size", function(){

    describe( "In order to know what size box I need
              As a distribution manager
              I want to know the volume of the box", function(){

        scenario( "Get box volume", function(){
            given( "I have entered a width of 20
                And a height of 30
                And a depth of 40", function(){
                when( "I run the calculation", function(){
                      then( "the result should be 24000", function(){
                          // call the method with the arguments and test the outcome
                          expect( myObject.myFunction(20,30,40) ).toBe( 24000 );
                      });
                 });
            });
        });
    });
});

The output from running the test will read as the original requirements, providing you with not only automated tests but also a living document of the requirements in a business-readable format.

story("As a distribution manager, I want to know the volume of the box I need", function() {
    given("I have a width of 20
        And a height of 30
        And a depth of 40", function() {
        when("I run the calculation", function() {
              then("the result should be 24000", function() {
                  // call the method with the arguments and test the outcome
                  expect(myObject.myFunction(20,30,40)).toBe(24000);
              });
         });
    });
});

As feature(), scenario() and story() are wrappers for describe() you can intermix them so that your can create tests which read as the business requirements. As with describe(), they can be nested to build up blocks.

With TestBox's BDD syntax, it is possible to create suites dynamically; however, there are a few things to be aware of.

Setup for dynamic suites must be done in the pseudo-constructor (versus in beforeAll()). This is because variables-scoped variables set in beforeAll() are not available in the describe closure (even though they are available in it closures). This behavior can be explained by the execution sequence of a BDD bundle: When the bundle's run() method is called, it collects preliminary test data via describes. After preliminary test data are collected, the beforeAll() runs, followed by the describe closures.

Additionally, care must be taken to pass data into the it closures, otherwise strange behavior will result (the values from the last loop iteration will be repeated in the body of each looped it).

Example

The following bundle creates suites dynamically, by looping over test metadata.

component
    extends="testbox.system.BaseSpec"
    hint="This is an example of a TestBox BDD test bundle containing dynamically-defined suites."
{

    /*
    * Need to do config for *dynamic* test suites here, in the
    * pseudo-constructor, versus in `beforeAll()`.
    */
    doDynamicSuiteConfig();

    /*
    * @hint This method is arbitrarily named, but it sets up 
    * metadata needed by the dynamic suites example. The setup
    * could have been done straight in the pseudo-constructor,
    * but it might be nice to organize it into such a method
    * as this.
    */
    function doDynamicSuiteConfig(){
        variables.dynamicSuiteConfig = ["foo","bar","baz"];
    }

    function run( testResults, testBox ){

        /*
        * @hint Dynamic Test Suites Example
        */
        // loop over test metadata
        for ( var thing in dynamicSuiteConfig ) {
            describe("Dynamic Suite #thing#", function(){
                // notice how data is passed into the it() closure:
                //  * data={ keyA=valueA, keyB=ValueB }
                //  * function( data )
                it( title=thing & "test", 
                    data={ thing=thing }, 
                    body=function( data ) {
                      var thing = data.thing;
                      expect( thing ).toBe( thing );
                });
            });
        }

    }

}

Specs and suites can be skipped from execution by prefixing certain functions with the letter x or by using the skip argument in each of them or by using the skip( message, detail ) function. The reporters will show that these suites or specs were skipped from execution. The functions you can prefix are:

• it()

• describe()

• story()

• given()

• when()

• then()

• feature()

Here are some examples:

xdescribe("A spec", function() {
     it("was just skipped, so I will never execute", ()=>{
          coldbox = 0;
          coldbox++;

          expect( coldbox ).toBe( 1 );
     });
});

describe("A spec", function() {
     it("is just a closure, so it can contain any code", ()=>{
          coldbox = 0;
          coldbox++;
          expect( coldbox ).toBe( 1 );
     });

     xit("can have more than one expectation, but I am skipped", ()=> {
          coldbox = 0;
          coldbox++;
          expect( coldbox ).toBe( 1 );
          expect( coldbox ).toBeTrue();
     });
     
     it( "can only run on lucee", ()=>{
          if( !server.keyExists( "lucee" ) ){
               skip( "Only for lucee" );
          }
     } );
});

Skip Argument

The skip argument can be a boolean value or a closure. If the value is true then the suite or spec is skipped. If the return value of the closure is true then the suite or spec is skipped. Using the closure approach allows you to dynamically at runtime figure out if the desired spec or suite is skipped. This is such a great way to prepare tests for different CFML engines.

describe(title="A railo suite", body=function() {
     it("can be expected to run", function() {
          coldbox = 0;
          coldbox++;

          expect( coldbox ).toBe( 1 );
     });

     it(title="can have more than one expectation and another skip closure", body=function() {
          coldbox = 0;
          coldbox++;

          expect( coldbox ).toBe( 1 );
          expect( coldbox ).toBeTrue();

     },skip=function(){
          return false;
     });

},skip=function(){
     return !structKeyExists( server, "railo" );
});

Skip Method

You can now use the skip( message, dteail ) method to skip any spec or suite a-la-carte instead of as an argument to the function definitions. This lets you programmatically skip certain specs and suites and pass a nice message.

it( "can do something", () => {
    ...
    if( condition ){
        skip( "Condition is true, skipping spec" )
    }
    ...
} )

A test suite in TestBox is a collection of specifications that model what you want to test. As we will investigate, the way the suite is expressed can be of many different types.

Test suite is a container that has a set of tests which helps testers in executing and reporting the test execution status.

A test suite begins with a call to our TestBox describe() function with at least two arguments: a title and a body function/closure. The title is the name of the suite to register and the body function/closure is the block of code that implements the suite.

When applying BDD to your tests, this function is used to describe your story scenarios that you will implement.

function run( testResults, testBox ){

     describe("A suite", function(){
          it("contains spec with an awesome expectation", function(){
               expect( true ).toBeTrue();
          });
          it("contains spec with a failure expectation", function(){
               expect( true ).toBeFalse();
          });
     });

}

Arguments

There are more arguments, which you can see below:

• makePublic( target, method, newName ) - Exposes private methods from objects as public methods

• querySim( queryData ) - Simulate a query

• getMockBox( [generationPath] ) - Get a reference to MockBox

• createEmptyMock( [className], [object], [callLogging=true]) - Create an empty mock from a class or object

• createMock( [className], [object], [clearMethods=false], [callLogging=true]) - Create a spy from an instance or class with call logging

• prepareMock( object, [callLogging=true]) - Prepare an instance of an object for method spies with call logging

• createStub( [callLogging=true], [extends], [implements]) - Create stub objects with call logging and optional inheritance trees and implementation methods

• getProperty( target, name, [scope=variables], [defaultValue] ) - Get a property from an object in any scope

TestBox CLI

The easiest way to run your tests is to use the TestBox CLI via the testbox run command. Ensure you are in the web root of your project or have configured the box.json to include the TestBox runner in it as shown below. If not CommandBox will try to run by convention your site + test/runner.cfm for you.

Here is a simple box.json config that has a runner and some watcher config.

"testbox":{
    "runner":"http://localhost:49616/tests/runner.cfm",
    "watchers":[
        "system/**.cfc",
        "tests/**.cfc"
    ],
    "watchDelay":"250"
}

URL Runner

Every test harness also has an HTML runner you can execute. By convention the URL is

http://localhost{port}/tests/runner.cfm

This will execute ALL tests in the tests/specs directory for you.

URL Spec Runner

You can also target a specific spec to execute via the URL

http://localhost{port}/tests/specs/MySpec.cfc

Global Runner

TestBox ships with a global runner that can run pretty much anything. You can customize it or place it wherever you need it:

Test Browser

TestBox ships with a test browser that is highly configurable to whatever URL-accessible path you want. It will then show you a test browser where you can navigate and execute not only individual tests but also directory suites.

describe("A spec", function() {
     it("is just a closure, so it can contain any code", function() {
          coldbox = 0;
          coldbox++;

          expect( coldbox ).toBe( 1 );
     });

     it("can have more than one expectation", function() {
          coldbox = 0;
          coldbox++;

          expect( coldbox ).toBe( 1 );
          expect( coldbox ).toBeTrue();
     });
});

Nesting describe Blocks

Calls to our describe() function can be nested with specs at any level or point of execution. This allows you to create your tests as a related tree of nested functions. Please note that before a spec is executed, TestBox walks down the tree executing each beforeEach() and afterEach() function in the declared order. This is a great way to logically group specs in any level as you see fit.

describe("A spec", function() {

     beforeEach(function( currentSpec ) {
          coldbox = 22;
          application.wirebox = new coldbox.system.ioc.Injector();
     });

     afterEach(function( currentSpec ) {
          coldbox = 0;
          structDelete( application, "wirebox" );
     });

     it("is just a function, so it can contain any code", function() {
          expect( coldbox ).toBe( 22 );
     });

     it("can have more than one expectation and talk to scopes", function() {
          expect( coldbox ).toBe( 22 );
          expect( application.wirebox.getInstance( 'MyService' ) ).toBeComponent();
     });

     describe("nested inside a second describe", function() {

          beforeEach(function( currentSpec ) {
               awesome = 22;
          });

          afterEach(function( currentSpec ) {
               awesome = 22 + 8;
          });

          it("can reference both scopes as needed ", function() {
            expect( coldbox ).toBe( awesome );
          });
     });

     it("can be declared after nested suites and have access to nested variables", function() {
          expect( awesome ).toBe( 30 );
     });

});

A spec is a declaration that will usually test your system with a requirement. They are defined by calling the TestBox it() global function, which takes in a title and a body function/closure. The title is the title of this spec you will write and the body function/closure is a block of code that represents the spec.

function run(){

     describe("A suite", function(){
          it("contains spec with an awesome expectation", function(){
               expect( true ).toBeTrue();
          });

          it("contains a spec with more than 1 expectation", function(){
               expect( [1,2,3] ).toBeArray();
               expect( [1,2,3] ).toHaveLength( 3 );
          });
     });

}

An expectation is a nice assertion DSL that TestBox exposes so you can pretty much read what should happen in the testing scenario. A spec will pass if all expectations pass. A spec with one or more expectations that fail will fail the entire spec.

Arguments

They are closures Ma!

function run(){

     describe("A suite is a closure", function(){
          c = new Calculator();

          it("and so is a spec", function(){
               expect( c ).toBeTypeOf( 'component' );
          });
     });

}

Spec Data Binding

The data argument can be used to pass in a structure of data into the spec so it can be used later within the body closure. This is great when doing looping and creating dynamic closure calls:

// Simple Example
it( title="can handle binding", body=function( data ){
    expect(    data.keep ).toBeTrue();
}, data={ keep = true } );

// Complex Example. Let's iterate over a bunch of files and create dynamic specs
for( var filePath in files ){

  it( 
    title="#getFileFromPath( filePath )# should be valid JSON", 
    // pass in a struct of data to the spec for later evaluation
    data={ filePath = filePath },
    // the spec closure accepts the data for later evaluation
    body=function( data ) {
      var json = fileRead( data.filePath );
      var isItJson = isJSON( json );

      expect( json ).notToBeEmpty();
      expect( isItJson ).toBeTrue();

      if( isItJson ){
          var jsonData = deserializeJSON(json);
          if( getFileFromPath( filePath ) != "index.json"){
              expect( jsonData ).toHaveKey( "name" );
              expect( jsonData ).toHaveKey( "type" );
          }
      }

  });
}

You can pass in an argument called data , which is a struct of dynamic data, to all life-cycle methods. This is useful when creating dynamic suites and specifications. This data will then be passed into the executing body for each life-cycle method for you.

Here is a typical example:

Global Callbacks

Global callbacks affect the execution of the entire test bundle CFC and all of its suites and specs.

beforeAll()

Executes once before all specs for the entire test bundle CFC. A great place to initialize the environment the bundle needs for testing.

afterAll()

Executes once after all specs for the entire test bundle CFC. A great place to teardown the environment the bundle needed for testing.

Copy

run( testResults, testBox )

Executes once so it can capture all your describe and it blocks so they can be executed by a TestBox runner.

Suite CallBacks

The following callbacks influence the execution of specification methods: it(), then(). The great flexibility of the BDD approach is that it allows you to nest describe, feature, story, given, scenario, when suite blocks to create very human readable and organized documentation for your tests. Each suite block can have its own life-cycle methods as well. Not only that, if they are nested, TestBox will walk the tree and call each beforeEach() and afterEach() in the order you declare them.

beforeEach( body, data )

The body closure will receive have the following signature:

afterEach( body, data )

The body closure will receive have the following signature:

Here are some examples:

aroundEach( body, data )

The body closure will receive have the following signature:

The spec is the currently executing specification, the suite is the suite this life-cycle is embedded in and data is the data binding, if any.

Here is an example:

Lifecycle Nesting Order

When you use beforeEach(), afterEach(), and aroundEach() at the same time, there is a specific order they fire in. For a given describe block, they will fire in this order. Remember, aroundEach() is split into two parts-- the half of the method before you call spec.body() and the second half of the method.

1. beforeEach

2. aroundEach (first half)

3. it() (the spec.body() call)

4. aroundEach (second half)

5. afterEach()

Here's an example:

If there are more than one it() blocks, the process repeats for each one. Steps 1, 2, 4, 5 will wrap every single it().

When you nest more than one describe block inside the other, the before/around/after order is the same but drills down to the innermost describe and then bubbles back up. That means the outermost beforeEach() starts and we end on the outermost afterEach().

Here's what an example flow would look like that had before/after/around specified in two levels of describes with a single it() in the inner most describe.

1. Outermost beforeEach() call

2. Innermost beforeEach() call

3. Outermost aroundEach() call (first half)

4. Innermost aroundEach() call (first half)

5. The it() block

6. Innermost aroundEach() calls (second half)

7. Outermost aroundEach() call (second half)

8. Innermost afterEach() call

9. Outermost afterEach() call

This works regardless of the number of levels and can obviously have many permutations, but the basic order is still the same. Before/around/after and starting at the outside working in, and back out again. This process happens for every single spec or it() block. This is as opposed to the beforeAll() and afterAll() method which only run once for the entire CFC regardless of how many specs there are.