> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# rainforest-qa/rainforest

Rainforest QA's CircleCI Orb
Prerequisites:
  - a Rainforest QA account (https://app.rainforestqa.com/trial)
  - a Rainforest QA API token (https://app.rainforestqa.com/settings/integrations)
  - a RunGroup with some tests (https://app.rainforestqa.com/run_groups)


## Commands

### install

Install the Rainforest QA CLI

| Parameter | Type | Default | Description |
|---|---|---|---|
| `architecture` | enum | amd64 | 386 (32-bit) or amd64 (64-bit). |
| `channel` | string |  | [DEPRECATED] This parameter no longer has any effect and will be removed in a future version |
| `github_token` | env_var_name | GITHUB_TOKEN | Name of the environment variable holding a GitHub token, used to avoid API rate limits when fetching the CLI release. |
| `install_path` | string | /usr/local/bin | Where to install the CLI. |
| `platform` | enum | linux | Which platform to install the CLI for. |
| `version` | string |  | Which (v-prefixed) version of the CLI to install. Defaults to the latest. |

### run_qa

Start a new Rainforest run

| Parameter | Type | Default | Description |
|---|---|---|---|
| `automation_max_retries` | string |  | If set to a value > 0 and a test run using automation fails, it will be retried within the same run, up to that number of times |
| `background` | boolean | false | Do not wait for a run to complete before exiting |
| `branch` | string |  | Use a specific Rainforest branch for this run |
| `conflict` | string |  | How other currently in-progress runs should be handled. Values are `cancel` to cancel runs in the same environment as your new run and `cancel-all` to cancel all runs |
| `custom_url` | string |  | Use a specific URL for this run |
| `description` | string | $CIRCLE_PROJECT_REPONAME - $CIRCLE_BRANCH $CIRCLE_BUILD_NUM $(date -u +'%FT%TZ') | An arbitrary string to associate with the run |
| `dry_run` | boolean | false | Set to true to run parameter validations without starting a new Rainforest run |
| `environment_id` | string |  | Use a specific environment for this run |
| `execution_method` | string |  | The execution method to use for this run |
| `junit_path` | string | rainforest | Folder under ~/results to store the JUnit results.xml file |
| `pipeline_id` | string |  | The CircleCI Pipeline ID ( << pipeline.id >> ), used to rerun only failed tests when a CircleCI workflow is rerun |
| `release` | string | $CIRCLE_SHA1 | Manually entered release information about the release the run is associated with |
| `run_group_id` | string |  | Only run tests tied to this Run Group |
| `token` | env_var_name | RAINFOREST_API_TOKEN | The name of the environment variable containing your Rainforest QA API token |

### save_run_id

Save Pipeline and RF Run ID

| Parameter | Type | Default | Description |
|---|---|---|---|
| `pipeline_id` | string |  | The CircleCI Pipeline ID ( << pipeline.id >> ), used to rerun only failed tests when a CircleCI workflow is rerun |
| `when` | enum | on_fail | When to run the steps in this command (always, on_success, or on_fail). Default is on_fail |

## Jobs

### run

Start a new Rainforest run

| Parameter | Type | Default | Description |
|---|---|---|---|
| `automation_max_retries` | string |  | If set to a value > 0 and a test run using automation fails, it will be retried within the same run, up to that number of times |
| `background` | boolean | false | Do not wait for a rainforest run to complete before exiting |
| `branch` | string |  | Use a specific Rainforest branch for this run |
| `cache_key` | string | rainforest-run-{{ .Revision }} | The cache key, used to store/restore a Rainforest Run ID |
| `conflict` | string |  | How other currently in-progress runs should be handled. Values are `cancel` to cancel runs in the same environment as your new run and `cancel-all` to cancel all runs |
| `custom_url` | string |  | Use a specific URL for this run |
| `description` | string | $CIRCLE_PROJECT_REPONAME - $CIRCLE_BRANCH $CIRCLE_BUILD_NUM $(date -u +'%FT%TZ') | An arbitrary string to associate with the run |
| `dry_run` | boolean | false | Set to true to run parameter validations without starting a new Rainforest run |
| `environment_id` | string |  | Use a specific environment for this run |
| `execution_method` | string |  | The execution method to use for this run |
| `executor` | executor | default | The executor to run this command in |
| `junit_path` | string | ~/results/rainforest | Folder under ~/results to store the JUnit results.xml file |
| `pipeline_id` | string |  | The CircleCI Pipeline ID ( << pipeline.id >> ), used to rerun only failed tests when a CircleCI workflow is rerun |
| `release` | string | $CIRCLE_SHA1 | Manually entered release information about the release the run is associated with |
| `run_group_id` | string |  | Only run tests tied to this Run Group |
| `token` | env_var_name | RAINFOREST_API_TOKEN | The name of the environment variable containing your Rainforest QA API token |

## Executors

### default

Latest Rainforest CLI Docker image

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | latest | A tag pointing to an older version of the Rainforest CLI Docker image.
A list of tags can be found at https://gcr.io/rf-public-images/rainforest-cli.
 |

## Examples

### simple

Run tests from a specific run group

```yaml
orbs:
  rainforest: rainforest-qa/rainforest@3
version: 2.1
workflows:
  build:
    jobs:
      - rainforest/run:
          pipeline_id: << pipeline.id >>
          run_group_id: '123'
```