Developing Spree extension with TDD

Here at Nebulab, we have just built an extension (Spree Subscriptions) that adds to Spree features needed to buy and manage subscription based items, ideal for magazines or similar products. We developed this extension for one of our clients and it has been our first official extension. Starting from scratch allowed us to better undestand how to develop Spree extensions using a TDD process and we wanted to share some thoughts and best practices about this topic. To make a rapid overview, in this article we will create a new extension, using some spree-subscriptions real scenarios and code, that adds a checkbox to the products edit page to denote if it is a subscribable product (a magazine). We will start writing tests and then we will make them pass.

Before starting

Choose the right tools

A Spree extension is essentially a simple Rails engine that has the spree_core gem (another engine) as dependency; this means we can use any preferred library to test it. Since Spree uses Rspec, FactoryGirl and Capybara we think that the best approach is to use the same tools in order to make Spree developers feel comfortable with tools they are used to work with and, eventually, reproduce or use some code already present in spree core. For example, in our extension we can reuse spree core factories or create new factories that have them as parents.

Create the new extension

It’s suggested to read Creating Extension Spree Official Guide before starting, which explores better this topic.

$ gem install rails
$ gem install spree

Now we can create the extension using the spree extension command.

$ cd ~/path/to/your/Code
$ spree extension Subscriptions
$ cd spree_subscriptions

Note: This guide refers to Spree 1.1 version of Spree. I think the only difference with the 1.2 (actually RC) will be with handling spree_auth that will not be a strict dependency of spree-core, letting us choose our favourite authentication system.

Generate a resource

Althoughe we have not to generate a resource for our extension example scenario, it could be useful to see how to do it and how to automatically create rspec files with a simple command. We have to add rspec gem to our extension Gemfile:

group :test do
  gem 'rspec'
end

After a bundle install we can lauch:

$ rails g resource spree/subscription
      invoke  active_record
      create    db/migrate/20120705112710_create_spree_subscriptions.rb
      create    app/models/spree/subscription.rb
      create    app/models/spree.rb
      invoke    rspec
      create      spec/models/spree/subscription_spec.rb
      invoke  controller
      create    app/controllers/spree/subscriptions_controller.rb
      invoke    erb
      create      app/views/spree/subscriptions
      invoke    rspec
      create      spec/controllers/spree/subscriptions_controller_spec.rb
      invoke    helper
      create      app/helpers/spree/subscriptions_helper.rb
      invoke      rspec
      create        spec/helpers/spree/subscriptions_helper_spec.rb
      invoke    assets
      invoke      js
      create        app/assets/javascripts/spree/subscriptions.js
      invoke      css
      create        app/assets/stylesheets/spree/subscriptions.css
      invoke  resource_route
       route    namespace :spree do resources :subscriptions end

And the tree will be correctly generated with rspec files too.

Include local factories

By default Spree extensions require the factories used for spree core testing. In fact into the spec_helper we can find:

require 'spree/core/testing_support/factories'

These factories can be very useful because we are sure we are modeling our test following real spree objects but if we want to test our extension we probably want to add some new factories. To add this feature we can simply add this lines after the core factories require:

Dir["#{File.dirname(__FILE__)}/factories/**/*.rb"].each do |f|
  fp =  File.expand_path(f)
  require fp
end

Now we can add our custom factories into spec/factories directory. We can also extend existing spree core factories using them as parents for our new factories, for example:

FactoryGirl.define do
  factory :subscribable_product, :parent => :product do
    subscribable true
  end
end

Using spree preferences in our tests

Testing an extension will probably let us bump into the setup of some spree preferences. Spree Core is tested resetting preferences to default values each time they are used to ensure tests always run in a default environment. To reproduce this behavior in our extension we can simply create (copy) a support method into /spec/support/preferences.rb

def reset_spree_preferences
  Spree::Preferences::Store.instance.persistence = false
  config = Rails.application.config.spree.preferences
  config.reset
  yield(config) if block_given?
end

that will allow us to setup required preferences in our tests:

before(:each) do
  reset_spree_preferences do |config|
    config.default_country_id = create(:country).id
    config.site_name = "my dummy test store for subscriptions"
  end
end

Add auth gem to test as an admin user

To test as admin interface functionality we have to sign in as admin user. To do it we have to require spree_auth into our lib/spree_subscriptions.rb file. which now will be like this:

require 'spree_core'
require 'spree_auth'
require 'spree_subscriptions/engine'

In order to complete login easily throught integration tests we can define another support method “sign_in_as!”, taken directly from spree_auth gem:

def sign_in_as!(user)
  visit '/login'
  fill_in 'Email', :with => user.email
  fill_in 'Password', :with => 'secret'
  click_button 'Login'
end

Run tests on extension

To test our extension we need to crate a dummy test app that will reside into spec/dummy/. This app will contain everything needed to execute the tests from our extension. Before running rspec for the first time and every time we make a structural change to the extension (like changing or adding a migration) we need to create the test app with this command:

$ rake test_app

Once completed we can run tests within our extension with:

$ rspec spec

Add some integration tests

Let’s say we want to test the ability of an admin user to flag a product as subscribable through the admin panel. We need to create some integation tests first. In spec/requests/admin/product_spec.rb:

require 'spec_helper'

describe "Product" do
  context "on edit" do
    it "should be selected as subscribable" do
      product = create(:product)
      user = create(:admin_user, :email => "[email protected]")
      sign_in_as!(user)
      visit spree.admin_path
      click_link "Products"
      within('table.index tr:nth-child(2)') { click_link "Edit" }
      check('product_subscribable')
      click_button "Update"
      page.should have_content("successfully updated!")
      page.has_checked_field?('product_subscribable').should == true
    end
  end
end

This test will not pass because the checkbox doesn’t exist yet. We can create with this Deface override:

Deface::Override.new(:virtual_path => "spree/admin/products/_form",
                     :name => "adds_subscribable_to_product",
                     :insert_bottom => "[data-hook='admin_product_form_right']",
                     :partial => "spree/admin/products/subscription_field")

As you can see, this override will render a partial in the right part of the product edit form. This partial contains:

<%= f.field_container :subscribable do %>
  <%= f.label :subscribable %><br />
  <%= f.check_box :subscribable %>
<% end %>

Test fails agin. This time because there are no setter and getter method for “subscribable” attribute. It’s time to add some model tests.

Add some model tests

Into spec/model/product_spec.rb we can add this code that test the existence of subscribable method and its default value:

require 'spec_helper'

describe Spree::Product do
  let(:subscribable_product) { Factory(:subscribable_product) }
  let(:simple_product) { Factory(:simple_product) }

  it "should respond to subscribable method" do
    subscribable_product.should respond_to :subscribable
  end

  it "should be subscribable" do
    subscribable_product.subscribable.should be_true
  end

  it "should have subscribable to false by default" do
    simple_product.subscribable?.should be false
  end
end

In order to let these tests pass, we have to add the subscribable field to the product table with a migration, then we have to recreate the test app to update its database that will include this last migration.

$ rails g migration add_subscribable_to_spree_products subscribable:boolean
$ rake test_app

We can try to run test but they will continue to fail. This time the issue is with mass assignment of subscribable attribute. To solve this problem we have to extend the product model creating a product decorator file in app/models/spree/product_decorator.rb:

Spree::Product.class_eval do
  attr_accessible :subscribable
end

These simple example tests pass so we can now be sure an admin user can set a product as subscribable.

Get a screenshot on test failure

Sometime we found really useful to view a screenshot (in .html format) of the page a test fails. There is a gem that does exactly the job: ‘capybara-screenshot’. To add it to our spree extension we can modify our Gemfile adding the gem to the test group:

group :test do
  gem 'capybara-screenshot', :require => false
end

and requiring it after rspec/rails in the spec_helper

...
require 'rspec/rails'
require 'capybara-screenshot'
require 'ffaker'
...

After a test failure we can find the html screenshot in /spec/dummy/tmp/capybara/ folder. Keep in mind that these files will be deleted everytime we run rake test_app.

Configure TravisCI for our extension

If we need a CI for our extension, we can simply configure TravisCI. The only extra configuration required to let it handle correctly an extension is related to the rake test_app command that we have to execute before running our tests. Here it is a sample .travis.yml file:

before_install: gem install bundler --pre
before_script:
  - "bundle exec rake test_app"
script: "DISPLAY=:99.0 bundle exec rspec spec"
notifications:
  email:
    - [email protected]
branches:
  only:
    - master
rvm:
  - 1.8.7
  - 1.9.2
  - 1.9.3

Conclusion

We want to get straight to the point: tests saved us a lot of time developing our first extension, expecially when we have to test orders. Imagine testing a critical feature that depends on checkout; every time you change something in the code you should test an order with guest checkout, an order for an already logged in user, an order for a user that signs up during the checkout, an admin order completion and probably other use cases we’ve not considered. Making things work without tests would surely be a pain.

Useful resources

• Creating Spree Extension Official Guide
• Tesing Spree Application Official Guide
• Spreecasts Episode 5 - Tdd an extension part 1