👋 Email us at [email protected] with questions or feedback. We'd love to hear from you. If you have an account with RWX, view your support page for access to support via Slack.

Getting Started with ABQ

ABQ is a universal test runner with support for distributing test suites across multiple machines. It uses a message queue to distribute the tests, ensuring that tests are as evenly distributed as possible.

We currently only support installing the ABQ binary on GitHub Actions, and we've only published integration bindings for RSpec. We're working on supporting additional CI providers and testing frameworks. Please let us know if you'd like to request a specific integration.

Access Token

You'll need an access token set in an environment variable named RWX_ACCESS_TOKEN.

Installing the CLI

You can use the setup-abq action to install the ABQ CLI.

- uses: rwx-research/setup-[email protected]
  with:
    access-token: ${{ secrets.RWX_ACCESS_TOKEN }}

Configuring RSpec

You'll need the rspec-abq gem to run your RSpec test suite with ABQ. Add rspec-abq to your Gemfile. Commonly, it's added under a test group.

group :test do
  gem "rspec-abq"
end

Run bundle install after updating your Gemfile.

Most likely, your project will be configured to automatically require all of the gems listed in your Gemfile. However, if your project isn't configured that way, you'll need to add require "rspec-abq" at the top of your spec_helper.rb file.

Running ABQ in GitHub Actions

ABQ has two commands: abq test will facilitate running a test suite and will report the results. abq work will run a worker that executes individual tests and reports the result back to the abq test process.

Since all of the work happens in abq work, that's where you'll need to set up your project. abq test needs very little configuration. It doesn't even need actions/checkout.

The easist way to migrate from running RSpec directly to running RSpec via ABQ is to convert your existing RSpec job into the abq work job, and then add a new abq test job. You'll need to move the actual command to execute your tests into abq test, but otherwise all of your project configuration can stay with abq work.

abq test

Here's a full example of configuring an abq test job.

abq-test:
  runs-on: ubuntu-latest
  steps:
    - uses: rwx-research/setup-[email protected]
      with:
        access-token: ${{ secrets.RWX_ACCESS_TOKEN }}
    - name: abq test
      run: abq test -- bundle exec rspec
      env:
        RWX_ACCESS_TOKEN: ${{ secrets.RWX_ACCESS_TOKEN }}

You can pass any command after the double hyphen that you want. For example, if you have other rspec flags that you're using, you could call:

abq test -- bundle exec rspec --tag integration

abq work

The abq work command will pick up tests from the queue and execute them. You'll need to configure this job with all of the setup necessary to run your tests.

You can use GitHub's matrix configuration to decide how much you want to parallelize your test suite.

abq-work:
  runs-on: ubuntu-latest
  strategy:
    fail-fast: false
    matrix:
      shard: [1, 2]
  steps:
    - uses: actions/[email protected]
    - uses: rwx-research/setup-[email protected]
      with:
        access-token: ${{ secrets.RWX_ACCESS_TOKEN }}
    - uses: ruby/setup-[email protected]
      with:
        bundler-cache: true
    - run: abq work
      env:
        RWX_ACCESS_TOKEN: ${{ secrets.RWX_ACCESS_TOKEN }}

abq work for Rails

Here's an example of what the abq work job may look like for a Rails project.

abq-work:
  runs-on: ubuntu-latest
  strategy:
    fail-fast: false
    matrix:
      shard: [1, 2]
  services:
    postgres:
      image: postgres:14.4
      ports:
        - "5432:5432"
      env:
        POSTGRES_USER: postgres
        POSTGRES_PASSWORD: password
      options: >-
        --health-cmd pg_isready
        --health-interval 1s
        --health-timeout 1s
        --health-retries 30
  env:
    RAILS_ENV: test
  steps:
    - uses: actions/[email protected]
    - uses: rwx-research/setup-[email protected]
      with:
        access-token: ${{ secrets.RWX_ACCESS_TOKEN }}
    - uses: ruby/setup-[email protected]
      with:
        bundler-cache: true
    - run: bin/rails db:create
    - run: bin/rails db:schema:load
    - run: bundle exec rake assets:precompile
    - run: abq work
      env:
        RWX_ACCESS_TOKEN: ${{ secrets.RWX_ACCESS_TOKEN }}