JSON assertions for PHPUnit

Author and copyright

Martin Helmich [email protected]
This library is MIT-licensed.

Installation

$ composer require --dev helmich/phpunit-json-assert

Compatibility notice: Version 1 (the v1 branch) of this library is compatible with PHPUnit 4.8 to 5. Version 2 (the master branch) is compatible with PHPUnit 6 and later. When using composer require, Composer should automatically pick the correct version for you.

Usage

Simply use the trait Helmich\JsonAssert\JsonAssertions in your test case. This trait offers a set of new assert* functions that you can use in your test cases:

<?php
use Helmich\JsonAssert\JsonAssertions;
use PHPUnit\Framework\TestCase;

class MyTestCase extends TestCase
{
  use JsonAssertions;

  public function testJsonDocumentIsValid()
  {
    $jsonDocument = [
      'id'          => 1000,
      'username'    => 'mhelmich',
      'given_name'  => 'Martin',
      'family_name' => 'Helmich',
      'age'         => 27,
      'hobbies'     => [
        "Heavy Metal",
        "Science Fiction",
        "Open Source Software"
      ]
    ];

    $this->assertJsonValueEquals($jsonDocument, '$.username', 'mhelmich');
    $this->assertJsonValueEquals($jsonDocument, '$.hobbies[*]', 'Open Source Software');
  }
}

Most assertions take a $jsonPath argument which may contain any kind of expression supported by the JSONPath library.

Alternatively, you can use the functional interface by including the file src/Functions.php into your test cases:

<?php
use Helmich\JsonAssert\JsonAssertions;
use PHPUnit\Framework\TestCase;

require_once('path/to/Functions.php');

class MyTestCase extends TestCase
{
  use JsonAssertions;

  public function testJsonDocumentIsValid()
  {
    $jsonDocument = [
      'id'          => 1000,
      'username'    => 'mhelmich',
      'given_name'  => 'Martin',
      'family_name' => 'Helmich',
      'age'         => 27,
      'hobbies'     => [
        "Heavy Metal",
        "Science Fiction",
        "Open Source Software"
      ]
    ];

    assertThat($jsonDocument, containsJsonValue('$.username', 'mhelmich'));
    assertThat($jsonDocument, matchesJsonConstraints([
        '$.given_name' => 'Martin',
        '$.age'        => greaterThanOrEqual(18),
        '$.hobbies'    => callback(function($a) { return count($a) > 2; })
    ]));
  }
}

Assertion reference

assertJsonValueEquals($doc, $jsonPath, $expected)

Asserts that the JSON value found in $doc at JSON path $jsonPath is equal to $expected.

assertJsonValueMatches($doc, $jsonPath, PHPUnit_Framework_Constraint $constraint)

Asserts that the JSON value found in $doc at JSON path $jsonPath matches the constraint $constraint.

Example:

$this->assertJsonValueMatches(
  $jsonDocument,
  '$.age',
  PHPUnit_Framework_Assert::greaterThanOrEqual(18)
);

assertJsonDocumentMatches($doc, $constraints)

Asserts that a variable number of JSON values match a constraint. $constraints is a key-value array in which JSON path expressions are used as keys to a constraint value.

Example:

$this->assertJsonDocumentMatches($jsonDocument, [
    '$.username' => 'mhelmich',
    '$.age'      => PHPUnit_Framework_Assert::greaterThanOrEqual(18)
]);

assertJsonDocumentMatchesSchema($doc, $schema)

Assert that a given JSON document matches a certain JSON schema.

Example:

$this->assertJsonDocumentMatchesSchema($jsonDocument, [
    'type'       => 'object',
    'required'   => ['username', 'age'],
    'properties' => [
        'username' => ['type' => 'string', 'minLength' => 3],
        'age'      => ['type' => 'number']
    ]
]);