Styles and Assets

## What a Cypress component test actually renders Cypress component testing never visits your application. When a run starts, Cypress boots the dev server named by `component.devServer`, and for each spec it loads a small page of its own — `cypress/support/component-index.html` by default — imports your support file, imports the spec, and lets `cy.mount()` put the component into that page. That page is deliberately bare. The scaffolded version carries a charset meta tag, a viewport meta tag, a `<title>` and a single root element, and nothing else. It is not your application's `index.html`, it has never executed your `main.js`, and no ancestor component of the thing under test has rendered. ## Why the rating widget looks wrong Almost every application does a pile of one-time work before its first component appears, and CSS is most of it: - The entry file (`main.js`, `main.ts`, `index.jsx`) imports `./main.css`, a normalize sheet, or a compiled Tailwind build. - The application's `index.html` head carries `<link>` tags for a font, an icon font or a vendor theme, or an `@import` rule inside a `<style>` block. - A root component such as `App.vue` or `App.svelte` embeds global rules — `#app { font-family: ... }` — that every descendant silently assumes. None of that happens in a component spec. So a rating widget draws its stars at the browser default size, a toast loses the `position: fixed` and stacking context its overlay depends on, and a data grid's sticky header collapses into the rows. The markup is correct; the cascade the markup was written against is simply absent. This matters well beyond appearance. Cypress runs in a real browser with a real box model, and commands such as `.click()` and assertions such as `.should('be.visible')` consult width, height, overflow and occlusion before they pass. An unstyled component therefore fails **behavioural** assertions too, and those failures are actively misleading: they name the component when the cause is a stylesheet that never loaded. ## The two hooks Cypress gives you | Hook | When it loads | Mirror it against | |---|---|---| | `cypress/support/component.js` | Compiled and executed before every spec in the run | The application's entry file (`main.js` / `index.jsx`) | | `cypress/support/component-index.html` | The page the component is mounted into | The application's `index.html` | The rule that keeps this maintainable fits in one sentence: **do it where your application does it.** If a stylesheet reaches the browser because the entry file says `import './main.css'`, import it in the support file. If it reaches the browser because the app's `<head>` carries a `<link>`, put the same `<link>` in the index file. Faithfully reproducing the real environment is the entire point of the exercise; guessing produces a harness that drifts. Two details are worth knowing about the support file. It is compiled and bundled by the same dev server that compiles your specs, so it can `import` exactly what your source can — a `.css` file, a `.scss` file, a design-token module. And it is optional: setting `supportFile` to `false` turns it off entirely, which is occasionally done for speed and almost always regretted, because that is the file the styles were living in. ## Do it once, not twice Duplicating the import list in two places guarantees the two lists diverge. The pattern to reach for is a single shared startup module imported from both entry points: 1. Create `src/setup.js` and move the global stylesheet imports into it, along with anything else the app builds once at startup. 2. Have `main.js` import that module and mount the real application. 3. Have `cypress/support/component.js` import the same module — often a single line. Adding a stylesheet to the application now adds it to the harness for free, and there is nothing left to keep in sync by hand. ## When it is still wrong Work through these in order before touching the component: - **Did the rule load at all?** Inspect the element's computed styles. A class that is present on the element but contributes nothing means the sheet never arrived. - **Did a file 404?** A `@font-face` or a background image referenced by URL has to be served by the dev server Cypress started, which is not the server that serves your app in development. - **Are the styles component-scoped already?** A codebase written entirely with CSS Modules or scoped single-file-component styles needs far less of this, because those styles travel with the component through the bundler. - **Does the rule assume an ancestor?** Something written as `#app .toast` needs that ancestor to exist in the mount page, or in whatever wrapper the component is mounted through. - **Does the theme live on the root element?** Applications commonly set a `data-theme` attribute or a `dark` class on `<html>` or `<body>` at startup. The mount page has neither, so a design system whose tokens are defined under a theme selector resolves every custom property to its fallback. The last one is the reason a component can look *almost* right — correct spacing, wrong colours — and it is worth checking early, because it looks nothing like a missing-stylesheet failure.