Starting now, all Cypress Cloud plans can use the Run Completion API, allowing the Cypress Cloud run to finalize immediately at the end of test recoding, instead of staying open for new tests.
Here's why that's important and how it can save you time.
Cloud runs can have multiple groups of tests
Cypress Cloud runs are often made up of many isolated cypress run groups. These may represent things like:
- separate parallel machines
- different browsers running the tests
- different testing types (component, end-to-end, or API)
- different operating systems, environments, or any settings that are set with the
cypress run
Combining these test groups into a single Cypress Cloud run keeps things organized, so you get a single set of results for your build and and triage and debug failures together.
Combining test groups also lets you get accessibility or UI Coverage metrics that are based on the total collection of tests related to a given build.
Test groups may start and end with time in between
Since some groups might finish before other groups have started, Cypress Cloud has a built-in buffer to wait for new groups before closing the run. This is the Run Completion Delay. The default is 60 seconds. It can be increased if your teams need more time because the gap between groups is going to be longer, or the gap is going to be unpredictable (for example when using Nx to drive your Continuous Integration workflows).
A long Run Completion Delay provides a safety net to ensure all expected test groups can join the run, avoiding the errors that would result from trying to add tests after the run was finished.
This lets you gracefully handle situations where, for example, your component tests finish quickly because they use a dev server from Cypress, but your end-to-end tests have not yet started, because it takes more time to stand up your application.
Note: the Run Completion Delay does not cause any idle time in your CI process itself. It only controls Cypress Cloud's behavior of keeping the run "open" for new machines/groups.
When you should use the Run Completion API
If you have workflows that depend on the Cypress Cloud run reaching a finalized pass/fail state, you should use this API to speed up the finalization based on the nature of that run.
Cypress Cloud's UI Coverage and Cypress Accessibility reports are good examples of post-run workflows. They are based on Test Replay data and produce reports that cross-reference the interactions and page states reached across all of your tests. Even though the Test Replay data is eagerly processed as the run results are uploaded, there is a final step that requires knowing all expected tests have been delivered. A long run completion delay can sometimes delay this step, if all other processing has completed.
Other examples are the Slack and Teams messages, Cypress App desktop notifications, and similar integrations that trigger once at the end of a run. If you have a long run completion delay and want these to be delivered sooner, this will help.
Finally, if you are using features like Cypress Cloud CLI or MCP to access run data, the run's status will be listed as running before the run reaches a terminal state. If you want your runs to resolve to that terminal state as quickly as possible, you can use this API to complete the run programmatically.
How the Run Completion API helps
This removes any compromises related to the buffer you need for CI jobs that might run at different times. You get the best of both worlds:
- A long run completion delay to be flexible in CI
- Have the run complete immediately when the final tests have finished
The safety buffer of the run completion delay can disappear as soon as you know it's no longer needed, but long gaps during the run won't cause a problem.
Get started now
The simplest way to get started is to use call API through the after:run hook in in your Cypress Config file, with the expected group count. This requires no CI pipeline updates, as all the necessary information to call the API is already available in that context.
It is also possible to call the API without an expected group count, to complete the run after your required CI jobs have all finished, no matter how many groups that turned out to be. For more complex CI setups with conditional logic for which tests well run, this approach can be simpler.
Learn more in the Run Completion API documentation.