RSpec

A guide for generating Trunk-compatible test reports for RSpec using Trunk’s RSpec plugin

You can automatically detect and manage flaky tests in your projects running RSpec by integrating with Trunk. This document explains how to use Trunk’s RSpec plugin to upload test results to Trunk.

Checklist

By the end of this guide, you should achieve the following before proceeding to the next steps to configure your CI provider.

• Set up and installed Trunk’s RSpec plugin
• Disable retries for better detection accuracy
• Test uploads locally

Using the plugin is the best way to accurately detect flaky RSpec tests.

You can also manually generate and upload test results in RSpec, however, manual RSpec uploads are not recommended.

Installing the plugin

Trunk detects flaky tests by analyzing test reports automatically uploaded from your CI jobs. You can do this for your Rspec tests using Trunk’s RSpec plugin.

To install the plugin in your project, add the rspec_trunk_flaky_tests gem to your Gemfile:

gem "rspec_trunk_flaky_tests"

Install the plugin:

bundle install

Then, load the plugin in spec_helper.rb:

require "trunk_spec_helper"

Disable Retries

You need to disable automatic retries if you previously enabled them. Retries compromise the accurate detection of flaky tests.

If you have a step in CI to rerun failed tests with the --only-failures option, or you’re using a package like rspec-retry, remember to disable them.

Versions and Updating the Plugin

You can find the Gem for rspec_trunk_flaky_tests here, along with its version history. This plugin is periodically updated for more robust support and bug fixes, and if you’re encountering something unexpected, we first encourage you to:

bundle update rspec_trunk_flaky_tests

Environment Variables

These optoinal environment variables can be set in your project to change the behavior of the RSpec plugin.

Repository metadata variables:

Argument	Description
TRUNK_REPO_ROOT	Path to repository root
TRUNK_REPO_URL	Repository URL (e.g., https://github.com/org/repo.git)
TRUNK_REPO_HEAD_SHA	HEAD commit SHA
TRUNK_REPO_HEAD_BRANCH	HEAD branch name
TRUNK_REPO_HEAD_COMMIT_EPOCH	HEAD commit timestamp (seconds since epoch)
TRUNK_REPO_HEAD_AUTHOR_NAME	HEAD commit author name

Configuration variables:

Argument	Description
TRUNK_CODEOWNERS_PATH	Path to CODEOWNERS file
TRUNK_VARIANT	Variant name for test results (e.g., ‘linux’, ‘pr-123’)
TRUNK_DISABLE_QUARANTINING	Set to ‘true’ to disable quarantining
TRUNK_ALLOW_EMPTY_TEST_RESULTS	Set to ‘true’ to allow empty results
TRUNK_DRY_RUN	Set to ‘true’ to save bundle locally instead of uploading
TRUNK_USE_UNCLONED_REPO	Set to ‘true’ for uncloned repo mode
TRUNK_LOCAL_UPLOAD_DIR	Directory to save test results locally (disables upload)
DISABLE_RPSEC_TRUNK_FLAY_TESTS	Set to ‘true’ to completely disable Trunk

Try It Locally

Test Upload

Before modifying your CI jobs to automatically upload test results to Trunk, try uploading a single test run manually.

You make an upload to Trunk using the following command:

TRUNK_ORG_URL_SLUG=<TRUNK_ORG_URL_SLUG> \
TRUNK_API_TOKEN=<TRUNK_ORG_TOKEN> \
bundle exec rspec

You can find your Trunk organization URL slug and token in the Settings or by following these instructions.

After your upload, you can verify that Trunk has received and processed it successfully in the Uploads tab. Warnings will be displayed if the test report uploaded by the plugin has issues.

You do not need to download the trunk-analytics-cli when using the Trunk RSpec plugin. Uploads are handled for you as long as you have set TRUNK_ORG_URL_SLUG and TRUNK_API_TOKEN.

Next Steps

Configure your CI to upload test runs to Trunk. Find the guides for your CI framework below:

Atlassian Bamboo		atlassian-bamboo
Azure DevOps Pipelines		azure-devops-pipelines	azure.png
BitBucket Pipelines		bitbucket-pipelines	bitbucket.png
BuildKite		buildkite	buildkite.png
CircleCI		circleci	circle-ci.png
Drone CI		droneci	drone.png
GitHub Actions		github-actions	github.png
Gitlab		gitlab	gitlab.png
Jenkins		jenkins	jenkins.png
Semaphore		semaphoreci	semaphore.png
TeamCity		https://github.com/trunk-io/docs/blob/main/.gitbook/includes/broken-reference/README.md	teamcity.png
Travis CI		travisci	travis.png
Other CI Providers		otherci	other.png