Testing

Resetting the Database Automatically Before each Test

Tests should be independent from each other to avoid side effects. For example, if some test modifies the database (by adding or removing an entity) it could change the results of other tests.

The DAMADoctrineTestBundle uses Doctrine transactions to let each test interact with an unmodified database. Install it using:

1

$ composer require --dev dama/doctrine-test-bundle

Now, enable it as a PHPUnit extension:

1
2
3
4
5
6
7
8

<!-- phpunit.xml.dist -->
<phpunit>
    <!-- ... -->

    <extensions>
        <extension class="DAMA\DoctrineTestBundle\PHPUnit\PHPUnitExtension"/>
    </extensions>
</phpunit>

That's it! This bundle uses a clever trick: it begins a database transaction before every test and rolls it back automatically after the test finishes to undo all changes. Read more in the documentation of the DAMADoctrineTestBundle.

Load Dummy Data Fixtures

Instead of using the real data from the production database, it's common to use fake or dummy data in the test database. This is usually called "fixtures data" and Doctrine provides a library to create and load them. Install it with:

1

$ composer require --dev doctrine/doctrine-fixtures-bundle

Then, use the make:fixtures command of the SymfonyMakerBundle to generate an empty fixture class:

1
2
3
4

$ php bin/console make:fixtures

The class name of the fixtures to create (e.g. AppFixtures):
> ProductFixture

Then you modify and use this class to load new entities in the database. For instance, to load Product objects into Doctrine, use:

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

// src/DataFixtures/ProductFixture.php
namespace App\DataFixtures;

use App\Entity\Product;
use Doctrine\Bundle\FixturesBundle\Fixture;
use Doctrine\Persistence\ObjectManager;

class ProductFixture extends Fixture
{
    public function load(ObjectManager $manager)
    {
        $product = new Product();
        $product->setName('Priceless widget');
        $product->setPrice(14.50);
        $product->setDescription('Ok, I guess it *does* have a price');
        $manager->persist($product);

        // add more products

        $manager->flush();
    }
}

Empty the database and reload all the fixture classes with:

1

$ php bin/console --env=test doctrine:fixtures:load

For more information, read the DoctrineFixturesBundle documentation.

Multiple Requests in One Test

After making a request, subsequent requests will make the client reboot the kernel. This recreates the container from scratch to ensures that requests are isolated and use new service objects each time. This behavior can have some unexpected consequences: for example, the security token will be cleared, Doctrine entities will be detached, etc.

First, you can call the client's disableReboot() method to reset the kernel instead of rebooting it. In practice, Symfony will call the reset() method of every service tagged with kernel.reset. However, this will also clear the security token, detach Doctrine entities, etc.

In order to solve this issue, create a compiler pass to remove the kernel.reset tag from some services in your test environment:

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

// src/Kernel.php
namespace App;

use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;

class Kernel extends BaseKernel implements CompilerPassInterface
{
    use MicroKernelTrait;

    // ...

    public function process(ContainerBuilder $container): void
    {
        if ('test' === $this->environment) {
            // prevents the security token to be cleared
            $container->getDefinition('security.token_storage')->clearTag('kernel.reset');

            // prevents Doctrine entities to be detached
            $container->getDefinition('doctrine')->clearTag('kernel.reset');

            // ...
        }
    }
}

Browsing the Site

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();

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);

Logging in Users (Authentication)

When you want to add application tests for protected pages, you have to first "login" as a user. Reproducing the actual steps - such as submitting a login form - makes a test very slow. For this reason, Symfony provides a loginUser() method to simulate logging in your functional tests.

Instead of logging in with real users, it's recommended to create a user only for tests. You can do that with Doctrine data fixtures to load the testing users only in the test database.

After loading users in your database, use your user repository to fetch this user and use $client->loginUser() to simulate a login request:

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

// tests/Controller/ProfileControllerTest.php
namespace App\Tests\Controller;

use App\Repository\UserRepository;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class ProfileControllerTest extends WebTestCase
{
    // ...

    public function testVisitingWhileLoggedIn()
    {
        $client = static::createClient();
        $userRepository = static::getContainer()->get(UserRepository::class);

        // retrieve the test user
        $testUser = $userRepository->findOneByEmail('john.doe@example.com');

        // simulate $testUser being logged in
        $client->loginUser($testUser);

        // test e.g. the profile page
        $client->request('GET', '/profile');
        $this->assertResponseIsSuccessful();
        $this->assertSelectorTextContains('h1', 'Hello John!');
    }
}

You can pass any UserInterface instance to loginUser(). This method creates a special TestBrowserToken object and stores in the session of the test client.

To set a specific firewall (main is set by default):

1

$client->loginUser($testUser, 'my_firewall');

Making AJAX Requests

The client provides an xmlHttpRequest() method, which has the same arguments as the request() method and is a shortcut to make AJAX requests:

1
2

// the required HTTP_X_REQUESTED_WITH header is added automatically
$client->xmlHttpRequest('POST', '/submit', ['name' => 'Fabien']);

Sending Custom Headers

If your application behaves according to some HTTP headers, pass them as the second argument of createClient():

1
2
3
4

$client = static::createClient([], [
    'HTTP_HOST'       => 'en.example.com',
    'HTTP_USER_AGENT' => 'MySuperBrowser/1.0',
]);

You can also override HTTP headers on a per request basis:

1
2
3
4

$client->request('GET', '/', [], [], [
    'HTTP_HOST'       => 'en.example.com',
    'HTTP_USER_AGENT' => 'MySuperBrowser/1.0',
]);

Reporting Exceptions

Debugging exceptions in application 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);

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
14

// 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();

// the Crawler instance
$crawler = $client->getCrawler();

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 runs 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.

Clicking on Links

Use the clickLink() method to click on the first link that contains the given text (or the first clickable image with that alt attribute):

1
2
3
4

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

$client->clickLink('Click here');

If you need access to the Link object that provides helpful methods specific to links (such as getMethod() and getUri()), use the Crawler::selectLink() method instead:

1
2
3
4
5
6
7
8

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

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

// use click() if you want to click the selected link
$client->click($link);

Submitting Forms

Use the submitForm() method to submit the form that contains the given button:

1
2
3
4
5
6

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

$crawler = $client->submitForm('Add comment', [
    'comment_form[content]' => '...',
]);

The first argument of submitForm() is the text content, id, value or name of any <button> or <input type="submit"> included in the form. The second optional argument is used to override the default form field values.

If you need access to the Form object that provides helpful methods specific to forms (such as getUri(), getValues() and getFiles()) use the Crawler::selectButton() method instead:

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

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

// select the button
$buttonCrawlerNode = $crawler->selectButton('submit');

// retrieve the Form object for the form belonging to this button
$form = $buttonCrawlerNode->form();

// set values on a form object
$form['my_form[name]'] = 'Fabien';
$form['my_form[subject]'] = 'Symfony rocks!';

// submit the Form object
$client->submit($form);

// optionally, you can combine the last 2 steps by passing an array of
// field values while submitting the form:
$client->submit($form, [
    'my_form[name]'    => 'Fabien',
    'my_form[subject]' => 'Symfony rocks!',
]);

Based on the form type, you can use different methods to fill in the input:

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

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

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

// uploads a file
$form['my_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

$client->submit($form, [], ['HTTP_ACCEPT_LANGUAGE' => 'es']);
$client->submitForm($button, [], 'POST', ['HTTP_ACCEPT_LANGUAGE' => 'es']);

Response Assertions

assertResponseIsSuccessful(string $message = '')

Asserts that the response was successful (HTTP status is 2xx).

assertResponseStatusCodeSame(int $expectedCode, string $message = '')

Asserts a specific HTTP status code.

assertResponseRedirects(?string $expectedLocation = null, ?int $expectedCode = null, string $message = '')

Asserts the response is a redirect response (optionally, you can check the target location and status code).

assertResponseHasHeader(string $headerName, string $message = '')/assertResponseNotHasHeader(string $headerName, string $message = '')

Asserts the given header is (not) available on the response, e.g. assertResponseHasHeader('content-type');.

assertResponseHeaderSame(string $headerName, string $expectedValue, string $message = '')/assertResponseHeaderNotSame(string $headerName, string $expectedValue, string $message = '')

Asserts the given header does (not) contain the expected value on the response, e.g. assertResponseHeaderSame('content-type', 'application/octet-stream');.

assertResponseHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = '')/assertResponseNotHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = '')

Asserts the given cookie is present in the response (optionally checking for a specific cookie path or domain).

assertResponseCookieValueSame(string $name, string $expectedValue, string $path = '/', ?string $domain = null, string $message = '')

Asserts the given cookie is present and set to the expected value.

assertResponseFormatSame(?string $expectedFormat, string $message = '')

Asserts the response format returned by the getFormat() method is the same as the expected value.

assertResponseIsUnprocessable(string $message = '')

Asserts the response is unprocessable (HTTP status is 422)

Request Assertions

assertRequestAttributeValueSame(string $name, string $expectedValue, string $message = '')

Asserts the given request attribute is set to the expected value.

assertRouteSame($expectedRoute, array $parameters = [], string $message = '')

Asserts the request matches the given route and optionally route parameters.

Browser Assertions

assertBrowserHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = '')/assertBrowserNotHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = '')

Asserts that the test Client does (not) have the given cookie set (meaning, the cookie was set by any response in the test).

assertBrowserCookieValueSame(string $name, string $expectedValue, string $path = '/', ?string $domain = null, string $message = '')

Asserts the given cookie in the test Client is set to the expected value.

assertThatForClient(Constraint $constraint, string $message = '')

Asserts the given Constraint in the Client. Useful for using your custom asserts in the same way as built-in asserts (i.e. without passing the Client as argument):

1
2
3
4
5

// add this method in some custom class imported in your tests
protected static function assertMyOwnCustomAssert(): void
{
    self::assertThatForClient(new SomeCustomConstraint());
}

Crawler Assertions

assertSelectorExists(string $selector, string $message = '')/assertSelectorNotExists(string $selector, string $message = '')

Asserts that the given selector does (not) match at least one element in the response.

assertSelectorTextContains(string $selector, string $text, string $message = '')/assertSelectorTextNotContains(string $selector, string $text, string $message = '')

Asserts that the first element matching the given selector does (not) contain the expected text.

assertSelectorTextSame(string $selector, string $text, string $message = '')

Asserts that the contents of the first element matching the given selector does (not) equal the expected text.

assertPageTitleSame(string $expectedTitle, string $message = '')

Asserts that the <title> element is equal to the given title.

assertPageTitleContains(string $expectedTitle, string $message = '')

Asserts that the <title> element contains the given title.

assertInputValueSame(string $fieldName, string $expectedValue, string $message = '')/assertInputValueNotSame(string $fieldName, string $expectedValue, string $message = '')

Asserts that value of the form input with the given name does (not) equal the expected value.

assertCheckboxChecked(string $fieldName, string $message = '')/assertCheckboxNotChecked(string $fieldName, string $message = '')

Asserts that the checkbox with the given name is (not) checked.

assertFormValue(string $formSelector, string $fieldName, string $value, string $message = '')/assertNoFormValue(string $formSelector, string $fieldName, string $message = '')

Asserts that value of the field of the first form matching the given selector does (not) equal the expected value.

Mailer Assertions

assertEmailCount(int $count, ?string $transport = null, string $message = '')

Asserts that the expected number of emails was sent.

assertQueuedEmailCount(int $count, ?string $transport = null, string $message = '')

Asserts that the expected number of emails was queued (e.g. using the Messenger component).

assertEmailIsQueued(MessageEvent $event, string $message = '')/assertEmailIsNotQueued(MessageEvent $event, string $message = '')

Asserts that the given mailer event is (not) queued. Use getMailerEvent(int $index = 0, ?string $transport = null) to retrieve a mailer event by index.

assertEmailAttachmentCount(RawMessage $email, int $count, string $message = '')

Asserts that the given email has the expected number of attachments. Use getMailerMessage(int $index = 0, ?string $transport = null) to retrieve a specific email by index.

assertEmailTextBodyContains(RawMessage $email, string $text, string $message = '')/assertEmailTextBodyNotContains(RawMessage $email, string $text, string $message = '')

Asserts that the text body of the given email does (not) contain the expected text.

assertEmailHtmlBodyContains(RawMessage $email, string $text, string $message = '')/assertEmailHtmlBodyNotContains(RawMessage $email, string $text, string $message = '')

Asserts that the HTML body of the given email does (not) contain the expected text.

assertEmailHasHeader(RawMessage $email, string $headerName, string $message = '')/assertEmailNotHasHeader(RawMessage $email, string $headerName, string $message = '')

Asserts that the given email does (not) have the expected header set.

assertEmailHeaderSame(RawMessage $email, string $headerName, string $expectedValue, string $message = '')/assertEmailHeaderNotSame(RawMessage $email, string $headerName, string $expectedValue, string $message = '')

Asserts that the given email does (not) have the expected header set to the expected value.

assertEmailAddressContains(RawMessage $email, string $headerName, string $expectedValue, string $message = '')

Asserts that the given address header equals the expected e-mail address. This assertion normalizes addresses like Jane Smith <jane@example.com> into jane@example.com.