Java Functional Testing with JRuby and RSpec

January 13, 2008 Pivotal Labs

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


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.


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.


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 define our Domain Specific Language or DSL

steps_for(:patent_state_operations) do

 Given "a patent" do

   $patent_state_action_stub ="local")

   $patent_id =


 Given "the patent roll up state is '$state'" do |state|

   patent_state_action_stub.setState(patent_id, state);


 When "a '$reviewer' releases the patent from the review bin" do |type|

    newState = patent_state_action_stub.releaseFromBin(patent_id, reviewer);


 When "a '$reviewer' reviews the patent" do |type|

    newState = patent_state_action_stub.addToBin(patent_id, reviewer);


 Then "patent state should be '$state'" do |state|

   newState.should be state




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 = []



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


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"


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.

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




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

About the Author


Teaching Your Tests To Report Unused Parameters
Teaching Your Tests To Report Unused Parameters

Recently I was about to check in some changes and did a last minute click through of the application. All ...

what to do with vtophys()
what to do with vtophys()

outside of work, I do some things with OpenBSD. Over the last month or so, I've been poking at the DRI cod...

SpringOne 2021

Register Now