How to Fix “JQuery Is Not Defined” in Cypress
Find whether the error is in Cypress, your app, or preprocessing, then fix load order, window scope, $ conflicts, and bundler setup.

Short answer: Cypress bundles its own jQuery, but that does not automatically add jQuery or $ to the application under test. First identify where the error occurs: application runtime, Cypress spec/support code, or the Cypress preprocessing step. Then fix the matching problem: load jQuery before dependent application scripts, inspect the AUT window with cy.window(), use Cypress.$ or Cypress commands inside tests, and configure bundler aliases explicitly when preprocessing imports fail.
1. Identify which runtime is failing
The same message can describe three different failures. Read the stack trace and note when it appears.

| Failure location | What it means | First check |
|---|---|---|
After cy.visit(), in application or plugin code |
The application window cannot resolve its expected jQuery global. | Inspect win.jQuery and win.$ with cy.window(). |
| Inside a spec or support file | The test code is using a browser global or a synchronous pattern unnecessarily. | Use Cypress commands or Cypress.$. |
| Before the browser opens, during compile/preprocess | The selected bundler cannot resolve an import or alias. | Check webpack/Vite configuration and the actual dependency installation. |
Cypress includes jQuery among its bundled testing libraries and exposes Cypress.$ for DOM traversal outside Cypress commands. That bundled function belongs to Cypress’s test runtime; the application has a separate browser window. See the Cypress.$ documentation and cy.window() documentation.
2. Fix an application-side missing jQuery global
Load jQuery before every dependent script
A plugin or inline script that calls jQuery or $ must run after the jQuery script has loaded. The order is the same in Cypress as it is in a normal browser.
<script src="/vendor/jquery.min.js"></script>
<script src="/vendor/jquery-plugin.js"></script>
<script>
jQuery(function () {
jQuery('#checkout').checkoutPlugin();
});
</script>
The jQuery Learning Center demonstrates this dependency order: load jquery.js before the ready handler or other code that calls it. Check the jQuery document-ready guide.
Verify the request and the build
- Open the browser’s Network panel and confirm the jQuery URL returns successfully.
- Check that the URL is not a 404, blocked by CSP, redirected to an HTML error page, or unavailable in the test environment.
- Confirm the test build includes the same entry point and vendor dependency as the application build.
- Make sure a dependent plugin is not loaded asynchronously before jQuery finishes.
Verify the application window from Cypress
describe('jQuery availability', () => {
it('loads jQuery in the application window', () => {
cy.visit('/checkout');
cy.window().should((win) => {
expect(typeof win.jQuery).to.equal('function');
expect(typeof win.$).to.equal('function');
});
});
});
cy.window() yields the active application window and retries the chained assertion. If your architecture intentionally does not expose a global, test the public behavior instead of adding a global solely to satisfy a test.
3. Fix module-based applications and legacy plugins
In a module-based application, import dependencies in order rather than assuming a browser global:
import $ from 'jquery';
import 'legacy-widget';
export function mountWidget() {
$('#widget').legacyWidget();
}
The exact import and global-exposure syntax depends on your framework and bundler. If a legacy plugin specifically reads window.jQuery, configure the application’s supported bundler to expose that global and verify it in the AUT window. Do not assume a TypeScript path alias alone changes what webpack or Vite can resolve.
4. Resolve $ conflicts separately
A missing jQuery identifier and a conflicting $ identifier are different problems. If jQuery exists but another library owns $, use the full name or put jQuery into no-conflict mode. The jQuery.noConflict() API relinquishes jQuery’s control of $.

jQuery.noConflict();
jQuery(function ($) {
// $ is a local jQuery alias inside this callback.
$('#profile').addClass('ready');
});
Use this only after jQuery has loaded. noConflict() cannot repair a failed network request or incorrect script order.
When multiple jQuery versions are present
Multiple versions can overwrite globals and create plugin incompatibilities. Establish which version owns the application global, use noConflict() where required, and avoid loading a second copy unless the plugin genuinely requires it.
5. Use Cypress’s APIs correctly in tests
Prefer Cypress commands for user-facing actions
cy.get('[data-testid="dialog"]')
.should('be.visible')
.find('button[type="submit"]')
.click();
Cypress commands are queued, retried, and yield Cypress-managed subjects. They are not synchronous jQuery calls. The Cypress introduction explicitly warns that a direct synchronous assignment does not work because Cypress does not return the element synchronously. See Introduction to Cypress.
Use Cypress.$ for immediate traversal
cy.window().then((win) => {
const $dialog = Cypress.$(win.document).find('[data-testid="dialog"]');
expect($dialog.length).to.equal(1);
});
Cypress.$ is useful in a callback or utility that needs immediate traversal. It does not replace the application’s own jQuery dependency. A legacy application plugin that calls window.jQuery still needs jQuery in the AUT.
Do not treat cy.get() as a returned jQuery object
This pattern is wrong:
const button = cy.get('button');
button.addClass('ready');
Use a Cypress chain:
cy.get('button').should('have.class', 'ready');
Or use a callback when you deliberately need the yielded subject:
cy.get('button').then(($button) => {
expect($button).to.have.length(1);
});
6. Fix compile and preprocessing errors
If the error appears before the test browser starts, inspect the preprocessor rather than the application page. A TypeScript compilerOptions.paths entry is not, by itself, a webpack alias.
- Identify the dev server or preprocessor configured in
cypress.config.js. - Confirm the package is installed in the workspace used to run Cypress.
- Add the alias to that bundler’s configuration.
- Restart the Cypress process after changing configuration.
- Use the import path supported by the selected bundler.
// cypress.config.js (illustrative webpack setup)
const { defineConfig } = require('cypress');
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
// Configure the chosen file preprocessor here and add its
// webpack alias for any application or test import that needs it.
return config;
}
}
});
The exact preprocessor and alias syntax is project-specific. The important distinction is that the tool compiling the spec must know the alias; TypeScript’s type checker does not configure that tool automatically.
7. A repeatable diagnostic workflow
- Copy the complete stack trace. Determine whether the file belongs to the AUT, a spec/support file, or a preprocessor.
- Check the AUT window. Run the
cy.window()assertion aftercy.visit(). - Check network loading. Confirm the jQuery request, status, content type, and execution order.
- Separate names. Test
typeof win.jQueryandtypeof win.$independently. - Replace test-only DOM code. Use
cy.get()for actions and assertions; useCypress.$for immediate traversal. - Inspect preprocessing. Resolve package installation and bundler aliases if the browser never starts.
- Retest the original behavior. A global assertion proves availability, but the dependent plugin or UI behavior proves the real fix.
8. Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
jQuery is not defined in application code |
jQuery failed, loaded too late, or was omitted from the test build. | Fix the request or dependency order and verify cy.window(). |
$ is not a function, while jQuery exists |
Another library owns $. |
Use jQuery explicitly or use noConflict() with a local alias. |
cy.get(...).click is not a function |
A Cypress chain was treated as a synchronous jQuery object. | Keep the operation in the Cypress chain. |
Cypress is not defined in application code |
Application code is trying to use a Cypress-only global. | Keep Cypress APIs in specs/support code; expose application behavior through the AUT. |
| Module not found during spec compilation | Missing package or missing bundler alias. | Install the dependency in the Cypress workspace and configure the selected preprocessor. |
| Global exists locally but not in CI | Different build entry point, asset path, environment variable, or network access. | Compare CI artifacts and network responses with the local run. |
| Plugin works in the app but fails in Cypress | The Cypress test loads a different page or build, or the plugin runs before its dependency. | Inspect the AUT document, load order, and test-specific entry point. |
9. Reliability and performance considerations
- Prefer the smallest supported dependency graph. Extra jQuery copies increase startup work and can create version conflicts.
- Use Cypress’s retryable commands for UI state that changes asynchronously; immediate
Cypress.$traversal is appropriate only when you control the timing. - Assert dependency availability after navigation when the page loads scripts dynamically.
- Keep a focused diagnostic test for legacy pages, but avoid making every test depend on a global that the application does not promise.
- For CI failures, record the failing URL, asset status, and build revision so a missing script can be distinguished from a namespace conflict.
10. Or skip the browser setup
If your goal is to capture a page image for a test artifact, visual regression job, documentation page, or debugging report, ScreenshotNeo provides a screenshot API and MCP server without maintaining a browser installation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
See the ScreenshotNeo API documentation for request options. Before capture, it can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets. Failed bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the shot was billed. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.
Create a free ScreenshotNeo account and start with the 1,000-shot monthly allowance.
FAQ
Is Cypress’s jQuery the same as my application’s jQuery?
No. Cypress bundles jQuery for its own test runtime. Your application window must load and expose its own dependency if application code requires it.
Should I add jQuery to Cypress support files?
Only if support code itself needs jQuery. For normal UI actions, use Cypress commands. For immediate traversal in a callback, use Cypress.$.
Does noConflict() fix “jQuery is not defined”?
No. It resolves ownership of $ after jQuery has loaded. It cannot fix a missing, blocked, or late script.
Why does the error happen only in CI?
CI may use a different application build, asset URL, environment, or network policy. Compare the loaded page and jQuery request rather than changing Cypress’s bundled jQuery.
Can I assert that jQuery exists without making it a product requirement?
Yes. Add a targeted diagnostic check for legacy pages. For applications designed without a global, test the supported UI or API behavior instead.


