CircleCI

Here, we'll walk through everything needed to integrate Captain with CircleCI.

An Example `.circleci/config.yml`

This document refers to snippets from this example. You can come back here to see the snippets in context.

version: 2.1
orbs:
  ruby: circleci/[email protected]

workflows:
  run-tests:
    jobs:
      - rspec:
          context: rwx

jobs:
  rspec:
    docker:
      - image: cimg/ruby:3.1.2
    steps:
      - checkout
      - ruby/install-deps
      - run:
          name: Download Captain
          command: |
            arch=x86_64  # Supported values are x86_64 or aarch64
            os=linux # Supported values are linux or darwin

            tmp="$(mktemp -d)/captain" && \
              curl -o $tmp -fsSL "https://releases.captain.build/v1/$os/$arch/captain" && \
              sudo install $tmp /usr/local/bin && \
              rm $tmp && \
              captain --version
      - run:
          name: run tests
          command: captain run captain-examples-rspec
      - store_test_results:
          path: tmp/junit.xml

Setting `RWX_ACCESS_TOKEN`

You need to make a rwx access token available as an environment variable called RWX_ACCESS_TOKEN in CircleCI. you'll do this by:

First generating an access token,
setting it in CircleCI as a context
associating the circle context with a job in our .circleci/config.yml

Generating an Access Token

Navigate to your Access Tokens settings page
- Log in to RWX
- From the hamburger navigation menu, select "Manage {organization}"
- Click on "Access Tokens" on the menu on the left
Click "Create new"
Enter a description, such as "GitHub Actions"
Click "Create token"
Copy the Access Token (you'll use it in the next section)

Setting the Access Token in CircleCI

Circle has two approaches to setting environment variables: context and project. We recommend using contexts as it allows you to share the token across multiple workflows.

On your organization settings page, click on "Contexts"
Click on "Create Context" and give it a name. In our documentation, we use a context named "rwx". If you use that name, it'll be easier to copy/paste our example workflows
Click on the context, then click "Add Environment Variable"
Enter RWX_ACCESS_TOKEN in the "Environment Variable Name" field
Paste the Access Token into the "Value" field

Additionally, you can limit member or repository access to the context. See CircleCI's documentation for more information.

Associating the CircleCI context with your job

In our example, the context called rwx contains our RWX_ACCESS_TOKEN environment variable. Make sure that you enable the correct context for each captain-enabled job in your workflow.

workflows:
  run-tests:
    jobs:
      - rspec: # <-- this is a job using the captain CLI
          context: rwx # <-- this is the context that contains the `RWX_ACCESS_TOKEN` environment variable

Installing Captain

In our example, captain runs on a linux x86_64 machine.

Here are supported OS, architectures, and their download URLs:

OS	Architecture	URL
`darwin`	`x86_64`	https://releases.captain.build/v1/darwin/x86_64/captain
`darwin`	`aarch64`	https://releases.captain.build/v1/darwin/aarch64/captain
`linux`	`x86_64`	https://releases.captain.build/v1/linux/x86_64/captain
`linux`	`aarch64`	https://releases.captain.build/v1/linux/aarch64/captain

jobs:
  rspec:
    # ...
    - run:
        name: download Captain
        command: |
          arch=x86_64  # Supported values are x86_64 or aarch64
          os=linux     # Supported values are linux or darwin

          tmp="$(mktemp -d)/captain" && \
            curl -o $tmp -fsSL "https://releases.captain.build/v1/$os/$arch/captain" && \
            sudo install $tmp /usr/local/bin && \
            rm $tmp && \
            captain --version

    # ...

Integrating Captain with your test framework

Captain integrates with many test frameworks. Find instructions for your specific test framework here.

This example integrates with Ruby's RSpec but can be used as a baseline for integrating with a different framework.

# .captain/config.yaml

test-suites:
  captain-examples-rspec:
    command: bundle exec rspec --format json --out tmp/rspec.json --format progress
    results:
      path: tmp/rspec.json
    output:
      reporters:
        junit-xml: tmp/junit.xml

The --suite-id parameter should be unique for every test suite within your organization.

# .circleci/config.yml

jobs:
  rspec:
    # ...
    steps:
      - run:
          name: run tests
          command: captain run captain-examples-rspec
      - store_test_results:
          path: tmp/junit.xml

Partitioning

Captain's partitioning feature works with CircleCI's parallelism.

Start by updating your Captain configuration to enable partitioning as follows:

# .captain/config.yaml

test-suites:
  captain-examples-rspec:
    # existing config...
    partition:
      command: bundle exec rspec --format json --out tmp/rspec.json --format progress {{ testFiles }}
      globs:
        - spec/**/*_spec.rb

When parallelism is enabled captain run will detect which partition it's on using Circle's $CIRCLE_NODE_INDEX and $CIRCLE_NODE_TOTAL environment variables.

# .circleci/config.yml

jobs:
  rspec:
      # ...
    parallelism: 2
    steps:
      # ...
     - run:
          name: run tests with partitioning
          command: |
            captain run captain-examples-rspec
      - store_test_results:
          path: tmp/junit.xml

For more examples of captain in CircleCI, see this example repo and its config.yml.