Skip to main content

Ruby

This guide will help build Ruby projects on Semaphore.

Overview​

The Ruby interpreters are pre-installed in the Linux and macOS Semaphore environments. You can switch the active interpreter using sem-version. You may also use Docker images.

How to select Ruby versions​

Change the active Ruby versions on Linux and macOS with sem-version. This command ignores .ruby-versions

sem-version ruby 3.2.2

Semaphore uses rbenv to switch versions for Ruby. The available Ruby versions depend on the OS image you're using. You can check the available Ruby versions by executing the following command inside a Semaphore job:

rbenv install --list

Using Docker containers​

The sem-version tool does not work on Docker containers. You must use a pre-built Docker image with the language versions you need and run the job using Docker environments.

You can use the pre-build Ruby images or build your own. Find Dockerfiles to build your custom images in the semaphoreci/docker-images repository.

How to cache Gems​

To cache downloaded Gems, you must download them to the vendor/bundle folder relative to the current directory.

So, the first job on the pipeline should contain the following commands:

checkout
cache restore
bundle install --deployment --path vendor/bundle
cache store

All successive jobs can reuse Gems from the cache with:

checkout
cache restore
bundle install --deployment --path vendor/bundle

How to set up test reports​

This section explains how to set up test reports (and flaky tests) for Ruby and RSpec.

  1. Install the rspec_junit_formatter Gem in your project. Add the following line to Gemfile

    gem "rspec_junit_formatter", :group => [:test]

  2. Install the dependencies

    bundle install

  3. Configure RSpec to use the Gem. This can be achieved in two ways:

    • Extending .rspec file configuration like this:

      --format RspecJunitFormatter
      --out junit.xml
      --format documentation

    • Or, changing the rspec invokation

      bundle exec rspec --format RspecJunitFormatter --out junit.xml --format documentation

  4. Follow Step 3 for every job in your pipeline that executes tests

  5. Create an after_pipeline job with the following command:

    test-results publish junit.xml
Example pipeline definition
Using test reports on Ruby
- name: Tests
  task:
    prologue:
      commands:
        - checkout
        - cache restore
        - bundle install --deployment --path vendor/bundle
        - cache store

    job:
      name: "Tests"
      commands:
        - checkout
        - cache restore
        - bundle install --deployment --path vendor/bundle
        # Or bundle exec rspec if using .rspec configuration file
        - bundle exec rspec --format RspecJunitFormatter --out junit.xml --format documentation

    epilogue:
      always:
        commands:
          - test-results publish junit.xml

How to parallelize tests​

You can run RSpec and Cucumber tests in parallel automatically using job parallelism.

For RSpec, follow these steps:

  1. Enable job parallelism

  2. Change your test command in the CI to:

    gem install semaphore_test_boosters
    rspec_booster --job $SEMAPHORE_JOB_INDEX/$SEMAPHORE_JOB_COUNT

On Cucumber, we use cucumber_booster instead:

  1. Enable job parallelism

  2. Change your test command in the CI to:

    gem install semaphore_test_boosters
    cucumber_booster --job $SEMAPHORE_JOB_INDEX/$SEMAPHORE_JOB_COUNT