PHPUnit Markup Assertions

This library introduces the MarkupAssertionsTrait trait for use in PHPUnit tests.

These assertions enable you to inspect generated markup without having to muddy tests with DOMDocument or nasty regular expressions. If you're generating markup at all with PHP, the PHPUnit Markup Assertions trait aims to make the output testable without making your tests fragile.

Example

use PHPUnit\Framework\TestCase;
use SteveGrunwell\PHPUnit_Markup_Assertions\MarkupAssertionsTrait;

class MyUnitTest extends TestCase
{
    use MarkupAssertionsTrait;

    /**
     * Ensure the #first-name and #last-name selectors are present in the form.
     */
    public function testRenderFormContainsInputs()
    {
        $markup = render_form();

        $this->assertContainsSelector('#first-name', $markup);
        $this->assertContainsSelector('#last-name', $markup);
    }
}

Installation

To add PHPUnit Markup Assertions to your project, first install the library via Composer:

$ composer require --dev stevegrunwell/phpunit-markup-assertions

Next, import the SteveGrunwell\PHPUnit_Markup_Assertions\MarkupAssertionsTrait trait into each test case that will leverage the assertions:

use PHPUnit\Framework\TestCase;
use SteveGrunwell\PHPUnit_Markup_Assertions\MarkupAssertionsTrait;

class MyTestCase extends TestCase
{
    use MarkupAssertionsTrait;
}

Making PHPUnit Markup Assertions available globally

If you'd like the methods to be available across your entire test suite, you might consider sub-classing the PHPUnit test case and applying the trait there:

# tests/TestCase.php

namespace Tests;

use PHPUnit\Framework\TestCase as BaseTestCase;
use SteveGrunwell\PHPUnit_Markup_Assertions\MarkupAssertionsTrait;

class TestCase extends BaseTestCase
{
    use MarkupAssertionsTrait;
}

Then update your other test cases to use your new base:

# tests/Unit/ExampleTest.php

namespace Tests/Unit;

use Tests\TestCase;

class MyUnitTest extends TestCase
{
    // This class now automatically has markup assertions.
}

Available methods

These are the assertions made available to PHPUnit via the MarkupAssertionsTrait.

• assertContainsSelector()
• assertNotContainsSelector()
• assertSelectorCount()
• assertHasElementWithAttributes()
• assertNotHasElementWithAttributes()
• assertElementContains()
• assertElementNotContains()
• assertElementRegExp()
• assertElementNotRegExp()

assertContainsSelector()

Assert that the given string contains an element matching the given selector.

(string) $selector

A query selector for the element to find.

(string) $markup

The markup that should contain the $selector.

(string) $message

A message to display if the assertion fails.

Example

public function testBodyContainsImage()
{
    $body = getPageBody();

    $this->assertContainsSelector('img', $body, 'Did not find an image in the page body.');
}

assertNotContainsSelector()

Assert that the given string does not contain an element matching the given selector.

This method is the inverse of assertContainsSelector().

(string) $selector

A query selector for the element to find.

(string) $markup

The markup that should not contain the $selector.

(string) $message

A message to display if the assertion fails.

assertSelectorCount()

Assert the number of times an element matching the given selector is found.

(int) $count

The number of matching elements expected.

(string) $selector

A query selector for the element to find.

(string) $markup

The markup to run the assertion against.

(string) $message

A message to display if the assertion fails.

Example

public function testPostList()
{
    factory(Post::class, 10)->create();

    $response = $this->get('/posts');

    $this->assertSelectorCount(10, 'li.post-item', $response->getBody());
}

assertHasElementWithAttributes()

Assert that an element with the given attributes exists in the given markup.

(array) $attributes

An array of HTML attributes that should be found on the element.

(string) $markup

The markup that should contain an element with the provided $attributes.

(string) $message

A message to display if the assertion fails.

Example

public function testExpectedInputsArePresent()
{
    $user = getUser();
    $form = getFormMarkup();

    $this->assertHasElementWithAttributes(
        [
            'name' => 'first-name',
            'value' => $user->first_name,
        ],
        $form,
        'Did not find the expected input for the user first name.'
    );
}

assertNotHasElementWithAttributes()

Assert that an element with the given attributes does not exist in the given markup.

(array) $attributes

An array of HTML attributes that should not be found on the element.

(string) $markup

The markup that should not contain an element with the provided $attributes.

(string) $message

A message to display if the assertion fails.

assertElementContains()

Assert that the element with the given selector contains a string.

(string) $contents

The string to look for within the DOM node's contents.

(string) $selector

A query selector for the element to find.

(string) $markup

The markup that should contain the $selector.

(string) $message

A message to display if the assertion fails.

Example

public function testColumnShowsUserEmail()
{
    $user = getUser();
    $table = getTableMarkup();

    $this->assertElementContains(
        $user->email,
        'td.email',
        $table,
        'The <td class="email"> should contain the user\'s email address.'
    );
}

assertElementNotContains()

Assert that the element with the given selector does not contain a string.

This method is the inverse of assertElementContains().

(string) $contents

The string to look for within the DOM node's contents.

(string) $selector

A query selector for the element to find.

(string) $markup

The markup that should contain the $selector.

(string) $message

A message to display if the assertion fails.

assertElementRegExp()

Assert that the element with the given selector contains a string.

This method works just like assertElementContains(), but uses regular expressions instead of simple string matching.

(string) $regexp

The regular expression pattern to look for within the DOM node.

(string) $selector

A query selector for the element to find.

(string) $markup

The markup that should contain the $selector.

(string) $message

A message to display if the assertion fails.

assertElementNotRegExp()

Assert that the element with the given selector does not contain a string.

This method is the inverse of assertElementRegExp() and behaves like assertElementNotContains() except with regular expressions instead of simple string matching.

(string) $regexp

The regular expression pattern to look for within the DOM node.

(string) $selector

A query selector for the element to find.

(string) $markup

The markup that should contain the $selector.

(string) $message

A message to display if the assertion fails.