Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/stevegrunwell/phpunit-markup-assertions

Assertions for PHPUnit to verify the presence or state of elements within markup
https://github.com/stevegrunwell/phpunit-markup-assertions

php phpunit testing xpath

Last synced: 24 days ago
JSON representation

Assertions for PHPUnit to verify the presence or state of elements within markup

Awesome Lists containing this project

README 

        
# PHPUnit Markup Assertions



![Build Status](https://github.com/stevegrunwell/phpunit-markup-assertions/workflows/Unit%20Tests/badge.svg)

[![Code Coverage](https://coveralls.io/repos/github/stevegrunwell/phpunit-markup-assertions/badge.svg?branch=develop)](https://coveralls.io/github/stevegrunwell/phpunit-markup-assertions?branch=develop)

[![GitHub Release](https://img.shields.io/github/release/stevegrunwell/phpunit-markup-assertions.svg)](https://github.com/stevegrunwell/phpunit-markup-assertions/releases)



This library introduces the `MarkupAssertionsTrait` trait for use in [PHPUnit](https://phpunit.de) tests.



These assertions enable you to inspect generated markup without having to muddy tests with [`DOMDocument`](http://php.net/manual/en/class.domdocument.php) 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



```php

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:



```sh

$ 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:



```php

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](https://phpunit.de/manual/current/en/extending-phpunit.html#extending-phpunit.PHPUnit_Framework_TestCase):



```php

# 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:



```php

# 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()`](#assertcontainsselector)

* [`assertNotContainsSelector()`](#assertnotcontainsselector)

* [`assertSelectorCount()`](#assertselectorcount)

* [`assertHasElementWithAttributes()`](#asserthaselementwithattributes)

* [`assertNotHasElementWithAttributes()`](#assertnothaselementwithattributes)

* [`assertElementContains()`](#assertelementcontains)

* [`assertElementNotContains()`](#assertelementnotcontains)

* [`assertElementRegExp()`](#assertelementregexp)

* [`assertElementNotRegExp()`](#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



```php

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()`](#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



```php

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



```php

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



```php

public function testColumnShowsUserEmail()

{

    $user = getUser();

    $table = getTableMarkup();



    $this->assertElementContains(

        $user->email,

        'td.email',

        $table,

        'The  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()`](#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()`](#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()`](#assertelementregexp) and behaves like [`assertElementNotContains()`](#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.