Automated testing in CircleCI
On This Page
CircleCI allows you to automatically test your code before changes are merged. You can integrate testing tools and frameworks such as Jest, Mocha,
pytest, JUnit, Selenium, XCTest, and more.
When you integrate your tests into your CircleCI pipelines, you not only deliver software to your users more reliably and efficiently, you get feedback more quickly so you can fix issues and failed tests faster. Test output data becomes available in CircleCI to help debug failed tests. If you save your test data in CircleCI, you can also take advantage of Test Insights as well as parallelism features to identify opportunities to further optimize your pipelines.
To automatically run your test suites in a project pipeline, you will add configuration keys in your
.circleci/config.yml file. These would typically be defined as a step or collection of steps to be executed in a job.
A pipeline might consist of a single workflow, with a single job defined that includes a step to execute a suite of tests within an execution environment.
|Using Docker? Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information see Using Docker authenticated pulls.|
jobs: build-and-test: docker: - image: cimg/node:16.10 steps: - checkout - node/install-packages: pkg-manager: npm - run: name: Run tests command: npm test
run is a built-in step that runs commands in a shell. To read more about the
run step for executing tests and other commands, go to the Configuration reference page.
Depending on your requirements, you might have more complex workflows that orchestrate multiple jobs. For example, you might have several concurrent jobs for building and testing your project in separate Linux, macOS, and Windows execution environments. You might also want to require that a test job is run only if a preceding build job is successful.
Use orbs to simplify testing
Orbs provide a way to integrate popular testing tools into your configuration. You can invoke CircleCI partner orbs such as Cypress, LambdaTest, and Sauce Labs in your
.circleci/config.yml file. These orbs will allow you to include common testing tasks in your pipelines by running built-in jobs or concise usage commands in your jobs.
Store test data
Results from testing can be saved in CircleCI in two different ways.
steps: ... # Steps to build and test your application - store_test_results: path: test-results
This step uploads and stores test results, and also enables direct access to output from failed tests on the Tests tab of a job in the web app.
More details on
store_test_resultscan be found on the Configuration reference page.
Store test results as artifacts:
Test results can also be stored as artifacts using the
steps: ... # Steps to build and test your application - store_artifacts: path: test-results destination: junit
Results can later be accessed or downloaded as files via the Artifacts section of a job in the CircleCI web app, or through the API.
For more detailed examples of storing test data with different testing frameworks, refer to the Collect test data page.
When parallelism and test splitting are enabled, CircleCI provides a bird’s-eye view into the timing of each parallel run in the Timing tab in the Job Details UI.
The Timing tab lets you identify which steps are taking the longest amount of time in a given parallel run so that you can make targeted improvements to reduce overall runtime.
The test Insights feature is not currently supported for GitLab or GitHub App projects. To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the GitHub App integration page.
When test results are stored, test analytics also become available on the Tests tab of the Insights page in the web app. Metrics for flaky tests, tests with the lowest success rates, and slow tests help you identify opportunities to optimize pipelines as well as further improve your testing strategy.
More information is available on the Test Insights page.
Re-run failed tests only (
circleci tests run)
You can configure jobs to re-run failed tests only. Using this option, when a transient test failure arises, only a subset of tests are re-run instead of the entire test suite. Also, only failed tests from the same commit are re-run, not new ones.
More information on how to use this option is available on the Rerun failed tests overview page. This functionality uses a command called
circleci tests run.
Historically, when your testing job in a workflow has flaky tests, the only option to get to a successful workflow was to re-run your workflow from failed. This type of re-run executes all tests from your testing job, including tests that passed, which prolongs time-to-feedback and consumes credits unnecessarily.
Further optimize your pipelines with parallelism and test splitting.
Try our test splitting tutorial.
Read our Browser testing guide to common methods for running and debugging browser tests in CircleCI.
To get event-based notifications in Slack about your pipelines (for example, if a job passes or fails), try our Slack orb tutorial.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.