Testing

Your First Functional Test

Functional tests are simple PHP files that typically live in the tests/AppBundle/Controller directory for your bundle. If you want to test the pages handled by your PostController class, start by creating a new PostControllerTest.php file that extends a special WebTestCase class.

As an example, a test could look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// tests/AppBundle/Controller/PostControllerTest.php
namespace Tests\AppBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class PostControllerTest extends WebTestCase
{
    public function testShowPost()
    {
        $client = static::createClient();

        $crawler = $client->request('GET', '/post/hello-world');

        $this->assertGreaterThan(
            0,
            $crawler->filter('html:contains("Hello World")')->count()
        );
    }
}

1
2
3
4
5
6
7

<?xml version="1.0" charset="utf-8" ?>
<phpunit>
    <php>
        <server name="KERNEL_DIR" value="/path/to/your/app/"/>
    </php>
    <!-- ... -->
</phpunit>

The createClient() method returns a client, which is like a browser that you'll use to crawl your site:

1

$crawler = $client->request('GET', '/post/hello-world');

The request() method (read more about the request method) returns a Crawler object which can be used to select elements in the response, click on links and submit forms.

Click on a link by first selecting it with the crawler using either an XPath expression or a CSS selector, then use the client to click on it. For example:

1
2
3
4
5
6
7
8

$link = $crawler
    ->filter('a:contains("Greet")') // find all links with the text "Greet"
    ->eq(1) // select the second link in the list
    ->link()
;

// and click it
$crawler = $client->click($link);

Submitting a form is very similar: select a form button, optionally override some form values and submit the corresponding form:

1
2
3
4
5
6
7
8

$form = $crawler->selectButton('submit')->form();

// set some values
$form['name'] = 'Lucas';
$form['form_name[subject]'] = 'Hey there!';

// submit the form
$crawler = $client->submit($form);

Now that you can navigate through an application, use assertions to test that it actually does what you expect it to. Use the Crawler to make assertions on the DOM:

1
2

// asserts that the response matches a given CSS selector.
$this->assertGreaterThan(0, $crawler->filter('h1')->count());

Or test against the response content directly if you just want to assert that the content contains some text or in case that the response is not an XML/HTML document:

1
2
3
4

$this->assertContains(
    'Hello World',
    $client->getResponse()->getContent()
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

use Symfony\Component\HttpFoundation\Response;

// ...

// asserts that there is at least one h2 tag
// with the class "subtitle"
$this->assertGreaterThan(
    0,
    $crawler->filter('h2.subtitle')->count()
);

// asserts that there are exactly 4 h2 tags on the page
$this->assertCount(4, $crawler->filter('h2'));

// asserts that the "Content-Type" header is "application/json"
$this->assertTrue(
    $client->getResponse()->headers->contains(
        'Content-Type',
        'application/json'
    ),
    'the "Content-Type" header is "application/json"' // optional message shown on failure
);

// asserts that the response content contains a string
$this->assertContains('foo', $client->getResponse()->getContent());
// ...or matches a regex
$this->assertRegExp('/foo(bar)?/', $client->getResponse()->getContent());

// asserts that the response status code is 2xx
$this->assertTrue($client->getResponse()->isSuccessful(), 'response status is 2xx');
// asserts that the response status code is 404
$this->assertTrue($client->getResponse()->isNotFound());
// asserts a specific 200 status code
$this->assertEquals(
    200, // or Symfony\Component\HttpFoundation\Response::HTTP_OK
    $client->getResponse()->getStatusCode()
);

// asserts that the response is a redirect to /demo/contact
$this->assertTrue(
    $client->getResponse()->isRedirect('/demo/contact')
    // if the redirection URL was generated as an absolute URL
    // $client->getResponse()->isRedirect('http://localhost/demo/contact')
);
// ...or simply check that the response is a redirect to any URL
$this->assertTrue($client->getResponse()->isRedirect());

Browsing

The Client supports many operations that can be done in a real browser:

1
2
3
4
5
6

$client->back();
$client->forward();
$client->reload();

// clears all cookies and the history
$client->restart();

Accessing Internal Objects

If you use the client to test your application, you might want to access the client's internal objects:

1
2

$history = $client->getHistory();
$cookieJar = $client->getCookieJar();

You can also get the objects related to the latest request:

1
2
3
4
5
6
7
8
9
10
11
12
13

// the HttpKernel request instance
$request = $client->getRequest();

// the BrowserKit request instance
$request = $client->getInternalRequest();

// the HttpKernel response instance
$response = $client->getResponse();

// the BrowserKit response instance
$response = $client->getInternalResponse();

$crawler = $client->getCrawler();

Accessing the Container

It's highly recommended that a functional test only tests the response. But under certain very rare circumstances, you might want to access some internal objects to write assertions. In such cases, you can access the Dependency Injection Container:

1
2
3

// will be the same container used in your test, unless you're using
// $client->insulate() or using real HTTP requests to test your application
$container = $client->getContainer();

For a list of services available in your application, use the debug:container command.

Accessing the Profiler Data

On each request, you can enable the Symfony profiler to collect data about the internal handling of that request. For example, the profiler could be used to verify that a given page executes less than a certain number of database queries when loading.

To get the Profiler for the last request, do the following:

1
2
3
4
5
6
7

// enables the profiler for the very next request
$client->enableProfiler();

$crawler = $client->request('GET', '/profiler');

// gets the profile
$profile = $client->getProfile();

For specific details on using the profiler inside a test, see the How to Use the Profiler in a Functional Test article.

Redirecting

When a request returns a redirect response, the client does not follow it automatically. You can examine the response and force a redirection afterwards with the followRedirect() method:

1

$crawler = $client->followRedirect();

If you want the client to automatically follow all redirects, you can force them by calling the followRedirects() method before performing the request:

1

$client->followRedirects();

If you pass false to the followRedirects() method, the redirects will no longer be followed:

1

$client->followRedirects(false);

Reporting Exceptions

Debugging exceptions in functional tests may be difficult because by default they are caught and you need to look at the logs to see which exception was thrown. Disabling catching of exceptions in the test client allows the exception to be reported by PHPUnit:

1

$client->catchExceptions(false);

Traversing

Like jQuery, the Crawler has methods to traverse the DOM of an HTML/XML document. For example, the following finds all input[type=submit] elements, selects the last one on the page, and then selects its immediate parent element:

1
2
3
4
5

$newCrawler = $crawler->filter('input[type=submit]')
    ->last()
    ->parents()
    ->first()
;

Many other methods are also available:

filter('h1.title')

Nodes that match the CSS selector.

filterXpath('h1')

Nodes that match the XPath expression.

eq(1)

Node for the specified index.

first()

First node.

last()

Last node.

siblings()

Siblings.

nextAll()

All following siblings.

previousAll()

All preceding siblings.

parents()

Returns the parent nodes.

children()

Returns children nodes.

reduce($lambda)

Nodes for which the callable does not return false.

Since each of these methods returns a new Crawler instance, you can narrow down your node selection by chaining the method calls:

1
2
3
4
5
6
7
8
9

$crawler
    ->filter('h1')
    ->reduce(function ($node, $i) {
        if (!$node->attr('class')) {
            return false;
        }
    })
    ->first()
;

Extracting Information

The Crawler can extract information from the nodes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// returns the attribute value for the first node
$crawler->attr('class');

// returns the node value for the first node
$crawler->text();

// extracts an array of attributes for all nodes
// (_text returns the node value)
// returns an array for each element in crawler,
// each with the value and href
$info = $crawler->extract(['_text', 'href']);

// executes a lambda for each node and return an array of results
$data = $crawler->each(function ($node, $i) {
    return $node->attr('href');
});

Links

To select links, you can use the traversing methods above or the convenient selectLink() shortcut:

1

$crawler->selectLink('Click here');

This selects all links that contain the given text, or clickable images for which the alt attribute contains the given text. Like the other filtering methods, this returns another Crawler object.

Once you've selected a link, you have access to a special Link object, which has helpful methods specific to links (such as getMethod() and getUri()). To click on the link, use the Client's click() method and pass it a Link object:

1
2
3

$link = $crawler->selectLink('Click here')->link();

$client->click($link);

Forms

Forms can be selected using their buttons, which can be selected with the selectButton() method, just like links:

1

$buttonCrawlerNode = $crawler->selectButton('submit');

The selectButton() method can select button tags and submit input tags. It uses several parts of the buttons to find them:

• The value attribute value;
• The id or alt attribute value for images;
• The id or name attribute value for button tags.

Once you have a Crawler representing a button, call the form() method to get a Form instance for the form wrapping the button node:

1

$form = $buttonCrawlerNode->form();

When calling the form() method, you can also pass an array of field values that overrides the default ones:

1
2
3
4

$form = $buttonCrawlerNode->form([
    'my_form[name]'    => 'Fabien',
    'my_form[subject]' => 'Symfony rocks!',
]);

And if you want to simulate a specific HTTP method for the form, pass it as a second argument:

1

$form = $buttonCrawlerNode->form([], 'DELETE');

The Client can submit Form instances:

1

$client->submit($form);

The field values can also be passed as a second argument of the submit() method:

1
2
3
4

$client->submit($form, [
    'my_form[name]'    => 'Fabien',
    'my_form[subject]' => 'Symfony rocks!',
]);

For more complex situations, use the Form instance as an array to set the value of each field individually:

1
2
3

// changes the value of a field
$form['my_form[name]'] = 'Fabien';
$form['my_form[subject]'] = 'Symfony rocks!';

There is also a nice API to manipulate the values of the fields according to their type:

1
2
3
4
5
6
7
8
9
10
11
12

// selects an option or a radio
$form['country']->select('France');

// ticks a checkbox
$form['like_symfony']->tick();

// uploads a file
$form['photo']->upload('/path/to/lucas.jpg');

// In the case of a multiple file upload
$form['my_form[field][0]']->upload('/path/to/lucas.jpg');
$form['my_form[field][1]']->upload('/path/to/lisa.jpg');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// gets the form
$form = $crawler->filter('button')->form();

// gets the raw values
$values = $form->getPhpValues();

// adds fields to the raw values
$values['task']['tags'][0]['name'] = 'foo';
$values['task']['tags'][1]['name'] = 'bar';

// submits the form with the existing and new values
$crawler = $client->request($form->getMethod(), $form->getUri(), $values,
    $form->getPhpFiles());

// the 2 tags have been added to the collection
$this->assertEquals(2, $crawler->filter('ul.tags > li')->count());

1
2
3
4
5
6
7
8
9
10
11
12

// gets the values of the form
$values = $form->getPhpValues();

// removes the first tag
unset($values['task']['tags'][0]);

// submits the data
$crawler = $client->request($form->getMethod(), $form->getUri(),
    $values, $form->getPhpFiles());

// the tag has been removed
$this->assertEquals(0, $crawler->filter('ul.tags > li')->count());

PHPUnit Configuration

Each application has its own PHPUnit configuration, stored in the phpunit.xml.dist file. You can edit this file to change the defaults or create a phpunit.xml file to set up a configuration for your local machine only.

By default, only the tests stored in /tests are run via the phpunit command, as configured in the phpunit.xml.dist file:

1
2
3
4
5
6
7
8
9
10

<!-- phpunit.xml.dist -->
<phpunit>
    <!-- ... -->
    <testsuites>
        <testsuite name="Project Test Suite">
            <directory>tests</directory>
        </testsuite>
    </testsuites>
    <!-- ... -->
</phpunit>

But you can add more directories. For instance, the following configuration adds tests from a custom lib/tests directory:

1
2
3
4
5
6
7
8
9
10
11

<!-- phpunit.xml.dist -->
<phpunit>
    <!-- ... -->
    <testsuites>
        <testsuite name="Project Test Suite">
            <!-- ... --->
            <directory>lib/tests</directory>
        </testsuite>
    </testsuites>
    <!-- ... -->
</phpunit>

To include other directories in the code coverage, also edit the <filter> section:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- phpunit.xml.dist -->
<phpunit>
    <!-- ... -->
    <filter>
        <whitelist>
            <!-- ... -->
            <directory>lib</directory>
            <exclude>
                <!-- ... -->
                <directory>lib/tests</directory>
            </exclude>
        </whitelist>
    </filter>
    <!-- ... -->
</phpunit>