Spinach - BDD framework on top of Gherkin

Spinach is a high-level BDD framework that leverages the expressive Gherkin language (used by Cucumber) to help you define executable specifications of your application or library's acceptance criteria.

Conceived as an alternative to Cucumber, here are some of its design goals:

Step maintainability: since features map to their own classes, their steps are just methods of that class. This encourages step encapsulation.
Step reusability: In case you want to reuse steps across features, you can always wrap those in plain ol' Ruby modules.

Spinach is tested against 2.0, 2.1, 2.2 and 2.3 as well as JRuby 9000.

Getting started

Start by adding spinach to your Gemfile:

group :test do
  gem 'spinach'
  # gem 'rspec'
end

Spinach works out-of-the-box with your favorite test suite, but you can also use it with RSpec as well if you put the following in features/support/env.rb:

require 'rspec'

Now create a features folder in your app or library and write your first feature:

Feature: Test how spinach works
  In order to know what the heck is spinach
  As a developer
  I want it to behave in an expected way

  Scenario: Formal greeting
    Given I have an empty array
    And I append my first name and my last name to it
    When I pass it to my super-duper method
    Then the output should contain a formal greeting

  Scenario: Informal greeting
    Given I have an empty array
    And I append only my first name to it
    When I pass it to my super-duper method
    Then the output should contain a casual greeting

Now for the steps file. Remember that in Spinach steps are just Ruby classes, following a camelcase naming convention. Spinach generator will do some scaffolding for you:

$ spinach --generate

Spinach will detect your features and generate the following class:

features/steps/test_how_spinach_works.rb

class Spinach::Features::TestHowSpinachWorks < Spinach::FeatureSteps
  step 'I have an empty array' do
  end

  step 'I append my first name and my last name to it' do
  end

  step 'I pass it to my super-duper method' do
  end

  step 'the output should contain a formal greeting' do
  end

  step 'I append only my first name to it' do
  end

  step 'the output should contain a casual greeting' do
  end
end

Then, you can fill it in with your logic - remember, it's just a class, you can use private methods, mix in modules or whatever!

class Spinach::Features::TestHowSpinachWorks < Spinach::FeatureSteps
  step 'I have an empty array' do
    @array = Array.new
  end

  step 'I append my first name and my last name to it' do
    @array += ["John", "Doe"]
  end

  step 'I pass it to my super-duper method' do
    @output = capture_output do
      Greeter.greet(@array)
    end
  end

  step 'the output should contain a formal greeting' do
    @output.must_include "Hello, mr. John Doe"
  end

  step 'I append only my first name to it' do
    @array += ["John"]
  end

  step 'the output should contain a casual greeting' do
    @output.must_include "Yo, John! Whassup?"
  end

  private

  def capture_output
    out = StringIO.new
    $stdout = out
    $stderr = out
    yield
    $stdout = STDOUT
    $stderr = STDERR
    out.string
  end
end

module Greeter
  def self.greet(name)
    if name.length > 1
      puts "Hello, mr. #{name.join(' ')}"
    else
      puts "Yo, #{name.first}! Whassup?"
    end
  end
end

Then run your feature again running spinach and watch it all turn green! :)

Shared Steps

You'll often find that some steps need to be used in many features. In this case, it makes sense to put these steps in reusable modules. For example, let's say you need a step that logs the user into the site.

This is one way to make that reusable:

# ... features/steps/common_steps/login.rb
module CommonSteps
  module Login
    include Spinach::DSL

    step 'I am logged in' do
      # log in stuff...
    end
  end
end

Using the module (in any feature):

# ... features/steps/buying_a_widget.rb
class Spinach::Features::BuyAWidget < Spinach::FeatureSteps
  # simply include this module and you are good to go
  include CommonSteps::Login
end

Audit

Over time, the definitions of your features will change. When you add, remove or change steps in the feature files, you can easily audit your existing step files with:

$ spinach --audit

This will find any new steps and print out boilerplate for them, and alert you to the filename and line number of any unused steps in your step files.

This does not modify the step files, so you will need to paste the boilerplate into the appropriate places. If a new feature file is detected, you will be asked to run spinach --generate beforehand.

Important: If auditing individual files, common steps (as above) may be reported as unused when they are actually used in a feature file that is not currently being audited. To avoid this, run the audit with no arguments to audit all step files simultaneously.

Hook architecture

Spinach provides several hooks to allow you performing certain steps before or after any feature, scenario or step execution.

So, for example, you could:

Spinach.hooks.before_scenario do |scenario|
  clear_database
end

Spinach.hooks.on_successful_step do |step, location|
  count_steps(step.scenario.steps)
end

Spinach.hooks.after_run do |status|
  send_mail if status == 0
end

Full hook documentation is here:

Spinach's hook documentation

Local Before and After Hooks

Sometimes it feels awkward to add steps into feature file just because you need to do some test setup and cleanup. And it is equally awkward to add a global hooks for this purpose. For example, if you want to add a session timeout feature, to do so, you want to set the session timeout time to 1 second just for this feature, and put the normal timeout back after this feature. It doesn't make sense to add two steps in the feature file just to change the session timeout value. In this scenario, a before and after blocks are perfect for this kind of tasks. Below is an example implementation:

class Spinach::Features::SessionTimeout < Spinach::FeatureSteps
  attr_accessor :original_timeout_value
  before do
    self.original_timeout_value = session_timeout_value
    change_session_timeout_to 1.second
  end

  after do
    change_session_timeout_to original_timeout_value
  end

  # remaining steps
end

RSpec mocks

If you need access to the rspec-mocks methods in your steps, add this line to your env.rb:

require 'spinach/rspec/mocks'

Reporters

Spinach supports two kinds of reporters by default: stdout and progress. You can specify them when calling the spinach binary:

spinach --reporter progress

When no reporter is specified, stdout will be used by default.

Other reporters:

For a console reporter with no colors, try spinach-console-reporter (to be used with Jenkins)
For a rerun reporter, try spinach-rerun-reporter (writes failed scenarios in a file)

Wanna use it with Rails 3?

Use spinach-rails

Other rack-based frameworks

Check out our spinach-sinatra demo

Resources

Related gems

guard-spinach
spinach-rails
spinach-console-reporter (to be used with Jenkins)
spinach-rerun-reporter (writes failed scenarios in a file)
spring-commands-spinach (to be used with spring)

Demos

Contributing

List of spinach contributors

You can easily contribute to Spinach. Its codebase is simple and extensively documented.

Fork the project.
Make your feature addition or bug fix.
Add specs for it. This is important so we don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. If you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull.
Send me a pull request. Bonus points for topic branches.

yarmiganosca/spinach