{"id":16427000,"url":"https://github.com/fesor/json_matcher","last_synced_at":"2025-07-04T20:38:36.497Z","repository":{"id":23299681,"uuid":"26659038","full_name":"fesor/json_matcher","owner":"fesor","description":"Library for simplifying data verification in functional tests for your JSON-based APIs","archived":false,"fork":false,"pushed_at":"2020-04-25T20:57:07.000Z","size":90,"stargazers_count":25,"open_issues_count":3,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-16T06:51:52.562Z","etag":null,"topics":["assertion-library","assertions","json","json-matcher","json-schema","jsonpath"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fesor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-14T21:49:39.000Z","updated_at":"2023-06-15T17:24:00.000Z","dependencies_parsed_at":"2022-08-18T01:05:20.396Z","dependency_job_id":null,"html_url":"https://github.com/fesor/json_matcher","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/fesor/json_matcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fesor%2Fjson_matcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fesor%2Fjson_matcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fesor%2Fjson_matcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fesor%2Fjson_matcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fesor","download_url":"https://codeload.github.com/fesor/json_matcher/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fesor%2Fjson_matcher/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262210146,"owners_count":23275493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assertion-library","assertions","json","json-matcher","json-schema","jsonpath"],"created_at":"2024-10-11T08:11:08.161Z","updated_at":"2025-07-04T20:38:36.419Z","avatar_url":"https://github.com/fesor.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Json Matcher\n====================\n\n[![Build Status](https://travis-ci.org/fesor/json_matcher.svg?branch=master)](https://travis-ci.org/fesor/json_matcher) \n[![Latest Stable Version](https://poser.pugx.org/fesor/json_matcher/v/stable.svg)](https://packagist.org/packages/fesor/json_matcher) \n[![Latest Unstable Version](https://poser.pugx.org/fesor/json_matcher/v/unstable.svg)](https://packagist.org/packages/fesor/json_matcher) \n[![License](https://poser.pugx.org/fesor/json_matcher/license.svg)](https://packagist.org/packages/fesor/json_matcher) \n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/fesor/json_matcher/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/fesor/json_matcher/?branch=master) \n[![Total Downloads](https://poser.pugx.org/fesor/json_matcher/downloads.svg)](https://packagist.org/packages/fesor/json_matcher)\n\nAssertion library for simplifying JSON data and structure verification in your tests. It's framework-agnostic, so you can use it with PhpUnit, PhpSpec, Peridot or whatever framework you use.\n\n## Why another JSON assertion library?\n\nIf you tried to test your JSON based REST APIs, then you probably faced a several issues:\n\n- You can't simply check is a response is equal to given string as there are things like server-generated IDs and timestamps.\n- Key ordering should be the same both for your API and for expected JSON.\n- Matching the whole responses breaks DRY for the tests\n\nAll these issues can be solved with two simple things: JSON normalization and key exclusion on matching. This is what this library does. It provides you a way to verify data in given JSON in multiple steps instead of one big assertion.\n\nFor example we are developing an friend list feature for our API for. What we want to check is only is given user presents in response, we don't want to check whole response, it could be done via json schema validation or on another test cases.\n\n```php\n\n$alice = new User('Alice', 'Miller');\n$john = new User('John', 'Smith');\n$alice-\u003eaddFriend($john);\n\n$json = JsonMatcher::create(\n    json_encode($alice-\u003etoArrayIncludingFriends()), ['id', 'created_at']\n);\n\n```\n\nIn above example we just created an `JsonMatcher` instance and specified excluded-by-default keys (`id` and `created_at`). Excluded keys will be removed from JSON and it's values will not interfere in equality assertion. You can also override this list of keys via matching `excluding` and `including` options.\n\nThen we can check is John presents in Alice's friend list at some specific position via json paths:\n```php\n$json-\u003eequal(json_encode($john-\u003etoArray()), ['at' =\u003e 'friends/0']);\n```\n\nOr if we don't know specific position, we can just check is John just presents in our friendlist.\n```php\n$json-\u003eincludes(json_encode($john-\u003etoArray()), ['at' =\u003e 'friends']);\n```\n\nOr we can just verify is any John presents in Alice's friend list:\n```php\n$json-\u003eincludes('{\"first_name\": \"John\"}'), ['at' =\u003e 'friends']);\n```\n\n## Getting started\n\nYou can install this library via composer:\n```\ncomposer require fesor/json_matcher\n```\n\nThen you will need an `JsonMatcher` instance to be created. To do this, you can:\n\n - manually create instance with all dependencies and set subject\n - use named constructor `JsonMatcher::create` as static factory-method. It will handle all dependencies for you.\n - use JsonMatcherFactory. This is useful when you have some IoC container in your test framework (Behat for example). In this case you'll need to register this class as a service.\n\nSubject on which assertion will be preformed is setted up in matcher consturctor. If you want to reuse the same instance of matcher for every assertions, you can just change subject via `setSubject` method.\n\nExample:\n```php\n$jsonResponse = JsonMatcher::create($response-\u003egetContent());\n\n// or you can use factory instead\n$jsonResponse = $matcherFactory-\u003ecreate($response-\u003egetContent());\n\n// and there you go, for example you may use something like this \n// for your gherkin steps implementations\n$jsonResponse\n    -\u003ehasSize(1, ['at' =\u003e 'friends']) // checks that list of friends was incremented\n    -\u003eincludes($friend, ['at' =\u003e 'friends']) // checks that correct record contained in collection\n;\n```\n\nYou can provide list of excluded-by-default keys as second argument in constructors:\n```php\n$matcher = JsonMatcher::create($subject, ['id', 'created_at']);\n```\n\nPlease note, that `id` key will be ignored by default.\n\n## Matchers\n\nAll matchers are supports fluent interface, negative matching and some options. See detailed description for more information about what options each matcher has.\n\n### equal\nThis is most commonly used matcher. You take two json strings and compare them. Except that before compassion this matcher will normalize structure of both JSON strings, reorder keys, exclude some of them (this is configurable) and then will simply assert that both strings are equal. You can specify list of excluded keys with `excluding` options:\n```php\n$actualJson = '[\"id\": 1, \"json\": \"spec\"]';\n$expectedJson = '[\"json\": \"spec\"]';\n$matcher\n    -\u003esetSubject($actualJson)\n    -\u003eequal($expectedJson, ['excluding' =\u003e ['id']])\n;\n```\n\nIf you have some keys, which contains some time dependent value of some server-generated IDs it is more convenient to specify list of excluded-by-default keys when you construct matcher object:\n```php\n$matcher = JsonMatcher::create($subject, ['id', 'created_at', 'updated_at']);\n```\n\nIf you want the values for these keys to be taken into account during the matching, you can specify list of included keys with `including` options\n```php\n$matcher = JsonMatcher::create($response-\u003egetContent(), ['id', 'created_at', 'updated_at']);\n$jsonResponseSubject-\u003eequal($expectedJson, ['including' =\u003e ['id']]);\n```\n\nAlso you can specify json path on which matching should be done via `at` options. We will back to this later since all matchers supports this option.\n\n### includes\nThis matcher works a little different from `equal` matcher. What it does is recursively scan subject JSON and tries to find any inclusions of JSON subset. This is useful for cases when you checking that some record exists in collection and you do not know or don't want to know specific path to it.\n\n```php\n$json = \u003c\u003c\u003cJSON\n{\n    \"id\": 1,\n    \"name\": \"Foo\",\n    \"collection\": [\n        {\"id\": 1, \"name\": \"Foo\"},\n        {\"id\": 2, \"name\": \"Bar\"},\n    ]\n}\nJSON;\n\n$matcher\n    -\u003esetSubject($json)\n    // check for value inclusion\n    -\u003eincludes('\"Foo\"')\n    // checks is json subset presents in any item of collection\n    -\u003eincludes('{\"name\": \"Bar\"}', ['at' =\u003e 'collection'])\n    // checks is json presents in collection\n    -\u003eincludes('{\"name\": \"Bar\", \"value\": \"FooBar\"}', ['at' =\u003e 'collection'])\n;\n```\n\nSince this matcher works the same way as `equal` matcher, it accepts same options.\n\n### hasPath\nThis matcher checks if given JSON have specific path ot not.\n\n```php\n$json = \u003c\u003c\u003cJSON\n{\n    \"collection\": [\n        \"json\",\n        \"matcher\"\n    ]\n}\nJSON;\n\n$matcher\n    -\u003esetSubject($json)\n    -\u003ehasPath('collection/1')\n;\n```\n\n### hasSize\nThis matcher checks is collection in given JSON contains specific amount of entities.\n\n```php\n$json = \u003c\u003c\u003cJSON\n{\n    \"collection\": [\n        \"json\",\n        \"matcher\"\n    ]\n}\nJSON;\n\n$matcher\n    -\u003esetSubject($json)\n    -\u003ehasSize(2, ['at' =\u003e 'collection'])\n;\n```\n\n### hasType\n```php\n$json = \u003c\u003c\u003cJSON\n{\n    \"collection\": [\n        {},\n        \"json\",\n        42,\n        13.45\n    ]\n}\nJSON;\n\n$matcher\n    -\u003esetSubject($json)\n    -\u003ehasType('array', ['at' =\u003e 'collection'])\n    -\u003ehasType('object', ['at' =\u003e 'collection/0'])\n    -\u003ehasType('string', ['at' =\u003e 'collection/1'])\n    -\u003ehasType('integer', ['at' =\u003e 'collection/2'])\n    -\u003ehasType('float', ['at' =\u003e 'collection/3'])\n;\n```\n\n### Negative matching\nTo invert expectations just call matcher methods with `not` prefix:\n```php\n$matcher\n    -\u003esetSubject($json)\n    -\u003enotEqual($expected)\n    -\u003enotIncludes($part)\n;\n```\n\n### Json Path\nAlso all methods have option, which specifies path which should be performed matching. For example:\n\n```php\n$actual = \u003c\u003c\u003cJSON\n{\n    \"collection\": [\n        \"item\"\n    ]\n}\nJSON;\n$expected = '\"item\"';\nJsonMatcher::create($actual)\n    -\u003eequal($expected, ['at' =\u003e 'collection/0'])\n;\n```\n## Contribution\nPlease welcome to contribute! \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffesor%2Fjson_matcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffesor%2Fjson_matcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffesor%2Fjson_matcher/lists"}