Download the PHP package fesor/json_matcher without Composer
On this page you can find all versions of the php package fesor/json_matcher. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download fesor/json_matcher
More information about fesor/json_matcher
Files in fesor/json_matcher
Package json_matcher
Short Description Collection if JSON matchers for painless usage
License MIT
Informations about the package json_matcher
Json Matcher
Assertion 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.
Why another JSON assertion library?
If you tried to test your JSON based REST APIs, then you probably faced a several issues:
- You can't simply check is a response is equal to given string as there are things like server-generated IDs and timestamps.
- Key ordering should be the same both for your API and for expected JSON.
- Matching the whole responses breaks DRY for the tests
All 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.
For 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.
In 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.
Then we can check is John presents in Alice's friend list at some specific position via json paths:
Or if we don't know specific position, we can just check is John just presents in our friendlist.
Or we can just verify is any John presents in Alice's friend list:
Getting started
You can install this library via composer:
Then you will need an JsonMatcher
instance to be created. To do this, you can:
- manually create instance with all dependencies and set subject
- use named constructor
JsonMatcher::create
as static factory-method. It will handle all dependencies for you. - 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.
Subject 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.
Example:
You can provide list of excluded-by-default keys as second argument in constructors:
Please note, that id
key will be ignored by default.
Matchers
All matchers are supports fluent interface, negative matching and some options. See detailed description for more information about what options each matcher has.
equal
This 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:
If 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:
If 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
Also 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.
includes
This 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.
Since this matcher works the same way as equal
matcher, it accepts same options.
hasPath
This matcher checks if given JSON have specific path ot not.
hasSize
This matcher checks is collection in given JSON contains specific amount of entities.
hasType
Negative matching
To invert expectations just call matcher methods with not
prefix:
Json Path
Also all methods have option, which specifies path which should be performed matching. For example:
Contribution
Please welcome to contribute!