index.html

---
layout: default
title: Event driven BDD test framework for PHP!
type: index
---

<div class="row">
    <div class="col-md-4 bucket-col">
        <div class="bucket">
            <p class="bucket-icon">
                <i class="fa fa-leaf icon-natural"></i>
            </p>
            <h2>Natural</h2>
            <p>
                Testing with Peridot is natural. Write tests using the familiar <code>describe-it</code> syntax. Easily and clearly describe how your code should behave in a language that makes sense. See <a href="#getting-started">getting started</a>.
            </p>
        </div>
    </div>
    <div class="col-md-4 bucket-col">
        <div class="bucket">
            <p class="bucket-icon">
                <i class="fa fa-plug icon-extensible"></i>
            </p>
            <h2>Extensible</h2>
            <p>
                Peridot is event driven, so writing plugins or ad hoc extensions is <em>painless</em>. Peridot <a href="/events.html">events</a> and <a href="/scopes.html">scopes</a> allow you to easily add test helpers, custom reporters, and plugins. WebDriver? Databases? Your framework of choice? No problem. We believe in a small core with endless possibilities.
            </p>
        </div>
    </div>
    <div class="col-md-4 bucket-col">
        <div class="bucket">
            <p class="bucket-icon">
                <i class="fa fa-bolt icon-fast"></i>
            </p>
            <h2>Fast</h2>
            <p>
                Peridot is lightweight. Peridot suites load and run <a href="https://github.com/peridot-php/bowling-kata" target="__blank">faster</a> than similar PHPUnit or phpspec suites. Have slow or bulky integration tests? No problem, Peridot can <a href="https://github.com/peridot-php/peridot-concurrency" target="__blank">run your tests concurrently</a>.
            </p>
        </div>
    </div>
</div>

<div class="row">
    <div class="col-xs-12">
        <h2 id="installation">Installing Peridot</h2>
        <p>
            Peridot can be installed several ways:
        </p>
        <h3>Composer</h3>
{% highlight shell %}
# global composer install
$ composer global require peridot-php/peridot

# ensure .composer/vendor/bin is on your PATH
$ export PATH="$PATH:$HOME/.composer/vendor/bin"

# local per project install (recommended)
$ composer require peridot-php/peridot
{% endhighlight %}

        <h3>Manual install</h3>

{% highlight shell %}
# download the latest phar
$ sudo wget http://peridot-php.github.io/downloads/peridot.phar -O /usr/local/bin/peridot

# or if you prefer curl
$ sudo curl http://peridot-php.github.io/downloads/peridot.phar -o /usr/local/bin/peridot

# make it executable
$ sudo chmod a+x /usr/local/bin/peridot
{% endhighlight %}

        <h3>Manual install (local)</h3>
        <p>
            <a class="btn btn-success" id="downloadLink" href="http://peridot-php.github.io/downloads/peridot.phar">Download Latest Stable Phar</a>
        </p>

        <h2 id="getting-started">Getting Started</h2>

        <p>
            Peridot uses the familiar <code>describe-it</code> syntax to create a clear and readable testing language.
        </p>

{% highlight php %}
<?php // arrayobject.spec.php
describe('ArrayObject', function() {
    beforeEach(function() {
        $this->arrayObject = new ArrayObject(['one', 'two', 'three']);
    });

    describe('->count()', function() {
        it('should return the number of items', function() {
            $count = $this->arrayObject->count();
            assert($count === 3, 'expected 3');
        });
    });
});
{% endhighlight %}

{% highlight text %}
$ peridot arrayobject.spec.php

  ArrayObject
    ->count()
      ✓ should return the number of items


  1 passing (19 ms)
{% endhighlight %}

        <h2 id="peridot-cli"><code class="code">peridot</code></h2>

{% highlight text %}
$ peridot --help
Usage:
  peridot [options] [files]

Options:
  -f, --focus=FOCUS                  Run tests matching <pattern>
  -s, --skip=SKIP                    Skip tests matching <pattern>
  -g, --grep=GREP                    Run tests with filenames matching <pattern> (default: *.spec.php)
  -b, --bail                         Stop on failure
  -r, --reporter=REPORTER            Select which reporter to use (default: spec)
      --reporters                    List all available reporters
  -C, --no-colors                    Disable output colors
      --force-colors                 Force output colors
  -c, --configuration=CONFIGURATION  A php file containing peridot configuration
  -V, --version                      Display the Peridot version number
  -h, --help                         Display this help message.
{% endhighlight %}

        <h3>-f, --focus</h3>
        <p>
            Only run tests whose title matches the provided pattern. See <a href="#focusing-and-skipping">Focusing and Skipping</a>.
        </p>

        <h3>-s, --skip</h3>
        <p>
            Only run tests whose title does not match the provided pattern. See <a href="#focusing-and-skipping">Focusing and Skipping</a>.
        </p>

        <h3>-g, --grep</h3>
        <p>
            Only run test files whose filename matches the provided pattern. The default grep pattern is <code>*.spec.php</code>
        </p>

        <h3>-b, --bail</h3>
        <p>
            Tell peridot to stop running tests as soon as there is a failure.
        </p>

        <h3>-r, --reporter</h3>
        <p>
            Select which reporter(s) to use (multiple values can be specified).
            See <a href="#specifying-reporters">Specifying Reporters</a>.
        </p>

        <h3>--reporters</h3>
        <p>
            List available test reporters.
        </p>

        <h3>-C, --no-colors</h3>
        <p>
            Disable colors in output.
        </p>

        <h3>-c, --configuration</h3>
        <p>
            A path to a peridot configuration file. Defaults to <code>getcwd() . '/peridot.php'</code>
        </p>

        <h2 id="focusing-and-skipping">Focusing and Skipping</h3>

        <p>See also <a href="syntax.html#focused-specs">Focused Specs</a>, which allow you to focus tests without using command line options.</p>
        <p>
            The <code>--focus</code> and <code>--skip</code> options can be used independently, or combined for complex test isolation.
            If both are used, <code>--skip</code> will take precedence.
        </p>
        <p>
            The patterns accepted by both of these options are PCRE regular expressions that are evaluated against the "title" of the test.
            The test title includes the description of the suite it is contained within, including any ancestors of that suite.
            For example, the test shown in <a href="#getting-started">Getting Started</a> has a title of: <code>ArrayObject ->count() should return the number of items</code>.
        </p>
        <p>
            If the provided pattern is not a complete PCRE regular expression, it will be surrounded in delimiters.
            For example, <code>--focus 'foo.*'</code> is equivalent to <code>--focus '~\bfoo.*\b~'</code>.
            If the provided pattern is not a valid PCRE regular expression, it will be treated as plain text.
            For example, <code>--focus 'foo('</code> is equivalent to <code>--focus '~\bfoo\(\b~'</code>.
            The addition of <code>\b</code> simply prevents accidental matching of substrings.
        </p>

        <h2 id="specifying-reporters">Specifying Reporters</h3>

        <p>
            The <code>--reporter</code> option can be used one or more times, and specifies the name of a reporter to use.
            Reporter names are registered via <a target="_blank" href="http://peridot-php.github.io/docs/class-Peridot.Reporter.ReporterFactory.html">ReporterFactory::register</a>.
        </p>
        <p>
            When multiple reporters are specified, the first reporter specified is the "primary" reporter, and any output generated by this reporter will be displayed as the suite runs.
            Any subsequent reporters will have their output buffered, and this output will be displayed after the suite has completed.
        </p>

        <h2 id="examples">Example Test Suites</h2>

        <p>
            You can head over to the <a href="https://github.com/peridot-php" target="__blank">Peridot</a> GitHub organization for plenty of examples using Peridot.
        </p>

        <p>
            We would love to see other projects using Peridot, so if you have a project that uses it, we would love to know. Feel free to <a href="mailto:bscaturro@gmail.com?Subject=We%20use%20Peridot">message us</a> and let us know. We will gladly list your project on the site.
        </p>

        <h2 id="peridot-tests">Running Peridot's tests</h2>

        <p>
            Peridot's tests were written using Peridot. After cloning Peridot, you can run tests using:
        </p>

{% highlight shell %}
$ bin/peridot
{% endhighlight %}
    </div>
</div>