README

Aims to write-and-run your specs in a easy way. Quickly.

Mock support for classes and functions*
Code-coverage reporting with PHPUnit
Don't struggle with classes!
Save as TAP or JSON
Watch mode

How to?

composer.json

{
  "require-dev": {
    "habanero/spectre": "v0.2.0"
  }
}

inc/sum.php

<?php

function sum($a, $b)
{
  return $a + $b;
}

specs/sum-spec.php

<?php

require 'inc/sum.php';

describe('sum()', function () {
  it('sums two numbers', function () {
    expect(sum(2, 2))->toBe(4);
  });
});

Execute your specs:

$ vendor/bin/spectre specs

Running specs...
  sum()
    ✓ sums two numbers ... OK

Done (0.0017s)

Available matchers

toBe($value) — Strict equal comparison (with ===)
toBeA($value) — Data-type comparison (with is_<type>())
toBeLike($value) — Alias for toEqual
toEquals($value) — Alias for toEqual
toBeGreaterThan($value) — Comparison using the > operator
toBeLessThan($value) — Comparison using the < operator
toBeAnInstanceOf($value) — Alias for toBeInstanceOf
toBeInstanceOf($value) — Comparison using the instanceof operator
toBeEmpty() — Tests agains empty()
toBeTruthy() — Test for truthy-values
toBeFalsy() — Test for falsy-values
toBeArray() — Test using is_array()
toBeBoolean() — Alias for toBeBool
toBeBool() — Test using is_bool()
toBeCallable() — Test using is_callable()
toBeDouble() — Test using is_double()
toBeFloat() — Test using is_float()
toBeInt() — Test using is_int()
toBeInteger() — Test using is_integer()
toBeLong() — Test using is_long()
toBeNull() — Test using is_null()
toBeNumeric() — Test using is_numeric()
toBeObject() — Test using is_object()
toBeReal() — Test using is_real()
toBeResource() — Test using is_resource()
toBeScalar() — Test using is_scalar()
toBeString() — Test using is_string()
toHaveKey($value) — Test arrays using isset()
toHaveLength([$value]) — Tests using count() and strlen()
toEndWith($value) — Test for trailing substrings
toStartWith($value) — Test for leading substrings
toContains($value) — Alias for toContain
toContain($value) — Test for including substrings
toEqual($value) — Weak equal comparison (with ==)
toMatch($value) — Test strings with regular expressions
toPrint($value) — Test for buffered-substrings (capture includes/echos with buffers)
toThrow([$value]) — Test for exceptions, if $value is provided will test against instanceof
toWarn([$value]) — Test for buffered-substrings at user-level errors, notices and warnings (no fatal ones)

Custom matchers

To register your own matchers you should implements the following code:

\Spectre\Base::customMatchers('toBeCustomValue', function ($expected, $value) {
  // test $value against $this->expected
  // then return true or false
  //
  // or for custom messages:
  //
  // return array(
  //   'result' => $expected === $value,
  //   'negative' => "Expected '{subject}' {verb} '{value}', but it did not",
  //   'positive' => "Did not expect '{subject}' {verb} '{value}', but it did",
  // );
});

Note that any additional arguments will be passed after the $value argument.

Mock support

Since 0.3.0 you can mock classes and some built-in functions using the same API, see spec/mock-spec.php for more examples.

In short, you can mock any class or function as follows:

// class
$stub = spy($namespace, $className)
    ->methods('testMethod')
    ->getMock();

$stub->expects($callback = any())
    ->method('testMethod')
    ->willReturn(42);

// function
$stub = fun($namespace, $function)
    ->expects($callback = any())
    ->willReturn(42);

Available constraints

any()
never()
atLeast($count)
atLeastOnce()
once()
exactly($count)
atMost($count)
at($index)
returnValue($test)
returnValueMap($test)
returnArgument($index)
returnCallback($fn)
returnSelf()
throwException($e)
onConsecutiveCalls()

Some constraints are also spies, given a $callback reference you can ask later for:

hasBeenInvoked()
getInvocations()
getInvocationCount()

CLI options

Type vendor/bin/spectre without arguments to get the following:

Usage: vendor/bin/spectre [options] <folders|files>

  -h --help      Display this help
  -w --watch     Enables the watch mode
  -t --timeout   Timeout in seconds for watch mode
  -c --coverage  Enables code coverage instrumentation
  -f --filter    Filter for executing specific tests by name
  -x --exclude   Folders and files to exclude from coverage
  -o --output    Custom filename for saving coverage report
  -r --reporter  Default reporter for coverage. Options: JSON, TAP

Examples

You can mix almost all arguments on several ways, i.e:

$ vendor/bin/spectre specs -rTAP -c -xvendor -xspecs
$ vendor/bin/spectre ./specs /path/to/specs --coverage --exclude docs
$ vendor/bin/spectre $PWD/specs --output results.json

habanero / spectre

Maintainers

Details