README

👁 Build Status

dspec is a BDD style testing tool for PHP 5.3. It's a little flaky. It's meant to be like the awesome mocha, but obviously not that good. There aren't any matchers, I use Hamcrest for the that, if you want mocks and stubs, use Mockery.

For more info, see the Documentation.

Installation

The only documented way to install dspec is with Composer

$ composer.phar require --dev davedevelopment/dspec:*

Usage

Create a Spec file

<?php

// BowlingSpec.php

require_once 'Bowling.php';
require_once 'hamcrest/Hamcrest.php';

describe("Bowling", function() {

 beforeEach(function() { // run before every sibling and descendant it() 
 $this->bowling = new Bowling; // PHP 5.4's closure binding allows the use of this
 }); 

 it("should score zero for gutter game", function() {
 for ($i = 0; $i < 20; $i++) {
 $this->bowling->hit(0);
 }

 assertThat($this->bowling->score, equalTo(0)); // hamcrest assertion
 });

});

Run it

$ vendor/bin/dspec BowlingSpec.php

For more examples, checkout the features or the spec dirs.

Config

There are a few command line switches, dspec --help will show you those. You can also use a configuration file, by specifying one on the command line, or by having a file name dspec.yml or dspec.yml.dist in the current working directory. Checkout the projects dspec.yml.dist for some examples of configuration.

Execution Scope

The closures in the various methods get bound to a Context object, which is cloned throughout the test run, in an attempt to share context where appropriate, but allow each example a clean version of that shared context. This is a last resort though, proper setup and tear down in beforeEach and afterEach hooks should provide adequate isolation.

<?php

describe("Context", function() {

 $this->objA = new stdClass;

 it("has acccess to objA", function() {
 if (!isset($this->objA)) {
 throw new Exception("Could not access objA");
 }

 $this->objB = new stdClass;
 });

 it("does not have access to objB", function() {
 if (isset($this->objB)) {
 throw new Exception("Could access objB");
 }
 });
});

Using $this is totally optional, in PHP 5.3 you can use let and injection to pass vars around:

<?php

describe("test", function() {
 let("objA", function() {
 return new stdClass;
 });

 it("has acccess to objA", function($objA) {
 assertThat($objA, anInstanceOf("stdClass"));
 });
});

Using regular variable binding with your closures is an alternative option, but can be a bit messier;

<?php

describe("Connection", function() {

 $db = new Connection();

 $dave = new User();
 $bex = new User();

 beforeEach(function() use ($db, $dave, $bex) {
 $db->truncate('users'); 
 $db->save($dave);
 $db->save($bex);
 });

 context("#findAll()", function() use ($db) {
 it("responds with all records", function() use ($db) {
 $users = $db->find('users');
 assertThat(count($users), equalTo(2));
 });
 });

});

Global functions

If global functions aren't your thing, you can use class methods of the DSpec class:

<?php

use DSpec\DSpec as ds;

ds::describe("something", function() {
 ds::context("when this", function() {
 ds::it("does this", function() {

 });
 });
});

Alternatively, DSpec includes your test files within the scope of the DSpec\Context\SpecContext, so you can also use $this, but I think it's a little ugly:

<?php 

$this->describe("something", function() {
 $this->context("when this", function() {
 $this->it("does this", function() {

 });
 });
});

Todo

• More tests
• Logging would be nice for debugging
• Documentation
• Profile and improve memory consumption

Contributing

Check the todo list above, there's a good chance I'm already working on those. Fork, branch, write tests, write code, refactor, repeat, pull request.

Copyright

Copyright (c) 2012 Dave Marshall. See LICENCE for further details