Skip to main content
Cypress App
End-to-End Only

Cypress.require

Cypress.require loads dependencies within the cy.origin() callback function. Cypress.require requires modules such as npm packages and other local files.

Cypress.require is functionally the same as using CommonJS require() in browser-targeted code.

Syntax​

caution

Using Cypress.require() within the cy.origin() callback requires enabling the experimentalOriginDependencies option in the Cypress configuration.

Cypress.require('moduleNameOrPath')

Usage​

Correct Usage

cy.origin('cypress.io', () => {
const _ = Cypress.require('lodash')
const utils = Cypress.require('./utils')

// ... use lodash and utils ...
})

Incorrect Usage

// `Cypress.require()` cannot be used outside the `cy.origin()` callback.
// Use CommonJS `require()` instead
const _ = Cypress.require('lodash')

cy.origin('cypress.io', async () => {
// `require()` and `import()` cannot be used inside the `cy.origin()` callback.
// Use `Cypress.require()` instead
const _ = require('lodash')
const utils = await import('./utils')
})

// `Cypress.require` must be passed a static string; dynamic values will not
// import correctly.
cy.origin('cypress.io', { args: { lodash: 'lodash' } }, ({ lodash }) => {
const _ = Cypress.require(lodash)
})

See Using dependencies and shared code in cy.origin() for more example usage.

TypeScript​

There are couple ways to have types inferred for the dependency required.

Casting​

cy.origin('cypress.io', async () => {
const _ = Cypress.require('lodash') as typeof import('lodash')

// lodash methods are properly typed
_.map([1, 2, 3], (num: number) => {
// ...
})
})

Generic​

import type { LoDashStatic } from 'lodash'

cy.origin('cypress.io', async () => {
const _ = Cypress.require < LoDashStatic > 'lodash'

// lodash methods are properly typed
_.map([1, 2, 3], (num: number) => {
// ...
})
})

Limitations / Requirements​

  • Cypress.require only works when called within the cy.origin() callback function. Cypress.require errors if used elsewhere.
  • Only the following file extensions are supported for dependencies required (either directly or indirectly):
    • .js
    • .jsx
    • .ts
    • .tsx
    • .mjs
    • .json
  • Cypress.require('dependency-name') must be on one line as a continuous string, and you can't define the dependency dynamically:
// ✅ GOOD
Cypress.require('lodash')

// ❌ BAD
const { require } = Cypress
require('lodash')

// ❌ BAD
Cypress
.require('lodash')

// ❌ BAD
Cypress . require('lodash')

// ❌ BAD
Cypress.require(
'lodash'
)

// ❌ BAD
const lodashPkgName = 'lodash'
Cypress.require(lodashPkgName)

Why not require or import?​

Cypress runs test code in the browser, so Cypress has to bundle any dependencies with the test code before running it. A preprocessor handles bundling for the majority of test code. However, due to the way that cy.origin() works, Cypress extracts the callback passed to it from the test code where the callback is defined and runs the callback in a different context. Running the callback in that context also separates it from any dependencies that are included in the test code bundle.

To solve this, we replace all instances of Cypress.require with require at runtime and bundle just the callback with any dependencies required within it.

Using Cypress.require in the test code instead of require or import keeps the dependencies required within the callback from being bundled with the rest of the test code. We cannot bring them along with the callback to where it is run, so it would waste execution time and memory to bundle its dependencies in the original preprocessing. Cypress bundles the dependencies with the code that needs them only when it preprocesses the callback itself.

Additionally, we tried a solution previously that allowed use of require and import, but found that it hurt performance not only for spec files using them within the cy.origin() callback, but even for spec files that did not use them. That solution was also preprocessor-dependent and only worked for the webpack preprocessor. Using Cypress.require is preprocessor-agnostic.

History​

VersionChanges
12.6.0Cypress.require added and support for using CommonJS require() and ES module import() removed
10.11.0Cypress.require removed in favor of CommonJS require() and ES module import()
10.9.0Cypress.require added

See also​