mkrogemann/poller-json

An extension of poller offering JSON matchers

poller-json

An extension of poller offering JSON matchers. Please consult the poller README before trying to use this gem to make the experience as smooth as possible.

Installation

The gem can be installed in the usual ways. Either let bundler take care of it and add to your Gemfile like this:

gem 'poller-json'

Or install it directly on your command line

gem install poller-json

Usage

In order to familiarize yourself with the underlying poller gem, check out its README and its Wiki.

Complementary to this section, there is also a Wiki page that has specific information about this gem (the poller-json rubygem) with more Usage Examples.

Here is one simple four-step example of how to make use of poller-json:

require 'poller/poller_json'

json_object = '{"value": "Close", "onclick": "CloseDoc()"}'
# this example specifies expected json object as a String
# alternatively, pass the expected object in as a Hash as produced by ::JSON.parse()

matcher = Matchers::JSON::JSONPathHasObject.new('$menu.popup.menuitem[2]', json_object)

poller = Poller::HTTP::HttpPoller.new('http://your.sut.example.com', matcher, 5.0, 1.0)
#  timeout 5s, poll every 1s

poller.check

In the example above, the expected JSON Object is passed into the matcher as a String.

Since a JSON Object is parsed into a Ruby Hash by the JSON::parse method, you can also pass in the expected object as a Ruby Hash, which you could produce comfortably in your tests by using ::JSON::parse('{...}') on String representations of your expected JSON Objects, JSON Arrays or JSON Values. More about these three fundamental concepts of JSON can be found at json.org.

Scope & Feature Requests

The gem brings with it a very limited implementation of JSONPath. The implementation is contained in the class lib/matchers/json/json_path.rb.

For the following discussion, consider this given JSON document:

{"menu": {
  "id": "file",
  "value": "File",
  "popup": {
    "menuitem": [
      {"value": "New", "onclick": "CreateNewDoc()"},
      {"value": "Open", "onclick": "OpenDoc()"},
      {"value": "Close", "onclick": "CloseDoc()"}
    ]
  }
}}

The one feature that is currently implemented is the ability to navigate along a very simple path such as those shown in these examples:

$menu.popup.menuitem[1].value

This expression applied to the above document would yield the simple value

 Open

and

$menu.popup.menuitem

would yield

[
  {"value": "New", "onclick": "CreateNewDoc()"},
  {"value": "Open", "onclick": "OpenDoc()"},
  {"value": "Close", "onclick": "CloseDoc()"}
]

The intention of this very basic JSONPath implementation is to be compatible with the JSONPath design document and thus with alternative JSONPath implementations. To simply switch to using the jsonpath rubygem is not an option right now mainly due to its missing support for Ruby 1.8.7.

The depth of the JSONPath implementation is covering all current use cases of poller-json.

As far as future development is concerned: I welcome Pull requests, proposals for additional features and bug reports.

Design

The gem has been developed to run in Ruby 1.9.3 and is today being continuously integrated in MRI 2.0.x, 2.1.x, 2.2.x, 2.3.x, 2.4.x, 2.5.x plus in JRuby 9.0.4.0.

It has become annoyingly difficult to still support 1.8.7 as well as 1.9.3 both locally and in Travis CI. The gem should still work with these MRI versions but they are no longer officially supported.

In order to provide JSON parsing capability, the gem makes use of further gems: multi_json on all platforms and json in the case of Ruby 1.8.7. Please note that the pure Ruby solution to JSON parsing, ie json_pure will work fine in case you do not want to compile any C code (the json gem makes use of native libs) or in case you have to work on a system that does not allow it (no gcc available, etc.)

Of course, another dependency is the poller gem.

It would be nice to use jsonpath to implement JSONPath based matchers but at the time of this writing, there are two issues that stop me from using it: Ruby 1.8.7 is no longer supported by jsonpath and there appear to be problems with certain characters in search expressions. Investigating