npm/vite-plugin-cypress-esm/README.md
A Vite plugin that intercepts and rewrites ES module imports within Cypress component tests. The ESM specification generates modules that are "sealed", requiring the runtime (the browser) to prevent any alteration to the module namespace. While this has security and performance benefits, it prevents use of mocking libraries which would need to replace namespace members. This plugin wraps modules in a special Proxy implementation, allowing for instrumentation by libraries such as Sinon.
Note: This package is a pre-release alpha and is not yet stable. There are likely to be bugs and edge cases. Please report any bugs here. Learn more about Cypress release stages and expectations around stability.
Run Cypress with DEBUG=cypress:vite-plugin-cypress-esm. You will get logs in the terminal, for the code transformation, and in the browser console, for intercepting and wrapping the modules in a Proxy.
| @cypress/vite-plugin-cypress-esm | cypress |
|---|---|
| >= v1 | >= v12 |
This plugin rewrites the ES modules served by Vite to make them mutable and therefore compatible with methods like cy.spy() and cy.stub() that require modifying otherwise-sealed objects. Since this is a testing-specific plugin it is recommended to apply it your Vite config only when running your Cypress tests. One way to do so would be in cypress.config:
import { defineConfig } from 'cypress'
import viteConfig from './vite.config'
import { mergeConfig } from 'vite'
import { CypressEsm } from '@cypress/vite-plugin-cypress-esm'
export default defineConfig({
component: {
devServer: {
bundler: 'vite',
framework: 'react',
viteConfig: () => {
return mergeConfig(
viteConfig,
{
plugins: [
CypressEsm(),
]
}
)
}
}
}
})
ignoreModuleListSome modules may be incompatible with Proxy-based implementation. The eventual goal is to support wrapping all modules in a Proxy to better facilitate testing. For now, if you run into any issues with a particular module, you can tell the plugin to skip it like so:
CypressEsm({
ignoreModuleList: ['react-router', 'react-router-dom']
})
You can also use a glob, which uses picomatch internally:
CypressEsm({
ignoreModuleList: ['*react*']
})
This will exclude modules matching the supplied pattern(s) from being processed by this plugin. It is important to note that the act of importing any matching module into other files/modules will still be processed unless those destinations are themselves excluded via the list, but those imports will receive the unaltered version.
Certain third-party dependencies such as React are known to have some conflicts with the Proxy implementation that cause problems stubbing internal functionality. Since it is unlikely you want to stub parts of React itself, it's a good idea to add it to the ignoreModuleList.
ignoreImportListThere may be times when you want to use an unaltered dependency rather than the proxied version created by this plugin in a specific location, or want to use the standard import mechanism rather than the one provided by this plugin. This may be because:
To instruct this plugin to skip a given import and use the unaltered target module use ignoreImportList. This also supports picomatch patterns.
CypressEsm({
ignoreImportList: ['**/internal/problematic-file.js']
})
If using the @cypress/react test harness, you may need to ignore the react-dom/client module by configuring as such:
CypressEsm({
ignoreImportList: ['**/react-dom/client']
})
All known import syntax is supported, however there may be edge cases that have not been identified.
This module uses Regular Expression matching to transform the modules on the server to facilitate wrapping them in a Proxy on the client. In future updates, a more robust AST-based approach will be explored. A limitation of the current approach is that it does not recognize syntax from actual code vs content found within strings (for instance, an error string that contains example code syntax). This can result in inappropriately modified string constants.
ESM imports are automatically hoisted to the top of a given module so they happen first before any code that references them. This plugin does not currently perform any hoisting, so imports are transformed to variable references in place. If you have code that attempts to reference an imported value prior to that import it will likely break. This is a known issue with HMR logic in Svelte projects, and will typically present as a "use before define" error.
This plugin works by intercepting calls coming in to a module. This will not work for situations where a module attempts to make internal calls to a function within the same module or directly compare against a function within the same module. Eg:
// mod_1.js
export function foo () {
// ...
}
export function bar (mod) {
return mod === foo
}
// mod_2.js
import { foo, bar } from './mod_1.js'
bar(foo) //=> false
In this example, bar(foo) is passing a reference to mod_1.foo, where mod_1 is a module wrapped in a Proxy. In the original mod_1.js, the reference to foo is the original, unwrapped foo, so the comparison return false. This may cause issues in some libraries, such as React Router when lazy loading routes. You can add modules to ignoreModuleList to work around this issue.
This plugin is designed to work with Sinon since that is what Cypress uses internally for cy.stub and cy.spy - attempting to utilize other stubbing/mocking libraries or directly mutating modules is not a supported use case and will likely not work as expected.
This is an Alpha release, meaning there a very likely bugs in the implementation and it is expected that you will encounter issues. We appreciate any bug reports once you have performed the troubleshooting process below.
If you encounter issues:
ignoreModuleList & ignoreImportList configThis project is licensed under the terms of the MIT license.