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 the 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.
jobs: build-and-test: docker: - image: cimg/node:16.10 auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference 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 Configuring CircleCI reference.
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.
Orbs are available for mobile testing, browser testing, load testing, and code coverage. To get started with orbs, refer to the Orbs Introduction document. To view the orb registry, visit the CircleCI Developer Hub.
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 in the Configuring CircleCI reference.
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 via the API.
For more detailed examples of storing test data with different testing frameworks, refer to the Collecting Test Data document.
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 in the Test Insights guide.
- Further optimize your pipelines with parallelism and test splitting.
- Try our test splitting tutorial.
- Integrate tests for macOS or iOS apps.
- 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 (e.g. 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 guidefirst).
- 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.