RSpec matchers and Cucumber step definitions for testing Protocol Buffers using json_spec
Usage
RSpec
protobuf_spec currently defines two matchers:
be_protobuf_eql
have_protobuf_path
The matchers can be used as their counterparts are used in json_spec
Cucumber
protobuf_spec provides cucumber steps that use its RSpec matchers.
In order to use the Cucumber steps, in your env.rb
you must:
require "protobuf_spec/cucumber"
You will need to load the ruby_protobuf generated classes you intend to test. This can be done by generating the classes into the cucumber support/
directory, or requiring them manually.
"Should" Assertions
In order to test the contents of a Protocol Buffer, you will need to define a last_protobuf
method. This method should return the protocol buffer to be tested by a protobuf_spec Cucumber step.
For example, suppose a step that aquires a Protocol Buffer and assigns it to @my_protocol_buffer
. In your features/support/env.rb
you could then have
def last_protobuf
@my_protocol_buffer
end
See features/support/env.rb
for a very simple implementation.
Now you can use proto_spec steps in your features:
Feature: Weather API
Background:
Given the weather is 58 degrees and cloudy in Chicago
And the weather is 72 degrees and sunny in Portland
Scenario: I can request the weather for a city
When I request weather for Portland
Then I should receive a ProtoBuf of type com.weather.WeatherResponse
And the ProtoBuf at "condition" should be "sunny"
And the ProtoBuf at "temperature" should be 72
When I request weather for Chicago
Then I should receive a ProtoBuf of type com.weather.WeatherResponse
And the ProtoBuf should be:
"""
{
"condition":"sunny",
"temperature":58
}
"""
Scenario: I can check if I need an umbrella
When I request the forecast for Chicago
Then I should receive a ProtoBuf of type com.weather.ForecastResponse
And the ProtoBuf should have "bring_umbrella"
And the ProtoBuf at "bring_umbrella" should be true
The background and request/receive steps above aren't provided by protobuf_spec. The remaining steps protobuf_spec provides. See json_spec documentation for more examples
Building Protobufs
In order to use the Cucumber steps for building protocol buffers, in your env.rb
you must:
require "protobuf_spec/builder"
Now you can use proto_spec builder steps in your features:
Feature: Weather Request API
Background:
Given the weather is 58 degrees and cloudy in Chicago
And the weather is 72 degrees and sunny in Portland
Scenario: I can request the weather for a city by protocol buffer
Given I create a ProtoBuf of type "com::weather::WeatherRequest"
And I set the ProtoBuf at "city" to "Portland"
And I set the ProtoBuf at "zipcode" to 97211
When I send the request
Then I should receive a ProtoBuf of type com::weather::WeatherResponse
And the ProtoBuf at "condition" should be "sunny"
And the ProtoBuf at "temperature" should be 72
Given I create the following protobuf of type "com::weather::WeatherRequest":
"""
{
"city": "Chicago",
"zipcode": 60606
}
"""
When I send the request
Then I should receive a ProtoBuf of type com::weather::WeatherResponse
And the ProtoBuf at "condition" should not be "sunny"
And the ProtoBuf at "temperature" should be 58
The built protocol buffer can be accessed through the protobuf
function in the ProtobufSpec::Builder
module.
Testing with a Transport Layer
Normally you will pair a serialization method like Protocol Buffers with a transport layer in systems that send and receive serialized data. protobuf_spec can easily integrated with a transport testing platform to test such systems. Consider again the weather example presented above. If the weather server used ZeroMQ as a transport layer, one could use an agent platform like agent_zmq to test and control the transport concern. Using agent_zmq, we could construct the following step definitions
When /^I send the request$/ do
AgentZeroMQ.agents_hash[:requester].publish [ProtobufSpec::Builder.protobuf.serialize_to_string]
end
Then /^I should receive a ProtoBuf of type com::weather::WeatherResponse$/
steps %{Then I should receive a response on ZeroMQ with agent "requester"}
@my_protocol_buffer=Com::weather::WeatherResponse.new
@my_protocol_buffer.parse_from_string last_zmq_message.last
end
...
See agent_zmq for additional information. A similar abstraction could be applied to any other transport layer.
More
Check out specs and features to see all the ways you can use protobuf_spec.
Install
gem install protobuf_spec
or add the following to Gemfile:
gem 'protobuf_spec'
and run bundle install
from your shell.
More Information
Contributing
Please see the contribution guidelines.
Credits
Contributers:
protobuf_spec is maintained and funded by Connamara Systems, llc.
The names and logos for Connamara Systems are trademarks of Connamara Systems, llc.
Licensing
protobuf_spec is Copyright © 2016 Connamara Systems, llc.
This software is available under the GPL and a commercial license. Please see the LICENSE file for the terms specified by the GPL license. The commercial license offers more flexible licensing terms compared to the GPL, and includes support services. Contact us for more information on the Connamara commercial license, what it enables, and how you can start developing with it.