https://github.com/thomasweinert/phpunit-xpath-assertions
Xpath based assertions for PHPUnit
https://github.com/thomasweinert/phpunit-xpath-assertions
dom php phpunit xml xpath
Last synced: 20 days ago
JSON representation
Xpath based assertions for PHPUnit
- Host: GitHub
- URL: https://github.com/thomasweinert/phpunit-xpath-assertions
- Owner: ThomasWeinert
- License: other
- Created: 2017-10-14T08:33:11.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-12-13T13:25:06.000Z (over 1 year ago)
- Last Synced: 2025-04-12T01:17:06.823Z (12 months ago)
- Topics: dom, php, phpunit, xml, xpath
- Language: PHP
- Size: 83 KB
- Stars: 14
- Watchers: 3
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# phpunit-xpath-assertions
[](https://github.com/ThomasWeinert/phpunit-xpath-assertions/actions/workflows/ci.yml)
[](https://github.com/thomasweinert/phpunit-xpath-assertions/blob/master/LICENSE)
[](https://packagist.org/packages/thomasweinert/phpunit-xpath-assertions)
[](https://packagist.org/packages/thomasweinert/phpunit-xpath-assertions)
Xpath assertions and constraints for use with PHPUnit.
## Example
```php
use PHPUnit\Framework\TestCase;
use PHPUnit\Xpath\AssertTrait as XpathAssertions;
class MyProjectExampleTest extends TestCase
{
use XpathAssertions;
public function testChildElementExistsInDocument()
{
$document = new \DOMDocument();
$document->loadXML('TEXT');
self::assertXpathMatch('//child', $document);
}
public function testCompareChildElementFromDocument()
{
$document = new \DOMDocument();
$document->loadXML('TEXT');
self::assertXpathEquals('TEXT', '//child', $document);
}
}
```
## Installation
### Composer
If you use [Composer](https://getcomposer.org/) to manage the dependencies of your project then you can add the PHPUnit example extension as a development-time dependency to your project:
```
$ composer require --dev thomasweinert/phpunit-xpath-assertions
```
## Usage
The library provides traits that you can use to add the assertions to your TestCase.
```php
use PHPUnit\Xpath\AssertTrait as XpathAssertions;
use PHPUnit\Xpath\ConstraintTrait as XpathConstraints;
class MyProjectExampleTest extends \PHPUnit\Framework\TestCase
{
use XpathAssertions;
use XpathConstraints;
}
```
### Constraints
Use trait `PHPUnit\Xpath\ConstraintTrait`. They can be used with `assertThat()` or
with Mocks.
#### self::matchesXpathExpression()
```php
function matchesXpathExpression(string $expression, array|\ArrayAccess $namespaces = [])
```
Validate if the provided Xpath expression matches something that is TRUE and not empty.
It will fail if the expression returns an empty node list or an empty string or FALSE.
```php
public function testChildElementExistsInDocument()
{
$document = new \DOMDocument();
$document->loadXML('TEXT');
self::assertThat(
$document,
self::matchesXpathExpression('//child')
);
}
```
#### self::matchesXpathResultCount()
```php
function matchesXpathResultCount(
int $expectedCount, string $expression, array|\ArrayAccess $namespaces = array()
)
```
Returns true if the provided Xpath expression matches exactly the expected count of nodes.
```php
public function testChildElementExistsOnTimeInDocument()
{
$document = new \DOMDocument();
$document->loadXML('TEXT');
self::assertThat(
$document,
self::matchesXpathResultCount(1, '//child')
);
}
```
#### self::equalToXpathResult()
```php
function equalToXpathResult(
mixed $expected,
string $expression,
array|\ArrayAccess,
$namespaces = array()
)
```
If the expressions return a node list it compares the serialized XML of the matched nodes with the provided XML string
or DOM. If the expression return a scalar uses a constraint depending on the type.
```php
public function testCompareChildElementFromDocument()
{
$document = new \DOMDocument();
$document->loadXML('TEXT');
self::assertThat(
$document,
self::equalToXpathResult(
'TEXT',
'//child'
)
);
}
```
```php
public function testCompareChildElementFromDocumentAsString()
{
$document = new \DOMDocument();
$document->loadXML('TEXT');
self::assertThat(
$document,
self::equalToXpathResult(
'TEXT',
'string(//child)'
)
);
}
```
### Assertions
Use trait `PHPUnit\Xpath\AssertTrait`. These assertions are shortcuts for
`assertThat()`.
* self::assertXpathMatch()
* self::assertXpathCount()
* self::assertXpathEquals()
### Namespaces
All methods have an optional argument that allow to provide an namespace definition.
```php
public function testChildWithNamespaceElementExistsTwoTimesInDocument()
{
$document = new \DOMDocument();
$document->loadXML(
'
TEXT
TEXT
'
);
self::assertThat(
$document,
self::matchesXpathResultCount(2, '//e:child', ['e' => 'urn:example'])
);
}
```
### JSON (>= 1.2.0)
The assertions can be used with JsonSerializable objects/arrays. They will be
converted into a DOM representation internally.
```php
public function testHomePhoneNumbersEqualsExpected()
{
self::assertXpathEquals(
[
[ 'type' => 'home', 'number' => '212 555-1234' ]
],
'phoneNumbers/*[type="home"]',
json_decode($wikipediaJsonExample)
);
}
```
# Contributing
Contributions are welcome, please use the issue tracker to report bug and feature ideas.