@cypress/webpack-preprocessor

What is @cypress/webpack-preprocessor?

The @cypress/webpack-preprocessor package is a plugin for Cypress that allows you to use webpack to preprocess your JavaScript files before they are loaded into Cypress. This enables you to use webpack features such as ES6 syntax, importing CSS or images, and bundling your test files.

What are @cypress/webpack-preprocessor's main functionalities?

Preprocessing test files with webpack

This feature allows you to preprocess your test files using webpack. You can specify your webpack configuration and watch options. This is useful for using ES6/ESNext features, importing CSS, images, or other assets in your test files.

const webpackPreprocessor = require('@cypress/webpack-preprocessor');

module.exports = (on) => {
  const options = {
    webpackOptions: require('./webpack.config'),
    watchOptions: {}
  };

  on('file:preprocessor', webpackPreprocessor(options));
};

Customizing webpack configuration

This feature allows you to customize the webpack configuration used for preprocessing. In this example, TypeScript files are being handled by adding a rule for `.ts` files and using the `ts-loader`.

const webpackPreprocessor = require('@cypress/webpack-preprocessor');
const webpackOptions = {
  resolve: {
    extensions: ['.ts', '.js']
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        exclude: /node_modules/,
        use: [{ loader: 'ts-loader' }]
      }
    ]
  }
};

const options = {
  webpackOptions,
  watchOptions: {}
};

module.exports = (on) => {
  on('file:preprocessor', webpackPreprocessor(options));
};

Other packages similar to @cypress/webpack-preprocessor

karma-webpack

While not a Cypress plugin, karma-webpack offers similar functionality for the Karma test runner. It preprocesses and bundles test files using webpack, similar to what @cypress/webpack-preprocessor does for Cypress.

README

Cypress Webpack Preprocessor

Cypress preprocessor for bundling JavaScript via webpack

Installation

npm install --save-dev @cypress/webpack-preprocessor

This package relies on the following peer dependencies:

• @babel/core
• @babel/preset-env
• babel-loader
• webpack

It is likely you already have these installed either directly or as a transient dependency, but if not, you will need to install them.

npm install --save-dev @babel/core @babel/preset-env babel-loader webpack

Compatibility

This version is only compatible with webpack 4.x+ and Babel 7.x+.

• If you need webpack 2 or 3 support, use @cypress/webpack-preprocessor 1.x
• If you need Babel 6 support, use @cypress/webpack-preprocessor <= 2.x

This plugin (and all Cypress plugins) run in Cypress's own version of Node. If you require npm packages or your own code into the pluginsFile, they needs to be compatible with the version of Node that Cypress uses.

Usage

In your project's plugins file:

const webpack = require('@cypress/webpack-preprocessor')

module.exports = (on) => {
  on('file:preprocessor', webpack())
}

Options

Pass in options as the second argument to webpack:

const webpack = require('@cypress/webpack-preprocessor')

module.exports = (on) => {
  const options = {
    // send in the options from your webpack.config.js, so it works the same
    // as your app's code
    webpackOptions: require('../../webpack.config'),
    watchOptions: {},
  }

  on('file:preprocessor', webpack(options))
}

webpackOptions

Object of webpack options. Just require in the options from your webpack.config.js to use the same options as your app.

Default:

{
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        exclude: [/node_modules/],
        use: [{
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env'],
          },
        }],
      },
    ],
  },
}

Source maps are always enabled unless explicitly disabled by specifying devtool: false.

watchOptions

Object of options for watching. See webpack's docs.

Default: {}

additionalEntries

An array of file path strings for additional entries to be included in the bundle.

By necessity, this preprocessor sets the entry point for webpack as the spec file or support file. The additionalEntries option allows you to specify more entry points in order to utilize webpack's multi-main entry. This allows runtime dependency resolution.

Default: []

Example:

const webpack = require('@cypress/webpack-preprocessor')

module.exports = (on) => {
  const options = {
    webpackOptions: require('../../webpack.config'),
    additionalEntries: ['./app/some-module.js'],
  }

  on('file:preprocessor', webpack(options))
}

Modifying default options

The default options are provided as webpack.defaultOptions so they can be more easily modified.

If, for example, you want to update the options for the babel-loader to add the stage-3 preset, you could do the following:

const webpack = require('@cypress/webpack-preprocessor')

module.exports = (on) => {
  const options = webpack.defaultOptions
  options.webpackOptions.module.rules[0].use[0].options.presets.push('babel-preset-stage-3')

  on('file:preprocessor', webpack(options))
}

Contributing

Use the version of Node that matches Cypress.

Run all tests once:

npm test

Run tests in watch mode:

npm run test-watch

License

This project is licensed under the terms of the MIT license.