PHPackages                             jroszkiewicz/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. jroszkiewicz/phpunit-xpath-assertions

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

jroszkiewicz/phpunit-xpath-assertions
=====================================

Xpath assertions and constraints for PHPUnit

3.1.0(3y ago)06.6k↓33.3%BSD-3-ClausePHPPHP ^7.3|^8.0

Since Oct 14Pushed 3y agoCompare

[ Source](https://github.com/jroszkiewicz/phpunit-xpath-assertions)[ Packagist](https://packagist.org/packages/jroszkiewicz/phpunit-xpath-assertions)[ RSS](/packages/jroszkiewicz-phpunit-xpath-assertions/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (10)Used By (0)

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

[](#phpunit-xpath-assertions)

[![Build Status](https://camo.githubusercontent.com/338f273f7374c9f85d1083cc8b0102d71e9fcc8aa14f84689de7b4a6f34c874c/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6a726f737a6b69657769637a2f706870756e69742d78706174682d617373657274696f6e732e737667)](https://travis-ci.com/jroszkiewicz/phpunit-xpath-assertions)

[![License](https://camo.githubusercontent.com/048cd94851a96202c902318d580e5fe4b80b0a1843eaf3083758ed96ebbad931/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6a726f737a6b69657769637a2f706870756e69742d78706174682d617373657274696f6e732e737667)](https://github.com/jroszkiewicz/phpunit-xpath-assertions/blob/master/LICENSE)[![Total Downloads](https://camo.githubusercontent.com/643974d75beb14378b973a2fbe5787d7c7eafc6f2d5467a9d2e819cf6aba0444/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a726f737a6b69657769637a2f706870756e69742d78706174682d617373657274696f6e732e737667)](https://packagist.org/packages/jroszkiewicz/phpunit-xpath-assertions)[![Latest Stable Version](https://camo.githubusercontent.com/58ca2a52bfe97d2805a88be47ec6671482d1bcc82cb50965da47691792fcd978/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a726f737a6b69657769637a2f706870756e69742d78706174682d617373657274696f6e732e737667)](https://packagist.org/packages/jroszkiewicz/phpunit-xpath-assertions)

Xpath assertions and constraints for use with PHPUnit.

Example
-------

[](#example)

```
use PHPUnit\Framework\TestCase;
use PHPUnit\Xpath\Assert 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)

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 jroszkiewicz/phpunit-xpath-assertions

```

Usage
-----

[](#usage)

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

```
use PHPUnit\Xpath\Assert as XpathAssertions;
use PHPUnit\Xpath\Constraint as XpathConstraints;

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

### Constraints

[](#constraints)

Use trait `PHPUnit\Xpath\Constraint`. 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\Assert`. 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

35

—

LowBetter than 80% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity22

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity74

Established project with proven stability

 Bus Factor1

Top contributor holds 81.6% 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 ~327 days

Recently: every ~491 days

Total

7

Last Release

1164d ago

Major Versions

1.1.0 → 2.0.02018-03-03

2.0.0 → 3.0.02021-08-10

PHP version history (2 changes)1.0.0PHP ^7.1

3.0.0PHP ^7.3|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a5eda0ea76c039a15c99f60bda898bbeec9d55fec934633e8a16b97de296bef?d=identicon)[roszkiewiczjakub](/maintainers/roszkiewiczjakub)

---

Top Contributors

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

### Embed Badge

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

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

###  Alternatives

[orchestra/testbench

Laravel Testing Helper for Packages Development

2.2k39.1M32.0k](/packages/orchestra-testbench)[timacdonald/log-fake

A drop in fake logger for testing with the Laravel framework.

4235.9M54](/packages/timacdonald-log-fake)[jasonmccreary/laravel-test-assertions

A set of helpful assertions when testing Laravel applications.

3513.9M32](/packages/jasonmccreary-laravel-test-assertions)[ergebnis/phpunit-slow-test-detector

Provides facilities for detecting slow tests in phpunit/phpunit.

1468.1M72](/packages/ergebnis-phpunit-slow-test-detector)[typo3/testing-framework

The TYPO3 testing framework provides base classes for unit, functional and acceptance testing.

675.0M774](/packages/typo3-testing-framework)[robiningelbrecht/phpunit-pretty-print

Prettify PHPUnit output

76460.0k15](/packages/robiningelbrecht-phpunit-pretty-print)

PHPackages © 2026

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