<commit_before>h2. Testing

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":http://guides.rubyonrails.org/testing.html for background information.

endprologue.

h3. Overview

The Spree project currently uses "RSpec":http://rspec.info and "Cucumber":http://cukes.info/ 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.


h3. Running the Tests

h4. Building a Test App

Spree consists of several different gems (see the "Source Code Guide":source_code.html 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.

<shell>
  $ rake test_app
</shell>

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.)

NOTE. 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.

h4. Running the Specs

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

<shell>
  $ rake spec
</shell>

Or you can also do

<shell>
  $ bundle exec rspec spec
</shell>


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

<shell>
  $ bundle exec rspec spec/models/state_spec.rb
</shell>

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

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

h3. 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.

h4. Testing Within Your Rails Application.

When you first start out coding a new extension, its a good idea 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 much easier to develop with it side by side with your application.

If you've read the "Extensions Guide":/extensions.html you know by now how easy it is to create a Spree extension within the context of a Rails/Spree application:

<shell>
  $ rails g spree:extension foofah
</shell>

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 then want to prepare your test database if you have not already done so.

<shell>
  $ rake db:prepare
</shell>

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 rake task to verify them.

<shell>
  $ cd foofah
  $ rake spec
</shell>
<commit_msg>added how to use factories in testing section<commit_after>h2. Testing

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":http://guides.rubyonrails.org/testing.html for background information.

endprologue.

h3. Overview

The Spree project currently uses "RSpec":http://rspec.info and "Cucumber":http://cukes.info/ 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.


h3. Running the Tests

h4. Building a Test App

Spree consists of several different gems (see the "Source Code Guide":source_code.html 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.

<shell>
  $ rake test_app
</shell>

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.)

NOTE. 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.

h4. Running the Specs

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

<shell>
  $ rake spec
</shell>

Or you can also do

<shell>
  $ bundle exec rspec spec
</shell>


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

<shell>
  $ bundle exec rspec spec/models/state_spec.rb
</shell>

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

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

h4. Using factories

spree uses "factory_girl":https://github.com/thoughtbot/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.

<shell>
  $ rails console
  $ require 'spree_core/testing_support/factories'
</shell>

h3. 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.

h4. Testing Within Your Rails Application.

When you first start out coding a new extension, its a good idea 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 much easier to develop with it side by side with your application.

If you've read the "Extensions Guide":/extensions.html you know by now how easy it is to create a Spree extension within the context of a Rails/Spree application:

<shell>
  $ rails g spree:extension foofah
</shell>

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 then want to prepare your test database if you have not already done so.

<shell>
  $ rake db:prepare
</shell>

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 rake task to verify them.

<shell>
  $ cd foofah
  $ rake spec
</shell>

{'fraction_non_alphanumeric': 0.04521617527094744, 'fraction_numerical': 0.0019811210814590376, 'mean_word_length': 3.9124212936462506, 'pattern_counts': {'":': 11, '<': 37, '<?xml version=': 0, '>': 37, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7633174', 'n_tokens_mistral': 2298, 'n_tokens_neox': 2219, 'n_words': 1415}