You can install ABQ locally on OS X using homebrew.
brew install rwx-research/tap/abq
We do not currently have packages available for other operating systems. Please let us know if you'd like to install ABQ locally on Linux.
To run ABQ locally, you'll need to configure your test framework using the same configuration you need when running ABQ on CI.
Once your test framework is configured, you can use ABQ to parallelize your test suite when running it locally.
Although ABQ is designed to run in a distributed network, when running the
abq test command locally, ABQ will start an
ephemeral queue and one or more workers locally.
The command can be invoked with any native test command, similar to how its used on CI.
abq test -- any test command goes here
For example with RSpec:
abq test -- bundle exec rspec
abq test will only run a single worker. You can set the number of workers by passing the
-n option. For example, to run two workers:
abq test -n 2 -- any test command goes here
If you'd like to run one worker per CPU core available, you can pass
You can see a full list of commands by running
abq help and a full list of arguments to
abq test by running
abq test --help.
Depending on your native test suite, you may need an environment variable to differentiate test processes.
For example, it's common in some frameworks to set up separate databases for each parallel test process.
ABQ will set an
ABQ_RUNNER environment variable that contains an integer sequence starting from 1.
For example, in a project that needs
TEST_ENV_NUMBER set to run tests in parallel, ABQ can be invoked like this:
abq test -n 2 -- bash -c 'TEST_ENV_NUMBER=$ABQ_RUNNER bundle exec rspec'
Occasionally it's useful to replay a remote test run locally.
We can achieve this by running ABQ with a personal access token. To generate a personal access token, perform the following:
- Navigate to your Personal Access Tokens settings page
- Log in to RWX
- From the hamburger navigation menu, select "Manage user"
- Click on "Personal Access Tokens" on the menu on the left
- Click "New Personal Access Token"
- Choose the organization you'd like to scope your personal access token to (if there are multiple)
- Enter a description, such as "Sally's GitHub Actions Token"
- Click "Create personal access token"
- Copy the Access Token
You may provide the abq command with your personal access token via the environment variable
RWX_ACCESS_TOKEN, as a
command line flag
--access-token, or by using the
abq login command to store a local configuration file.
After doing this, invoke
abq test --run-id <EXISTING_RUN_ID> --worker <WORKER> --num <NUM> to replay your remote run
on that worker and runner locally.
abq report list-tests --run-id <EXISTING_RUN_ID> --worker <WORKER> --num <NUM> to
list which tests were run in what order on that worker & runner.