# Configuration file reference

TURBO TEST uses a TOML (Tom's Obvious Minimal Language) configuration file for customising and controlling how your tests are run on Ubuntu 22.04.3 LTS servers.

The configuration file is divided into four parts:


`[base_image]`	Commands run once to install and configure apt packages
`[before_test_run]`	Commands run before every test run
`[cache]`	A list of directories to cache dependencies between test runs
`[test_run.default]`	An executable command and list of files to run groups tests

The minimum requirements for a valid configuration are:

.turbo_test.toml file present at the root of the project directory
valid TOML syntax
at least one test run
test runs specify an executable command
test runs specify at least one file glob used to execute your test files
package setup commands execute successfully
suite setup commands execute successfully

Here's an example configuration for a Ruby on Rails project.

.turbo_test.toml
# The top level env specifies environment variables available globally.
# Environment variables are specified as key/value pairs.
[env]
RAILS_ENV=test

# A string specifying the command which executes one test file.
#
# This is where you install required programming languages, databases and other
# supporting libraries.
#
# Your repository source code is available in the /src directory.
#
# The installation is cached as a virtual machine image for subsequent test
# runs. When the install section changes, the virtual machine image is
# re-created.
 #
# Installation commands are specified as a TOML multi-line string.
#
# N.B. Shell commands MUST execute non-interactively. For example, commands
# requiring user input will hang until the test run is cancelled or after a
# 15 minute timeout.
#
# You can find an overview of the configuration, packages and services available
# in the TURBO TEST Ubuntu 22.04 LTS environment here:
# http://turbo-test.com/installing_dependencies/ubuntu_2204_lts_environment

# The default ruby version mananger is chruby.
# You can find the TURBO TEST Ubuntu 22.04 LTS ruby installation script here:
# https://github.com/turbotest/ubuntu_2204_LTS/blob/main/install/ruby.sh

[base_image]
commands = '''
sudo apt update -y

# Install extra packages not already included in the base image
# sudo DEBIAN_FRONTEND=noninteractive apt install --no-install-recommends -yq \
#   EXTRA_APT_PACKAGES

nvm use 20
chruby 3.3.0
bundle install

# (!) Re-build the operating system image by adding a adding a new UUID:
# clear-cache: 45f09fa5-5431-4319-8081-218fe9debf9e
'''

# (!) If you're using importmaps, you can delete node_modules / .nvm / yarn
[cache]
directories = [ "vendor/bundle", "node_modules", "/home/ubuntu/.nvm", "/home/ubuntu/.cache/yarn" ]

# The before_test_run definition specifies commands to execute before running
# your test runs.
#
# Unlike the base_image definition, before_test_run is not cached and executes
# on every test run.
#
# Use this definition to:
# - update project dependencies
# - compile classes
# - start operating system services
[before_test_run]
commands = '''
# Uncomment services needed for your project:
# sudo systemctl start elasticsearch
# sudo systemctl start memcached
# sudo systemctl start mysql
# sudo systemctl start postgresql@15-main.service
# sudo systemctl start postgresql@16-main.service
# sudo systemctl start rabbitmq
# sudo systemctl start redis

bundle install
bundle exec rails db:setup
bundle exec rails assets:precompile # May be required for UI tests
'''

# Test runs are inferred from each TOML key starting with test_run.
#
# Specify multiple test runs by adding test_run keys. For example:
# [test_run."system tests"]
# [test_run.integration]
#
# Create a default test_run if you only require one test run.
[test_run.default]

# A string specifying the command which executes one test file.
#
# The test file is passed as the last argument to the command.
command = "bundle exec rails test"

# Uncomment the line below if your project uses the Rspec testing framework.
# command = "bundle exec rspec"

# An array of file path globs which expands to a list of files. File paths are
# relative to the project directory.
#
# Each file is passed as the last argument to your test command.
# Default Rails test
files = ["test/**/*_test.rb"]

# Uncomment the line below if your project uses the Rspec testing framework.
# files = ["test/**/*_spec.rb"]

# An array of file path globs which expands to a list of files. File paths are
# relative to the project directory.
#
# No tests will be executed with any files matched in this definition section.
ignore = [
  "test/models/IGNORE_test.rb"
]

# Create additional test runs when the command or files are different to the
# default test run. For example:
#
# [test_run.cucumber]
# command = "bundle exec cucumber"
# files = ["features/**/*.feature"]

# `env`

Encrypted environment variables created in the web UI override variables specified in the configuration file.

The top level env specifies environment variables available globally. Environment variables are specified as key/value pairs.

.turbo_test.toml
[env]
RAILS_ENV = "test"

In the example above, RAILS_ENV is set to "test" and available from the operating system as $RAILS_ENV :

$ echo $RAILS_ENV
test

# `[base_image]`

This section contains the commands needed to create a virtual machine capable of running your tests. This is where you install required programming languages, databases and other supporting libraries.

N.B

Shell commands MUST execute non-interactively. For example, any commands that require user input will hang until the test run is cancelled or after a 15 minute timeout.

The base image is cached as a virtual machine image for subsequent test runs. When the install section changes, the virtual machine image is re-created.

The base image commands are specified as a TOML multi-line string. For example:

.turbo_test.toml
[base_image]
commands = '''
sudo apt update -y
sudo apt install -y build-essential gcc g++ make cmake pkg-config
'''

The repository source code is available in the /src directory. If you cd into a different directory, don't forget to cd back to the /src directory to access your project code.

# `[before_test_run]`

This section specifies commands to execute before running your test runs. Use the setup definition to update your project dependencies or compile classes.

For example, in a Ruby on Rails project this is where you update dependencies and run migrations.

.turbo_test.toml
[before_test_run]
commands = '''
bundle install
bundle exec rails db:migrate
'''

Unlike the [base_image] section, [before_test_run] commands are not cached and execute on every test run.

# `[cache]`

This section specifies directories to persist between test runs.

It accepts a string or array of file path globs which expands to a list of files. File paths are relative to the project directory.

For instance, the Ruby package manager bundler uses the vendor directory to tore store and load gem bundles and configurations.

.turbo_test.toml
[cache]
directories = ["vendor"]

# `[test_run.default]`

This section defines the default test run and is divided into four parts:

--- | --- command | The command to run the tests files | An array of UNIX file globs are executed as the last argument to the command above ignore | An array of UNIX file globs specifies files to ignore during testing env | Environment variables local to this test run (optional)

Here's a Ruby on Rails test run configuration:

.turbo_test.toml
[test_run.default]
command = "bundle exec rails test"
files   = ["test/**/*_test.rb"]
ignore  = ["test/application_system_case.rb", "test/test_helper.rb"]

# env

Environment variables specified in the test run definition override global environment variables.

# command

A string specifying the command which executes one test file. For example, to execute tests in a rails project:

.turbo_test.toml
[test_run.default]
command = "bundle exec rails test"

The test file is passed as the last argument to the command. In the above example, the command will be executed with a file:

bundle exec rails test test/models/user_test.rb

If your test command needs to pass in the file as a positional argument (i.e. not the last argument), you'll need to create a shell script which:

accepts a file name
executes the test command with the script argument in the correct position for the executable command

For example:

.turbo_test.toml .turbo_test.toml
[test_run.default]
command = "./bin/test"
files   = ["test/**/*_test.rb"]

./bin/test
test-command $1 --extra-args --must-be --at-the-end

# files

A string or array of file path globs which expands to a list of files. File paths are relative to the project directory.

Each file is passed as the last argument to your test command. Given the following configuration:

.turbo_test.toml
[test_run.default]
command = "bundle exec rails test"
files = "test/models/**/*_test.rb"

All of your tests will be executed concurrently as follows:

bundle exec rails test test/models/user_test.rb
bundle exec rails test test/models/signup_test.rb
bundle exec rails test test/models/billing_test.rb
# More test files ...

Bash globstar is enabled

You can use the ** expansion to specify all files including all subdirectories.

For example in a Ruby on Rails project, you should specify all files ending with _test.rb in the test/ directory:

.turbo_test.toml
[test_run.default]
files = "test/**/*_test.rb"

For a refresher, check out the Wikipedia entry on UNIX style file globs.

# ignore

A string or array of file path globs which expands to a list of files. File paths are relative to the project directory.

No tests will be executed with files matched in this definition section.

In the following example, helper files are ignored as they are not executable commands.

.turbo_test.toml
[test_run.default]
files   = ["test/**/*_test.rb"]
ignore  = ["test/application_system_case.rb", "test/test_helper.rb"]

# [test_run.X]

In addition to the default test run, you can define other test runs by replacing default with the desired suite name.

For instance, to create a test run specifically to run Ruby on Rails system tests:

.turbo_test.toml
[test_run."system tests"]
command = "bundle exec rails test"
files   = ["test/system/**/*_test.rb"]
ignore  = ["test/application_system_case.rb", "test/test_helper.rb"]

# Secrets

You may not want to store credentials such as API keys in the configuration file. Please read the following page to add secrets from the web UI:

Add Secrets

../managing_secrets/

# Configuration file reference

# env

# [base_image]

N.B

# [before_test_run]

# [cache]

# [test_run.default]

# env

# command

# files

Bash globstar is enabled

# ignore

# [test_run.X]

# Secrets

# `env`

# `[base_image]`

# `[before_test_run]`

# `[cache]`

# `[test_run.default]`