cypress-codegen

cypress-codegen

A Cypress plugin and CLI tool which automatically adds and enables IntelliSense for your custom commands!

Table of Contents

• Why Do I Need This Plugin?
• Installation
• Usage
• Example
• Configuration

Why Do I Need This Plugin?

The process for adding Cypress custom commands to test suites is quite manual and involves bloating projects with too much boilerplate code. Additionally, custom commands are hard to write because we don't get IntelliSense or the ease of navigating to the command's definition. The cypress-codegen plugin will dynamically import all of your project's custom commands and will even enable IntelliSense and "go to definition" shortcuts!

Installation

npm i --save-dev cypress-codegen

Plugin Usage

Model your Cypress project exactly like the one in this repository!

1. Add the required plugin code to cypress.config.ts like so:

import { cypressCodegen } from 'cypress-codegen/plugin';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      cypressCodegen(on, config);
      return config;
    }
  },

  component: {
    setupNodeEvents(on, config) {
      cypressCodegen(on, config);
      return config;
    },
    devServer: {
      framework: 'create-react-app',
      bundler: 'webpack'
    }
  }
});

1. Add to cypress/support/component.ts and/or cypress/support/e2e.ts:

import 'cypress-codegen';

1. Put all of your custom commands in cypress/commands as regular functions. It is recommended to separate each command into its own file of the same name.

2. Run any Cypress test, and cypress-codegen will:

   • load these functions as valid custom commands
   • generate a special Cypress type definition for each function which will enable IntelliSense and "go to definition" shortcuts in your Cypress test code

Example

Check out this project's cypress directory for a generic example!

Custom Command Chaining

If you want to create custom commands that are meant to be scoped to a previous command's result, put Scoped at the end of your custom command function name (e.g. myCustomCommandScoped). This will set the prevSubject option when adding the custom command. See the Cypress docs for more details.

Code Styling

cypress-codegen will attempt to read your prettierrc config by default. However, you may pass a config override in the cypress.config.ts invocation:

setupNodeEvents(on, config) {
    cypressCodegen(on, config, prettierConfigOverride);
    return config;
}

Command Line Usage

You can also run cypress-codegen in your terminal to generate types for your Cypress project!

Optionally pass the --prettier-config flag to pass in a stringified prettier config object.

Configuration

Project Flag

If you are using the --project flag when starting Cypress, you will need to set the Cypress environment variable PROJECT to your project name.

In cypress.config.ts:

env: {
  PROJECT: 'my-project';
}

Javascript

The IntelliSense codegen feature is enabled by default. To disable the codegen feature (perhaps for a Javascript Cypress project), set the CODEGEN Cypress environment variable to false. You will still get the benefit of the custom commands being loaded automatically without even having to invoke Cypress.Commands.add()!

CYPRESS_CODEGEN=false npx cypress run

or in cypress.config.js:

env: {
  CODEGEN: false;
}