Download the PHP package sinnbeck/laravel-dom-assertions without Composer

DOM Assertions for Laravel

This package provides some extra assertion helpers to use in HTTP Tests. If you have ever needed more control over your view assertions than assertSee, assertSeeInOrder, assertSeeText, assertSeeTextInOrder, assertDontSee, and assertDontSeeText then this is the package for you.

Installation

You can install the package via composer:

Version 3.x and above requires PHP 8.1+ and Laravel 10+.

Note: If you're using PHP 8.0 or Laravel 9, please use version 2.x:

Table of contents

• Asserting on elements
• Asserting on forms
• Asserting on selects
• Asserting on datalists
• Asserting on text
• Quick existence checks
• Usage with Livewire
• Usage with Blade views and components
• Method reference
• Rector rules
• Contributing
• Credits
• License

Asserting on elements

Use assertElementExists() (or its alias assertElement()) on a test response to assert against the DOM. This package assumes a valid HTML document and will wrap your markup in <html>, <head>, and <body> tags if they are missing.

Called with no arguments, it simply asserts that a <body> element was parsed:

Pass a CSS selector as the first argument to target a specific element:

The second argument is a closure that receives an AssertElement instance, which is where all of the fluent assertions below live.

Asserting the element type

Asserting attributes

Assert that an attribute is present, optionally with a specific value:

Or assert that it is absent:

You can also check multiple attributes at once by passing an array of attribute => value pairs:

Asserting on children

Confirm a child element exists:

Narrow it down with a CSS selector:

Assert that the child carries certain attributes:

Assert it appears an exact number of times by passing a count as the final argument:

When you only care about the count, drop the attributes argument:

Or assert that no matching child exists:

Drilling into a child

find() selects the first matching child and lets you assert against it. Pass a closure to receive a fresh AssertElement for that child:

To assert against every matching element rather than just the first, use each():

Because each find() hands you another AssertElement, you can drill arbitrarily deep into the DOM:

Magic methods

Element type and attribute assertions have convenient magic-method shortcuts:

Asserting on forms

Forms support every element assertion above, plus a handful of form-specific helpers. Use assertFormExists() (alias assertForm()), which targets the first <form> on the page by default:

Pass a selector to target a specific form:

The closure receives an AssertForm instance. Assert on the action and method:

Omit the selector entirely and pass the closure directly to target the first form:

CSRF tokens and method spoofing

Any method other than GET or POST is automatically treated as a spoofed method, so this is equivalent to calling hasSpoofMethod('PUT'):

Arbitrary attributes are supported too, including via magic methods:

Inputs, textareas, and buttons

You can also assert on arbitrary children, or their absence:

Asserting on selects

findSelect() takes a selector and a closure that receives an AssertSelect instance. Assert on the select's own attributes:

Assert on its options. Check one at a time with containsOption(), or several at once with containsOptions():

Assert on the selected value, or on multiple selected values for a multi-select:

Asserting on datalists

Datalists work like selects via findDatalist(), which provides an AssertDatalist instance. The selector must be either datalist or an id such as #skills:

Asserting on text

containsText() and doesntContainText() assert against an element's text content:

For the common case of asserting a single element contains some text, assertElementContainsText() is a shorthand that skips the closure:

It selects the element (failing if the selector matches nothing), asserts its text contains the needle, and returns the response so calls can be chained. It takes the same $ignoreCase and $normalizeWhitespace arguments as containsText():

assertElementContainsNormalizedText() is the same shorthand with whitespace normalisation always on, regardless of the config value:

Whitespace normalisation

By default these comparisons match text exactly as it appears in the DOM. Templates often introduce a lot of incidental whitespace, such as indented Blade, multi-line content, or \r\n line endings, so you can collapse and trim it instead.

Enable it for a single call:

Or use the dedicated methods, which always normalise regardless of the config value:

Enable it globally from TestCase::setUp() or AppServiceProvider::boot():

Or publish the config file if you prefer:

This creates config/dom-assertions.php:

When normalizeWhitespace is left as null, it falls back to this config value. With the global default on, pass normalizeWhitespace: false to force strict matching for a single assertion.

Quick existence checks

For simple checks where a full closure is overkill, use assertContainsElement() and assertDoesntExist() directly on the response. assertContainsElement() optionally accepts an array of expected attributes:

When a check fails, chain ddContent() to dump the parsed page and see what was actually rendered:

[!TIP] These methods are shared across the response, view, and component macros, so they are available anywhere this package can be used.

Usage with Livewire

Livewire's testing helpers return Laravel's TestResponse, so everything works without any changes:

Usage with Blade views and components

Test a Blade view directly:

Or a Blade component:

Wrapping partial output

Form element components sometimes render a fragment. An <x-select> renders <option> tags with no surrounding <select>. wrap() supplies the missing parent so assertSelect() and assertForm() can be used:

Pass an array as the second argument to give the wrapping element attributes:

Attribute names may use Alpine and Livewire syntax such as wire:model.live, x-on:click and :bound, but not the @click shorthand — @ is not valid in a parsed attribute name, so wrap() rejects it rather than silently dropping it. Use x-on:click instead.

Calls nest, and wrap() is available on responses and views too. It returns a TestHtml, which carries the same assertions — you can also build one directly from any html string with TestHtml::make($html).

Method reference

Element methods (AssertElement)

Form methods (AssertForm)

All AssertElement methods are also available on forms.

Select methods (AssertSelect)

Rector rules

This package ships Rector rules to keep your assertions consistent as the package evolves.

Register a rule in your rector.php:

AssertElementToAssertContainsElementRule

Converts assertElement() calls whose closures only use find, contains, containsText, or has into flat assertContainsElement() chains:

Testing this package

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• René Sinnbeck
• Jack Bayliss
• All Contributors

License

The MIT License (MIT). Please see License File for more information.