This guide covers the test strategies and test support for Spree. After reading it you should be familiar with:

  • How to run the tests for the Spree code
  • How to test extensions to the Spree code

Before you dive into the detail, it’s worth reviewing the Rails guide on testing for background information.

1 Overview

The Spree project currently uses RSpec for all of its tests. Each of the gems that makes up Spree has a test suite that can be run to verify the code base.

The Spree test code is an evolving story. We started out with RSpec, then switched to Shoulda and now we’re back to RSpec. RSpec has evolved considerably since we first tried it. When looking to improve the test coverage of Spree we took another look at RSpec and it was the clear winner in terms of strength of community and documentation.

2 Running the Tests

2.1 Building a Test App

Spree consists of several different gems (see the Source Code Guide for more details.) Each of these gems has its own test suite which can be found in the spec directory. Since these gems are also Rails engines, they can’t really be tested in complete isolation - they need to be tested within the context of a Rails application.

You can easily build such an application by using the Rake task designed for this purpose.

  $ bundle exec rake test_app

This will build the appropriate test application inside of your spec directory. It will also add the gem under test to your Gemfile along with the spree_core gem as well (since all of the gems depend on this.)

This rake task will regenerate the application (after deleting the existing one) each time you run it. It will also run the migrations for you automatically so that your test database is ready to go.

2.2 Running the Specs

Once your test application has been built, you can then run the specs in the standard RSpec manner:

  $ bundle exec rake spec

Or you can also do

  $ bundle exec rspec spec

If you wish to run spec for a single file then you can do so like this:

  $ bundle exec rspec spec/models/state_spec.rb

If you wish to test a particular line number of the spec file then you can do so like this:

  $ bundle exec rspec spec/models/state_spec.rb:7

2.3 Using factories

spree uses factory_girl to create valid records for testing purpose. All the factories are also packaged in the gem. So ff you are writing an extension or if you just want to play with spree models then you can use these factories as illustrated below.

  $ rails console
  $ require 'spree/core/testing_support/factories'

3 Testing Your Extensions

The generator used by Spree to create new extensions will do all of the work to get your extension ready for testing. There are some cases, however, where you may wish to maintain an extension in its own repository as a standalone gem (so you can redistribute and share the code.) In these cases there is a little more work to be done before you can start testing. We’ll cover both scenarios here.

3.1 Testing Integrated Extensions

When you first start out coding a new extension, you may want to work with it right alongside the Spree project that you plan to use it in. Even if you’re eventually planning to break it out into a gem and share the source code its sometimes easier to develop with it side by side with your application.

If you’ve read the Creating Extensions Guide you know by now how easy it is to create a Spree extension within the context of a Rails/Spree application:

  $ spree extension foofah

This generator automatically creates a spec directory along with a spec_helper.rb file. If you’re not a fan of RSpec you can feel free to switch to a test framework of your choosing. You’ll also need to add the rspec-rails gem to your Gemfile if its not already present.

  gem 'rspec-rails'

Then its time to write some specs/tests for your extension. We’re not going to cover how to write tests here - there’s already plenty of resources that cover this topic in depth. Once your tests are written you simply use the standard rspec command to verify them.

  $ bundle exec rspec spec

3.2 Testing Standalone Extensions

Most extensions that you’ll be working with (including all of the ones in the extension registry) are so-called isolated extensions. They exist in their own Github repositories independent of any specific Rails application. Fortunately we have devised a way to test these extensions as well.

Lets start by creating a new extension - although the procedure is basically the same for an extension that you’ve cloned from Github.

  $ spree extension foofah

There’s an extra step needed in the isolated case before we can run our tests. We need to create a “dummy” rails application to serve as a context for the specs.

Perform the following one-time step

  $ bundle exec rake test_app

The resulting dummy Rails application should never be committed to your source code respository. You can always regenerate them with the rake task.

Once the test app has been created, your specs can run in the manner you’re used to with a full-fledged Rails application.

  $ bundle exec rspec spec

4 Cucumber

Cucumber is dropped in favor for RSpec + Capybara. All cucumbers tests are converted and located inside spec/requests directory.

4.1 Factory girl

The spree_core gem has a good number of factories which can be used for testing. If you are writing an extension or just testing spree you can make use of these factories.

  $ require 'spree/core/testing_support/factories'

Above command might result in following message.

LoadError: no such file to load -- factory_girl

If you encounter above message then just add factory_girl to your Gemfile.

gem 'factory_girl'

This project is maintained by a core team of developers and is freely available for commercial use under the terms of the New BSD License.