habanero/spectre

Simple spec-testing tools

Spectre

Aims to write-and-run your specs in a easy way. Quickly., _(*1)

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

, _(*2)

How to?

composer.json, _(*3)

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

inc/sum.php, _(*4)

<?php

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

specs/sum-spec.php, _(*5)

<?php

require 'inc/sum.php';

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

Execute your specs:, _(*6)

$ 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:, _(*7)

\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., _(*8)

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., _(*9)

In short, you can mock any class or function as follows:, _(*10)

// 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:, _(*11)

• hasBeenInvoked()
• getInvocations()
• getInvocationCount()

CLI options

Type vendor/bin/spectre without arguments to get the following:, _(*12)

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:, _(*13)

$ 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