Extending Cypress With Plugins

November 22, 2017

By Brian Mann

One of the greatest (and unique) advantages of Cypress is that all of your test code runs in the browser. This provides us a significant architectural advantage over every other testing tool out there.

While this makes for a much more reliable testing experience, and enables you to write tests much easier - it does make communicating outside of the browser more difficult.

Users have expressed a desire to be able to customize and modify many of the internals of the way Cypress runs. Although its our goal to be very opinionated, we always strive to create balance and flexibility for our users.

Node Code

As of v1.1.0 - we’ve released the first iteration of our Plugins API. We now automatically seed a new file: cypress/plugins/index.js.

In this file you can write regular Node.js code that taps into the various events that Cypress exposes throughout its lifecycle. This is a great place to write your own project specific code, or import existing plugins others have contributed.

We’ve made the ergonomics around writing plugins as easy and as simple as possible. Check out the docs if you’re curious how to write a plugin.

File Preprocessing

As of today - we’ve added only a single event: file:preprocessor. This event enables you to swap out or modify the way in which Cypress prepares your test files for the browser.

Using this event it is now possible to do things like:

  • Add TypeScript support
  • Add CoffeeScript 2.0 support
  • Transpile JavaScript from another language like Clojurescript
  • Use Webpack instead of Browserify
  • Modify the default Babel options
  • Add new ES7 features

To make this happen, we extracted the internal portions of Cypress responsible for transpiling your test code for the browser. We’ve now packaged this into its own NPM module: @cypress/browserify-preprocessor.

Although we bundle this module directly in with Cypress - because it lives as a separate module, that also means users can independently install this in their projects - making it easy to modify the default options. It also means we can update and release new versions of this module without having to immediately release a new version of Cypress.

Because we are nice and we know users like Webpack (and want to use the same Webpack options as they use in their applications), we’ve also created a @cypress/webpack-preprocessor.

Other Events

We will soon be adding other events that we think you’ll find very useful.

We’ll be adding events that enable you to:

  • Programmatically change the configuration and environment variables
  • Modify the launch flags for browsers and Electron
  • Pass messages directly from your test code to this backend process
  • Require and utilize your own application code to make it easier to seed and query your database

As we expand Cypress and improve its feature set, this Plugin API will serve as a “seam” and an escape hatch so you can write custom code to achieve whatever it is you want to do.

You can follow along the Github issue outlining many of our goals with Plugins.

Plugin Submissions

Beyond creating a series of plugin events - we also want to promote the discovery of official Cypress plugins and those submitted by the community. Today the list is small, but we anticipate creating and curating a list of plugins and extensions to Cypress.

We’ll soon be adding our official ESLint plugin, as well as JS framework specific extensions for things like React, Angular and Vue.

You can see our current list of plugins here.