<commit_before># Ruby Collectors

<div class="Docs__wip-note">
<p class="Docs__wip-heading">Test Analytics is an invite-only beta feature. Join the <a href="https://buildkite.com/test-analytics">waitlist</a>.</p>
</div>

The beta release of Test Analytics ships with RSpec collector. You you can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).

## RSpec collector

[RSpec](https://rspec.info/) is a behaviour-driven development library for Ruby.
If you're already using RSpec for your tests, add the `rspec-buildkite-analytics` gem to your code to collect your test results into your Test Analytics dashboard.

1. Create a new branch:

    ```
    git checkout -b install-buildkite-test-analytics
    ```

2. Add `rspec-buildkite-analytics` to your `Gemfile` in the `:test` group:

    ```rb
    group :test do
      gem "rspec-buildkite-analytics"
    end
    ```

3. Run `bundle` to install the gem and update your `Gemfile.lock`:

    ```sh
    $ bundle
    ```

3. Add the Test Analytics code to your application in `spec/spec_helper.rb`, and set the environment variable [securely](/docs/pipelines/secrets) on your agent or agents.

    ```rb
    require "rspec/buildkite/analytics"

    RSpec::Buildkite::Analytics.configure(ENV["TEST_ANALYTICS_TOKEN"])
    ```

4. Commit and push your changes:

    ```sh
    $ git add .
    $ git commit -m "Install and set up Buildkite Test Analytics"
    $ git push
    ```

5. Make sure that the Test Analytics [environment variables](#environment-variables) are set so that the RSpec collector can use them in your Test Analytics dashboard.


Once you're done, in your Test Analytics dashboard, you'll see analytics of test executions on all branches that include this code.

## Environment variables

Test Analytics uses environment variables to populate test information. Regardless of the CI provider you use to run your builds, you need to make sure that environment variables are available to the RSpec collector or import API. You also need to make sure that the environment variables are passed through to a container if your builds are running in containers.

Not all of these variables are set or available for each CI provider. For more details on specific integrations and providers see:

* [RSpec on Buildkite](#environment-variables-rspec-on-buildkite)
* [RSpec on CircleCI](#environment-variables-rspec-on-circleci)
* [RSpec on GitHub Actions](#environment-variables-rspec-on-github-actions)
* [RSpec on other CI providers](#environment-variables-rspec-on-other-ci-providers)
* For other CI providers and collectors see [Importing JUnit XML](/docs/test-analytics/importing-junit-xml) and [Importing JSON](/docs/test-analytics/importing-json)

The only required environment variable is the unique key for the build that initiated the Test Analytics run (`BUILDKITE_ANALYTICS_KEY`), but some features of Test Analytics aren't available if the other environment variables are not set.

If you're not using CI, you can still use Test Analytics by running the RSpec collector, [JUnit import](/docs/test-analytics/importing-junit-xml), or [JSON import](/docs/test-analytics/importing-json) yourself to upload data to Test Analytics.

### RSpec on Buildkite

The following variables are set automatically when the RSpec collector is running on Buildkite:

| Variable                       | Description and source                                                   |
|--------------------------------|--------------------------------------------------------------------------|
| `key`         | a unique key for the build that initiated the Test Analytics run<br />`BUILDKITE_BUILD_ID` |
| `url`         | URL that links to the build <br /> `BUILDKITE_BUILD_URL`                                   |
| `branch`      | the branch or reference that this run is for<br />`BUILDKITE_BRANCH`                       |
| `commit_sha`  | the commit sha for the head of the branch<br />`BUILDKITE_COMMIT`                          |
| `number`      | the build number of the build<br />`BUILDKITE_BUILD_NUMBER`                                |
| `job_id`      | the id of a job within the build<br />`BUILDKITE_JOB_ID`                                   |
| `message`     | the commit message for the head of the branch<br />`BUILDKITE_JOB_ID`                      |

### RSpec on CircleCI

The following variables are set automatically when the RSpec collector is running on CircleCI:

| Variable     | Description and source                                                                                          |
|--------------|-----------------------------------------------------------------------------------------------------------------|
| `key`        | a unique key for the build that initiated the Test Analytics run<br />`CIRCLE_WORKFLOW_ID` and `CIRCLE_BUILD_NUM` |
| `url`        | a URL that links to the build <br /> `CIRCLE_BUILD_URL`                                                         |
| `branch`     | the branch or reference that this run is for<br />`CIRCLE_BRANCH`                                                     |
| `commit_sha` | the commit SHA for the head of the branch<br />`CIRCLE_SHA1`                                                    |
| `number`     | the build number of the build<br />    `CIRCLE_BUILD_NUM`                                                       |

To pass a human-readable commit message through to Test Analytics, set the `BUILDKITE_ANALYTICS_MESSAGE` variable.

### RSpec on GitHub Actions

The following variables are set automatically when the RSpec collector is running on GitHub Actions:

| Variable     | Description and source                                                                                                               |
|--------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `key`        | a unique key for the build that initiated the Test Analytics run<br />`GITHUB_ACTION` and `GITHUB_RUN_NUMBER` and `GITHUB_RUN_ATTEMPT` |
| `url`        | a URL that links to the build <br /> `GITHUB_REPOSITORY` and `GITHUB_RUN_ID`                                                         |
| `branch`     | the branch or reference that this run is for<br />`GITHUB_REF`                                                                             |
| `commit_sha` | the commit SHA for the head of the branch<br />`GITHUB_REF`                                                                          |
| `number`     | the build number of the build<br />    `GITHUB_RUN_NUMBER`                                                                           |

To pass a human-readable commit message through to Test Analytics, set the `BUILDKITE_ANALYTICS_MESSAGE` variable.

### RSpec on other CI providers

If you're using other CI providers, you need to configure these environment variables yourself. The only required environment variable is the unique key for the build that initiated the Test Analytics run (`BUILDKITE_ANALYTICS_KEY`), but some features of Test Analytics aren't available if the other environment variables are not set:

| Variable                       | Description and source                                         |
|--------------------------------|----------------------------------------------------------------|
| `BUILDKITE_ANALYTICS_KEY`      | a unique key for the build that initiated the Test Analytics run |
| `BUILDKITE_ANALYTICS_URL`      | URL that links to the build                                    |
| `BUILDKITE_ANALYTICS_BRANCH`   | the branch or reference that this run is for                         |
| `BUILDKITE_ANALYTICS_SHA`      | the commit SHA for the head of the branch                      |
| `BUILDKITE_ANALYTICS_NUMBER`   | the build number of the build                                  |
| `BUILDKITE_ANALYTICS_JOB_ID`   | the id of a job within the build                               |
| `BUILDKITE_ANANLYTICS_MESSAGE` | the commit message for the head of the branch                  |<commit_msg>Remove incorrect env var reference<commit_after># Ruby Collectors

<div class="Docs__wip-note">
<p class="Docs__wip-heading">Test Analytics is an invite-only beta feature. Join the <a href="https://buildkite.com/test-analytics">waitlist</a>.</p>
</div>

The beta release of Test Analytics ships with RSpec collector. You you can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).

## RSpec collector

[RSpec](https://rspec.info/) is a behaviour-driven development library for Ruby.
If you're already using RSpec for your tests, add the `rspec-buildkite-analytics` gem to your code to collect your test results into your Test Analytics dashboard.

1. Create a new branch:

    ```
    git checkout -b install-buildkite-test-analytics
    ```

2. Add `rspec-buildkite-analytics` to your `Gemfile` in the `:test` group:

    ```rb
    group :test do
      gem "rspec-buildkite-analytics"
    end
    ```

3. Run `bundle` to install the gem and update your `Gemfile.lock`:

    ```sh
    $ bundle
    ```

3. Add the Test Analytics code to your application in `spec/spec_helper.rb`, and set the environment variable [securely](/docs/pipelines/secrets) on your agent or agents.

    ```rb
    require "rspec/buildkite/analytics"

    RSpec::Buildkite::Analytics.configure(ENV["TEST_ANALYTICS_TOKEN"])
    ```

4. Commit and push your changes:

    ```sh
    $ git add .
    $ git commit -m "Install and set up Buildkite Test Analytics"
    $ git push
    ```

5. Make sure that the Test Analytics [environment variables](#environment-variables) are set so that the RSpec collector can use them in your Test Analytics dashboard.


Once you're done, in your Test Analytics dashboard, you'll see analytics of test executions on all branches that include this code.

## Environment variables

Test Analytics uses environment variables to populate test information. Regardless of the CI provider you use to run your builds, you need to make sure that environment variables are available to the RSpec collector or import API. You also need to make sure that the environment variables are passed through to a container if your builds are running in containers.

Not all of these variables are set or available for each CI provider. For more details on specific integrations and providers see:

* [RSpec on Buildkite](#environment-variables-rspec-on-buildkite)
* [RSpec on CircleCI](#environment-variables-rspec-on-circleci)
* [RSpec on GitHub Actions](#environment-variables-rspec-on-github-actions)
* [RSpec on other CI providers](#environment-variables-rspec-on-other-ci-providers)
* For other CI providers and collectors see [Importing JUnit XML](/docs/test-analytics/importing-junit-xml) and [Importing JSON](/docs/test-analytics/importing-json)

The only required environment variable is the unique key for the build that initiated the Test Analytics run, but some features of Test Analytics aren't available if the other environment variables are not set.

If you're not using CI, you can still use Test Analytics by running the RSpec collector, [JUnit import](/docs/test-analytics/importing-junit-xml), or [JSON import](/docs/test-analytics/importing-json) yourself to upload data to Test Analytics.

### RSpec on Buildkite

The following variables are set automatically when the RSpec collector is running on Buildkite:

| Variable                       | Description and source                                                   |
|--------------------------------|--------------------------------------------------------------------------|
| `key`         | a unique key for the build that initiated the Test Analytics run<br />`BUILDKITE_BUILD_ID` |
| `url`         | URL that links to the build <br /> `BUILDKITE_BUILD_URL`                                   |
| `branch`      | the branch or reference that this run is for<br />`BUILDKITE_BRANCH`                       |
| `commit_sha`  | the commit sha for the head of the branch<br />`BUILDKITE_COMMIT`                          |
| `number`      | the build number of the build<br />`BUILDKITE_BUILD_NUMBER`                                |
| `job_id`      | the id of a job within the build<br />`BUILDKITE_JOB_ID`                                   |
| `message`     | the commit message for the head of the branch<br />`BUILDKITE_JOB_ID`                      |

### RSpec on CircleCI

The following variables are set automatically when the RSpec collector is running on CircleCI:

| Variable     | Description and source                                                                                          |
|--------------|-----------------------------------------------------------------------------------------------------------------|
| `key`        | a unique key for the build that initiated the Test Analytics run<br />`CIRCLE_WORKFLOW_ID` and `CIRCLE_BUILD_NUM` |
| `url`        | a URL that links to the build <br /> `CIRCLE_BUILD_URL`                                                         |
| `branch`     | the branch or reference that this run is for<br />`CIRCLE_BRANCH`                                                     |
| `commit_sha` | the commit SHA for the head of the branch<br />`CIRCLE_SHA1`                                                    |
| `number`     | the build number of the build<br />    `CIRCLE_BUILD_NUM`                                                       |

To pass a human-readable commit message through to Test Analytics, set the `BUILDKITE_ANALYTICS_MESSAGE` variable.

### RSpec on GitHub Actions

The following variables are set automatically when the RSpec collector is running on GitHub Actions:

| Variable     | Description and source                                                                                                               |
|--------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `key`        | a unique key for the build that initiated the Test Analytics run<br />`GITHUB_ACTION` and `GITHUB_RUN_NUMBER` and `GITHUB_RUN_ATTEMPT` |
| `url`        | a URL that links to the build <br /> `GITHUB_REPOSITORY` and `GITHUB_RUN_ID`                                                         |
| `branch`     | the branch or reference that this run is for<br />`GITHUB_REF`                                                                             |
| `commit_sha` | the commit SHA for the head of the branch<br />`GITHUB_REF`                                                                          |
| `number`     | the build number of the build<br />    `GITHUB_RUN_NUMBER`                                                                           |

To pass a human-readable commit message through to Test Analytics, set the `BUILDKITE_ANALYTICS_MESSAGE` variable.

### RSpec on other CI providers

If you're using other CI providers, you need to configure these environment variables yourself. The only required environment variable is the unique key for the build that initiated the Test Analytics run, but some features of Test Analytics aren't available if the other environment variables are not set:

| Variable                       | Description and source                                         |
|--------------------------------|----------------------------------------------------------------|
| `BUILDKITE_ANALYTICS_KEY`      | a unique key for the build that initiated the Test Analytics run |
| `BUILDKITE_ANALYTICS_URL`      | URL that links to the build                                    |
| `BUILDKITE_ANALYTICS_BRANCH`   | the branch or reference that this run is for                         |
| `BUILDKITE_ANALYTICS_SHA`      | the commit SHA for the head of the branch                      |
| `BUILDKITE_ANALYTICS_NUMBER`   | the build number of the build                                  |
| `BUILDKITE_ANALYTICS_JOB_ID`   | the id of a job within the build                               |
| `BUILDKITE_ANANLYTICS_MESSAGE` | the commit message for the head of the branch                  |
{'fraction_non_alphanumeric': 0.12735415005214404, 'fraction_numerical': 0.000858843015765904, 'mean_word_length': 1.8092366017577115, 'pattern_counts': {'":': 0, '<': 49, '<?xml version=': 0, '>': 49, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 69, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1204509', 'n_tokens_mistral': 4017, 'n_tokens_neox': 3797, 'n_words': 1580}