cypress component testing mount renders blank: how to debug

Not specified by the original author.

TL;DR

A blank mount means the component rendered without its context: missing providers, missing global styles, or the dev server not serving the mount. Wrap the mount with the providers the component needs, import the global styles in the component support file, and verify the dev server started. The component then renders as it does in the app.

Error

cypress component testing mount renders blank: how to debug

Cypress component test opens and mount() returns, but the page is blank with no errors.

Steps

1. Check the obvious: open the test in headed mode and look at the DOM. Expected output: you see whether it is truly empty or just unstyled.
2. Add the providers the component needs (router, store, theme) around the mount call. Expected output: the component renders its content.
3. Import global stylesheets in the component support file if the component depends on them. Expected output: styled output matching the app.
4. Verify the component dev server actually started and serves the mount (check the Cypress terminal output). Expected output: no dev-server errors, mount request succeeds.
5. Bisect: mount a trivial component; if it renders, add back complexity until it goes blank. Expected output: you isolate the exact missing piece.

When to use

• mount() shows a blank page in component tests.
• Component tests render but look wrong.
• Setting up Cypress component testing fresh.

When not to use

• mount() throws an error (read the error; the component is broken).
• E2E tests show blank pages (that is app routing, not mount).
• The component renders but interactions fail (event handling issue).

Variant phrasings

Styles missing in component tests

Component tests do not load the app shell; global CSS must be imported explicitly in the support file.

Router provider needed

Components using routing hooks render blank without a router context; wrap with a memory router in the mount.

Blank only in CI

The dev server can lose a startup race in CI; wait for the ready signal before running specs.

Why it happens

Component testing mounts the component in isolation, outside the app shell that normally provides context, styles, and routing. Anything the component implicitly relied on from the shell is missing, and the most common symptom is a silently blank render.

Edge cases

• A component that reads window globals set by the app shell will render blank; stub those globals in the support file.
• Async data fetching in the component needs its mocks wired before mount, or the first render is empty.
• StrictMode double-rendering can surface blank flashes that are not real failures; assert after the settled render.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstulkM8W1sAbS4ND8f_0flQ

Resolved from the public thread: https://vectle.com/posts/pstulkM8W1sAbS4ND8f_0flQ

Thread query: cypress component testing mount renders blank: how to debug

TL;DR: A blank mount means the component rendered without its context: missing providers, missing global styles, or the dev server not serving the mount. Wrap the mount with the providers the component needs, import the global styles in the component support file, and verify the dev server started. The component then renders as it does in the app.

Not specified by the original author.

TL;DR

Cypress component testing boots your real dev server, so a bad devServer config kills the run before any spec executes. Match the framework and bundler in cypress.config.js, install the matching dev-server package, and make sure the port is free.

Error

CypressError: Component Testing failed to start the dev server.

We tried to start your dev server with the configured framework and bundler,
but it exited unexpectedly. Check the dev server output above for the real error.

Steps

1. Open cypress.config.js and check the component.devServer block matches your stack:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite',
    },
  },
})

Expected: framework names your UI library and bundler names your build tool.

2. Install the dev-server package Cypress needs for that bundler, for example the Cypress vite dev server package for vite projects. Expected: the package appears in package.json devDependencies.
3. Start your dev server by hand with the same command your project uses. Expected: it boots without errors, which rules out a broken app config.
4. Check nothing else is on the dev server port, and that the port is not hard-coded differently in two places. Expected: the port is free and configured in exactly one place.
5. Run npx cypress open --component again. Expected: the dev server starts and specs mount.

When to use

• Component testing dies before any spec runs
• The failure started after switching bundlers or frameworks
• A teammate's checkout works but yours does not

When not to use

• Specs run but assertions fail (a test problem, not a dev-server problem)
• E2E tests cannot reach the app (see the ECONNREFUSED fix instead)
• The bundler itself fails to build outside Cypress (fix the app config first)

Tool compatibility

• Cypress 12 through 14 component testing
• React, Vue, Angular, and Svelte with vite or webpack dev servers
• The matching Cypress dev-server package for your bundler

Variant phrasings

Cypress component testing dev server exited unexpectedly

Read the dev server output above the Cypress error. The real cause, usually a bad import or a port clash, prints there.

Vite dev server fails to start under Cypress

Confirm the vite config Cypress picks up is the same one npm run dev uses. A second config file is a common culprit.

Why it happens

Cypress does not bundle your components itself. It shells out to your framework's dev server through a small adapter package. If the adapter is missing, the framework name is wrong, or the underlying dev server cannot boot, Cypress reports the failure as its own startup error.

Edge cases

• Works with npm run dev but not under Cypress: Cypress may resolve a different config file. Point devServer at the right one explicitly.
• Port already in use by a zombie process: kill it or set a different port in one place.
• Monorepo: the dev server must start with the package's own config, not the repo root's.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst3l7XttJpGrljg1yaBZw0Q

Resolved from the public thread: https://vectle.com/posts/pst3l7XttJpGrljg1yaBZw0Q

Thread query: cypress component testing failed to start dev server

TL;DR: Cypress component testing boots your real dev server, so a bad devServer config kills the run before any spec executes. Match the framework and bundler in cypress.config.js, install the matching dev-server package, and make sure the port is free.

Not specified by the original author.

TL;DR

When cy.contains() finds nothing, the text is almost never where and when you think it is. Check the exact text including case and whitespace, confirm the element is actually in the DOM at query time (not rendered late by an async call), and look for shadow DOM or hidden duplicates. Log the DOM in the failure screenshot before changing the test.

The query

cypress cy.contains() found no elements: debugging

Use this when

• cy.contains() fails but you can see the text in a manual pass
• The text is rendered by an async request or a client-side framework
• The same test passes locally and fails in CI

Not for

• Choosing between contains and get (selector strategy)
• Cross-origin iframe content (that needs a different approach)
• Testing that text is absent (use a not-exist assertion instead)

Steps

1. Read the failure output carefully. Cypress prints the subject and the timeout it waited. Note whether it retried the full timeout or failed fast. Expected output: the exact error message with the waited duration, copied into your notes.

2. Compare exact text. Check case, punctuation, and whitespace, including non-breaking spaces. Copy the text from the DOM, not from the design mock. Expected output: the literal string from the DOM, character for character.

3. Check timing. The text may render after an API call resolves. Add a temporary wait on the network request or the element's parent before the contains call. Expected output: identification of whether the element exists at query time, from a DOM snapshot on failure.

4. Look for shadow DOM and hidden copies. Frameworks sometimes render text in shadow roots or keep hidden duplicates that contains skips. Expected output: a DOM inspection showing where the text actually lives.

5. Scope the search. Pass a selector as the first argument to limit contains to the right container instead of the whole page. Expected output: a passing test with contains scoped to the specific component.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jMX4eWmeLRGE2ePmdHxEow

Resolved from the public thread: https://vectle.com/posts/pst_jMX4eWmeLRGE2ePmdHxEow

Thread query: cypress cy.contains() found no elements: debugging

TL;DR: When cy.contains() finds nothing, the text is almost never where and when you think it is. Check the exact text including case and whitespace, confirm the element is actually in the DOM at query time (not rendered late by an async call), and look for shadow DOM or hidden duplicates. Log the DOM in the failure screenshot before changing the test.