Test Before

Test Before (TB) is an ExtendScript testing suite that helps developers catch/prevent bugs within their scripts.

How Does It Work?

Test Before allows you to define different assertions that can be organized within test groups and "modules" and generates a report on your assertions. The general structure of a Test Before script is:

Module > Tests > Assertsions

The following are definitions of the different aspects of Test Before and what they do.

Modules

Modules allow you to group multiple test groups together. This is beneficial if you want test summaries to be calculated within groups instead of all together.

Modules are defined as follows:

TB.module("Module Name");

If using the default TB formatter (more on this below), this will output the following to the ExtendScript console:

Module Name
===========

All tests that are created after this module definition will be added to this module's list of tests. If no module is defined within your TB test script, a "Main" module is created for you.

Tests

Tests, or test groups, are containers for assertions. Like modules, test summaries are calculated for each test so you can easily separate each test's results.

Tests are defined as follows:

TB.test('Test Name', function () {
    //Assertions go here.
});

If using the default TB formatter, this will output the following to the ExtendScript console:

Test Name
---------
    **Assertion results would go here**
---------
Test Name Results: PASSED #, FAILED #

All assertions that are created within this test are evaluated and their results are consolidated and presented to you as a summary once the test is complete.

Assertions

Assertions are the meat of any testing suite. Assertions, or "statements of fact", are defined within test groups and, as you would guess, are either true or false. Each assertion declares a condition and a message for the assertion.

Assertions come in many different flavors (listed below) and look like this:

TB.notEqual(true, false, "True should not be equal to false!");

If using the default TB formatter, the message is displayed next to the result of the condition in the ExtendScript console:

> PASSED - True should not be equal to false!

Running The Tests

Once you have entered all of your modules, tests and assertions, all that is left is to run the tests with TB.runTests():

TB.runTests();

Full Example

In order to give you a full example of how to use TB, let's create a script that defines some basic funcationality and then test it!

//dummyScript.jsx

var dummy = {
    returnOne: function () {
        return 1;
    },
    returnTrue: function () {
        return true;
    },
    returnBlahString: function () {
        return "blah";
    }
};

The following is an example of what a basic TB script would look like:

#include <path to testbefore.jsxbin>
#include dummyScript.jsx

TB.module("Dummy Tests");

TB.test('Basic Tests', function () {
    TB.equal(dummy.returnOne(), 1, "1 should be returned!");
    TB.equal(dummy.returnTrue(), true, "true should be returned!");
    TB.equal(dummy.returnBlahString(), "monkey", "blah should be returned!");
});

TB.runTests();

When using the default formatter, the following will be output to the console:

Dummy Tests (1 test)
=================

Basic Tests (3 assertions)
-----------------

 > PASSED - 1 should be returned!
 > PASSED - true should be returned!
 > FAILED - blah should be returned!
     EXPECTED: monkey
     ACTUAL:   blah

-----------------
Basic Tests results: PASSED: 2, FAILED: 1

=================
Dummy Tests results: PASSED: 2, FAILED: 1

##### SUMMARY #####
Total Modules: 1
Total Tests: 1
Total Assertions: 3
Total Passed: 2
Total Failed: 1

Assertion Types

The following are the current assertions that TB defines:

###TB.ok(actual, message)###

Asserts the actual value is true.

Example:

TB.ok( "asdfasdf".length > 5, "There must be at least 5 chars" );

###TB.equal(actual, expected, message)###

Checks that the first two arguments are equal. Prefered to TB.ok(actual == expected, message).

NOTE: This method uses a relaxed comparison (==). For a more strict comparison, see TB.strictEqual.

Example:

TB.equal("2", 2, "\"2\" is equal to 2");

###TB.notEqual(actual, expected, message)###

Checks that the first two arguments are not equal.

NOTE: This method uses a relaxed comparison (==). For a more strict comparison, see TB.strictNotEqual.

Example:

TB.notEqual("3", 2, "\"3\" is not equal to 2");

###TB.strictEqual(actual, expected, message)###

Strictly checks that the first two arguments are equal. Prefered to TB.ok(actual === expected, message)

NOTE: This method uses a strict comparison (===), for a more relaxed comparison, use TB.equal.

Example:

TB.strictEqual(parseInt("04"), 4, "\"04\" parses to 4");

###TB.strictNotEqual(actual, expected, message)###

Strictly checks that the first two arguments are not equal. Prefered to TB.ok(actual !== expected, message)

NOTE: This method uses a strict comparison (===), for a more relaxed comparison, use TB.notEqual.

Example:

TB.strictNotEqual("4", 4, "\"4\" is not strictly equal to 4");

###TB.deepEqual(actual, expected, message)###

A deep recursive comparison assertion that works on primitive types, arrays and objects. Similar to equal, it compares the content of the given objects. It's also more strict than equal: Comparisons are done using ===.

Example:

//Given:
var x = {one: "1"},
    y = {one: "1"};

TB.deepEqual(x, y, "The x object is deeply equal to the y object");

###TB.notDeepEqual(actual, expected, message)###

A deep recursive comparison assertion that works on primitive types, arrays and objects. Similar to notEqual, it compares the content of the given objects. It's also more strict than notEqual: Comparisons are done using ===.

Example:

//Given:
var x = {one: "1"},
    y = {one: "1", two: "2"};

TB.notDeepEqual(x, y, "The x object is not deeply equal to the y object");

###TB.hasProperty(obj, prop, message)###

Asserts that a given object has a method or field with the given property name.

Example:

//Given:
var x = {
    one: "1",
    two: "2"
};

TB.hasProperty(x, "one", "The x object has a property named \"one\"");

###TB.defined(val, message)###

Asserts that a given value is defined.

Example:

//Given:
var x,
    y = 10;

TB.defined(y, "y is defined"); //Passes
TB.defined(x, "x is defined"); //Fails

Custom Output Formatting

Test Before will soon allow you to define your own formatting object that takes the results from your Modules, Tests and Assertions and outputs them however you want. Currently, the default formatter outputs to the ExtendScript console. However, one could create a formatter that output to a file in any format! This functionality will be released soon.