---
title: Test Impact Analysis for Ruby
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > Test Optimization in Datadog > Test Impact Analysis > Configure Test
  Impact Analysis > Test Impact Analysis for Ruby
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Test Impact Analysis for Ruby

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

## Compatibility{% #compatibility %}

Test Impact Analysis is only supported in the following versions and testing frameworks:

- `datadog-ci >= 1.0`
- `Ruby >= 2.7`
- `rspec >= 3.0.0`
- `minitest >= 5.0.0`
- `cucumber >= 3.0.0`

## Setup{% #setup %}

### Test Optimization{% #test-optimization %}

Prior to setting up Test Impact Analysis, set up [Test Optimization for Ruby](https://docs.datadoghq.com/tests/setup/ruby.md). If you are reporting data through the Agent, use v6.40 and later or v7.40 and later.

### Activate Test Impact Analysis for the test service{% #activate-test-impact-analysis-for-the-test-service %}

You, or a user in your organization with the **Intelligent Test Runner Activation** (`intelligent_test_runner_activation_write`) permission, must activate Test Impact Analysis on the [Test Service Settings](https://app.datadoghq.com/ci/settings/test-service) page.

## Run tests with Test Impact Analysis enabled{% #run-tests-with-test-impact-analysis-enabled %}

After completing setup, run your tests as you normally do.

## Known limitations{% #known-limitations %}

Test Impact Analysis uses code coverage data to determine whether or not tests should be skipped. In certain situations, code coverage data alone is not enough to determine whether to skip a test.

### Coverage limitations{% #coverage-limitations %}

The following limitations apply to how code coverage is collected:

- **Non-Ruby files are not tracked by default**: Changes to non-Ruby files such as fixtures, YAML configuration, i18n translation files, or other data files are not detected by code coverage. Tests that read data from these files may be incorrectly skipped when these files change.
- **Suite-level hooks**: Code coverage for suite-level hooks (for example, `before(:all)` or `before(:context)` in RSpec) is attributed to the entire test suite rather than individual tests. This may affect skip decisions for tests that depend on setup performed in these hooks.
- **Forked processes**: Per-test code coverage only collects coverage for the main process. Tests that spawn child processes or use forked execution do not have coverage collected for code running in those processes.

### External dependencies{% #external-dependencies %}

Tests that interact with external systems may be incorrectly skipped:

- Tests that make calls to external APIs or services (such as remote REST APIs)
- Tests that run external processes or shell commands
- Tests that depend on global shared state (for example, caches, databases, or files created by a different test or process)

### Recommendations{% #recommendations %}

When you encounter these limitations, consider the following approaches:

- **Mark tests as unskippable**: For tests that make external calls, fork processes, or depend on global shared state, mark them as unskippable so they always run.
- **Add custom impacted files**: If you can determine which non-Ruby files affect a test or suite, associate those files with the test or suite. When one of the files changes, Test Impact Analysis runs the associated tests instead of running the entire test set.
- **Configure tracked files**: If a non-Ruby file can affect many tests and you cannot associate it with specific tests or suites, add the file to your [tracked files configuration](https://docs.datadoghq.com/tests/test_impact_analysis.md#tracked-files). This causes all tests to run when the file changes.

## Add custom impacted files{% #add-custom-impacted-files %}

Custom impacted files are supported in `datadog-ci >= 1.36.0`.

Ruby code coverage cannot observe files executed outside the Ruby process. For example, a Capybara test can load JavaScript, TypeScript, or templates in a browser. If one of these files changes without a covered Ruby file changing, Test Impact Analysis might skip a test that the change affects.

Register these dependencies as custom impacted files to associate them with a test or suite. This gives Test Impact Analysis more complete coverage data while preserving test-skipping savings for unrelated tests.

### Add files for a test{% #add-files-for-a-test %}

Call `Datadog::CI.active_test.add_impacted_files` from a `before` or `after` hook. Use this API for files that affect an individual test. The following RSpec example registers frontend files collected from the browser:

```ruby
RSpec.configure do |config|
  config.after do
    loaded_frontend_files = javascript_files_loaded_by_browser.map do |path|
      File.expand_path(path, Dir.pwd)
    end

    Datadog::CI.active_test&.add_impacted_files(loaded_frontend_files)
  end
end
```

### Add files for a suite{% #add-files-for-a-suite %}

Call `Datadog::CI.active_test_suite.add_impacted_files` for files that affect every test in a suite, such as shared frontend setup:

```ruby
RSpec.configure do |config|
  config.before(:context) do
    Datadog::CI.active_test_suite&.add_impacted_files(
      [
        "app/frontend/test_setup.js",
        "app/frontend/components/shared_layout.tsx"
      ]
    )
  end
end
```

Test Impact Analysis uses test-level skipping by default. In this mode, add suite-level files before the first test in the suite starts. For RSpec, use a `before(:context)` hook. Adding suite-level files after a test starts raises a `RuntimeError`.

### File path requirements{% #file-path-requirements %}

Pass an array of paths to `add_impacted_files`. Each call adds files to those already registered. Datadog removes duplicate paths when it sends the coverage data.

Paths must resolve inside the Git repository and use one of these formats:

- A relative path from the repository root, such as `app/frontend/components/checkout.tsx`.
- An absolute path to a file inside the repository.

Paths must not contain redundant `.` or `..` segments. If a collector returns paths relative to the process working directory, convert them to normalized absolute paths with `File.expand_path(path, Dir.pwd)`. Datadog ignores absolute paths outside the repository. Files do not need to exist when you register them.

## Rails system tests{% #rails-system-tests %}

Test Impact Analysis supports Rails system tests that use `ActionDispatch::SystemTestCase` or `ApplicationSystemTestCase`, as long as the server runs in the same process as the test code. This is the default behavior in Rails system tests.

## Unskippable tests{% #unskippable-tests %}

You can override the Test Impact Analysis's behavior and prevent specific tests from being skipped. These tests are referred to as unskippable tests.

### Marking tests as unskippable{% #marking-tests-as-unskippable %}

{% tab title="RSpec" %}
To prevent RSpec from skipping tests in a specific block, add the metadata key `datadog_itr_unskippable` with the value `true`. Add the key to any `describe`, `context`, or `it` block. This marks all tests in that block as unskippable.

```ruby
# mark the whole file as unskippable
RSpec.describe MyClass, datadog_itr_unskippable: true do
  describe "#my_method" do
    context "when called without arguments" do
      it "works" do
      end
    end
  end
end

# mark one test as unskippable
RSpec.describe MyClass do
  describe "#my_method" do
    context "when called without arguments" do
      it "works", datadog_itr_unskippable: true do
      end
    end
  end
end

# mark specific block as unskippable
RSpec.describe MyClass do
  describe "#my_method", datadog_itr_unskippable: true do
    context "when called without arguments" do
      it "works" do
      end
    end
  end
end
```

{% /tab %}

{% tab title="Cucumber" %}
To mark an entire feature file as unskippable in Cucumber, use the `@datadog_itr_unskippable` tag. This prevents Test Impact Analysis from skipping any of the scenarios defined in that feature file.

To make only specific scenarios unskippable, apply this tag directly to the desired scenario.

```ruby
@datadog_itr_unskippable
Feature: Unskippable feature
  Scenario: Say greetings
    When the greeter says greetings
    Then I should have heard "greetings"

Feature: An unskippable scenario

  @datadog_itr_unskippable
  Scenario: Unskippable scenario
    When the ITR wants to skip this scenario
    Then it will never be skipped

  Scenario: Skippable scenario
    When the ITR wants to skip this scenario
    Then it will be skipped
```

{% /tab %}

{% tab title="Minitest" %}
To make an entire Minitest subclass unskippable, use the `datadog_itr_unskippable` method. If you want to mark specific tests within the subclass as unskippable, provide the names of these test methods as arguments to the `datadog_itr_unskippable` method call.

```ruby
# mark the whole class unskippable
class MyTest < Minitest::Test
  datadog_itr_unskippable

  def test_my_method
  end
end

# here only test1 and test2 are unskippable
class MyTest < Minitest::Test
  datadog_itr_unskippable "test1", "test2"

  def test1
  end

  def test2
  end

  def test3
  end
end
```

{% /tab %}

### Temporarily disabling Test Impact Analysis{% #temporarily-disabling-test-impact-analysis %}

Test Impact Analysis can be disabled locally by setting the `DD_CIVISIBILITY_ITR_ENABLED` environment variable to `false` or `0`.

{% dl %}

{% dt %}
`DD_CIVISIBILITY_ITR_ENABLED` (Optional)
{% /dt %}

{% dd %}
Enable the Test Impact Analysis coverage and test skipping features **Default**: `(true)`
{% /dd %}

{% /dl %}

## Further Reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Explore Test Results and Performance](https://docs.datadoghq.com/tests.md)
- [Troubleshooting Test Optimization](https://docs.datadoghq.com/tests/troubleshooting.md)