/phpunit-json-assertions

JSON assertions for PHPUnit (including JSON Schema)

Primary LanguagePHPMIT LicenseMIT

phpunit-json-assertions

Latest Stable Version Total Downloads Test StyleCI Average time to resolve an issue Percentage of issues still open

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 EnricoStahn\JsonAssert\Tests;

use EnricoStahn\JsonAssert\Assert 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 EnricoStahn\JsonAssert\Tests;

use EnricoStahn\JsonAssert\AssertClass 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 EnricoStahn\JsonAssert\Tests;

use EnricoStahn\JsonAssert\AssertClass 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 EnricoStahn\JsonAssert\Extension\Symfony allows to pass in the actual response object generated by the symfony framework and takes care of the decoding part.

BEFORE:

use EnricoStahn\JsonAssert\Assert as JsonAssert;

// ...

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

AFTER:

use EnricoStahn\JsonAssert\Extension\Symfony as JsonAssert;

// ...

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

Tests

To run the test suite, you need composer.

$ composer install
$ bin/phpunit

Badge Mania

Build Status Scrutinizer Code Quality Code Coverage Codacy Badge Codacy Badge

Alternatives

License

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

Stargazers over time

Stargazers over time