stevegrunwell / phpunit-markup-assertions
Assertions for PHPUnit to verify the presence or state of elements within markup
Fund package maintenance!
stevegrunwell
Installs: 120 675
Dependents: 5
Suggesters: 0
Security: 0
Stars: 15
Watchers: 4
Forks: 3
Open Issues: 4
Requires
- php: ^5.6 || ^7.0 || ^8.0
- laminas/laminas-dom: ~2.7.2 || ^2.8
Requires (Dev)
- symfony/phpunit-bridge: ^5.2 || ^6.2
This package is auto-updated.
Last update: 2024-10-18 10:59:12 UTC
README
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.