Create a Plugins / Extensions API

The idea behind this

As it stands - while users can create custom commands in the driver, we do not expose any real way to alter, modify or change Cypress’s behavior BEHIND the driver (in the node server code).

Currently all we expose is a simple cypress.json to change the way Cypress works. This is heavily limiting.

What we need to do is expose a public interface so users can write node code to modify and alter the internals.

The use cases we’re specifically trying to support are:

Custom Preprocessors

Swapping out the default preprocessor for custom ones. This is the thing that processes the spec files and ultimately serves them to the browser.

Customizing the preprocess would enable users to write typescript, coffeescript 2.0, clojurescript, use webpack, customize babel options, use newer ES7 features, etc, etc. Big win.

Browser Configuration

Users would have access to the browser processes and launch configuration. This would enable them to change the flags used to launch browsers.

You could also use this to load in browser extensions.

Browser Finding

Changes / modifies the logic we use to find browsers on the system.

Custom Configuration

Having just a single cypress.json is limiting. Users have expressed a desire to have more programatic control over things like environment variables.

Backend Messaging

While we currently expose cy.exec and cy.request, there is still a desire to message / talk directly to your backend.

Exposing this API would enable you to do things like call your application code directly to do things like setup / seed / create / update database records.

Screenshot Diffing

As we continue to expand the features of Cypress we would expand these API’s to do things like letting you swap out the screenshot diffing algorithm.

The Cypress Ecosystem

Going down this route will enable us to develop a Cypress Ecosystem consisting of official extensions (created by us) as well as user submitted extensions.

We’ll also need to create an “index” of extensions that enable users to search, browse, and submit new extensions.

Things to consider

• How will we / users handle versioning for plugins? We may need to set a process.versions.cypress
• How will we differentiate official plugins from regular ones? We could publish them under our @cypress npm namespace.
• How will we make modifying the default plugin that Cypress uses by default. Users may want to swap out entire implementations (like the preprocessor) or perhaps just modify the configuration for the default one.
• We should likely seed a commented out cypress/plugins/index.js with all of the API’s that we support.
• We should enable users to easily debug their node code by passing a flag to Cypress which spawns the internal chrome inspector.
• Users code will run in the builtin node environment that comes with Cypress.

Examples of how we could do this

// cypress/plugins/index.js

module.exports = ((register, config, utils, defaults) => {
  register('on:spec:file:preprocessor', (filePath, options) => {
    // do your own custom preprocessing on the spec
  })

  register('on:before:browser:launch', (browserName, flags) => {
    // do your own custom bits on launching the browser
    // such as loading in an extension or modifying the flags
    // used to launch the browser
  })

  register('on:find:all:browsers', (browsersFound) => {
    // add or modify the browsers we found
  })

  register('on:config', (config) => {
    // read in your own yaml files to change some
    // environment variables
    return fs.readFile("./some/yaml", "utf8")
    .then((str) => {
      const yaml = jsYaml.parse(str)

      config.env.yml = yaml

      return config
    })
  })

  register('on:driver:message', (msg, options) => {
    const db = require('./lib/db') // your db

    const request = require('request') // 3rd party request module

    // pass custom messages and do your own thing here loading
    // your own application files
    switch (msg) {
      case 'create:user':
        return db.seed(options)
      case 'reset:db':
        return db.reset()
      case 'make:request':
        return Promise.all(options.urls, request)
    }
  })
})

[bahmutov]

Example repos with TypeScript test compilation (using Cypress from source)

• https://github.com/cypress-io/cypress-example-typescript
• https://github.com/cypress-io/cypress-example-typescript-browserify

[laurentpayot]

@brian-mann I made the switch to Cypress 3.0.1 yesterday. I had some minor CoffeeScript file related issues (#2046) but making firebase-related tasks work was a pain because firebase use grpc and grpc and electron do not live together well. I encountered the following issue https://github.com/grpc/grpc/issues/6138 that I fixed by a postinstall of the electron runtime of grpc, plus I had to create symbolic links to it because Firebase (or Cypress?) was still looking for the node version of grpc.