Spree Testing

Spree Testing

Before writing code

Fetch live docs:

1. Fetch https://spreecommerce.org/docs/developer/tutorial/testing for the canonical testing tutorial.
2. Check the spree_dev_tools gem on RubyGems and GitHub for the current factory inventory and helpers.
3. Inspect the Spree gem's own spec/ directory for the latest test patterns.
4. Cross-reference Rails 7+ testing docs for current request/system spec patterns.
5. For RSpec, FactoryBot, Capybara — check current gem versions vs your Spree's Gemfile.lock.

Conceptual Architecture

The Testing Stack

spree_dev_tools (v5.2+)

Formally introduced in v5.2 as a separate gem (was previously bundled). Provides:

• Pre-built factories for every Spree model (Spree::Order, Spree::Product, Spree::User, etc.)
• Shared examples for common test patterns
• Helpers for creating realistic test scenarios (create_order_with_two_items, etc.)
• Engine spec setup for extension testing

# Gemfile
group :development, :test do
  gem 'spree_dev_tools'
end

Spec Types

build vs create

# Slow — hits the database
let(:product) { create(:product) }

# Fast — in-memory only
let(:product) { build(:product) }

# Stub — fastest, no validation
let(:product) { build_stubbed(:product) }

Use build when you only need the object to call methods. Reach for create only when you need persistence (find_by, foreign keys, callbacks that hit the DB).

Common Factories

create(:product)                     # basic product
create(:product, name: 'Foo')        # with overrides
create(:product_in_stock)            # has stock
create(:order_with_line_items, line_items_count: 3)
create(:order_ready_to_complete)
create(:completed_order_with_pending_payment)
create(:user_with_addresses)
create(:admin_user)                   # has admin role

Verify the actual factory names against the spree_dev_tools source.

Testing a Decorator

# spec/models/spree/product_decorator_spec.rb
require 'rails_helper'

RSpec.describe Spree::Product, type: :model do
  describe 'editor_pick scope' do
    let!(:pick) { create(:product, editor_pick: true) }
    let!(:other) { create(:product, editor_pick: false) }

    it 'returns only editor-picked products' do
      expect(Spree::Product.editor_picks).to contain_exactly(pick)
    end
  end

  describe '#display_name' do
    let(:product) { build(:product, seo_title: 'Premium Tee', name: 'Tee') }

    it 'prefers seo_title' do
      expect(product.display_name).to eq('Premium Tee')
    end
  end
end

Testing a Subscriber

# spec/subscribers/order_completed_subscriber_spec.rb
require 'rails_helper'

RSpec.describe OrderCompletedSubscriber do
  let(:order) { create(:order, state: 'complete') }

  it 'enqueues an accounting sync' do
    expect {
      Spree::Bus.publish('order.completed', order: order, user: order.user)
    }.to have_enqueued_job(AccountingSyncJob).with(order_id: order.id)
  end
end

Testing a Service / Dependency Override

RSpec.describe MyApp::CartAddItemService do
  let(:order)   { create(:order) }
  let(:variant) { create(:variant) }

  it 'adds an item with extra metadata' do
    service = described_class.new
    result = service.call(order: order, variant: variant, quantity: 1, options: { source: 'app' })

    expect(result).to be_a(Spree::LineItem)
    expect(result.metafields.find_by(key: 'source').value).to eq('app')
  end
end

Feature/System Specs (Hotwire-aware)

Spree v5 admin uses Hotwire/Turbo. System specs need a JS driver:

# spec/system/admin/products_spec.rb
require 'rails_helper'

RSpec.describe 'Admin products', type: :system do
  let(:admin) { create(:admin_user) }
  before { sign_in admin; driven_by(:cuprite) }   # or :selenium_chrome_headless

  it 'creates a product' do
    visit spree.admin_products_path
    click_on 'New Product'
    fill_in 'Name', with: 'Test Product'
    fill_in 'Price', with: '19.99'
    click_on 'Create'
    expect(page).to have_content('Test Product')
  end
end

Testing API v3 Endpoints

RSpec.describe 'Store API v3 products', type: :request do
  let(:store) { create(:store) }
  let(:api_key) { create(:publishable_api_key, store: store).key }
  let!(:product) { create(:product, stores: [store]) }

  it 'lists products' do
    get '/api/v3/store/products', headers: { 'Authorization' => "Bearer #{api_key}" }
    expect(response).to have_http_status(:ok)
    body = JSON.parse(response.body)
    expect(body['data'].first['id']).to start_with('prod_')
    expect(body['data'].first['name']).to eq(product.name)
  end
end

(Verify the factory name :publishable_api_key in current spree_dev_tools.)

Testing With Sidekiq

# config/initializers/sidekiq.rb in test env auto-uses InlineTesting
require 'sidekiq/testing'
Sidekiq::Testing.fake!   # default for specs

RSpec.describe 'webhook delivery' do
  it 'enqueues a delivery job on order.completed' do
    order = create(:order, state: 'complete')
    expect {
      Spree::Bus.publish('order.completed', order: order)
    }.to change(Spree::WebhookDeliveryJob.jobs, :size).by(1)
  end
end

(Verify the job class name in the current Webhooks 2.0 implementation.)

Testing an Extension's Engine

Extensions test against a dummy Rails app:

cd spree_my_extension
bundle exec rake test_app  # generates spec/dummy
bundle exec rspec

The test_app rake task (verify it exists in current scaffolding) creates spec/dummy mounting Spree + your extension. Specs run against it.

Mocking External APIs

# spec/requests/stripe_webhook_spec.rb
RSpec.describe 'Stripe webhook', type: :request do
  it 'processes payment_intent.succeeded' do
    stub_request(:get, %r{api\.stripe\.com/v1/payment_intents})
      .to_return(body: { id: 'pi_…', status: 'succeeded' }.to_json)
    # ...
  end
end

WebMock is the standard; VCR is heavier-handed (records real responses to replay).

Implementation Guidance

Spec Suite Setup

# spec/rails_helper.rb
require 'spec_helper'
ENV['RAILS_ENV'] ||= 'test'
require_relative '../config/environment'
require 'rspec/rails'
require 'capybara/rspec'
require 'sidekiq/testing'

Dir[Rails.root.join('spec/support/**/*.rb')].sort.each { |f| require f }

RSpec.configure do |config|
  config.use_transactional_fixtures = true
  config.infer_spec_type_from_file_location!
  config.filter_rails_from_backtrace!

  config.include FactoryBot::Syntax::Methods
  config.include Spree::TestingSupport::AuthorizationHelpers, type: :controller
  config.include Spree::TestingSupport::ControllerRequests, type: :controller
  config.include Spree::TestingSupport::Capybara, type: :feature
end

(Verify the exact testing-support modules — they evolve.)

Speed Strategies

1. Prefer build and build_stubbed over create
2. Don't load full Rails for unit-y specs when possible
3. Parallel test execution — parallel_tests gem with N processes
4. Skip image processing in tests — Spree::Config.image_processor = :stub (verify config name)
5. Limit js: true to specs that genuinely need a browser
6. Mock external HTTP — every real request is a slow test

CI Patterns

# .github/workflows/ci.yml (sketch)
jobs:
  rspec:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
      redis:
        image: redis:7
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
      - run: bundle install --jobs 4
      - run: bin/rails db:create db:migrate
      - run: bundle exec rspec --format progress

Common Pitfalls

• Using create everywhere — specs take 10x longer than necessary.
• Forgetting Sidekiq::Testing.fake! — jobs fire synchronously and pollute specs.
• System specs without driven_by(:cuprite) or similar — Turbo events don't fire.
• Stubbing Spree::Order#total — breaks downstream service-object behavior; create the right line items instead.
• Not testing decorators with the real model loaded — autoloading order matters.
• Brittle Capybara selectors — use semantic selectors (data-test-id) not classes.
• Forgetting to seed default Store / Country / Zone — spree_dev_tools provides setup helpers; use them.

Always cross-reference the current spree_dev_tools factories and the Spree gem's own spec/ for the canonical patterns for the version you target.