TestBox 2.5.0 is a minor release with some great new functionality and tons of fixes. You can find the release notes here and the major updates for this release. One of the biggest features for TestBox that was not part of TestBox, was the addition of TestBox Watchers to CommandBox.

TestBox Watchers

CommandBox CLI has added watching capabilities to the testbox namespace. Which means you can now run the following command in the root of your project: testbox watch and it will monitor all your CFCs for changes. If a change is detected, then it will fire the new testbox run command with our CLI reporter.

Life-Cycle Data Binding

We had introduced spec data binding in TestBox for creating dynamic specs and passing dynamic data into them. We have extended this feature into life-cycle methods:

• beforeEach()

• afterEach()

• aroundEach()

You can now pass in an argument called data which is a struct of dynamic data to pass into the life-cycle method. You can then pickup this data in the closure for the life-cycle. Here is a typical example:

describe( "Ability to bind data to life-cycle methods", function(){

    var data = [
        "spec1",
        "spec2"
    ];

    for( var thisData in data ){
        describe( "Trying #thisData#", function(){

            beforeEach( data={ myData = thisData }, body=function( currentSpec, data ){
                targetData = arguments.data.myData;
            });

            it( title="should account for life-cycle data binding", 
                data={ myData = thisData},
                body=function( data ){
                    expect(    targetData ).toBe( data.mydata );
                }
            );

            afterEach( data={ myData = thisData }, body=function( currentSpec, data ){
                targetData = arguments.data.myData;
            });
        });
    }

    for( var thisData in data ){

        describe( "Trying around life-cycles with #thisData#", function(){

            aroundEach( data={ myData = thisData }, body = function( spec, suite, data ){
                targetData = arguments.data.myData;
                arguments.spec.body( data=arguments.spec.data );
            });

            it( title="should account for life-cycle data binding", 
                data={ myData = thisData },
                body=function( data ){
                    expect(    targetData ).toBe( data.mydata );
                }
            );

        });

    }
});

Release Notes

Bugs

• [TESTBOX-177] - Simple reporter broken on Adobe servers

• [TESTBOX-180] - HTML Runner links should include directory param

• [TESTBOX-181] - AsyncAll Errroring on xUnit runner

• [TESTBOX-183] - the 'type' argument was being ignored if the 'regex' argument was provided and matched the exception data

Improvements

• [TESTBOX-178] - Remove thread scope from debug stream

• [TESTBOX-184] - Passing Data to Dynamic Tests via life-cycle methods: around, after, before

• [TESTBOX-185] - Preserve whitespace in HTML (simple) Reporter

• [TESTBOX-186] - Include TestBox version in TestResult memento

• [TESTBOX-187] - Let travis handle upload of api docs and snapshot binaries

• [TESTBOX-188] - Aggregate suite stats from nested suties

TestBox 2.2.0 is a minor release with some great new functionality and tons of fixes.

Release Notes

Bugs

• [TESTBOX-48] - Syntax error in docs for Assertion Registration

• [TESTBOX-49] - Docs for Assertion CFCs inadequate, or functionality just doesn't work?

• [TESTBOX-120] - MXUnit injectMethod not working if calls to methods being replaced are not "this" scoped

• [TESTBOX-122] - Order of args for init function did not match the interface

• [TESTBOX-134] - Mockbox: object instances as args do not always pass comparison

New Features

• [TESTBOX-129] - throwErrorCode addition to mock method generator

• [TESTBOX-132] - Ability to bind data to a spec

• [TESTBOX-133] - Support story-given-when-then style of representing tests

• [TESTBOX-136] - MockBox no longer standalone package

• [TESTBOX-138] - run method listeners so you can do callbacks on testing progress

Improvements

• [TESTBOX-121] - Ability to read assets from current directory to support lucee

• [TESTBOX-124] - Support Lucee's localMode="modern"

• [TESTBOX-126] - it() callback should not need to be a closure

• [TESTBOX-130] - Mocking method CallBack argument receives all arguments now.

• [TESTBOX-135] - Change toIncludeWithCase arguments to match toInclude

TestBox 2.8.0 is a minor release with some great new functionality and tons of fixes. You can find the release notes here and the major updates for this release.

Release Notes

Bugs

• [TESTBOX-224] - Bug on SimpleReporter name not complete

• [TESTBOX-231] - Recurse parameter not honored #71 on html runner

• [TESTBOX-232] - Junit reporter blows up on null values in server scope

• [TESTBOX-233] - Update Expectation.cfc to make toMatchWithCase consistent as it is not working

New Features

• [TESTBOX-225] - Add ability to exclude labels from running using `url.excludes`

Improvements

• [TESTBOX-230] - Incompatibilities with Adobe on many isValid and isInstanceOf

TestBox 2.7.0 is a minor release with some great new functionality and tons of fixes. You can find the release notes here and the major updates for this release.

Release Notes

Bugs

• [TESTBOX-217] - new version of Lucee has complex values in UDF implementation that breaks the mock generator

• [TESTBOX-222] - Heap issues and stack overflow issues when normalizing ORM entities in mocking arguments

New Features

• [TESTBOX-221] - Complete refactoring of around,before,after each executions to support concurrency

Improvements

• [TESTBOX-219] - some refactoring to use invoke() instead of evaluate()

• [TESTBOX-220] - some speed improvements by not using createuuid anymore

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.

Important TestBox is a standalone testing package and is meant to be used with any ColdFusion (CFML) application, framework or library. IT IS NOT ONLY FOR COLDBOX APPLICATIONS.

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

If you are going to be using the xUnit style of testing which includes MXUnit compatibility, then you don't need the latest CFML engines. BDD uses closures to declare your specs, so it it is only available on newer versions of your CFML engine.

• ColdFusion 10+

• Lucee 4.5+

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.

TestBox & MockBox Manual v2.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

• 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

Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

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

TestBox has the following supported IDE Tools:

• Sublime -

• VSCode -

• CFBuilder -

The source code for this book is hosted in GitHub: . You can freely contribute to it and submit pull requests. The contents of this book is copyright by 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 -

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

TestBox & MockBox Manual v2.x

TestBox is a next generation testing framework for ColdFusion (CFML) that is based on (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

• Testing life-cycle methods

• 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

  • 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

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

• Copyright by Ortus Solutions, Corp

• TestBox is a registered trademark by Ortus Solutions, Corp

Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

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

TestBox 2.4.0 is a minor release with some great new functionality and tons of fixes. This release has been a great community effort as many people in the community contributed to its release. Special thanks to Eric Peterson, Joe Gooch and Sean Corfield for their additions, testing and contributions.

New toSatisfy matcher

This new matcher is thanks to Sean Corfield. It allows you to create your own closure that will evaluate the expectation and then decide if it passes the given truth test.

New expectAll() collection expectation

Sean was busy in this release and provided us with this awesome feature in which you can call on a new expectAll() and pass either an array or struct. TestBox will then iterate for you and call all the chained matchers upon the collection items.

New mintext Reporter

This new reporter is to enhance console based runners in order for the report to be more legible.

New JSON Matchers & Assertions

You can now use a toBeJSON() matcher or a $assert.isJSON assertion.

No more runRemote

You no longer need to pass ?method=runRemote in the URL when executing a test bundle via the URL. This will automatically be added for you.

New Fluent API for Testing Declarations

Thanks to Joe Gooch you can now use the new methods in the TestBox cfc

• addDirectory()

• addDirectories()

• addBundles()

You can chain them as you see fit and they will aggregate the specs collected.

Release Notes

Here is the full release notes for this release

Bugs

New Features

Improvements

TestBox 2.6.0 is a minor release with some great new functionality and tons of fixes. You can find the release notes here and the major updates for this release.

Chained DSL Improvements

The methods aroundEach(), beforeEach() and afterEach() can now be chained as they return the Base Spec as well. So get funky with the DSL.

Null Support

You can now pass null into an expectation and TestBox will gracefully represent it instead of blowing up!

Method Mocking Performance

Thanks to method mocking performance has sky rocketed. He changed the filename generation to an MD5 hash of the code, and disabled removing the files. This allows TestBox to leverage ColdFusion template caching. This reduces the time that $() takes from ~30 ms to ~0 ms. It is a happy day for mocking!

Eager Failures

We have added a new argument to all TestBox run(), runRemote(), runRaw() commands: eagerFailure, which defaults to false. If this is turned on, then TestBox will gracefully short-circuit out of testing further Test Bundles if it finds any failures or errors on previous ones. This is useful for large suites that you want to stop testing if a failure is discovered.

Help for the Color Blind

This was another community driven contribution by to help those folks with . You can see the differences in color in the github pull request:

Before

After

Expanding of x exclusion Methods

You can now prefix the following methods with the letter x to exclude them from execution:

• story()

• given()

• when()

• then()

• feature()

Release Notes

Bugs

New Features

Improvements

TestBox can be downloaded from or can be installed via . CommandBox is our preferred approach for all package installations, updates and more.

Note Please note the --saveDev flag which tells CommandBox that TestBox is a development dependency and not a production dependency.

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.

You can also clone from and help us out :)

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.

component extends="testbox.system.BaseSpec"{

     // executes before all suites
     function beforeAll(){}

     // executes after all suites
     function afterAll(){}

     // All suites go in here
     function run( testResults, testBox ){

     }

}

This bundle CFC can contain 2 life-cycle functions and a single run() function where you will be writing your test suites and specs. 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 teardown in your tests.

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.

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

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.

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

We have prepared an awesome PDF ref card for working with TestBox BDD:

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

BDD RefCard

xUnit RefCard

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. There are more arguments which you can see below:

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 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 . Luis resides in The Woodlands, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

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

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.

TestBox 2.1.0 is a minor release with some great new functionality and tons of fixes.

Release Notes

Bugs Fixed

• [] - isEqual on Query fails when queries are equal

• [] - equalize fails on struct/objects/arrays when null values exist within them

• [] - Floating Point Number isEqual Fails

• [] - Specs with the same name cause thread name exceptions when using async

• [] - Download file has "samples" instead of "tests" directory

• [] - tobe() cannot handle sparse arrays on Adobe CF

• [] - xUnit compatibility CF9 broken due to isClosure() being utilized

• [] - skip closures get more metadata arguments when being executed.

• [] - testbox errors when using complete null support in railo

Improvement

• [] - Have debug() include information about where it came from

• [] - remove extra whitespace in text reporter

• [] - Remove CF7,8 incompatibilities

• [] - ColdFusion 11 cfinclude compatibilities

New Feature

Global Enhancements

• Better whitespace management on text enabled reporting

• ColdFusion 11 compatibilities

• ColdFusion 9 support on xUnit and Assertions

• HTML Runners now have a high request timeout for long-lasting tests

Debugging Enhancements

TestBox's debug() method has been enhanced to provide greater messages and telemetry. You can even control the depth of the dumps of each of the debugged data as it is sent. Here is the new signature:

The output will now include information as to what spec produced the output, timestamps, data, and thread data.

Expectation Chaining

You can now chain your matchers on a specific expectation to produce an even nicer DSL when trying to assert data on a single expectation:

AroundEach() Life-Cycle Method

We have added a new life-cycle method to the suites called aroundEach() which will completely wrap your spec in another closure. This is an elegant way for you to provide a complete around AOP advice to a specificiation. 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 specificiations within a single suite. The method signature is below:

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:

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

Simple Reporter Bundle Filter

The simple reporter has been enhanced to add a bundle test filter that can help reduce noise when looking for a specific bundle result:

run() Enhancements

The traditional BDD run() has been enhanced so it now receives the TestBox TestResults object as a reference and TestBox as a reference. This way you can have more metadata and access to what will be reported to users in a reporter. You can also use it to decorate it 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.

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

Specifications (Specs) 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.

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:

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.

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

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.

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 )

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 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 language; using it we can gather and document the requirements as:

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

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.

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.

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:

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.

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

});

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: https://www.npmjs.com/package/testbox-runner

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

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

Included Evaluators

TestBox has a plethora (That's Right! I said Plethora) of evaluators that are included in the release. The best way to see all the latest evaluator methods is to visit our API and digest the coldbox.system.Assertion class. There is also the ability to register and write custom assertion evaluators in TestBox via our addAssertions() function.

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

/*********************************** LIFE CYCLE Methods ***********************************/

     function beforeTests(){
          application.salvador = 1;
     }

     function afterTests(){
          structClear( application );
     }

     function setup(){
          request.foo = 1;
     }

     function teardown(){
          structClear( request );
     }

/*********************************** Test Methods ***********************************/

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

     function testIncludesWithCase(){
          $assert.includesWithCase( "hello", "he" );
          $assert.includesWithCase( [ "Monday", "Tuesday" ] , "Monday" );
     }

     function testnotIncludesWithCase(){
          $assert.notincludesWithCase( "hello", "aa" );
          $assert.notincludesWithCase( [ "Monday", "Tuesday" ] , "monday" );
     }

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

     function testIsEmpty(){
          $assert.isEmpty( [] );
          $assert.isEmpty( {} );
          $assert.isEmpty( "" );
          $assert.isEmpty( queryNew("") );
     }

     function testIsNotEmpty(){
          $assert.isNotEmpty( [1,2] );
          $assert.isNotEmpty( {name="luis"} );
          $assert.isNotEmpty( "HelloLuis" );
          $assert.isNotEmpty( querySim( "id, name
               1 | luis") );
     }

     function testSkipped() skip{
          $assert.fail( "This Test should fail" );
     }

     boolean function isRailo(){
          return structKeyExists( server, "railo" );
     }

     function testSkippedWithConstraint() skip="isRailo"{
          $assert.fail( "This Test should fail" );
     }

     function testFails(){
          //$assert.fail( "This Test should fail" );
     }

     function testFailsShortcut() labels="railo"{
          //fail( "This Test should fail" );
     }

     function testAssert() {
          $assert.assert( application.salvador == 1 );
     }

     function testAssertShortcut() {
          assert( application.salvador == 1 );
     }

     function testisTrue() {
          $assert.isTrue( 1 );
     }

     function testisFalse() {
          $assert.isFalse( 0 );
     }

     function testisEqual() {
          $assert.isEqual( 0, 0 );
          $assert.isEqual( "hello", "HEllO" );
          $assert.isEqual( [], [] );
          $assert.isEqual( [1,2,3, {name="hello", test="this"} ], [1,2,3, {test="this", name="hello"} ] );
     }

     function testisNotEqual() {
          $assert.isNotEqual( this, new coldbox.system.MockBox() );
          $assert.isNotEqual( "hello", "test" );
          $assert.isNotEqual( 1, 2 );
          $assert.isNotEqual( [], [1,3] );
     }

     function testisEqualWithCase() {
          $assert.isEqualWithCase( "hello", "hello" );
     }

     function testnullValue() {
          $assert.null( javaCast("null", "") );
     }

     function testNotNullValue() {
          $assert.notNull( 44 );
     }

     function testTypeOf() {
          $assert.typeOf( "array", [ 1,2 ] );
          $assert.typeOf( "boolean", false );
          $assert.typeOf( "component", this );
          $assert.typeOf( "date", now() );
          $assert.typeOf( "time", timeformat( now() ) );
          $assert.typeOf( "float", 1.1 );
          $assert.typeOf( "numeric", 1 );
          $assert.typeOf( "query", querySim( "id, name
               1 | luis") );
          $assert.typeOf( "string", "hello string" );
          $assert.typeOf( "struct", { name="luis", awesome=true } );
          $assert.typeOf( "uuid", createUUID() );
          $assert.typeOf( "url", "http://www.coldbox.org" );
     }

     function testNotTypeOf() {
          $assert.notTypeOf( "array", 1 );
          $assert.notTypeOf( "boolean", "hello" );
          $assert.notTypeOf( "component", {} );
          $assert.notTypeOf( "date", "monday" );
          $assert.notTypeOf( "time", "1");
          $assert.notTypeOf( "float", "Hello" );
          $assert.notTypeOf( "numeric", "eeww2" );
          $assert.notTypeOf( "query", [] );
          $assert.notTypeOf( "string", this );
          $assert.notTypeOf( "struct", [] );
          $assert.notTypeOf( "uuid", "123" );
          $assert.notTypeOf( "url", "coldbox" );
     }

     function testInstanceOf() {
          $assert.instanceOf( new coldbox.system.MockBox(), "coldbox.system.MockBox" );
     }

     function testNotInstanceOf() {
          $assert.notInstanceOf( this, "coldbox.system.MockBox" );
     }

     function testMatch(){
          $assert.match( "This testing is my test", "(TEST)$" );
     }

     function testMatchWithCase(){
          $assert.match( "This testing is my test", "(test)$" );
     }

     function testNotMatch(){
          $assert.notMatch( "This testing is my test", "(hello)$" );
     }

     function testKey(){
          $assert.key( {name="luis", awesome=true}, "awesome" );
     }

     function testNotKey(){
          $assert.notKey( {name="luis", awesome=true}, "test" );
     }

     function testDeepKey(){
          $assert.deepKey( {name="luis", awesome=true, parent = { age=70 } }, "age" );
     }

     function testNotDeepKey(){
          $assert.notDeepKey( {name="luis", awesome=true, parent = { age=70 } }, "luis" );
     }

     function testLengthOf(){
          $assert.lengthOf( "heelo", 5 );
          $assert.lengthOf( [1,2], 2 );
          $assert.lengthOf( {name="luis"}, 1 );
          $assert.lengthOf( querySim( "id, name
               1 | luis"), 1 );

     }

     function testNotLengthOf(){
          $assert.notLengthOf( "heelo", 3 );
          $assert.notLengthOf( [1,2], 5 );
          $assert.notLengthOf( {name="luis"}, 5 );
          $assert.notLengthOf( querySim( "id, name
               1 | luis"), 0 );

     }

     // railo 4.1+ or CF10+
      function testThrows(){
          $assert.throws(function(){
               var hello = invalidFunction();
          });
     }

      // railo 4.1+ or CF10+
     function testNotThrows(){
          $assert.notThrows(function(){
               var hello = 1;
          });
     }

/*********************************** NON-RUNNABLE Methods ***********************************/

     function nonStandardNamesWillNotRun() {
          fail( "Non-test methods should not run" );
     }

     private function privateMethodsDontRun() {
          fail( "Private method don't run" );
     }

}