syntax.html

---
layout: default
title: Testing Languages
type: leaf
---

<h1 class="text-center">Testing Languages</h1>

<p>
    By default, Peridot uses a BDD style DSL for describing your code's behavior via specs. Here's the breakdown:
</p>

<ul class="reference-list">
    <li>
        <div><code>describe($description, $func)</code></div>
        <p>
            This function creates a suite, and is used to organize behaviors. It's fair game to nest these.
        </p>
    </li>
    <li>
        <div><code>context($description, $func)</code></div>
        <p>
            This function is identical to <code>describe</code>. It is provided to offer additional organization for your specs.
        </p>
    </li>
    <li>
        <div><code>beforeEach($setupFunc)</code></div>
        <p>
            You can add setup functions that execute for all specs using this function. If you set variables on <code>$this</code> inside of the function body, it will create instance variables that are inherited by specs and suites.
        </p>
    </li>
    <li>
        <div><code>afterEach($tearDownFunc)</code></div>
        <p>
            You can add teardown functions that execute for all specs using this function.
        </p>
    </li>
    <li>
        <div><code>it($description, $func)</code></div>
        <p>
            This function creates a single test and adds it to the suite it is nested in.
        </p>
    </li>
</ul>

<p>
    An example might look like this:
</p>

{% highlight php %}
<?php
describe('TodoRepository', function () {
    beforeEach(function () {
        $interface = 'Doctrine\Common\Persistence\ObjectManager';
        // lets assume we are using the peridot-prophecy-plugin
        $this->em = $this->getProphet()->prophesize($interface);
        $this->repository = new TodoRepository($this->em->reveal());
    });

    afterEach(function () {
        $this->getProphet()->checkPredictions();
    });

    context('when calling ->get()', function () {
        it('should find the todo', function () {
            $this->repository->get(1);
            $this->em->find('Todos\Todo', 1)->shouldBeCalled();
        });
    });
});
{% endhighlight %}

<h2 id="pending-specs">Pending Specs</h2>

<p>
    "Pending" specs are not executed, but still appear in Peridot's output.
    This is typically used to temporarily skip a broken spec or suite.
</p>
<p>
    You can make any spec or suite pending, by prefixing the function with an <strong>x</strong>.
</p>

{% highlight php %}
<?php
xdescribe('A pending suite', function() {
    xcontext('when using a pending context', function() {
        xit('should have a pending spec', function() {
            // ...
        });
    });
});
{% endhighlight %}

<p>
    Or you can simply omit the test function.
</p>

{% highlight php %}
<?php
describe('A pending suite', function() {
    it('should have a pending spec');
});
{% endhighlight %}

<h2 id="focused-specs">Focused Specs</h2>

<p>
    "Focusing" lets you isolate indivdual specs or suites.
    If there are focused specs in a suite, then any unfocused specs in the same suite will be skipped entirely.
</p>
<p>
    You can make any spec or suite "focused", by prefixing the function with an <strong>f</strong>.
</p>

{% highlight php %}
<?php
describe('A suite with nested suites', function() {
    fcontext('A focused suite', function() {
        it('should execute this spec', function() {
            // ...
        });

        it('should also execute this spec', function() {
            // ...
        });
    });

    describe('An unfocused suite', function() {
        it('should not execute this spec', function() {
            // ...
        });
    });
});
{% endhighlight %}

<p>
    A suite is also considered "focused" if any of its nested specs or suites are focused.
    This allows focusing of a deeply nested spec without the pain of also marking all of its ancestors as focused.
</p>

{% highlight php %}
<?php
describe('A suite with nested suites', function() {
    context('A suite with nested focused specs', function() {
        fit('should execute this spec', function() {
            // ...
        });

        it('should not execute this spec', function() {
            // ...
        });
    });

    describe('An unfocused suite', function() {
        it('should not execute this spec', function() {
            // ...
        });
    });
});
{% endhighlight %}

<p>
    If multiple specs or suites within a suite are focused, then all the focused specs will be executed:
</p>

{% highlight php %}
<?php
describe('A suite with nested suites', function() {
    fit('should execute this spec', function() {
        // ...
    });

    fit('should also execute this spec', function() {
        // ...
    });

    it('should not execute this spec', function() {
        // ...
    });
});
{% endhighlight %}

<p>
    When any combination of <code>fdescribe()</code>, <code>fcontext()</code>, or <code>fit()</code> is used, Peridot will exit with a status code of <code>2</code> (unless a focused spec actually failed, in which case the status code will be <code>1</code>).
    This helps prevent accidentally committed focused tests from passing under CI conditions.
</p>

<p>
    If you wish to use focused tests with a CI service, it is recommended to use the <code>--focus</code> and/or <code>--skip</code> command line options instead, as these will not affect Peridot's exit status code.
</p>

<h2 id="custom-dsls">Custom DSLs</h2>

<p>
    You can also create your own testing DSLs! Check out <a href="https://github.com/peridot-php/peridot-dsl-example" target="_blank">Example: Creating An Acceptance Testing DSL.</a>
</p>

<p>
    The linked example above demonstrates creating a custom DSL to support the following testing language:
</p>

{% highlight php %}
<?php
Feature("chdir","
    As a PHP user
    I need to be able to change the current working directory",
    function () {

        Scenario(function () {

            Given('I am in this directory', function () {
                chdir(__DIR__);
            });

            When('I run getcwd()', function () {
                $this->cwd = getcwd();
            });

            Then('I should get this directory', function () {
                if ($this->cwd != __DIR__) {
                    throw new \Exception("Should be current directory");
                }
            });

        });

    });
{% endhighlight %}

<h2 id="assertions">Assertions</h2>

<p>
    A Peridot test fails when an exception is thrown. Peridot's default DSL configures the default behavior of PHP's native <a target="_blank" href="http://us3.php.net/manual/en/function.assert.php">assert</a> function to throw exceptions, but you could just as easily use an existing matcher library or roll your own.
</p>

<p>
We recommend the <a href="http://peridot-php.github.io/leo/" target="_blank">Leo</a> assertion and matcher library. It was developed by the Peridot team to create an expressive assertion language to complement Peridot's BDD style. However, Peridot was built to be unopinionated about such things, and you can find a list of other matchers <a href="https://github.com/peridot-php/peridot/wiki/Matchers" target="__blank">here</a>.
</p>