Tests and suites can be tagged with TestBox labels. Labels allows you to further categorize different tests or suites so that when a runner executes with labels attached, only those tests and suites will be executed, the rest will be skipped. Labels can be applied globally to the component declaration of the test bundle suite or granularly at the test method declaration.

TestBox BDD v3.x

TestBox is a next generation testing framework for ColdFusion (CFML) that is based on BDD (Behavior Driven Development) for providing a clean obvious syntax for writing tests. It contains not only a testing framework, runner, assertions and expectations library but also ships with MockBox, A mocking and stubbing companion. It also supports xUnit style of testing and MXUnit compatibilities.

Features At A Glance

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

• BDD style testing

• xUnit style testing

• Code Coverage via FusionReactor

• Testing life-cycle methods

• MockBox integration for mocking and stubbing

• Ability to extend and create custom test runners

• Ability to extend and create custom test reporters

• Extensible reporters, bundled with tons of them:

  • JSON

  • XML

  • JUnit 4 XML

  • Text (80's style)

  • Console

  • TAP (Test Anything Protocol)

  • Simple HTML

  • Min - Minimalistic Heaven

  • Raw

  • CommandBox

• Asynchronous testing

• Multi-suite capabilities

• Test skipping

• Suite skipping

• Dynamic skipping support via runtime executions

• Test one or more suites exclusively

• Test one or more tests/specs exclusively

• Test labels and tagging

• Testing debug output stream

• Clickable suite titles to filter test execution

• Much more!

Versioning

TestBox is maintained under the Semantic Versioning guidelines as much as possible.Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

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

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

• Bug fixes and misc changes bumps the patch

License

TestBox and MockBox are open source and licensed under the Apache 2 License. If you use them please try to make mention of it in your code or web site.

• Copyright by Ortus Solutions, Corp

• TestBox is a registered trademark by Ortus Solutions, Corp

Discussion & Help

• Help Group : https://groups.google.com/a/ortussolutions.com/forum/#!forum/testbox

• BoxTeam Slack : https://boxteam.herokuapp.com

• CFML Slack: Look for the box-products channel: http://cfml.slack.com

Reporting a Bug

We all make mistakes from time to time :) So why not let us know about it and help us out. We also love pull requests, so please star us and fork us: https://github.com/Ortus-Solutions/TestBox

• By Jira: https://ortussolutions.atlassian.net/browse/TESTBOX

Professional Open Source

TestBox is a professional open source software backed by Ortus Solutions, Corp offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

Resources

• Official Site: https://www.ortussolutions.com/products/testbox

• Current API Docs: https://apidocs.ortussolutions.com/testbox/current

• Help Group: https://groups.google.com/a/ortussolutions.com/forum/#!forum/testbox

• Source Code: https://github.com/Ortus-Solutions/TestBox

• Bug Tracker : https://ortussolutions.atlassian.net/browse/TESTBOX

• Twitter: @ortussolutions

• Facebook: https://www.facebook.com/ortussolutions

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its 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

Bugs

• [] - Code coverage doesn't always capture ending parenthesis

• [] - When the key existed notToHaveKey wasn't failing

• [] - missing raw_trace in simple.cfm

• [] - Lowercase cbstreams for case-sensitive file systems

Improvements

• [] - Moved invoke block from bottom of method into if block for "detect negation" instead of stack overflow errors

• [] - Add formatting config and scripts

Major Features

Focused Suites and Specs

This was asked for a long time ago and finally we can oblige. You can now prefix any of the suite and spec methods with the letter f and they will be focused. Meaning, ONLY those suites or specs will be executed.

• fit(), fthen() - Spec Methods

• fdescribe(), fscenario(), fstory(), ffeature(), fgiven(), fwhen() - Suite Methods

This is great if you ONLY want certain things to execute instead of the x prefix which was used to EXCLUDE specs and suites.

function run( testResults, testBox ){
	// all your suites go here.
	describe( "My First Suite", function(){

		it( "A Spec that should not run", function(){
			fail( 'implement' );
		});

		it( "A Spec that should not run", function(){
			fail( 'implement' );
		});

		fit( "This should execute", function(){
			expect( 1 ).toBeTrue();
		});

		it( "A Spec that should not run", function(){
			fail( 'implement' );
		});

		fit( "This should execute as well", function(){
			expect( 1 ).toBeTrue();
		});

		fdescribe( "All specs here should run", function(){

			it( "should run", function(){

			});
			it( "should run", function(){

			});
			it( "should run", function(){

			});
		} );

		describe( "All specs here should NOT run", function(){

			it( "A Spec that should not run", function(){
				fail( 'implement' );
			});

			it( "A Spec that should not run", function(){
				fail( 'implement' );
			});

			it( "A Spec that should not run", function(){
				fail( 'implement' );
			});

		} );

	});

	fdescribe( "My Focused Suite", function(){

		it( "This should execute", function(){
			expect( 1 ).toBeTrue();
		});

		describe( "All specs here should run", function(){

			it( "should run", function(){

			});
			it( "should run", function(){

			});
			it( "should run", function(){

			});
		} );

		xdescribe( "skipped suites", function(){

			it( "A Spec that should not run", function(){
				fail( 'implement' );
			});

			it( "A Spec that should not run", function(){
				fail( 'implement' );
			});

			it( "A Spec that should not run", function(){
				fail( 'implement' );
			});

		} );

	});

Here are the results:

toHaveKey() can now work with key lists

How many times did you want to check if a struct had ALL the keys or NO keys at all. Well, now you can. You can pass a list of keys into the toHaveKey() expectation and we will make sure your structure has ALL the keys in it.

var s = {
	"data" : {},
	"error" : {},
	"name" : {},
	"age" : 0
};

expect( s ).toHaveKey( "error" );
expect( s ).notToHaveKey( "luis" );

// Multiple
expect( s ).toHaveKey( "data,error,name,age" );
expect( function(){
	expect( s ).toHaveKey( "data,error,name,age2" );
}).toThrow();
expect( s ).notToHaveKey( "luis,joe,tom" );
expect( function(){
	expect( s ).toHaveKey( "luis,joe,data" );
}).toThrow();

fail() Improvements

You can now pass in a detail to the fail messages that can be used to track exception details, stacktraces, extended info and much more. Sometimes, this can be a life-saver when dealing with toThrow() expectations:

/**
 * Fail an assertion
 *
 * @message The message to fail with.
 * @detail The detail to fail with.
 */
function fail( message = "", detail = "" ){
	variables.assert.fail( argumentCollection = arguments );
}

Which is exactly what we did. The catching of expected exceptions now pass in the exact stacktrace where they failed instead of the nested exception. Which goes nicely into our next major improvement.

Nested Exceptions

We all hate them and not easy to track. In this release we at least try to add more debugging on the results by introducing the following new keys and output on the reporters:

• failDetail

• failExtendedInfo

• failStacktrace

CFML Engine/Version Detection

The reporters know will output the CFML engine the report is executed on. Also, the raw json/xml reporters will also report back the CFML engine and version.

Release Notes

Bugs

• [TESTBOX-251] - Scripts don't output if runner.cfm has enableCFoutputOnly set to true

• [TESTBOX-252] - JSON,xml,Junit, Ant reporters fails for integration tests with cfhtmlhead and cfheader

• [TESTBOX-257] - Update build process to upload the right version assets

New Features

• [TESTBOX-255] - Added new spec stats to track nested exceptions: failDetail, failExtendedInfo, failStacktrace

• [TESTBOX-256] - Add a detail argument to the fail() method to allow for more in-depth tracking of failures, especially when using the `toThrow()` expectation

• [TESTBOX-258] - Added CFMLEngine and CFMLEngineVersion to results memento so any consumer can display this information

• [TESTBOX-253] - Display the CFML engine in use when using the simple reporter

• [TESTBOX-198] - Add support to fit, fdescribe, fscenario,fwhen, fgiven, fstory, ffeature, fthen

Improvements

• [TESTBOX-254] - check if fail origin is an array in case internal TestBox borks out in all the reporters

• [TESTBOX-259] - Turn off code coverage when clicking a link in the HTML reporter

• [TESTBOX-260] - toHaveKey() now accepts a list of keys that MUST or MUST NOT exist in the collection

TestBox can be downloaded from https://www.ortussolutions.com/products/testbox or can be installed via CommandBox CLI. CommandBox is our preferred approach for all package installations, updates and more.

// latest stable version
box install testbox --saveDev

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

This will install TestBox in a /testbox folder from where you called the command. You can also extract the download zip and place it anywhere you like and create a mapping called _/testbox_that points to testbox in the distribution folder, this is the most secure approach. However, you can just place it in the webroot if you like.

this.mappings[ "/testbox" ] = expandPath( "C:/frameworks/testbox/" );

You can also clone from Github and help us out :)

git clone git://github.com/ortus-solutions/testbox testbox

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

box testbox generate harness

System Requirements

• Lucee 5.x+

• ColdFusion 11+

What's Included

The download structure includes:

• apidocs : The API docs for TestBox

• system : The main system framework folder

• test-browser : This is a little utility to facilitate navigating big testing suites. This helps navigate to the suites you want and execute them instead of typing all the time.

• test-harness : A simplified version of the TestBox runner that can be placed anywhere in your application. It includes an ANT build that allows you to execute your tests and produce results via ANT and also JUnit compliant reports via the junitreport task.

• test-runner : The pre-built TestBox Global Runner. You can pass in a directory mapping or bundles and select labels and boom run the tests.

• test-visualizer: A static visualizer of json reports. Just drop in a test-results.json and run it!

• tests : Several sample tests and runners which actually are used to build TestBox

The only required folder is system and it does not need to be web-accessible. The other folders are all optional tools to help you that expect to be web-accessible. You can safely remove everything except the system folder if you want to build your own test browsers. If you are placing TestBox outside of your web root, the /testbox mapping needs to point to the parent folder containing the system directory as all TestBox models start with testbox.system in their package path.

TestBox has the following supported IDE Tools:

• Sublime - https://packagecontrol.io/packages/ColdBox Platform

• VSCode - https://marketplace.visualstudio.com/items?itemName=ortus-solutions.vscode-testbox

• CFBuilder - https://www.forgebox.io/view/ColdBox-Platform-Utilities

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 3.0

In this release we focused on dropping engine supports for legacy CFML engines. We had a major breakthrough in introducing Code Coverage thanks to the FusionReactor folks as well. This major release came also with a new UI for all reporters and streamlining the result view ports.

Version 2.0

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.0

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

TestBox is a xUnit style and behavior-driven development (BDD) testing framework for CFML (ColdFusion). It does not depend on any other framework for operation and it has a clean and descriptive syntax that will make you giggle when writing your tests. It ships with not only the xUnit and BDD testing capabilities, but also an assertions and expectations library, several different runners, reporters and MockBox, for mocking and stubbing capabilities.

In this section we will go over the major features of our behavior driven development syntax. Let's begin.

The source code for this book is hosted in GitHub: https://github.com/Ortus-Solutions/testbox-docs. You can freely contribute to it and submit pull requests. The contents of this book is copyright by Ortus Solutions, Corp and cannot be altered or reproduced without author's consent. All content is provided "As-Is" and can be freely distributed.

• The majority of code examples in this book are done in cfscript.

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - http://www.ortussolutions.com/products/commandbox

• All ColdFusion examples designed to run on the open soure Railo Platform or Adobe ColdFusion 9.0.2+

External Trademarks & Copyrights

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

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 with respect to 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

We highly encourage contribution to this book and our open source software. The source code for this book can be found in our GitHub repository where you can submit pull requests.

Charitable Proceeds

15% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - http://www.harvesting.org/. So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.

Shalom Children's Home

Shalom Children’s Home (http://www.harvesting.org/) is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children werecame on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.

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 that either have no families or have been abandoned. This is good earth to seed and plant.

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer with over 16 years of software development and systems architecture experience. He was born in San Salvador, El Salvador in the late 70’s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at Florida International University. Luis resides in The Woodlands, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion projects. He is also the Adobe ColdFusion user group manager for the Inland Empire. You can read his blog at www.luismajano.com

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 is an Industrial and Systems Engineer born in El Salvador. After finishing his Bachelor studies at the Monterrey Institute of Technology and Higher Education ITESM, Mexico, he went back to his home country where he worked as the COO of Industrias Bendek S.A.. In 2012 he left El Salvador and moved to Switzerland in persuit of the love of his life. He married her and today he resides in Basel with his lovely wife Marta and their daughter Sofía.

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

TestBox 3.0.0 is a major release. It has compatibility changes that you should be aware and lots of good feaures!

Compatibility

The major compatibility issues are the engine support removals:

• Lucee 4.5 Support Dropped

• Adobe ColdFusion 10 Dropped

Updating

It is easy to update, just type update testbox and you are done!

Major Features

The most notable features of this release can be found below.

Code Coverage

This has been fully documented and you can find much more information in the code coverage section.

Static Test Visualizer

The static test visualizer is basically the simple reporter but works in offline mode. This means that it will read a static TestBox results json file and create the report for it in the browser. This is incredibly useful for CI integrations and representing any TestBox results json file visually.

Location

You will find the analyzer under /test-visualizer in the root of the TestBox installation.

/test-analyzer
  + index.html (visualizer)
  + test-results.json (sample test results)

Running It

To run it all you need to do is put alongside of it a test-results.json file and then run the index.html and voila! Test Results Visualized!

Release Notes

Bugs

• [TESTBOX-234] - bddrunner.cfm: now compiles properly on ACF

• [TESTBOX-248] - Skip methods for given/when/then fail without `this` reference

New Features

• [TESTBOX-236] - Add CodeCoverage Reporter to TestBox

• [TESTBOX-239] - Update the UI for the code coverage reporting and code visualizer

• [TESTBOX-243] - Complete UI updates for test reporters

• [TESTBOX-245] - Static Test Visualizer

Improvements

• [TESTBOX-237] - Update usage of htmleditformat to encodeForHTML

• [TESTBOX-242] - Removal of old cfml engines support acf10 and lucee 4.5

• [TESTBOX-244] - streamify the code coverage collection

• [TESTBOX-249] - Add original method name to mocking function so it can help in debugging

TestBox is a next generation testing framework for ColdFusion (CFML) that is based on BDD (Behavior Driven Development) for providing a clean obvious syntax for writing tests. It contains not only a testing framework, runner, assertions, mocking/stubbing and expectations library. It also supports xUnit style of testing with MXUnit compatibilities.

Useful Resources

• Approaches to Mocking

• Wikipedia Mock Objects

• Using mock objects for complex unit tests IBM developerWorks

• Unit testing with mock objects IBM developerWorks

• Emergent Design by Scott Bain

• Mocks Aren't Stubs by Martin Fowler

Ref Cards

Our RefCards will get you up and running in no time.

BDD RefCard

xUnit RefCard

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.

This bundle CFC can contain 2 life-cycle functions and a single run() function where you will be writing 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 kind of 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 can be picked up later by reports. 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.

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.

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

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.

Arguments

There are more arguments which you can see below:

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.

A spec will contain most likely one or more expectations that will test the state of the (software under test) or sometimes referred to as code under test. In BDD style, your specifications are what is used to validate your requirements of a scenario which is your describe() block of your .

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!

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:

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.

Included Matchers

Custom Matchers

Specs and suites can be focused so ONLY those suites and specs execute. You will do this by prefixing certain functions with the letter f or by using the focused argument in each of them. The reporters will show that these suites or specs where execute ONLY The functions you can prefix are:

• it()

• describe()

• story()

• given()

• when()

• then()

• feature()

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

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

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

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

     fit("can have more than one expectation, but I am skipped", function() {
          coldbox = 0;
          coldbox++;

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

Specs and suites can be tagged with TestBox labels. Labels allows you to further categorize different specs or suites so that when a runner executes with labels attached, only those specs and suites will be executed, the rest will be skipped.

describe(title="A spec", labels="stg,railo", body=function() {
     it("executes if its in staging or in railo", function() {
          coldbox = 0;
          coldbox++;

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

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

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

     it(title="can have more than one expectation and labels", labels="dev,stg,qa,shopping", body=function() {
          coldbox = 0;
          coldbox++;

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

As we have seen before, the describe() function describes a test suite of related specs in a test bundle CFC. The title of the suite is concatenated with the title of a spec to create a full spec's name which is very descriptive. If you name them well, they will read out as full sentences as defined by BDD style.

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 );
     });

});

Given-When-Then is a style of writing tests where you describe the state of the code you want to test (Given), the behavior you want to test (When) and the expected outcome (Then). (See Specification By Example)

Testbox supports the use of function names given() and when() in-place of describe() function calls. The then() function call is an alternative for it() function calls. The advantage of this style of behavioural specifications is that you can gather your requirements and write your tests in a common language that can be understood by developers and stake-holders alike. This common language format is often referred to as the Gherkin language; using it we can gather and document the requirements as:

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.

If you prefer to gather requirements as User Stories then you may prefer to take advantage of the story() wrapper for describe() instead.

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.

Before and After Specs

If you are familiar with xUnit style frameworks, the majority of them provide a way to execute functions before and after every single test case or spec in BDD. This is a great way to keep your tests DRY (Do not repeat yourself)! TestBox provides the beforeEach() and afterEach() methods that each take in a closure as their argument that receive the name of the spec that's about to be executed or just executed. As their names indicate, they execute before a spec and after a spec in a related describe block.

describe("A spec (with setup and tear-down)", 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();
     });
});

Around Specs

The aroundEach() life-cycle method will completely wrap your spec in another closure. This is an elegant way for you to provide a complete around AOP advice to a specification. You can use it to surround the execution in transaction blocks, ORM rollbacks, logging, and so much more. This life-cycle method will decorate ALL specs within a single suite and any children suites. The method signature is below:

aroundEach( function( spec, suite ){
     // execute the spec
     arguments.spec.body();
} );

The method receives a structure of data representing the spec. This contains the following elements:

• body : The actual closure for the spec that you will use to execute within it.

• labels : The labels used in the spec

• name : The name of the spec

• order : The order of execution of the spec

• skip : The skip flag or closure that determines if the spec runs

The method also receives a structure of metadata about the suite this spec is contained in. It has information about life-cycle closures, async information, names, parents, etc. Here is a very practical example of creating and around each closure to provide rollbacks for specs:

aroundEach( function( spec, suite ){

     transaction action="begin"{
          try{/
               // execute the spec
               arguments.spec.body();
          } catch( Any e ){
               rethrow;
          } finally{
               transaction action="rollback";
          }
     }
} );

This simple around each life-cycle closure will rollback ALL my spec's executions even if they throw exceptions.

Annotations

TestBox since v2.3.0 also allows you to declare life-cycle methods via annotations. Please see our Annotations section for more information.

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:

describe( 'my describe', function(){
	
    beforeEach( function( currentSpec ){
        // I run first
    } );
    	 
    aroundEach( function( spec, suite ){
        // I run second
        arguments.spec.body();
        // I run fourth
    });
    
    afterEach( function( currentSpec ){
        // I run fifth
    } );
    
    it( 'my it', function(){
        // I run third
    } );
    
} );

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.

TestBox is a xUnit style and behavior-driven development (BDD) testing framework for CFML (ColdFusion). It does not depend on any other framework for operation and it has a clean and descriptive syntax that will make you giggle when writing your tests. It ships with not only the xUnit and BDD testing capabilities, but also an assertions and expectations library, several different runners, reporters and MockBox, for mocking and stubbing capabilities.

Info Note: This article is a primer to get you started with the xUnit capabilities of TestBox, if you would like to explore the BDD style capabilities of TestBox we recommend you visit the BDD primer chapter.

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. The reporters will show that these suites or specs where skipped from execution. The functions you can prefix are:

• it()

• describe()

• story()

• given()

• when()

• then()

• feature()

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.

Please refer to our section to take advantage of all the mocking and stubbing you can do. However, every BDD TestBundle has the following functions available to you for mocking and stubbing purposes:

• 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 comes also with a nice plethora of reporters:

• ANTJunit : A specific variant of JUnit XML that works with the ANT junitreport task

• Codexwiki : Produces MediaWiki syntax for usage in Codex Wiki

• Console : Sends report to console

• Doc : Builds semantic HTML to produce nice documentation

• Dot : Builds an awesome dot report

• JSON : Builds a report into JSON

• JUnit : Builds a JUnit compliant report

• Raw : Returns the raw structure representation of the testing results

• Simple : A basic HTML reporter

• Text : Back to the 80's with an awesome text report

• XML : Builds yet another XML testing report

• Tap : A test anything protocol reporter

• Min : A minimalistic view of your test reports

• MinText : A minimalistic view of your test reports in consoles

• NodeJS : User-contributed:

As you can see from our arguments for a test suite, you can pass an asyncAll argument to the describe() blocks that will allow TestBox to execute all specs in separate threads for you concurrently.

Caution Once you delve into the asynchronous world you will have to make sure your tests are also thread safe (var-scoped) and provide any necessary locking.

TestBox ships with several test runners internally but we have tried to simplify and abstract it with our testbox object which can be found in the testbox.system package. The TestBox object allows you to execute tests from a variety of entry points and languages such as CFC, CFM, HTTP, NodeJS, SOAP or REST. You can also make your CFC's extend from our BaseSpec class so you can execute it directly via the URL. The main execution methods are:

Info We encourage you to read the API docs included in the distribution for the complete parameters for each method.

run() Arguments

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

runRemote() arguments

Here are the arguments you can use for executing the runRemote() 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.

Global Runner

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:

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 as well.

ANT Runner

In our test samples and templates we include an ANT runner 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. You can find this runner in the test samples and runner template directory.

Bundle(s) Runner

Test Runner

Directory Runner

SOAP Runner

You can run tests via SOAP by leveraging the runRemote() method. The WSDL URL will be

HTTP/REST Runner You can run tests via HTTP/REST by leveraging the runRemote() endpoint. The URL will be

NodeJS Runner

There is a user-contributed NodeJS Runner that looks fantastic and can be downloaded here:

Just use node to install:

The xUnit functionalities of TestBox will require Railo 4.1+, Lucee 4.5+ or ColdFusion 9.01+.

TestBox not only provides you with global life-cycle methods but also with localized test methods. This is a great way to keep your tests DRY (Do not repeat yourself)! TestBox provides the setup( currentMethod ) and teardown( currentMethod ) methods that each receives the name of the test method in question. which as their names indicate, they execute before a test and after a test in a test bundle.

component displayName="TestBox xUnit suite" labels="railo,cf"{

     function setup( currentMethod ){
          application.wirebox = new coldbox.system.ioc.Injector();
          structClear( request );
     }

     function teardown( currentMethod ){
          structDelete( application, "wirebox" );
          structClear( request );
     }

     function testThrows(){
          $assert.throws(function(){
               var hello = application.wirebox.getInstance( "myINvalidService" ).run();
          });
     }

     function testNotThrows(){
          $assert.notThrows(function(){
               var hello = application.wirebox.getInstance( "MyValidService" ).run();;
          });
     }

}

TestBox relies on the fact of creating testing bundles which are basically CFCs. A bundle CFC will hold all the tests the TestBox runner will execute and produce reports on. Thus, sometimes this test bundle is referred to as a test suite in xUnit terms.

component displayName="My test suite" extends="testbox.system.BaseSpec"{

     // executes before all tests
     function beforeTests(){}

     // executes after all tests
     function afterTests(){}

}

This bundle can contain 2 life-cycle methods, the beforeTests() and afterTests() methods will execute once before ALL your tests run and then after ALL your tests run. This is a great way to do any kind of global setup or teardown in your tests. It also contains a displayName argument in the component declaration which gives you a way to name your testing suite. We will see later the other annotations you can add to the component declaration further in the primer.

Assertions are self-concatenated strings that evaluate an actual value to an expected value or condition. These are initiated by the global TestBox variable called $assert which contains tons of included assertion methods so you can evaluate your tests.

Evaluators

Each assertion evaluator will compare 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 evaluator also has a negative counterpart assertion by just prefixing the call to the method with a not expression.

      function testIncludes(){
          $assert.includes( "hello", "HE" );
          $assert.includes( [ "Monday", "Tuesday" ] , "monday" );
     }

     function testNotIncludes(){
          $assert.notIncludes( "hello", "what" );
          $assert.notIncludes( [ "Monday", "Tuesday" ] , "Friday" );
     }