How to Test Your Gem Across Multiple Rails Versions

When developing a public Ruby gem, ensuring compatibility with various versions of Rails is crucial. Testing your gem against multiple Rails versions can prevent compatibility issues and build confidence in your code. A powerful tool for this task is **Appraisal**.

What is Appraisal?

Appraisal is a Ruby gem that simplifies testing your code against different dependencies. It works seamlessly with Bundler and allows you to define multiple gemsets (appraisal files), each created to a specific combination of dependencies (like Rails versions).

Setting Up Appraisal for Your Gem

Here’s a step-by-step guide to integrate Appraisal into your gem:

1. Add Appraisal to Your Gem

Include Appraisal in your `Gemfile` under the `development` group:

group :development do
  gem 'appraisal'
end

Run `bundle install` to install the gem.

2. Create an Appraisal File

Run the following command to initialize Appraisal:

bundle exec appraisal init

This generates an `Appraisals` file. Here, you define the Rails versions your gem will support. For example from tramway gem:

appraise 'rails-7.0' do
  gem 'rails', '~> 7.0.0'
  gem 'view_component', '< 4'
  gem 'sqlite3', '~> 1.4'
end

appraise 'rails-7.1' do
  gem 'rails', '~> 7.1.0'
  gem 'sqlite3', '~> 1.4'
end

appraise 'rails-7.2' do
  gem 'rails', '~> 7.2.0'
  gem 'sqlite3', '~> 1.4'
end

appraise 'rails-8.0' do
  gem 'rails', '~> 8.0.0'
  gem 'sqlite3', '>= 2.1'
end

3. Install Dependencies

Run the following command to install all appraised dependencies:

bundle exec appraisal install

This creates a `gemfiles/` directory with separate lockfiles for each gemset. Don’t forget to add gemfiles/*.lock to your .gitignore .

4. Run Tests with Appraisal

To run tests for all Rails versions, use for RSpec:

bundle exec appraisal rspec

Appraisal runs your test suite for each gemset defined in the `Appraisals` file.

5. Automate with CI

Integrate Appraisal with your CI/CD pipeline to automate testing across Ruby and Rails versions. For example, from tramway gem:

name: RSpec with Appraisal

on: [workflow_call]

jobs:
  rspec:
    strategy:
      fail-fast: false
      matrix:
        ruby: ['3.2', '3.3']
        appraisal: ['rails-7.0', 'rails-7.1', 'rails-7.2', 'rails-8.0']

    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: ${{ matrix.ruby }}
          bundler-cache: true

      - name: Install dependencies for Appraisal
        run: |
          bundle install --jobs 4 --retry 3 --path vendor/bundle
          bundle exec appraisal install

      - name: Precompile assets
        run: |
          bundle exec appraisal ${{ matrix.appraisal }} rails -C spec/dummy assets:precompile

      - name: Initialize db
        run: |
          bundle exec appraisal ${{ matrix.appraisal }} rails -C spec/dummy db:create db:migrate

      - name: Run RSpec tests
        run:
          bundle exec appraisal ${{ matrix.appraisal }} rspec

Conclusion

Appraisal is an essential tool for gem developers aiming to maintain compatibility with multiple Rails versions. By leveraging Appraisal, you can save time, automate testing, and ensure your gem is robust for a variety of Rails projects.