habanero/spectre

v0.3.0 2016-02-01 22:10 UTC

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

Build Status

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 = fn($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