DOCSEARCHbyAlgolia
Submit Docs

rspec-rails

repository·main·Indexed 26 days ago

https://github.com/rspec/rspec-rails

A library that integrates the RSpec testing framework into Ruby on Rails applications, providing a specification-based alternative to Minitest. It includes specialized spec types for models, controllers, mailers, routing, and system tests, along with Rails-specific matchers like render_template and redirect_to. The library supports various Rails versions, from legacy 2.x up to Rails 8.0.

Tokens
7.8K
Snippets
34
Records
69
Agent score
90%

What's inside rspec-rails

  1. Understand the RSpec Rails versioning strategy

    main

    RSpec Rails follows Semantic Versioning (SemVer) but aligns its release cycle with the Rails release cycle rather than the core RSpec gems. This ensures that RSpec Rails accurately tracks its primary dependency, Rails.

    Versioning Rules:

    • Major Versions: Incremented when removing support for a Rails or Ruby version, or when adding support for a new Rails major version.
    • Minor Versions: Incremented when adding support for a new Rails minor version or when introducing new RSpec features.
    • Patchlevels: Incremented for frequent bug fixes.

    Note that RSpec Rails' major version may increment more frequently than core RSpec gems because it tracks Rails dependency changes.

  2. Understand rspec-rails versioning and support

    main

    RSpec Rails follows semantic versioning (x.y.z):

    • x (Major): Contains breaking changes and changes to supported Rails versions.
    • y (Minor): Contains feature additions and bug fixes.
    • z (Patch): Contains bug fixes for the currently supported Rails versions.

    The RSpec team maintains the current major/minor version. New Rails minor releases typically trigger a new RSpec Rails minor release, though a major release may occur to drop support for older Rails versions.

  3. Upgrade to Capybara 3.x

    main

    If you are upgrading your project to Capybara 3.x, you must follow the official Capybara migration guide to handle breaking changes.

    https://github.com/teamcapybara/capybara/blob/master/UPGRADING.md#upgrading-from-capybara-2x-to-3x

  4. Prepare database and run RSpec

    main

    Before running your tests for the first time, ensure your database is migrated and prepared for the test environment. You can then execute your specs using rake spec or the rspec CLI command.

    To prepare the database:

    $ rails db:migrate && rails db:test:prepare

    To run the specs:

    $ rake spec
# OR
$ rspec spec --format documentation
    $ rails db:migrate && rails db:test:prepare
$ rake spec

  5. Upgrade from rspec-rails 3.x to version 4

    main

    RSpec Rails 4 supports Rails 5 and 6. No code changes are required to upgrade from 3.x to 4 if you are using Rails 5 or 6.

    • Rails 4.2 Support: You can use RSpec Rails 4 with Rails 4.2, but support is not maintained. This is considered a breaking change.
    • Requirement: You must be on Ruby 2.2 or higher to use RSpec Rails 4.

  6. Upgrade from rspec-rails 6.x to version 7

    main

    RSpec Rails 7 supports Rails versions 7.0, 7.1, and 7.2.

    • If you are upgrading Rails versions alongside RSpec, it is recommended to upgrade to Rails 7.1 and RSpec Rails 6.1.x before moving to Rails 7.2 and RSpec Rails 7.0.
    • Constraint: If you are using Rails 6.1, you must continue using RSpec Rails 6.1.

  8. Upgrade from rspec-rails 4.x to version 5

    main

    RSpec Rails 5 supports Rails versions 5.2, 6.0, and 6.1. No code changes are required to upgrade from 4.x to 5 for these Rails versions.

    • Legacy Support: If you are using older Rails versions, RSpec Rails 4.x provides hard support for Rails 5.0 and 5.1, and soft support for Rails 4.2 (unmaintained).

  9. Use Capybara::RSpecMatchers for HTML assertions

    main

    To use Capybara matchers (such as have_selector or should_not have_selector) to verify HTML content, ensure your specs are located in one of the following directories where Capybara::RSpecMatchers is automatically included:

    • spec/features
    • spec/controllers
    • spec/views
    • spec/helpers
    • spec/mailers

  10. Manage data isolation with before(:context) hooks

    main

    before(:context) hooks are invoked before the transaction is opened. While this can improve performance by creating data once for a group of tests, the data is not automatically rolled back.

    If you use before(:context), you must follow these two guidelines to prevent data leakage and synchronization issues:

    1. Manual Cleanup: Use an after(:context) hook to destroy any data created in the context hook.
    2. Object Reloading: Use a before(:example) hook to call .reload on the objects created in the context. This ensures the Ruby object stays in sync with the database after transactions are rolled back during individual examples.
    # 1. Manual Cleanup
before(:context) do
  @widget = Widget.create!
end

after(:context) do
  @widget.destroy
end

# 2. Object Reloading
before(:context) do
  @widget = Widget.create!
end

before(:example) do
  @widget.reload
end

  11. Define Controller Specs

    main

    Controller specs are RSpec wrappers for Rails functional tests. To define a controller spec, you must either explicitly mark the spec with type: :controller or ensure your RSpec configuration has config.infer_spec_type_from_file_location! enabled and place the file in spec/controllers.

    Controller specs allow you to simulate single HTTP requests and verify outcomes such as rendered templates, redirects, assigned instance variables, and cookies.

    RSpec.describe TeamsController, type: :controller do
  describe "GET index" do
    it "assigns @teams" do
      team = Team.create
      get :index
      expect(assigns(:teams)).to eq([team])
    end

    it "renders the index template" do
      get :index
      expect(response).to render_template("index")
    end
  end
end

  12. Install rspec-rails in a new Rails application

    main

    To set up rspec-rails in a fresh Rails project, follow these steps:

    1. Install Rails (ensure version compatibility, e.g., ~> 7.2.0).
    2. Generate a new Rails application: rails new example_app.
    3. Add rspec-rails to your Gemfile within the :development and :test groups.
    4. Run bundle install.
    5. Bootstrap RSpec configuration using the generator: rails generate rspec:install.
    $ gem install rails -v "~> 7.2.0"
$ rails new example_app
$ cd example_app
$ echo 'gem "rspec-rails", group: [:development, :test]' >> Gemfile
$ bundle install
$ rails generate rspec:install