Glad You're Ready. Let's Get Started!

Let us know how we can contact you.

Thank you!

We'll respond shortly.

Java Functional Testing with JRuby and RSpec

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

  1. Brian Takita says:


  2. Joe Moore says:

    Great post! Maybe we can use this on our project. I’m very curious about the Story text file and the Steps file.

  3. Ola Bini says:

    Hi Paul,

    Got the link to this post from Paul Hammant.

    I actually just released JtestR, a framework that takes care of the integration between your build process in Java, and testing frameworks in Ruby. I still haven’t support for the story runner, but that’s coming in 0.2. For now, it includes Test/Unit, dust, RSpec, mocha and ActiveSupport. Mocha has been modified and extended so you can mock any (non-final) methods and classes.

    More info at:

    There seems to be some overlap in what we’re doing.


  4. It’s great to see RSpec break into the Java space. I hope the .Net folks will follow soon.

    Ola, Paul – I’d love to see you two collaborating on your similar efforts.

  5. Jim Alateras says:

    This is very interesting. I have been developing with Java for over 10 years and have recently started working with Ruby and RoR. I have used rspec and absolutely love it and am looking at also using cucumber.

    Will definitely be following your progress on this.

Post a Comment

Your Information (Name required. Email address will not be displayed with comment.)

* Copy This Password *

* Type Or Paste Password Here *