phpunit json assertions

phpunit-json-assertions

JSON assertions for PHPUnit includes traits/methods to help validate your JSON data through various methods.

Features

• Validate your JSON data via JSON Schema
  • describes your existing data format
  • clear, human- and machine-readable documentation
  • complete structural validation, useful for
    • automated testing
    • validating client-submitted data
  • See more details here
• Access JSON data through expressions (e.g. foo.bar[3])
  • See more details here

Install

$ composer require estahn/phpunit-json-assertions --dev

or in your composer.json:

{
    "require-dev": {
        "estahn/phpunit-json-assertions": "@stable"
    }
}

Asserts

Assert	Description	Available in
assertJsonMatchesSchema	Asserts that json content is valid according to the provided schema file	All
assertJsonMatchesSchemaString	Asserts that json content is valid according to the provided schema string	All
assertJsonValueEquals	Asserts if the value retrieved with the expression equals the expected value	All
assertJsonValueEquals	Asserts if the value retrieved with the expression equals the expected value	All
assertJsonResponse	Asserts that a response is successful and of type json	Symfony

Usage

You can either use the trait or class version.

Trait

<?php

namespace EnricoStahnJsonAssertTests;

use EnricoStahnJsonAssertAssert as JsonAssert;

class MyTestCase extends PHPUnit_Framework_TestCase
{
    use JsonAssert;

    public function testJsonDocumentIsValid()
    {
        // my-schema.json
        //
        // {
        //   "type" : "object",
        //   "properties" : {
        //     "foo" : {
        //       "type" : "integer"
        //     }
        //   },
        //   "required" : [ "foo" ]
        // }

        $json = json_decode('{"foo":1}');

        $this->assertJsonMatchesSchema($json, './my-schema.json');
        $this->assertJsonValueEquals(1, '* | [0]', $json);
    }
}

Class

In case you don't want to use the trait you can use the provided class wich extends from PHPUnit_Framework_TestCase. You can either extend your test case or use the static methods like below.

<?php

namespace EnricoStahnJsonAssertTests;

use EnricoStahnJsonAssertAssertClass as JsonAssert;

class MyTestCase extends PHPUnit_Framework_TestCase
{
    public function testJsonDocumentIsValid()
    {
        // my-schema.json
        //
        // {
        //   "type" : "object",
        //   "properties" : {
        //     "foo" : {
        //       "type" : "integer"
        //     }
        //   },
        //   "required" : [ "foo" ]
        // }

        $json = json_decode('{"foo":1}');

        JsonAssert::assertJsonMatchesSchema($json, './my-schema.json');
        JsonAssert::assertJsonValueEquals(1, '* | [0]', $json);
    }
}

Schema storage

The schema storage of justinrainbow/json-schema allows to register schemas which will effectively override the actual schema location.

Example:

{"$ref" : "https://iglu.foobar.com/myschema.json#/definitions/positiveInteger"}

The resolver will fetch the schema from this endpoint and match the JSON document against it. Using schema storage you're able to override this behaviour.

$schemastorage->addSchema('https://iglu.foobar.com/myschema.json', (object)['type' => 'string']);

With this in place the resolver will take the schema that is already in place without downloading it again.

<?php

namespace EnricoStahnJsonAssertTests;

use EnricoStahnJsonAssertAssertClass as JsonAssert;

class MyTestCase extends PHPUnit_Framework_TestCase
{
    public function setUp()
    {
        self::$schemaStorage = new SchemaStorage();
        
        self::$schemaStorage->addSchema('<id>', obj);
        ...
    }
    
    public function testJsonDocumentIsValid()
    {
        // my-schema.json
        //
        // {
        //   "type" : "object",
        //   "properties" : {
        //     "foo" : {
        //       "type" : "integer"
        //     }
        //   },
        //   "required" : [ "foo" ]
        // }

        $json = json_decode('{"foo":1}');

        JsonAssert::assertJsonMatchesSchema($json, './my-schema.json');
        JsonAssert::assertJsonValueEquals(1, '* | [0]', $json);
    }
}

Extensions

phpunit-json-assertions provides extensions for simpler handling in different use cases.

Symfony HttpFoundation Component

The extension EnricoStahnJsonAssertExtensionSymfony allows to pass in the actual response object generated by the symfony framework and takes care of the decoding part.

BEFORE:

use EnricoStahnJsonAssertAssert as JsonAssert;

// ...

$content = $response->getContent();
$json = json_decode($content);
JsonAssert::assertJsonMatchesSchemaString('./my-schema.json', $json);

AFTER:

use EnricoStahnJsonAssertExtensionSymfony as JsonAssert;

// ...

JsonAssert::assertJsonMatchesSchemaString('./my-schema.json', $response);

Tests

To run the test suite, you need composer.

$ composer install
$ bin/phpunit

Badge Mania

Alternatives

• https://github.com/martin-helmich/phpunit-json-assert - Doesn't support JSON Schema and uses JSONPath instead of jmespath.php

License

The phpunit-json-assertions library is licensed under the MIT.

Stargazers over time