README.md

Lab

Lab is a concise and direct testing framework that isolates testing contexts, class interaction,
etc. It is simple to use and very direct. It works well with
Parody to provide much of the same testing capacity as more
complex frameworks with a sweeter API and overall simpler approach.

Basic Usage

Adding a Test Set and Tests

To add a set of tests to Lab you can create a file in the tests folder with the name of the test
set you want. Unlike other testing frameworks, this file is a simple PHP file that just returns an
array. Let's add the following template to a file called Example Tests.php:

Making an Assertion

Each test will make one or more assertion. Lab provides an Assertion class which can be used to
make assertions, however, you can use a third party library or basic PHP code if you prefer.
Regardless of how you make assertions, a test will fail in Lab whenever an uncaught exception is
thrown. Let's examine this with a basic assertion using the Lab assert function which will
create a new instance of the build in Assertion class.

This time, when we rerunning Lab, we see the failure immediately as well as some information
regarding the failure:

"Smart" Assertions

The Assertion class is designed to provide features for the 90% of test cases you will need to
run with a concise and flexible syntax. Part of its convenience is how it parses string input and
attempts to determine whether or not the string represents another piece of code, for example, a
class method, a property, or a function. The following two lines of code are, for the most part,
equivalent:

Multiple Assertions

Although each of the above will do the exact same comparison to assert equal values, the second
benefits in two ways. Firstly, by providing a function, method, or property name to assert()
directly, it is possible to run multiple assertions over a single method without repeating the
actual method name:

Testing Private/Protected

In addition to running multiple assertions easily, using a "smart" assertions allows you to access
private and protected methods and properties. Let's use the following absolutely useless class
to illustrate this:

The above code also shows how we can call the using method to specify on which object we want to
access the property or method. This allows us to easily test a number of objects which may have
been instantiated differently to ensure that behavior is consistent across a wider number of cases.

Fixtures

It is important to understand that each test set / file which is added to Lab will run in a
completely separate execution of PHP. Although we recommend organizing test sets per fixture, you
can create separate fixture includes and add them across multiple test sets if need be. In all
cases, anything you need to do to prepare your testing environment or create data to test against
should be added to the setup key in the test set array:

If you have any setup that is required across all test sets / files, then you can add that
logic to the lab.config file in the closure referenced by the same key name. Similarly you
will also find a cleanup key there which can be used for global cleanup code as well as added
to each separate test set for specific cleanup code:

//// The global 'cleanup' key can contain a closure to run fixture cleanup logic at the end// of every test file//'cleanup'=>function($data) {},

Custom Configuration Data

By now you may have realized that every closure either in the lab.config file or in a test set
takes in a $data parameter. You may have also noted the data key in the lab.config which
points to an array. By default this array contains only a root key which points to the directory
where the lab.config file is found.

You can add any arbitrary pieces of information you might need on a per test / setup / or cleanup
basis to this array. Or use the provided root, for example, to load your classes using the needs
function:

'setup'=>function($data) { needs($data['root'] .'/src/Adder.php');}

Dependencies

The needs function, as seen in code above, provides a clean way to require your source files with
the nicely formatted output of Lab:

You may be, however, otherwise tempted to throw an autoloader or something similar in your setup
function(s). While this is 100% possible, you'll need to set the disable_autoloading to FALSE
in the lab.config file. If this is set to TRUE (default), Lab will register an autoloader
almost immediately which will prevent (by throwing an Exception) classes from being loaded in that
manner. This is to reduce the chance that an unknown or unseen dependency will cause your unit
tests to become something more like integration tests.

Conclusion

Lab is an easy-to-use, quick-to-set-up, and generally fun testing framework. Combined with
Parody it represents a powerful tool for PHP testing which encompasses a lot of best practices
with regards to testing, including by not limited to: