Running tests

Most Ruby libraries contain code to test the functionality provided by the library and compare results with known inputs. It is recommended that these tests are run during the package building so that the functionality of the package may be confirmed. There are many testing frameworks available in Ruby, the leading ones in usage being RSpec and Minitest.

Recent versions of gem2deb automatically identifies the Testing framework, and create debian/ruby-tests.rake file automatically to run the tests. This is done by analysing the test or spec directory present in the upstream source.

Note: If the gem uses some other Test framework for running tests, you may have to replace debian/ruby-tests.rake with debian/ruby-tests.rb and fix that properly.

Upstream gem file doesn't contain tests

Chances are there the upstream developers didn't include the tests they use in the gem file they provide. This is justified by the fact that end users doesn't often require and bother to run theses tests. There are two scenarios associated with this - tests are present in upstream code repository, tests are nowhere available.

Upstream repo contains the tests

If the upstream repo contains the tests and it is only the gem file that is missing them, the solution is pretty simple. Instead of using the gem file from the Rubygems, we provide the tarball that is provided in the upstream repo. The steps are (taking the gem akismet as example)

1. Download the tarball provided by upstream. Most of the Ruby libraries are hosted in Github and they provide tarballs from their releases page. They can be downloaded from there. For example,

$ wget https://github.com/jonahb/akismet/archive/v2.0.0.tar.gz

2. Rename the tarball to <gemname>-<version>.tar.gz

$ mv v2.0.0.tar.gz akismet-2.0.0.tar.gz

3. Run gem2deb <tarball name>

$ gem2deb akismet-2.0.0.tar.gz

4. Change watch file inside debian/directory to point to the upstream location as specified in debian/watch

5. Continue as you do for normal package from step 3.1 of packaging

No tests are available, even in the upstream repo

If the upstream doesn't provide any tests, even in their repo, you can either

1. file a bug upstream to add necessary tests or

2. if you are knowledgable about the gem you can write your own tests, add them as patch and forward to upstream so that they can also use it.

Test Failures

Identifying and fixing test failures require knowledge about the programming language, how tests are written, how they are invoked, how they interact with each other etc and can not be generalized in a document. However, the following are some of the general issues that may arise during packaging.

Tests reporting that a library/gem is missing

The symptom of this failure is an error message similar to the following in the test logs

no such file to load -- <gem name> (LoadError), 

Example:

no such file to load -- shoulda (LoadError), 

This error means the test suite was unable to find out the specified gem in your system and thus load it. So, you will have to install it in your system. For that, first check if that gem is packaged using

$ apt-cache search ruby-shoulda

and if it is packaged, install it. If the gem is not packaged, you will have to first package that gem and come back to the current one.

Tests suggesting to run bundle install

Sometimes, running tests may show error messages like

Could not find gem <gem name> in the gems available on this machine.
Run `bundle install` to install missing gems.

This is because, the tests have specified to use bundler, the package management system of Ruby, for detecting and using the gems. However, in Debian we have apt to do that job and thus the usage of bundler should be removed. For that, 1. Find out the usage of bundler in spec or test folder

$ grep -iR "bundler" test (or spec, based on the directory structure

The normal locations of these statements are the helper.rb, test_helper.rb or spec_helper.rb files.

2. Use quilt to comment out/remove those references

Tests saying <:locale> is not a valid locale

Sometimes, the tests fail and the error message is similar to

I18n::InvalidLocale: :en is not a valid locale

This is caused due to API issues in new versions of the i18n gem. To solve this, use quilt and patch test_helper.rb (or the similar file available) and add the following line in which we explicitly specify the available locales

I18n.config.available_locales = :en

If multiple locales are reporting the error, add them as a comma seperated list

Example:

I18n.config.available_locales = :en, :de, :xx