Our company Cypress.io has made an open source, MIT-licensed, free end-to-end test runner that can test anything that runs in a browser. The test runner makes it easy to effectively test complex modern web applications, yet it is simple to install, easy to learn, and it just works.
The problem
The Cypress test runner can be used to run tests either locally on a developer’s machine, or on a continuous integration server. We strongly believe that every commit should be tested, thus we have documented how to set up CI tests, and even run our own example projects on a large number of CI providers. But setting up a CI suite is never as easy as it should be. Of course, a developer could copy code from our examples and paste it into their config, but they would generally have to run the project and tweak the settings until the project’s builds and tests pass. Our team realized that this entire process was more difficult than it should be, and often quite frustrating. We, the authors of the tool, had no way to help developers configure their CI suite.
The orb
That is, until we saw the CircleCI Orb proposal and examples. Wow - now the Cypress team could make small reusable pieces of CI configuration, and share them with our users! Here is the simplest example that our users that run end-to-end tests on CircleCI can use:
version: 2.1
orbs:
cypress: cypress-io/cypress@1.0.0
workflows:
build:
jobs:
- cypress/run
Seven lines, ten words: and it correctly checks out code, installs npm dependencies as well as the Cypress application, caches everything that needs to be cached, and runs all end-to-end tests. Beautiful and elegant.
Here is a more complicated example for a user who wants to build the application and also record test results and artifacts on the Cypress Dashboard. No need to write any custom code - because the cypress/run job accepts parameters for these common use cases:
version: 2.1
orbs:
cypress: cypress-io/cypress@1.0.0
workflows:
build:
jobs:
- cypress/run:
build: "npm run build"
record: true
The parameters are statically checked and prevent at least some configuration mistakes. Even a complex workflow that our users typically need, like “install and build app on one machine, then run all tests with load-balancing across 10 machines” can be done through parameters to the cypress/run job almost as easily:
version: 2.1
orbs:
cypress: cypress-io/cypress@1.0.0
workflows:
build:
jobs:
- cypress/install:
build: "npm run build"
- cypress/run:
record: true
parallel: true
parallelism: 10
Minimal amount of configuration, but maximum efficiency.
Custom configuration
The jobs provided by the Cypress Orb are thorough enough to cover most of the typical use cases. Eventually, your project might reach a point where it really needs a custom setup. When you reach that point, you can “eject” and replace the local circle.yml configuration file with the fully resolved version that exposes all of the Cypress Orb commands with their full YAML text. You would need to install CircleCI CLI tool for this and run:
$ circleci config process config.yml > config.yml
By running this command, the project’s config.yml file will be replaced by the fully resolved configuration, without using the Cypress Orb. Now you can tweak the configuration to your project’s needs. ⚠️ Warning: there is no automated way to go from the “ejected” configuration back to using the orb.
Final thoughts
I have never been this excited about continuous integration services since Docker came along and made setting up repeatable builds super simple. Orbs give us, the testing tool authors, the power to create reusable, versioned pieces of CI config that immediately make our users’ lives much simpler.
Be sure to check out our orb documentation at on.cypress.io/circleci-orb and check out the repo cypress-io/circleci-orb.
Gleb Bahmutov is JavaScript ninja, image processing expert, and software quality fanatic. During the day Gleb is making the web a better place as VP of Engineering at Cypress.io. At night he is fighting software bugs and blogs about it at https://glebbahmutov.com/blog/. Microsoft MVP for Open Source Software. You can follow him and his work @bahmutov and find the slides from his conference presentations at https://slides.com/bahmutov.
