PHPackages                             thomasweinert/phpunit-xpath-assertions - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. thomasweinert/phpunit-xpath-assertions

ActiveLibrary[Testing & Quality](/categories/testing)

thomasweinert/phpunit-xpath-assertions
======================================

Xpath assertions and constraints for PHPUnit

v4.1.0(6mo ago)1424.3k4[1 issues](https://github.com/ThomasWeinert/phpunit-xpath-assertions/issues)5BSD-3-ClausePHPPHP ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0CI passing

Since Oct 14Pushed 6mo ago2 watchersCompare

[ Source](https://github.com/ThomasWeinert/phpunit-xpath-assertions)[ Packagist](https://packagist.org/packages/thomasweinert/phpunit-xpath-assertions)[ RSS](/packages/thomasweinert-phpunit-xpath-assertions/feed)WikiDiscussions master Synced today

READMEChangelog (8)Dependencies (4)Versions (10)Used By (5)

phpunit-xpath-assertions
========================

[](#phpunit-xpath-assertions)

[![CI](https://github.com/ThomasWeinert/phpunit-xpath-assertions/actions/workflows/ci.yml/badge.svg)](https://github.com/ThomasWeinert/phpunit-xpath-assertions/actions/workflows/ci.yml)[![License](https://camo.githubusercontent.com/c20b6d7c5f1c737fe73ed3c6ec2488c16677596bedbfbcd6c4cb1aae869192a4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f74686f6d61737765696e6572742f706870756e69742d78706174682d617373657274696f6e732e737667)](https://github.com/thomasweinert/phpunit-xpath-assertions/blob/master/LICENSE)[![Total Downloads](https://camo.githubusercontent.com/fc693f021b5bec8de3110f9fbf8cb775e62df57c1f355d25e28f6826ede61bb2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f74686f6d61737765696e6572742f706870756e69742d78706174682d617373657274696f6e732e737667)](https://packagist.org/packages/thomasweinert/phpunit-xpath-assertions)[![Latest Stable Version](https://camo.githubusercontent.com/ecc14be844c9f0ae2784cf6a6c847a011b2b5c411f64571d6b075ebcac17bee0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74686f6d61737765696e6572742f706870756e69742d78706174682d617373657274696f6e732e737667)](https://packagist.org/packages/thomasweinert/phpunit-xpath-assertions)

Xpath assertions and constraints for use with PHPUnit.

Example
-------

[](#example)

```
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
------------

[](#installation)

### Composer

[](#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
-----

[](#usage)

The library provides traits that you can use to add the assertions to your TestCase.

```
use PHPUnit\Xpath\AssertTrait as XpathAssertions;
use PHPUnit\Xpath\ConstraintTrait as XpathConstraints;

class MyProjectExampleTest extends \PHPUnit\Framework\TestCase
{
    use XpathAssertions;
    use XpathConstraints;
}
```

### Constraints

[](#constraints)

Use trait `PHPUnit\Xpath\ConstraintTrait`. They can be used with `assertThat()` or with Mocks.

#### self::matchesXpathExpression()

[](#selfmatchesxpathexpression)

```
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.

```
public function testChildElementExistsInDocument()
{
    $document = new \DOMDocument();
    $document->loadXML('TEXT');

    self::assertThat(
        $document,
        self::matchesXpathExpression('//child')
    );
}
```

#### self::matchesXpathResultCount()

[](#selfmatchesxpathresultcount)

```
function matchesXpathResultCount(
    int $expectedCount, string $expression, array|\ArrayAccess $namespaces = array()
)
```

Returns true if the provided Xpath expression matches exactly the expected count of nodes.

```
public function testChildElementExistsOnTimeInDocument()
{
    $document = new \DOMDocument();
    $document->loadXML('TEXT');

    self::assertThat(
        $document,
        self::matchesXpathResultCount(1, '//child')
    );
}
```

#### self::equalToXpathResult()

[](#selfequaltoxpathresult)

```
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.

```
public function testCompareChildElementFromDocument()
{
    $document = new \DOMDocument();
    $document->loadXML('TEXT');

    self::assertThat(
        $document,
        self::equalToXpathResult(
            'TEXT',
            '//child'
        )
    );
}
```

```
public function testCompareChildElementFromDocumentAsString()
{
    $document = new \DOMDocument();
    $document->loadXML('TEXT');

    self::assertThat(
        $document,
        self::equalToXpathResult(
            'TEXT',
            'string(//child)'
        )
    );
}
```

### Assertions

[](#assertions)

Use trait `PHPUnit\Xpath\AssertTrait`. These assertions are shortcuts for `assertThat()`.

- self::assertXpathMatch()
- self::assertXpathCount()
- self::assertXpathEquals()

### Namespaces

[](#namespaces)

All methods have an optional argument that allow to provide an namespace definition.

```
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)

[](#json--120)

The assertions can be used with JsonSerializable objects/arrays. They will be converted into a DOM representation internally.

```
public function testHomePhoneNumbersEqualsExpected()
{
    self::assertXpathEquals(
        [
            [ 'type' => 'home', 'number' => '212 555-1234' ]
        ],
        'phoneNumbers/*[type="home"]',
        json_decode($wikipediaJsonExample)
    );
}
```

Contributing
============

[](#contributing)

Contributions are welcome, please use the issue tracker to report bug and feature ideas.

###  Health Score

55

—

FairBetter than 97% of packages

Maintenance64

Regular maintenance activity

Popularity33

Limited adoption so far

Community21

Small or concentrated contributor base

Maturity86

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 60% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~425 days

Recently: every ~741 days

Total

8

Last Release

206d ago

Major Versions

1.1.0 → 2.0.02018-03-03

2.0.0 → 3.0.02021-12-03

3.0.0 → v4.0.02025-11-26

PHP version history (4 changes)1.0.0PHP ^7.1

3.0.0PHP ^7.4 || ~8.0.0

v4.0.0PHP ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0

v4.1.0PHP ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/236825?v=4)[Thomas Weinert](/maintainers/ThomasWeinert)[@ThomasWeinert](https://github.com/ThomasWeinert)

---

Top Contributors

[![ThomasWeinert](https://avatars.githubusercontent.com/u/236825?v=4)](https://github.com/ThomasWeinert "ThomasWeinert (48 commits)")[![fabiang](https://avatars.githubusercontent.com/u/348344?v=4)](https://github.com/fabiang "fabiang (25 commits)")[![sebastianbergmann](https://avatars.githubusercontent.com/u/25218?v=4)](https://github.com/sebastianbergmann "sebastianbergmann (5 commits)")[![thewilkybarkid](https://avatars.githubusercontent.com/u/1784740?v=4)](https://github.com/thewilkybarkid "thewilkybarkid (2 commits)")

---

Tags

domphpphpunitxmlxpath

###  Code Quality

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/thomasweinert-phpunit-xpath-assertions/health.svg)

```
[![Health](https://phpackages.com/badges/thomasweinert-phpunit-xpath-assertions/health.svg)](https://phpackages.com/packages/thomasweinert-phpunit-xpath-assertions)
```

###  Alternatives

[brianium/paratest

Parallel testing for PHP

2.5k136.1M985](/packages/brianium-paratest)[drupal/core-dev

require-dev dependencies from drupal/drupal; use in addition to drupal/core-recommended to run tests from drupal/core.

2022.6M343](/packages/drupal-core-dev)[webmozarts/strict-phpunit

Enables type-safe comparisons of objects in PHPUnit

30314.4k7](/packages/webmozarts-strict-phpunit)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)