{"id":4723,"date":"2023-09-18T04:01:48","date_gmt":"2023-09-18T04:01:48","guid":{"rendered":"https:\/\/rengga.dev\/blog\/?p=4723"},"modified":"2023-09-18T04:05:12","modified_gmt":"2023-09-18T04:05:12","slug":"symfonys-domcrawler-with-laravel-http-tests","status":"publish","type":"post","link":"https:\/\/rengga.dev\/blog\/symfonys-domcrawler-with-laravel-http-tests\/","title":{"rendered":"Symfony’s DomCrawler with Laravel HTTP Tests"},"content":{"rendered":"

Have you ever needed to assert part of an HTML response from within an\u00a0HTTP test<\/a>\u00a0in 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?<\/p>\n

Here’s the testing API we are going to build:<\/p>\n

$node = $response->get('\/')\r\n    ->crawl()\r\n    ->filter('a')\r\n    ->reduce(function (Crawler $node): bool {\r\n        return $node->attr('href') === 'https:\/\/rengga.dev\/blog\/';\r\n    });\r\n \r\n$this->assertCount(1, $node);<\/pre>\n
There are a few options for parsing and traversing the DOM within PHP, such as PHP’s\u00a0DOMDocument<\/a>, 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.<\/p>\n
Let’s see how we can quickly incorporate the DOMCrawler component in our Laravel HTTP tests!<\/p>\n
Example<\/h3>\n
The gist of using the DOMCrawler is creating a new\u00a0Crawler<\/code>\u00a0instance with the HTML content passed to the constructor:<\/p>\n
use Symfony\\Component\\DomCrawler\\Crawler;\r\n \r\n$crawler = new Crawler($response->getContent());\r\n \r\nforeach ($crawler as $domElement) {\r\n    var_dump($domElement->nodeName);\r\n}<\/pre>\n
Using the Crawler instance directly works but is repetitive. Given Laravel’s powerful macro feature, we can quickly define a macro to crawl a\u00a0TestResponse<\/code>.<\/p>\n
Here’s what the usage of my macro looks like:<\/p>\n
$response = $this->get('\/');\r\n \r\n$crawler = $response->crawl();\r\n \r\n\/\/ DOM traversal\r\n\/\/ Assertions<\/pre>\n
If you want to try it out, define the following macro in a service provider’s\u00a0boot()<\/code>\u00a0method:<\/p>\n
use Illuminate\\Support\\ServiceProvider;\r\nuse Illuminate\\Testing\\TestResponse;\r\nuse Symfony\\Component\\DomCrawler\\Crawler;\r\nuse PHPUnit\\Framework\\Assert as PHPUnit;\r\n \r\n\/\/ ...\r\n \r\npublic function boot(): void\r\n{\r\n    TestResponse::macro('crawl', function(?callable $callback = null): Crawler {\r\n        if (empty($content = $this->getContent())) {\r\n            PHPUnit::fail('The HTTP response is empty.');\r\n        }\r\n \r\n        $callback ??= fn ($c): Crawler => $c;\r\n \r\n        return call_user_func($callback, new Crawler($content));\r\n    });\r\n}<\/pre>\n
Our macro does the following:<\/p>\n
    \n
  1. Get the response content and fail the test immediately if it’s empty<\/li>\n
  2. Create a pass-through callback if the user didn’t provide one using the null coalescing assignment operator<\/li>\n
  3. Pass a new\u00a0Crawler<\/code>\u00a0instance through the callback, which should return a\u00a0Crawler<\/code>\u00a0instance in the end<\/li>\n<\/ol>\n
    Using the null coalescing assignment operator, we avoid any\u00a0if<\/code>\u00a0checks by providing a default pass-through callback if the user doesn’t pass one.<\/p>\n
    The idea of the\u00a0callable<\/code>\u00a0is that the user could traverse the DOM, do some assertions, and ultimately return a subset of the DOM via\u00a0crawl()<\/code>\u00a0if only a part of the DOM is needed:<\/p>\n
    \/\/ Return the full content\r\n$crawler = $response->crawl();\r\n \r\n\/\/ Filter and return the filtered crawler instance\r\n$card = $response->crawl(function (Crawler $c) {\r\n    return $c->filter('a')\r\n        ->reduce(function (Crawler $node) {\r\n            return $node->attr('href') === 'https:\/\/rengga.dev\/blog\/';\r\n        });\r\n});<\/pre>\n
    Maybe this example is a bit overkill, but let’s validate the Laravel News HTML included in the\u00a0welcome.blade.php<\/code>\u00a0within a default Laravel installation:<\/p>\n
    use Symfony\\Component\\DomCrawler\\Crawler;\r\n \r\n\/\/ ...\r\n \r\n\/**\r\n * A basic test example.\r\n *\/\r\npublic function test_the_application_returns_a_successful_response(): void\r\n{\r\n    $response = $this->get('\/');\r\n \r\n    $response->assertStatus(200);\r\n \r\n    \/\/ Find the Laravel News node\r\n    $card = $response->crawl()\r\n        ->filter('a')\r\n        ->reduce(function (Crawler $node) {\r\n            return $node->attr('href') === 'https:\/\/rengga.dev\/blog\/';\r\n        });\r\n \r\n    $this->assertNotEmpty($card, 'The Laravel News homepage card was not found!');\r\n \r\n    \/\/ Validate that the $card node has an H2 with `Laravel News`\r\n    $this->assertEquals(\r\n        'Laravel News',\r\n        $card->filter('h2')->first()->text()\r\n    );\r\n \r\n    \/\/ Validate that the page shows the blurb\r\n    $blurb = $card\r\n        ->filter('p')\r\n        ->reduce(function (Crawler $n) {\r\n            return str($n->text())->startsWith('Laravel News is a community driven portal');\r\n        });\r\n \r\n    $this->assertCount(1, $blurb);\r\n}<\/pre>\n
    Bonus<\/h3>\n
    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:<\/p>\n
    $response\r\n    ->assertStatus(200)\r\n    ->assertNodeExists('a[href=\"https:\/\/rengga.dev\/blog\/\"]');<\/pre>\n
    And here’s the macro I’ve defined, which also allows chaining with the\u00a0TestResponse<\/code>\u00a0instance:<\/p>\n
    TestResponse::macro('assertNodeExists', function(string $selector): static {\r\n    $node = $this->crawl()->filter($selector);\r\n    $message = \"Failed asserting the node exists with selector \\\"{$selector}\\\".\";\r\n \r\n    PHPUnit::assertGreaterThan(0, $node->count(), $message);\r\n \r\n    return $this;\r\n});<\/pre>\n
    If the node doesn’t exist, here’s an example of what our macro will look like in our test output:<\/p>\n
    1) Tests\\Feature\\ExampleTest::test_the_application_returns_a_successful_response\r\n   Failed asserting the node exists with selector \"a[href=\"https:\/\/rengga.dev\/blog\/\"]\".\r\n   Failed asserting that 0 is greater than 0.<\/pre>\n
    I’d recommend checking out the capabilities of the Symphony\u00a0The DomCrawler Component<\/a>. It includes powerful XPath and CSS selectors, node traversal, and more!<\/p>\n","protected":false},"excerpt":{"rendered":"
    Have you ever needed to assert part of an HTML response from <\/a><\/p>\n","protected":false},"author":1,"featured_media":4608,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[12],"tags":[711,712,708,713],"newstopic":[597,574],"class_list":{"0":"post-4723","1":"post","2":"type-post","3":"status-publish","4":"format-standard","5":"has-post-thumbnail","7":"category-web-development","8":"tag-admin-dashboard","9":"tag-http","10":"tag-laravel","11":"tag-symfonys-domcrawler","12":"newstopic-laravel","13":"newstopic-php"},"_links":{"self":[{"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/posts\/4723","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/comments?post=4723"}],"version-history":[{"count":2,"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/posts\/4723\/revisions"}],"predecessor-version":[{"id":4725,"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/posts\/4723\/revisions\/4725"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/media\/4608"}],"wp:attachment":[{"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/media?parent=4723"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/categories?post=4723"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/tags?post=4723"},{"taxonomy":"newstopic","embeddable":true,"href":"https:\/\/rengga.dev\/blog\/wp-json\/wp\/v2\/newstopic?post=4723"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}