{ "doc": { "id": "app/component-testing/styling-components", "title": "Test your component's styles | Cypress Documentation", "description": "Learn how to test your component's markup, styles, and script logic with Cypress Component Testing", "section": "app", "source_path": "/llm/markdown/app/component-testing/styling-components.md", "version": "48b03b5502f7aea1d0454750cce208f775403542", "updated_at": "2026-05-20T19:00:20.270Z", "headings": [ { "id": "app/component-testing/styling-components#styling-components", "text": "Styling Components", "level": 1 }, { "id": "app/component-testing/styling-components#what-youll-learn", "text": "What you'll learn", "level": 5 }, { "id": "app/component-testing/styling-components#why-test-your-components-styles", "text": "Why Test Your Component's Styles?", "level": 2 }, { "id": "app/component-testing/styling-components#rendering-components-correctly", "text": "Rendering Components Correctly", "level": 2 }, { "id": "app/component-testing/styling-components#component-support-file", "text": "Component Support File", "level": 2 }, { "id": "app/component-testing/styling-components#3rd-party-css-libraries-tailwind-bootstrap-popperjs", "text": "3rd Party CSS Libraries (Tailwind, Bootstrap, PopperJS)", "level": 2 }, { "id": "app/component-testing/styling-components#importing-stylesheets", "text": "Importing Stylesheets", "level": 2 }, { "id": "app/component-testing/styling-components#rules-for-setting-up-your-styles", "text": "Rules for Setting Up Your Styles", "level": 2 }, { "id": "app/component-testing/styling-components#global-app-styles", "text": "Global App Styles", "level": 3 }, { "id": "app/component-testing/styling-components#css-reset-or-normalize-isnt-applied", "text": "CSS Reset or Normalize isn't applied", "level": 3 }, { "id": "app/component-testing/styling-components#fonts-everything-is-rendering-in-times-new-roman", "text": "Fonts: Everything is rendering in Times New Roman", "level": 3 }, { "id": "app/component-testing/styling-components#icon-fonts-none-of-my-icons-are-rendering", "text": "Icon Fonts: None of my icons are rendering", "level": 3 }, { "id": "app/component-testing/styling-components#theme-providers-my-components-dont-look-right-compile-because-they-cant-access-providers", "text": "Theme Providers: My components don't look right/compile because they can't access providers", "level": 3 } ] }, "chunks": [ { "id": "app/component-testing/styling-components#what-youll-learn", "doc_id": "app/component-testing/styling-components", "heading": "What you'll learn", "heading_level": 5, "content_markdown": "##### What you'll learn\n\n* Why you should test your component's styles\n* How to render components correctly with their CSS styles\n* How to handle 3rd party CSS libraries\n", "section": "app", "anchors": [ "what-youll-learn" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 40 }, { "id": "app/component-testing/styling-components#why-test-your-components-styles", "doc_id": "app/component-testing/styling-components", "heading": "Why Test Your Component's Styles?", "heading_level": 2, "content_markdown": "## Why Test Your Component's Styles?\n\nStylesheets are a critical part of your component's business logic. One of the best examples of this is a modal component. Common modal bugs include: z-index issues, inability to dismiss the overlay, and inability to interact with the parent page _after_ dismissing the modal.\n\nNode-based test runners like Jest or Vitest can't catch these kinds of issues because they render your styles in **emulated DOM environments** like JSDom. JSDom doesn't have a box model and certain kinds of assertions, such as if a parent is covering a child and preventing clicks, are not possible to test without a more realistic environment.\n\nOn the other hand, browser-based runners like Cypress allow you to render your application's styles and components and allow Cypress's Driver to take advantage of the real box-model and style rendering engine. Cypress's commands like `cy.click` and assertions like `should('be.visible')` have business logic that makes sure the UI you're trying to assert on and interact with is visible and interactible for your end users. This is a benefit unique to browser-based test runners.\n", "section": "app", "anchors": [ "why-test-your-components-styles" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 240 }, { "id": "app/component-testing/styling-components#rendering-components-correctly", "doc_id": "app/component-testing/styling-components", "heading": "Rendering Components Correctly", "heading_level": 2, "content_markdown": "## Rendering Components Correctly\n\nThe first time you mount _any_ new component, you may notice that the component doesn't look like it should. Unless your application is written _exclusively_ using Component-scoped CSS (e.g. Styled Components or Vue's Scoped Styles) you will need to follow this guide in order to get your component looking **and behaving** like it will in production.\n\nEnsure that whatever you're doing in production is happening within either the Component HTML file or the Component Support File.\n", "section": "app", "anchors": [ "rendering-components-correctly" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 107 }, { "id": "app/component-testing/styling-components#component-support-file", "doc_id": "app/component-testing/styling-components", "heading": "Component Support File", "heading_level": 2, "content_markdown": "## Component Support File\n\nWhen you load a component or end-to-end spec file, it will first load something called a supportFile. By default, this is created for you during first-time setup of Cypress Component Testing and is located at `cypress/support/component.js`. This file gives you the opportunity to set up your spec's environment.\n\nFor component specs, you use this file to set up page-level concerns that would usually exist by the time you mount the component. Some examples include:\n\n1. Run-time JavaScript code (state management, routers, UI libraries)\n2. Global styles (style resets, Tailwind)\n\nAs a rule, your Component Support File should look **very similar** to your application's main JavaScript (ie: main.js, index.js) and main CSS (ie: main.css, index.css) files.\n", "section": "app", "anchors": [ "component-support-file" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 159 }, { "id": "app/component-testing/styling-components#3rd-party-css-libraries-tailwind-bootstrap-popperjs", "doc_id": "app/component-testing/styling-components", "heading": "3rd Party CSS Libraries (Tailwind, Bootstrap, PopperJS)", "heading_level": 2, "content_markdown": "## 3rd Party CSS Libraries (Tailwind, Bootstrap, PopperJS)\n\nComponents can have three parts: markup, styles, and script logic. All three of these work together in order to deliver a working component.\n\nStyles are business logic, too.\n\n1. Tailwind\n2. CSS Modules\n3. Scoped Styled\n4. Styled Components\n5. Regular Stylesheets\n6. UI Libraries\n\nThis guide will help you setup your test infrastructure to render your component's styles properly.\n\nDepending on how your application is built, the first time you mount a new component, it may be completely or somewhat unstyled.\n\nThis makes sense. Many applications have some amount of one-time setup that is run outside of the component file.\n\nWe build our applications within the context that they're supposed to run in, and we make assumptions that our components will always be rendered within a root-level component (such as an ``) or a top-level selector with style rules (such as `#app { /* styles in here */ }` )\n\nWhen we attempt to isolate our component to put it under test, we need to put that environment back together. We'll go into that in a moment. First, let's talk about stylesheets, testing, and one of Cypress's biggest differences in contrast to other component testing tools.\n", "section": "app", "anchors": [ "3rd-party-css-libraries-tailwind-bootstrap-popperjs" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 273 }, { "id": "app/component-testing/styling-components#importing-stylesheets", "doc_id": "app/component-testing/styling-components", "heading": "Importing Stylesheets", "heading_level": 2, "content_markdown": "## Importing Stylesheets\n\nEach application or component library imports styles a little differently. We'll go over a few methods and describe how you can quickly restructure your components to become more testable.\n\nIf you do not follow this guide, your components will mount, but they won't look correct and you may not be able to benefit from some of the most valuable parts of Cypress. Namely, implicit checks for width, height, and overflow to ensure that your components not only exist in the page's HTML but are also visible.\n", "section": "app", "anchors": [ "importing-stylesheets" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 119 }, { "id": "app/component-testing/styling-components#rules-for-setting-up-your-styles", "doc_id": "app/component-testing/styling-components", "heading": "Rules for Setting Up Your Styles", "heading_level": 2, "content_markdown": "## Rules for Setting Up Your Styles\n\nAll of your application's styles need to end up in Cypress so that when your component mounts, it looks right.\n\nWe expose two hooks for you to configure your styles:\n\n1. An HTML file called `cypress/support/component-index.html`\n2. A JavaScript support file called `cypress/support/component.js`\n\nWhen creating a production-like test environment, you should _always_ mimic your own application's setup. If your application has multiple `` tags to load fonts or other stylesheets within the `head`, ensure that the `cypress/support/component-index.html` file contains the same `` tags. The same logic follows for any styles loaded in your Application's `main.js` file. If you import a `./styles.css` at the top of your `main.js` file, make sure to `import` it in your `cypress/support/component.js` file.\n\nFor this reason, it's strongly suggested to make a `src/setup.js` file that will be re-used in your `main.js` entrypoint as well as in your test setup. An example project structure would look like so:\n\n```\n> /cypress> /support> /component.js> /src> /main.js> /main.css> /setup.js\n```\n\nThe contents of **setup.js** may look like so:\n\n```\nimport '~normalize/normalize.css'import 'font-awesome'import './main.css'export const createStore = () => { return /* store */}export const createRouter = () => { return /* router */}export const createApp = () => { return }\n```\n\nand its usage in `main.js` could look like so:\n\n```\nimport { createApp } from './setup.js'ReactDOM.render(createApp())\n```\n\nand Cypress would re-use it in its support file\n\n```\n/* And that's it! */import '../../src/setup.js'\n```\n\nThe rest of this section is dedicated to discussing specific style problems you may have, including: Fonts, Icon Fonts, Style Resets, Global App Styles, and 3rd party component library styles.\n\n### Global App Styles\n\nYour global application styles are usually in one of the following places:\n\n1. A `styles.css` file you import within the `head` of your application.\n\nThis should be loaded within your Cypress Index HTML file.\n\n1. Within a root-level component like `App.jsx`, `App.vue`, `App.svelte`, etc.\n\nDecouple your Root CSS from your App or Entrypoint component by pulling out these global styles into a top-level stylesheet. Both Vue and Svelte embed global application styles into the main entry point components. The rest of your application expects to be rendered _within_ those components, and so any assumptions you made when writing those components must be replicated in your test environment or else your components won't look right.\n\n```\n\n```\n\nShould become\n\n```\n/* App.vue */ \n```\n\n1. Your main stylesheet loads fonts\n\n```\n/* main.css */@font-face { font-family: 'Fira Sans'; src: url('fonts/fira/eot/FiraSans-Regular.eot'); src: url('fonts/fira/eot/FiraSans-Regular.eot') format('embedded-opentype'), url('fonts/fira/woff2/FiraSans-Regular.woff2') format('woff2'), url('fonts/fira/woff/FiraSans-Regular.woff') format('woff'), url('fonts/fira/woff2/FiraSans-Regular.ttf') format('truetype'); font-weight: normal; font-style: normal;}\n```\n\n### Icon Fonts: None of my icons are rendering\n\n### Theme Providers: My components don't look right/compile because they can't access providers\n\nTheme Provider or other application-level wrappers like I18n or Material UI work by injecting themselves around your application. When you're component testing, you haven't rendered the component hierarchy surrounding your component.\n\nTo solve issues like these, people review the Custom Commands and Wrappers\n\nTo first explain why it's not right, you first have to explain what production-like even means.\n\nSo we have this before & after up, and now our job is to step through the component under test and try to figure out where the differences between Production and Test are.\n\nSometimes these are as simple as colors or fonts not lining up. Other times, the entire component or sections of it may not compile.\n\nThe reason this doesn't look right is because:\n\n1. My browser supports dark mode\n2. The `` component provides its own styles\n", "section": "app", "anchors": [ "rules-for-setting-up-your-styles" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 1012 }, { "id": "app/component-testing/styling-components#global-app-styles", "doc_id": "app/component-testing/styling-components", "heading": "Global App Styles", "heading_level": 3, "content_markdown": "### Global App Styles\n\nYour global application styles are usually in one of the following places:\n\n1. A `styles.css` file you import within the `head` of your application.\n\nThis should be loaded within your Cypress Index HTML file.\n\n1. Within a root-level component like `App.jsx`, `App.vue`, `App.svelte`, etc.\n\nDecouple your Root CSS from your App or Entrypoint component by pulling out these global styles into a top-level stylesheet. Both Vue and Svelte embed global application styles into the main entry point components. The rest of your application expects to be rendered _within_ those components, and so any assumptions you made when writing those components must be replicated in your test environment or else your components won't look right.\n\n```\n\n```\n\nShould become\n\n```\n/* App.vue */ \n```\n\n1. Your main stylesheet loads fonts\n\n```\n/* main.css */@font-face { font-family: 'Fira Sans'; src: url('fonts/fira/eot/FiraSans-Regular.eot'); src: url('fonts/fira/eot/FiraSans-Regular.eot') format('embedded-opentype'), url('fonts/fira/woff2/FiraSans-Regular.woff2') format('woff2'), url('fonts/fira/woff/FiraSans-Regular.woff') format('woff'), url('fonts/fira/woff2/FiraSans-Regular.ttf') format('truetype'); font-weight: normal; font-style: normal;}\n```\n", "section": "app", "anchors": [ "fonts-everything-is-rendering-in-times-new-roman" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 115 }, { "id": "app/component-testing/styling-components#theme-providers-my-components-dont-look-right-compile-because-they-cant-access-providers", "doc_id": "app/component-testing/styling-components", "heading": "Theme Providers: My components don't look right/compile because they can't access providers", "heading_level": 3, "content_markdown": "### Theme Providers: My components don't look right/compile because they can't access providers\n\nTheme Provider or other application-level wrappers like I18n or Material UI work by injecting themselves around your application. When you're component testing, you haven't rendered the component hierarchy surrounding your component.\n\nTo solve issues like these, people review the Custom Commands and Wrappers\n\nTo first explain why it's not right, you first have to explain what production-like even means.\n\nSo we have this before & after up, and now our job is to step through the component under test and try to figure out where the differences between Production and Test are.\n\nSometimes these are as simple as colors or fonts not lining up. Other times, the entire component or sections of it may not compile.\n\nThe reason this doesn't look right is because:\n\n1. My browser supports dark mode\n2. The `` component provides its own styles\n", "section": "app", "anchors": [ "theme-providers-my-components-dont-look-right-compile-because-they-cant-access-providers" ], "path": "/llm/json/chunked/app/component-testing/styling-components.json", "token_estimate": 201 } ] }