@spree/docs 0.1.0

package/dist/developer/tutorial/testing.md

@@ -0,0 +1,558 @@
+Learn how to write automated tests for the Brands feature
+
+Automated testing is a crucial part of the development process. It helps you ensure that your code works as expected and catches bugs early.
+Spree uses [RSpec](https://rspec.info), [Factory Bot](https://github.com/thoughtbot/factory_bot_rails), and [Capybara](https://github.com/teamcapybara/capybara) for testing.
+We also provide the `spree_dev_tools` gem that helps you write Spree-specific tests.
+
+> **INFO:** This guide assumes you've completed all previous tutorials through [Page Builder](/developer/tutorial/page-builder). You should have a complete `Spree::Brand` model with admin, storefront, and SEO features.
+
+## Setup
+
+### Step 1: Set RSpec as the Test Framework
+
+```bash
+bin/rails g rspec:install
+```
+
+### Step 2: Run the spree\_dev\_tools Generator
+
+```bash
+bin/rails g spree_dev_tools:install
+```
+
+This adds Spree-specific test helpers to your `spec/support/` directory, including:
+
+* Authorization helpers (`stub_authorization!`)
+* Factory Bot configuration
+* Capybara setup for feature tests
+* and more…
+
+### Step 3: Create the Fixtures Directory and File
+
+When writing tests that involve file attachments (like images, PDFs, etc.), you need fixture files that your factories can use. Here's how to set them up.
+
+```bash
+mkdir -p spec/fixtures/files && printf '\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05\x18\xd8N\x00\x00\x00\x00IEND\xaeB`\x82' > spec/fixtures/files/logo.png
+```
+
+### Step 4: Generate Test Files
+
+```bash
+bin/rails g rspec:model Spree::Brand
+```
+
+This creates `spec/models/spree/brand_spec.rb`.
+
+## Writing Factories
+
+Factories provide a convenient way to create test data. Create a factory for your Brand model:
+
+```ruby spec/factories/spree/brand_factory.rb
+FactoryBot.define do
+  factory :brand, class: Spree::Brand do
+    sequence(:name) { |n| "Brand #{n}" }
+    sequence(:slug) { |n| "brand-#{n}" }
+
+    trait :with_description do
+      description { '<div>A great brand for <strong>quality products</strong></div>' }
+    end
+
+    trait :with_logo do
+      after(:create) do |brand|
+        brand.logo.attach(
+          io: File.new(Rails.root.join('spec', 'fixtures', 'files', 'logo.png')),
+          filename: 'logo.png'
+        )
+      end
+    end
+
+    trait :with_products do
+      transient do
+        products_count { 3 }
+        store { nil }
+      end
+
+      after(:create) do |brand, evaluator|
+        store = evaluator.store || create(:store)
+        create_list(:product, evaluator.products_count, brand: brand, stores: [store])
+      end
+    end
+  end
+end
+```
+
+### Factory Usage Examples
+
+```ruby
+# Basic factory
+brand = create(:brand)
+
+# With traits
+brand = create(:brand, :with_description, :with_logo)
+
+# With custom attributes
+brand = create(:brand, name: 'Nike')
+
+# Build without persisting (faster for unit tests)
+brand = build(:brand)
+
+# Create multiple records
+brands = create_list(:brand, 5)
+
+# With associated products
+brand = create(:brand, :with_products)
+brand = create(:brand, :with_products, products_count: 5)
+```
+
+## Writing Model Tests
+
+Model tests verify your business logic, validations, associations, and scopes.
+
+```ruby spec/models/spree/brand_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::Brand, type: :model do
+  describe 'associations' do
+    it 'has many products' do
+      association = described_class.reflect_on_association(:products)
+      expect(association.macro).to eq(:has_many)
+      expect(association.class_name).to eq('Spree::Product')
+    end
+  end
+
+  describe 'validations' do
+    it 'validates presence of name' do
+      brand = build(:brand, name: nil)
+      expect(brand).not_to be_valid
+      expect(brand.errors[:name]).to include("can't be blank")
+    end
+
+    describe 'slug uniqueness' do
+      let!(:existing_brand) { create(:brand, slug: 'nike') }
+
+      it 'validates uniqueness of slug' do
+        brand = build(:brand, slug: 'nike')
+        expect(brand).not_to be_valid
+        expect(brand.errors[:slug]).to include('has already been taken')
+      end
+    end
+  end
+
+  describe 'FriendlyId' do
+    it 'generates slug from name' do
+      brand = create(:brand, name: 'Nike Sportswear', slug: nil)
+      expect(brand.slug).to eq('nike-sportswear')
+    end
+
+    it 'handles duplicate names by appending UUID' do
+      create(:brand, name: 'Nike', slug: 'nike')
+      brand = create(:brand, name: 'Nike', slug: nil)
+      expect(brand.slug).to match(/nike-[a-f0-9-]+/)
+    end
+  end
+
+  describe '#image' do
+    let(:brand) { create(:brand, :with_logo) }
+
+    it 'returns logo as image for Open Graph' do
+      expect(brand.image).to eq(brand.logo)
+    end
+  end
+end
+```
+
+### Testing Decorators
+
+When you extend core Spree models with decorators (see [Extending Core Models](/developer/tutorial/extending-models)), test the added functionality:
+
+```ruby spec/models/spree/product_decorator_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Spree::Product brand association' do
+  let(:store) { @default_store }
+  let(:brand) { create(:brand) }
+  let(:product) { create(:product, stores: [store]) }
+
+  describe 'brand association' do
+    it 'can be assigned a brand' do
+      product.brand = brand
+      product.save!
+
+      expect(product.reload.brand).to eq(brand)
+    end
+
+    it 'is optional' do
+      product.brand = nil
+      expect(product).to be_valid
+    end
+  end
+
+  describe 'brand.products' do
+    let!(:product1) { create(:product, brand: brand, stores: [store]) }
+    let!(:product2) { create(:product, brand: brand, stores: [store]) }
+    let!(:other_product) { create(:product, stores: [store]) }
+
+    it 'returns products for the brand' do
+      expect(brand.products).to contain_exactly(product1, product2)
+    end
+
+    it 'nullifies brand_id when brand is destroyed' do
+      brand.destroy
+      expect(product1.reload.brand_id).to be_nil
+    end
+  end
+end
+```
+
+## Writing Controller Tests
+
+Controller tests verify that your endpoints respond correctly and perform the expected actions.
+
+### Admin Controller Tests
+
+```ruby spec/controllers/spree/admin/brands_controller_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::Admin::BrandsController, type: :controller do
+  stub_authorization!
+  render_views
+
+  describe 'GET #index' do
+    let!(:brand1) { create(:brand, name: 'Adidas') }
+    let!(:brand2) { create(:brand, name: 'Nike') }
+
+    it 'returns a successful response' do
+      get :index
+      expect(response).to be_successful
+    end
+
+    it 'displays all brands' do
+      get :index
+      expect(response.body).to include('Adidas')
+      expect(response.body).to include('Nike')
+    end
+  end
+
+  describe 'GET #new' do
+    it 'returns a successful response' do
+      get :new
+      expect(response).to be_successful
+    end
+
+    it 'displays the new brand form' do
+      get :new
+      expect(response.body).to include('brand[name]')
+    end
+  end
+
+  describe 'POST #create' do
+    context 'with valid params' do
+      let(:valid_params) do
+        { brand: { name: 'New Brand' } }
+      end
+
+      it 'creates a new brand' do
+        expect {
+          post :create, params: valid_params
+        }.to change(Spree::Brand, :count).by(1)
+      end
+
+      it 'redirects to the edit page' do
+        post :create, params: valid_params
+        expect(response).to redirect_to(spree.edit_admin_brand_path(Spree::Brand.last))
+      end
+    end
+
+    context 'with invalid params' do
+      let(:invalid_params) do
+        { brand: { name: '' } }
+      end
+
+      it 'does not create a new brand' do
+        expect {
+          post :create, params: invalid_params
+        }.not_to change(Spree::Brand, :count)
+      end
+
+      it 'returns unprocessable entity status' do
+        post :create, params: invalid_params
+        expect(response).to have_http_status(:unprocessable_content)
+      end
+    end
+  end
+
+  describe 'GET #edit' do
+    let(:brand) { create(:brand) }
+
+    it 'returns a successful response' do
+      get :edit, params: { id: brand.id }
+      expect(response).to be_successful
+    end
+  end
+
+  describe 'PUT #update' do
+    let(:brand) { create(:brand, name: 'Old Name') }
+
+    context 'with valid params' do
+      it 'updates the brand' do
+        put :update, params: { id: brand.id, brand: { name: 'New Name' } }
+        expect(brand.reload.name).to eq('New Name')
+      end
+
+      it 'redirects to the edit page' do
+        put :update, params: { id: brand.id, brand: { name: 'New Name' } }
+        expect(response).to redirect_to(spree.edit_admin_brand_path(brand))
+      end
+    end
+  end
+
+  describe 'DELETE #destroy' do
+    let!(:brand) { create(:brand) }
+
+    it 'removes the brand from the database' do
+      expect {
+        delete :destroy, params: { id: brand.id }, format: :html
+      }.to change(Spree::Brand, :count).by(-1)
+    end
+  end
+end
+```
+
+### Storefront Controller Tests
+
+```ruby spec/controllers/spree/brands_controller_spec.rb
+require 'rails_helper'
+
+RSpec.describe Spree::Brand, type: :model do
+  describe 'associations' do
+    it 'has many products' do
+      association = described_class.reflect_on_association(:products)
+      expect(association.macro).to eq(:has_many)
+      expect(association.class_name).to eq('Spree::Product')
+    end
+  end
+
+  describe 'validations' do
+    it 'validates presence of name' do
+      brand = build(:brand, name: nil)
+      expect(brand).not_to be_valid
+      expect(brand.errors[:name]).to include("can't be blank")
+    end
+
+    describe 'slug uniqueness' do
+      let!(:existing_brand) { create(:brand, slug: 'nike') }
+
+      it 'validates uniqueness of slug' do
+        brand = build(:brand, slug: 'nike')
+        expect(brand).not_to be_valid
+        expect(brand.errors[:slug]).to include('has already been taken')
+      end
+    end
+  end
+
+  describe 'FriendlyId' do
+    it 'generates slug from name' do
+      brand = create(:brand, name: 'Nike Sportswear', slug: nil)
+      expect(brand.slug).to eq('nike-sportswear')
+    end
+
+    it 'handles duplicate names by appending UUID' do
+      create(:brand, name: 'Nike', slug: 'nike')
+      brand = create(:brand, name: 'Nike', slug: nil)
+      expect(brand.slug).to match(/nike-[a-f0-9-]+/)
+    end
+  end
+
+  describe '#image' do
+    let(:brand) { create(:brand, :with_logo) }
+
+    it 'returns logo as image for Open Graph' do
+      expect(brand.image).to eq(brand.logo)
+    end
+  end
+end
+```
+
+## Writing Feature Tests
+
+Feature tests (also called system tests) simulate real user interactions using Capybara.
+
+### Admin Feature Tests
+
+```ruby spec/features/spree/admin/brands_spec.rb
+require 'rails_helper'
+
+RSpec.feature 'Admin Brands', type: :feature do
+  stub_authorization!
+
+  describe 'listing brands' do
+    let!(:brand1) { create(:brand, name: 'Nike') }
+    let!(:brand2) { create(:brand, name: 'Adidas') }
+
+    it 'displays all brands' do
+      visit spree.admin_brands_path
+
+      expect(page).to have_content('Nike')
+      expect(page).to have_content('Adidas')
+    end
+  end
+
+  describe 'creating a brand' do
+    it 'creates a new brand successfully' do
+      visit spree.admin_brands_path
+      click_on 'New Brand'
+
+      fill_in 'Name', with: 'Puma'
+      fill_in 'Slug', with: 'puma'
+
+      click_on 'Create'
+      wait_for_turbo
+
+      expect(page).to have_content('Brand "Puma" has been successfully created!')
+      expect(Spree::Brand.find_by(name: 'Puma')).to be_present
+    end
+
+    it 'shows validation errors' do
+      visit spree.new_admin_brand_path
+
+      click_on 'Create'
+      wait_for_turbo
+
+      expect(page).to have_content("can't be blank")
+    end
+  end
+
+  describe 'editing a brand' do
+    let!(:brand) { create(:brand, name: 'Nike') }
+
+    it 'updates the brand successfully' do
+      visit spree.admin_brands_path
+      click_on 'Edit'
+
+      fill_in 'Name', with: 'Nike Inc.'
+      within('#page-header') { click_button 'Update' }
+
+      wait_for_turbo
+      expect(page).to have_content('Brand "Nike Inc." has been successfully updated!')
+      expect(brand.reload.name).to eq('Nike Inc.')
+    end
+  end
+
+  describe 'deleting a brand' do
+    let!(:brand) { create(:brand, name: 'Nike') }
+
+    it 'removes the brand' do
+      expect {
+        page.driver.submit :delete, spree.admin_brand_path(brand), {}
+      }.to change(Spree::Brand, :count).by(-1)
+    end
+  end
+end
+```
+
+## Test Helpers
+
+### Authorization Helper
+
+Use `stub_authorization!` to bypass authorization checks in admin tests:
+
+```ruby
+RSpec.describe Spree::Admin::BrandsController, type: :controller do
+  stub_authorization!  # Grants full admin access
+
+  # ... your tests
+end
+```
+
+### wait\_for\_turbo Helper
+
+When testing with Turbo/Hotwire, use `wait_for_turbo` to ensure the page has fully loaded:
+
+```ruby
+click_on 'Create'
+wait_for_turbo
+expect(page).to have_content('Success!')
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/models/spree/brand_spec.rb
+
+# Run specific test
+bundle exec rspec spec/models/spree/brand_spec.rb:15
+
+# Run with documentation format
+bundle exec rspec --format documentation
+
+# Run only feature tests
+bundle exec rspec spec/features/
+```
+
+## Best Practices
+
+
+  - **Use build over create** — Use `build` instead of `create` when you don't need a persisted record. It's faster because it skips database operations.
+
+  - **Use let over instance variables** — Prefer `let` and `let!` over instance variables. They're lazily evaluated and scoped to each example.
+
+  - **One assertion per test** — Keep tests focused on a single behavior. Use `aggregate_failures` if you need multiple assertions.
+
+  - **Test behavior, not implementation** — Focus on what the code does, not how it does it. This makes tests more resilient to refactoring.
+
+
+### Example: aggregate\_failures
+
+```ruby
+it 'creates brand with all attributes', :aggregate_failures do
+  brand = create(:brand, name: 'Nike')
+
+  expect(brand.name).to eq('Nike')
+  expect(brand.slug).to eq('nike')
+end
+```
+
+## Complete Test Suite Structure
+
+After completing this tutorial, your test structure should look like:
+
+```
+spec/
+├── factories/
+│   └── spree/
+│       ├── brand_factory.rb
+│       └── brands.rb
+├── models/
+│   └── spree/
+│       ├── brand_spec.rb
+│       └── product_decorator_spec.rb
+├── controllers/
+│   └── spree/
+│       ├── admin/
+│       │   └── brands_controller_spec.rb
+│       └── brands_controller_spec.rb
+├── features/
+│   └── spree/
+│       └── admin/
+│           └── brands_spec.rb
+├── support/
+│   └── (various support files)
+├── rails_helper.rb
+└── spec_helper.rb
+```
+
+## Related Documentation
+
+* [Model Tutorial](/developer/tutorial/model) - Creating the Brand model
+* [Admin Tutorial](/developer/tutorial/admin) - Building the admin interface
+* [Extending Core Models](/developer/tutorial/extending-models) - Connecting Brands to Products
+* [Storefront Tutorial](/developer/tutorial/storefront) - Creating storefront pages
+* [RSpec Documentation](https://rspec.info/documentation/) - Official RSpec docs
+* [Factory Bot Documentation](https://github.com/thoughtbot/factory_bot/blob/main/GETTING_STARTED.md) - Factory Bot guide
+
+
+---

package/dist/developer/upgrades/2.0-to-2.1.md

@@ -0,0 +1,46 @@
+---
+title: 2.0 to 2.1
+description: 'This guide covers upgrading a 2.0 Spree store, to a 2.1 store.'
+---
+
+## Overview
+
+This guide has been written from the perspective of a blank Spree 2.0 store with no extensions.
+
+If you have extensions that your store depends on, you will need to manually verify that each of those extensions works within your 2.1 store once this upgrade is complete. Typically, extensions that are compatible with this version of Spree will have a 2-1-stable branch.
+
+This is the first Spree release that supports Rails 4 exclusively. Spree releases after this point will continue to support Rails 4 only.
+
+## Upgrade Rails
+
+For this Spree release, you will need to upgrade your Rails version to at least 4.0.0.
+
+It is recommended to read through the [Upgrading Ruby on Rails guide](http://guides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-%20from-rails-3-2-to-rails-4-0) to learn what needs to be done for your application to migrate to Rails 4.
+
+```ruby
+gem 'rails', '~> 4.0'
+```
+
+## Upgrade Spree
+
+For best results, use the 2-1-stable branch from GitHub:
+
+```ruby
+gem 'spree', '~> 2.1'
+```
+
+Run `bundle update spree`.
+
+## Copy and run migrations
+
+Copy over the migrations from Spree (and any other engine) and run them using
+these commands:
+
+```bash
+    rake railties:install:migrations
+    rake db:migrate
+```
+
+## Read the release notes
+
+For information about changes contained with this release, please read the [2.1.0 Release Notes](https://github.com/spree/spree/releases/tag/v2.1.0).

package/dist/developer/upgrades/2.1-to-2.2.md

@@ -0,0 +1,59 @@
+---
+title: 2.1 to 2.2
+section: upgrades
+description: 'This guide covers upgrading a 2.1 Spree store, to a 2.2 store.'
+---
+
+## Overview
+
+This guide has been written from the perspective of a blank Spree 2.1 store with no extensions.
+
+If you have extensions that your store depends on, you will need to manually verify that each of those extensions works within your 2.2 store once this upgrade is complete. Typically, extensions that are compatible with this version of Spree will have a 2-2-stable branch.
+
+## Upgrade Rails
+
+For this Spree release, you will need to upgrade your Rails version to at least 4.0.6.
+
+```ruby
+gem 'rails', '~> 4.0.6'
+```
+
+## Upgrade Spree
+
+For best results, use the 2-2-stable branch from GitHub:
+
+```ruby
+gem 'spree', '~> 2.2'
+```
+
+Run `bundle update spree`.
+
+## Copy and run migrations
+
+Copy over the migrations from Spree (and any other engine) and run them using
+these commands:
+
+```bash
+rake railties:install:migrations
+```
+
+```bash
+rake db:migrate
+```
+
+## Read the release notes
+
+For information about changes contained with this release, please read the [2.2.0 Release Notes](http://guides.spreecommerce.org/release_notes/spree_2_2_0.html).
+
+### Rename assets
+
+As mentioned in the release notes, asset paths have changed. Change the references on the left, to the ones on the right:
+
+* `admin/spree_backend` => `spree/backend`
+* `store/spree_frontend` => `spree/frontend`
+
+This applies across the board on Spree, and may need to be done in your store's extensions.
+
+### Paperclip settings have been removed from master
+
+Please consult [this section](http://guides.spreecommerce.org/release_notes/spree_2_2_0.html#paperclip-settings-have-been-removed) of the release notes if you were using custom Paperclip settings. This will direct you what to do in that particular case.

package/dist/developer/upgrades/2.2-to-2.3.md

@@ -0,0 +1,44 @@
+---
+title: 2.2 to 2.3
+description: 'This guide covers upgrading a 2.2 Spree store, to a 2.3 store.'
+---
+
+## Overview
+
+This guide has been written from the perspective of a blank Spree 2.2 store with no extensions.
+
+If you have extensions that your store depends on, you will need to manually verify that each of those extensions works within your 2.3 store once this upgrade is complete. Typically, extensions that are compatible with this version of Spree will have a 2-3-stable branch.
+
+This is the first Spree release that supports Rails 4.1.
+
+## Upgrade Rails
+
+For this Spree release, you will need to upgrade your Rails version to at least 4.1.2.
+
+```ruby
+gem 'rails', '~> 4.1.2'
+```
+
+## Upgrade Spree
+
+For best results, use the 2-3-stable branch from GitHub:
+
+```ruby
+gem 'spree', '~> 2.3'
+```
+
+Run `bundle update spree`.
+
+## Copy and run migrations
+
+Copy over the migrations from Spree (and any other engine) and run them using
+these commands:
+
+```bash
+    rake railties:install:migrations
+    rake db:migrate
+```
+
+## Read the release notes
+
+For information about changes contained with this release, please read the [2.3.0 Release Notes](https://github.com/spree/spree/releases/tag/v2.3.0).