Symfony's DomCrawler with Laravel HTTP Tests

Have you ever needed to assert part of an HTML response from within an HTTP test in Laravel? I recently needed to validate parts of a response to verify an important piece of content was rendered. For example, let's say you have a critical JavaScript file that you want to ensure is contained within the DOM?

Here's the testing API we are going to build:

$node = $response->get('/')
    ->crawl()
    ->filter('a')
    ->reduce(function (Crawler $node): bool {
        return $node->attr('href') === 'https://laravel-news.com';
    });
 
$this->assertCount(1, $node);

There are a few options for parsing and traversing the DOM within PHP, such as PHP's DOMDocument, PHPUnit's DOM assertions (which are deprecated), Symfony's DOMCrawler component, and various others. I happen to prefer Symfony's DOMCrawler component, which has really powerful filtering, traversal and more.

Let's see how we can quickly incorporate the DOMCrawler component in our Laravel HTTP tests!

#Example

The gist of using the DOMCrawler is creating a new Crawler instance with the HTML content passed to the constructor:

use Symfony\Component\DomCrawler\Crawler;
 
$crawler = new Crawler($response->getContent());
 
foreach ($crawler as $domElement) {
    var_dump($domElement->nodeName);
}

Using the Crawler instance directly works but is repetitive. Given Laravel's powerful macro feature, we can quickly define a macro to crawl a TestResponse.

Here's what the usage of my macro looks like:

$response = $this->get('/');
 
$crawler = $response->crawl();
 
// DOM traversal
// Assertions

If you want to try it out, define the following macro in a service provider's boot() method:

use Illuminate\Support\ServiceProvider;
use Illuminate\Testing\TestResponse;
use Symfony\Component\DomCrawler\Crawler;
use PHPUnit\Framework\Assert as PHPUnit;
 
// ...
 
public function boot(): void
{
    TestResponse::macro('crawl', function(?callable $callback = null): Crawler {
        if (empty($content = $this->getContent())) {
            PHPUnit::fail('The HTTP response is empty.');
        }
 
        $callback ??= fn ($c): Crawler => $c;
 
        return call_user_func($callback, new Crawler($content));
    });
}

Our macro does the following:

1. Get the response content and fail the test immediately if it's empty
2. Create a pass-through callback if the user didn't provide one using the null coalescing assignment operator
3. Pass a new Crawler instance through the callback, which should return a Crawler instance in the end

Using the null coalescing assignment operator, we avoid any if checks by providing a default pass-through callback if the user doesn't pass one.

The idea of the callable is that the user could traverse the DOM, do some assertions, and ultimately return a subset of the DOM via crawl() if only a part of the DOM is needed:

// Return the full content
$crawler = $response->crawl();
 
// Filter and return the filtered crawler instance
$card = $response->crawl(function (Crawler $c) {
    return $c->filter('a')
        ->reduce(function (Crawler $node) {
            return $node->attr('href') === 'https://laravel-news.com';
        });
});

Maybe this example is a bit overkill, but let's validate the Laravel News HTML included in the welcome.blade.php within a default Laravel installation:

use Symfony\Component\DomCrawler\Crawler;
 
// ...
 
/**
 * A basic test example.
 */
public function test_the_application_returns_a_successful_response(): void
{
    $response = $this->get('/');
 
    $response->assertStatus(200);
 
    // Find the Laravel News node
    $card = $response->crawl()
        ->filter('a')
        ->reduce(function (Crawler $node) {
            return $node->attr('href') === 'https://laravel-news.com';
        });
 
    $this->assertNotEmpty($card, 'The Laravel News homepage card was not found!');
 
    // Validate that the $card node has an H2 with `Laravel News`
    $this->assertEquals(
        'Laravel News',
        $card->filter('h2')->first()->text()
    );
 
    // Validate that the page shows the blurb
    $blurb = $card
        ->filter('p')
        ->reduce(function (Crawler $n) {
            return str($n->text())->startsWith('Laravel News is a community driven portal');
        });
 
    $this->assertCount(1, $blurb);
}

#Bonus

You may want to write more convenience helpers to validate DOM elements in your tests. For example, here's a simple assertion that validates a node exists:

$response
    ->assertStatus(200)
    ->assertNodeExists('a[href="https://laravel-news.com"]');

And here's the macro I've defined, which also allows chaining with the TestResponse instance:

TestResponse::macro('assertNodeExists', function(string $selector): static {
    $node = $this->crawl()->filter($selector);
    $message = "Failed asserting the node exists with selector \"{$selector}\".";
 
    PHPUnit::assertGreaterThan(0, $node->count(), $message);
 
    return $this;
});

If the node doesn't exist, here's an example of what our macro will look like in our test output:

1) Tests\Feature\ExampleTest::test_the_application_returns_a_successful_response
   Failed asserting the node exists with selector "a[href="https://laravelnews.com"]".
   Failed asserting that 0 is greater than 0.

I'd recommend checking out the capabilities of the Symphony The DomCrawler Component. It includes powerful XPath and CSS selectors, node traversal, and more!