or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-cypress--webpack-preprocessor

Cypress preprocessor for bundling JavaScript via webpack

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@cypress/webpack-preprocessor@5.7.x

To install, run

npx @tessl/cli install tessl/npm-cypress--webpack-preprocessor@5.7.0

Cypress Webpack Preprocessor

Cypress Webpack Preprocessor enables bundling JavaScript and TypeScript test files using webpack during test execution. It provides seamless integration with webpack configurations, allowing users to leverage their existing webpack setup including loaders, transformations, and module resolution for their Cypress tests.

Package Information

Package Name: @cypress/webpack-preprocessor
Package Type: npm
Language: TypeScript
Installation: npm install --save-dev @cypress/webpack-preprocessor

Core Imports

import * as webpackPreprocessor from "@cypress/webpack-preprocessor";

For CommonJS:

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

Basic Usage

// In your cypress/plugins/index.js or cypress.config.js
const webpackPreprocessor = require("@cypress/webpack-preprocessor");

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

Architecture

The preprocessor is built around several key components:

Main Preprocessor Function: Factory function that creates file preprocessors with custom webpack configurations
Bundle Management: Caches bundle promises to avoid duplicate webpack compilations for the same files
File Watching: Integrates with Cypress's file watching system to trigger re-runs when files change
Error Handling: Provides clear, formatted error messages from webpack compilation
TypeScript Integration: Special handling for TypeScript source maps and compiler options

Capabilities

Main Preprocessor Function

Creates a Cypress file preprocessor with optional webpack configuration.

/**
 * Creates a webpack file preprocessor for Cypress
 * @param options - Configuration options for the preprocessor (defaults to empty object)
 * @returns File preprocessor function that Cypress can use
 */
function webpackPreprocessor(options: PreprocessorOptions = {}): FilePreprocessor;

interface PreprocessorOptions {
  /** Webpack configuration object */
  webpackOptions?: webpack.Configuration;
  /** Webpack watch options */
  watchOptions?: Object;
  /** Path to TypeScript installation for source map overrides */
  typescript?: string;
  /** Additional entry points for webpack bundle */
  additionalEntries?: string[];
}

type FilePreprocessor = (file: FileEvent) => Promise<string>;

Usage Examples:

// Basic usage with default webpack options
const webpackPreprocessor = require("@cypress/webpack-preprocessor");

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

// With custom webpack configuration
const webpackPreprocessor = require("@cypress/webpack-preprocessor");

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

// Using default options as a starting point
const webpackPreprocessor = require("@cypress/webpack-preprocessor");
const defaults = webpackPreprocessor.defaultOptions;

module.exports = (on) => {
  // Modify default babel preset to use .babelrc
  delete defaults.webpackOptions.module.rules[0].use[0].options.presets;
  
  on("file:preprocessor", webpackPreprocessor(defaults));
};

Default Options Property

Provides access to default webpack configuration that can be modified.

/**
 * Default preprocessor options that can be modified
 */
webpackPreprocessor.defaultOptions: Omit<PreprocessorOptions, 'additionalEntries'>;

The default options include:

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

File Event Interface

Interface for file objects passed by Cypress to the preprocessor.

interface FileEvent extends EventEmitter {
  /** Path to the input file being processed */
  filePath: string;
  /** Path where the bundled file should be written */
  outputPath: string;
  /** Whether Cypress should watch this file for changes */
  shouldWatch: boolean;
  
  /** Event emitted when file should be closed/cleaned up */
  on(event: 'close', listener: (cb?: () => void) => void): this;
  /** Event emitted to trigger test re-run */
  emit(event: 'rerun'): boolean;
}

Webpack Preprocessor Interface

Extended interface for the main preprocessor function with static properties.

interface WebpackPreprocessor extends WebpackPreprocessorFn {
  /** Default options that can be modified and passed to the preprocessor */
  defaultOptions: Omit<PreprocessorOptions, 'additionalEntries'>;
}

type WebpackPreprocessorFn = (options: PreprocessorOptions) => FilePreprocessor;

Types

Required imports for the type definitions above:

import { EventEmitter } from 'events';
import { Configuration } from 'webpack';

The webpack.Configuration type referenced in PreprocessorOptions.webpackOptions is the standard webpack configuration interface from the webpack package.

Configuration Examples

Using Project's Babel Configuration

const webpackPreprocessor = require("@cypress/webpack-preprocessor");
const defaults = webpackPreprocessor.defaultOptions;

module.exports = (on) => {
  // Remove default preset to use .babelrc
  delete defaults.webpackOptions.module.rules[0].use[0].options.presets;
  on("file:preprocessor", webpackPreprocessor(defaults));
};

TypeScript Support

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

module.exports = (on) => {
  const options = {
    webpackOptions: {
      resolve: {
        extensions: [".ts", ".tsx", ".js"],
      },
      module: {
        rules: [
          {
            test: /\.tsx?$/,
            loader: "ts-loader",
            options: {
              transpileOnly: true,
            },
          },
        ],
      },
    },
  };
  
  on("file:preprocessor", webpackPreprocessor(options));
};

Additional Entry Points

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

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

Error Handling

The preprocessor provides enhanced error messages:

Module Resolution Errors: Reformatted to show clear file paths that couldn't be resolved
Compilation Errors: Webpack compilation errors with stack traces removed for clarity
Source Map Errors: Automatic source map configuration to ensure proper debugging
File Path Context: All errors include the original file path being processed

Debugging

Enable debug output with environment variables:

# General webpack preprocessor debugging
DEBUG=cypress:webpack

# Webpack compilation statistics
DEBUG=cypress:webpack:stats

Peer Dependencies

Required peer dependencies that must be installed:

@babel/core: Babel transpiler core
@babel/preset-env: Babel preset for modern JavaScript
babel-loader: Webpack loader for Babel
webpack: Module bundler (4.x+ required)

Compatibility

Webpack: 4.x+ required
Babel: 7.x+ required
Node.js: Uses the Node version bundled with Cypress, or system Node if configured
TypeScript: Optional, detected automatically when present