One of our client Java projects is pioneering the use of RSpec Story Framework for functional tests.

Overview

RSpec provides two frameworks for writing and executing examples of how your application should behave:

• a Story Framework for describing behaviour at the application level
• a Spec Framework for describing behaviour at the object level

JRuby is an 100% pure-Java implementation of the Ruby programming language.

How can Java projects benefit from RSpec Story Framework? Let's consider an example.

Example

There is a Java back-end application server with proprietary remote interface. The server manages current states of all patents reviewed by multiple patent offices. Close to real life examples below have no proprietary information and object names has been changed. RSpec can help describe how server works and should be used, also what happens in special conditions.

stories/councilReview.txt

one of stories from the server specification:

Story: patent review by counsel

  A Council review of a patent should change the patent review state
  and affect rolled up state of the patent application case.

   Scenario: legal counsel reviews patent
    Given a patent
    And the patent roll up state is ACTIVE
    When the legal council reviews the patent
    Then patent state should be ON_HOLD
    And patent case rolled up state should be SUSPENDED

   Scenario: legal counsel releases patent from the review bin
    Given a patent
    And the patent roll up state is ON_HOLD
    When the legal council release the patent from the review bin
    Then the patent state should be ACTIVE
    And the patent case rolled up state should be ACTIVE

How it works with Java

steps/patentstateoperations.rb

Steps define our Domain Specific Language or DSL

steps_for(:patent_state_operations) do

 Given "a patent" do
   $patent_state_action_stub = PatentStateActionManager.new("local")
   $patent_id = Random.new
  end

 Given "the patent roll up state is '$state'" do |state|
   patent_state_action_stub.setState(patent_id, state);
 end

 When "a '$reviewer' releases the patent from the review bin" do |type|
    newState = patent_state_action_stub.releaseFromBin(patent_id, reviewer);
 end

 When "a '$reviewer' reviews the patent" do |type|
    newState = patent_state_action_stub.addToBin(patent_id, reviewer);
 end

 Then "patent state should be '$state'" do |state|
   newState.should be state
 end
end

helpers/helper.rb

loads required Java classes using JRuby:

 require 'rubygems'
 require 'spec'
 require 'spec/story'
 require 'java'

 include_class 'client.project.functionaltests.PatentStateActionManager'

 class Spec::Story::Runner::ScenarioRunner
   def initialize
    @listeners = []
  end
end

Dir[File.dirname(__FILE__) + "/../steps/*.rb"].uniq.each { |file| require file }

all.rb

JRuby runs all the stories for the project:

 dir = File.expand_path(File.dirname(__FILE__))
 require "#{dir}/helpers/helper"

 with_steps_for :patent_state_operations do
   run "#{dir}/stories/councilReview.txt"
 end

And since we are on Java Project developers use the above Ruby steps to delegate most of the calls to some Java manager, which serves as a fixture for the functional tests.

PatentStateActionManager.java

This is a Java fixture to pass data to the application via RPC

 public class PatentStateActionManager {

  public PatentStateActionManager(String instanceType) {
  ... // get connection to server via RPC
  }

  public String addToBin(long patentId, String review) {
  ... // call RPC method
  }

  public String releaseFromBin(long patentId, String review) {
  ... // another RPC call
  }

  public void setState(long patentId, String newState) {
  ... // java land, Java developers do what they want
  }
}

Results

As a result we have a executable text specification described in close to English language. Majority of the boiler-plate code contained in Java fixtures and Ruby steps.

Project Managers and Quality Engineers can use RSpec stories to define and exercise the behavior of the application.

Java Developers implemented a few stories to demonstrate the use of all steps for Quality Engineers. In addition to Java unit tests that cover the project code, functional tests cover the application use cases.

Next steps

Quality Engineers will fill the story book with more stories covering many conditions and states.

Java Developers will provide support for fixtures as interfaces evolves over the time.

Customers will define future stories as Pending stories.

And Test Valentines are moving to wider adoption of RSpec including:

• continuous build integration
• test results publishing
• common steps for widely used interfaces:
  • Remote Control of Web apps using Selenium-RC
  • Command line and shell
• interactive console introduction
• functional point coverage