Download the PHP package duxet/json_spec without Composer

Json Spec

Json Spec provides set of easy-to-use matcher that should help you to validate data in JSON responses from your api with less pain.

If you working with JSON-based REST APIs there are several issues:

• You can't simply check is a response is equal to given string as there are things like server-generated IDs or keys sorting.
• Key ordering should be the same both for your API and for expected JSON.
• Matching the whole responses breaks DRY for the spec

json_spec solves this problems as it normalize JSON before match it.

Let's see simple example:

{
   "id": 1421,
   "created_at": "1977-05-25 00:00:00"
   "last_name": "Skywalker",
   "first_name": "Luke",
}
        
      

{
   "first_name": "Luke",
   "last_name": "Skywalker"
}
        
      

json_spec will assume that this JSON documents are equal. Before asserting, json_spec will exclude keys id, created_at and updated_at from response JSON (List of excluded keys is configurable). Then it will normalize JSON (reorder keys, pretty-print) and after, just check for string equality. That's all. Also you can match JSON by given path instead of describing whole response in your specification, check is JSON collection contains some record and many more.

Installation

To install json_spec you may want to use composer:

After that you should enable json_spec behat extension and optionally add context provided with json_spec in your . For example:

Usage

json_spec provides you two ways of how you can use matchers:

• Using json_spec context, which implements steps for verifying json responses. This approach best fits for cases, when developers uses feature specs as API documentation and tests.
• Inject JsonMatcherFactory into your context, so you can use it in your step definitions. This approach preferable since you can practice BDD with it. For more information about how to write feature specs please read Modeling by examples.

Using json_spec Context

json_spec provides Behat context which implements steps utilizing all matchers provided by json_matcher. This is perfect for testing your app's JSON API.

One note. json_spec should have access to responses. If you are using Mink, that it's just fine. json_spec will get responses from Mink. This means that all you need to do to start working, is just to enable MinkExtension in your behat.yml:

That's all, now json_spec have access to all responses. You may also want to use behatch:rest context from sanpii/behatch-contexts instead of mink context.

If you are using your own context, which not using Mink, then just implement interface for your context:

Now, you can use the json_spec steps in your features:

The background steps above and the "visit" steps aren't provided by json_spec. The remaining steps, json_spec provides. They're versatile and can be used in plenty of different formats:

All instances of "should" above could be followed by "not" and all instances of "JSON" could be downcased and/or followed by "response."

Table Format

Another step exists that uses Behat's table formatting and wraps two of the above steps:

Then the JSON should have the following:

Any number of rows can be given. The step above is equivalent to:

If only one column is given:

This is equivalent to:

JSON Memory

There's one more Behat step that json_spec provides which hasn't been used above. It's used to memorize JSON for reuse in later steps. You can "keep" all or a portion of the JSON by giving a name by which to remember it.

You can memorize JSON at a path:

You can remember JSON at a path:

You can also remember JSON inline:

Also starting from version 0.2.3 you can inject memory helper into your feature context to define some variables. To do so, your context should implement MemoryHelperAware interface.

More Examples

Check out the features to see all the various ways you can use json_spec.

Using json matcher in your step definitions

To inject JsonMatcherFactory you can just implement JsonMatcherAware interface in your context, or just use JsonMatcherAwareTrait:

Contributing

If you come across any issues, please tell me . Pull requests (with tests) are appreciated. No pull request is too small. Please help with:

• Reporting bugs
• Suggesting features
• Writing or improving documentation
• Fixing typos
• Cleaning whitespace
• Refactoring code
• Adding tests
• Closing issues

If you report a bug and don't include a fix, please include a failing test.

Credits

• json_spec - Ruby's gem for handling JSON in RSpec and Cucumber. This library is mainly just php port of this great library.