Cancelling Runs

Cancelling CI tests runs

Runs that are currently in progress can be cancelled using the dashboard controls or via an API call.

Cancelling a run can be useful for:

preventing a run from timing out
optimizing usage of your CI provider resources
reducing the number of recorded tests

Please note: Cancelling a run cannot be undone

Cancelling Runs via Dashboard

In-progress runs can be cancelled by clicking the "Cancel Run" button in the Runs Feed view. You can also cancel a run when from the Run Details view.

The canceled run will be tagged accordingly, and the dashboard will display the user, date, and time of cancellation.

Cancelling Runs from CI

A cancelled CI job stops reporting mid-run, whether you cancelled it yourself or a newer commit superseded it. The run stays in progress until it hits the project's Run Timeouts. Add a step that cancels the run when the job is cancelled:

- name: Cancel the run if the workflow is cancelled
  if: ${{ cancelled() }}
  run: npx --package @currents/cmd@2 currents run cancel

currents run cancel authenticates with the Record Key the job already uses to report results, so it needs no additional secret, and it identifies the run by its CI Build ID or its run ID, so the command works on any CI provider. if: ${{ cancelled() }} is GitHub Actions syntax; on other providers, run the command from the hook that runs on cancellation, as shown for GitLab CI in Cancelling from other CI providers. See currents run cancel for the available options.

On GitHub Actions the same thing is available as an action. See Cancel Runs on Workflow Cancellation.

Cancelling Runs via API

You can programmatically cancel a run via the PUT runs/:runId/cancel HTTP API call. For example, here is an example of curl command that cancels a particular run

curl --location --request PUT 'https://api.currents.dev/v1/runs/:runId/cancel' \
--header 'Authorization: Bearer <currents API token>'

By using the API call you can extend the - for example:

cancel a run after CI pipeline is stopped/cancelled
cancel a run when a particular condition is met, e.g.:
- activate HTTP Webhooks and parse the results
- based on the results (e.g. encountering a particular error message), send the cancellation request
cancel a run when a certain number of failed tests are detected (it is natively supported via Failing Fast)

Cancellation by Fail-Fast

If you have Failing Fast activated for a project, runs cancelled because of fail-fast strategy will be marked with a special badge:

GitHub Actions Workflow Cancellation

On GitHub Actions the same cancellation is also available as an action, cancel-run-gh-action. See Cancel Runs on Workflow Cancellation for a complete workflow.

- name: Run tests
  env:
    CURRENTS_RECORD_KEY: ${{ secrets.CURRENTS_RECORD_KEY }}
    CURRENTS_PROJECT_ID: my-project-id
    CURRENTS_CI_BUILD_ID: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }}
  run: npx playwright test

- name: Cancel the run if the workflow is cancelled
  if: ${{ cancelled() }}
  uses: currents-dev/cancel-run-gh-action@v1
  with:
    record-key: ${{ secrets.CURRENTS_RECORD_KEY }}
    project-id: my-project-id
    ci-build-id: ${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }}

All three inputs default to CURRENTS_RECORD_KEY, CURRENTS_PROJECT_ID and CURRENTS_CI_BUILD_ID, so a job that already exports them for the reporting step can use the action with no inputs at all.

Pass run-id instead of ci-build-id to cancel a run you already have the id of. It defaults to CURRENTS_RUN_ID and takes precedence when both are set.

After the step is enabled, cancelling a GitHub Actions workflow will trigger cancellation:

The associated Currents run will be cancelled with the corresponding notes:

Cancelling with an API key

The action also accepts an API Keys instead of a record key. It then identifies the run by the GitHub run id and attempt recorded on it, so no other input is needed:

- name: Cancel the run if the workflow is cancelled
  if: ${{ cancelled() }}
  uses: currents-dev/cancel-run-gh-action@v1
  with:
    api-token: ${{ secrets.CURRENTS_API_KEY }}

Pass project-id and ci-build-id as well to identify the run by its CI Build ID instead. Use this form when the workflow records under a CI Build ID of its own:

Declare the variables on the job, not on the reporting step. A step's env is visible only to that step, so the cancelling step reads them as empty:

jobs:
  run-tests:
    runs-on: ubuntu-latest
    env:
      CURRENTS_CI_BUILD_ID: "a-custom-ci-build-id"
      CURRENTS_PROJECT_ID: "my-project-id"
    steps:
      - name: Run tests
        run: npx pwc --key ${{ secrets.CURRENTS_RECORD_KEY }}

      - name: Cancel the run if the workflow is cancelled
        if: ${{ cancelled() }}
        uses: currents-dev/cancel-run-gh-action@v1
        with:
          api-token: ${{ secrets.CURRENTS_API_KEY }}
          project-id: ${{ env.CURRENTS_PROJECT_ID }}
          ci-build-id: ${{ env.CURRENTS_CI_BUILD_ID }}

FAQ

What happens when a run is cancelled?

Cancelling a run affects in-progress and pending tests, as well as integrations and run analytics.

the run will be marked as "Cancelled", depending on the test's status, it can also become "Failed" or "Passed". See Test Status.
in-progress tests will run to completion, the dashboard will accept their result
attempts to start a new test for a cancelled run would fail with the error message Run is cancelled

Cancelling runs and analytics

Cancelled runs are excluded from Runs Duration Insights
Cancelled runs are excluded from Test / Spec Size Insights
Tests recorded as part of a cancelled run are still included in Tests Insights charts

How does cancelling a run affect test records plan usage?

Only fully recorded tests consume your organization's test records limit.
Cancelled runs do consume your organization's runs limit (for organizations on deprecated runs-based plans)

How does cancelling a run affect integrations (GitHub, Slack, etc.)?

GitHub / BitBucket Commit Status Check

Commit status checks will display Cancelled by <username> message
Commit status check outcome will be set according to the last known run status, for example
- if no failed tests were recorded before the cancellation, the status check outcome will be a success
- otherwise, the status check outcome will be a failure