[Awesome Ruby Gem] Use appraisals gem to integrate the different versions of gem dependencies

Posted on Edited on In , , Views: Word count in article: 4.7k Reading time ≈ 4 mins.

appraisal

Appraisal integrates with bundler and rake to test your library against different versions of dependencies in repeatable scenarios called “appraisals.” Appraisal is designed to make it easy to check for regressions in your library without interfering with day-to-day development using Bundler.

Installation

You can install it as a gem:

1
$ gem install appraisal

or add it into a Gemfile (Bundler):

1
2
3
4
5
# Gemfile

# thoughtbot/appraisal: A Ruby library for testing your library against different versions of dependencies.
# https://github.com/thoughtbot/appraisal
gem 'appraisal', `2.4.0'

Then, run bundle install.

1
$ bundle install

Note that gems must be bundled in the global namespace. Bundling gems to a local location or vendoring plugins is not supported. If you do not want to pollute the global namespace, one alternative is RVM’s Gemsets - http://rvm.io/gemsets.

Setup

Setting up appraisal requires an Appraisals file (similar to a Gemfile) in your project root, named “Appraisals” (note the case), and some slight changes to your project’s Rakefile.

An Appraisals file consists of several appraisal definitions. An appraisal definition is simply a list of gem dependencies. For example, to test with a few versions of Rails:

1
2
3
4
5
6
7
8
9
# Appraisals

appraise "rails-3" do
  gem "rails", "3.2.14"
end

appraise "rails-4" do
  gem "rails", "4.0.0"
end

The dependencies in your Appraisals file are combined with dependencies in your Gemfile, so you don’t need to repeat anything that’s the same for each appraisal. If something is specified in both the Gemfile and an appraisal, the version from the appraisal takes precedence.

Usage

Once you’ve configured the appraisals you want to use, you need to install the dependencies for each appraisal:

1
$ bundle exec appraisal install

This will resolve, install, and lock the dependencies for that appraisal using bundler. Once you have your dependencies set up, you can run any command in a single appraisal:

1
$ bundle exec appraisal rails-3 rake test

This will run rake test using the dependencies configured for Rails 3. You can also run each appraisal in turn:

1
$ bundle exec appraisal rake test

If you want to use only the dependencies from your Gemfile, just run rake test as normal. This allows you to keep running with the latest versions of your dependencies in quick test runs, but keep running the tests in older versions to check for regressions.

In the case that you want to run all the appraisals by default when you run rake, you can override your default Rake task by put this into your Rakefile:

1
2
3
if !ENV["APPRAISAL_INITIALIZED"] && !ENV["TRAVIS"]
  task :default => :appraisal
end

(Appraisal sets APPRAISAL_INITIALIZED environment variable when it runs your process. We put a check here to ensure that appraisal rake command should run your real default task, which usually is your test task.)

Note that this may conflict with your CI setup if you decide to split the test into multiple processes by Appraisal and you are using rake to run tests by default. Please see Travis CI Integration for more detail.

Commands

1
2
3
4
5
6
7
appraisal clean                  # Remove all generated gemfiles and lockfiles from gemfiles folder
appraisal generate               # Generate a gemfile for each appraisal
appraisal help [COMMAND]         # Describe available commands or one specific command
appraisal install                # Resolve and install dependencies for each appraisal
appraisal list                   # List the names of the defined appraisals
appraisal update [LIST_OF_GEMS]  # Remove all generated gemfiles and lockfiles, resolve, and install dependencies again
appraisal version                # Display the version and exit

Under the hood

Running appraisal install generates a Gemfile for each appraisal by combining your root Gemfile with the specific requirements for each appraisal. These are stored in the gemfiles directory, and should be added to version control to ensure that the same versions are always used.

When you prefix a command with appraisal, the command is run with the appropriate Gemfile for that appraisal, ensuring the correct dependencies are used.

Removing Gems using Appraisal

It is common while managing multiple Gemfiles for dependencies to become deprecated and no longer necessary, meaning they need to be removed from the Gemfile for a specific appraisal. To do this, use the remove_gem declaration within the necessary appraise block in your Appraisals file.

Example Usage

1
2
3
4
5
6
7
8
# Gemfile

gem 'rails', '~> 4.2'

group :test do
  gem 'rspec', '~> 4.0'
  gem 'test_after_commit'
end

Appraisals file

1
2
3
4
5
6
7
8
9
# Appraisals

appraise 'rails-5' do
  gem 'rails', '~> 5.2'

  group :test do
    remove_gem :test_after_commit
  end
end

Using the Appraisals file defined above, this is what the resulting Gemfile will look like:

1
2
3
4
5
6
7
# gemfiles/rails-5.gemfile

gem 'rails', '~> 5.2'

group :test do
  gem 'rspec', '~> 4.0'
end

Version Control

When using Appraisal, we recommend you check in the Gemfiles that Appraisal generates within the gemfiles directory, but exclude the lockfiles there (*.gemfile.lock).

References

[1] thoughtbot/appraisal: A Ruby library for testing your library against different versions of dependencies. - https://github.com/thoughtbot/appraisal

[2] appraisal | RubyGems.org | your community gem host - https://rubygems.org/gems/appraisal