{
  "doc": {
    "id": "app/component-testing/component-framework-configuration",
    "title": "Configure Component Tests | Cypress Documentation",
    "description": "Configure Cypress for component testing with custom index files, dev servers, and spec patterns.",
    "section": "app",
    "source_path": "/llm/markdown/app/component-testing/component-framework-configuration.md",
    "version": "6a908a532b1fca4ed18538a4c1c5a9bc7f24f403",
    "updated_at": "2026-05-01T19:25:18.656Z",
    "headings": [
      {
        "id": "app/component-testing/component-framework-configuration#component-testing-configuration",
        "text": "Component Testing Configuration",
        "level": 1
      },
      {
        "id": "app/component-testing/component-framework-configuration#what-youll-learn",
        "text": "What you'll learn",
        "level": 5
      },
      {
        "id": "app/component-testing/component-framework-configuration#custom-index-file",
        "text": "Custom Index File",
        "level": 2
      },
      {
        "id": "app/component-testing/component-framework-configuration#custom-dev-server",
        "text": "Custom Dev Server",
        "level": 2
      },
      {
        "id": "app/component-testing/component-framework-configuration#spec-pattern-for-component-tests",
        "text": "Spec Pattern for Component Tests",
        "level": 2
      },
      {
        "id": "app/component-testing/component-framework-configuration#additional-config",
        "text": "Additional Config",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "Component Testing Configuration"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 5,
        "children": [
          {
            "type": "text",
            "value": "What you'll learn"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "How to configure Cypress for component testing"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "How to use a custom index file"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "How to use a custom dev server"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "How to set a custom spec pattern for component tests"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When you launch Cypress for the first time in a project, the app will automatically guide you through setup and configuration. You don't need to do anything additional to get started."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Refer to the \"Framework Configuration\" guide in each UI framework's overview guide for a list of supported development servers and how they are configured."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Below are more advanced configuration options you can customize to fit your project."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Custom Index File"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "By default, Cypress renders your components into an HTML file located at `cypress/support/component-index.html`."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The index file allows you to add in global assets, such as styles, fonts, and external scripts."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can provide an alternative path to the file using the `indexHtmlFile` option in the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/configuration.md#component",
            "children": [
              {
                "type": "text",
                "value": "component config"
              }
            ]
          },
          {
            "type": "text",
            "value": " options:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  component: {    devServer,    indexHtmlFile: '/custom/path/to/component-index.html'  }}"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Custom Dev Server"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "A custom function can be passed into the `devServer` option, which allows the use of build systems not provided by Cypress out of the box. These can be from the Cypress community, preview builds not included with the app, or a custom one you create."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The function's signature takes in an object with the following properties as its only parameter and needs to resolve an object containing the port of your dev server and a callback to shut it down."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "interface DevServerOptions {  specs: Cypress.Spec[]  cypressConfig: Cypress.PluginConfigOptions  devServerEvents: NodeJS.EventEmitter}"
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "cypress.config.js"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "cypress.config.ts"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const { defineConfig } = require('cypress')module.exports = defineConfig({  component: {    async devServer({ specs, cypressConfig, devServerEvents }) {      const { port, close } = await startDevServer(        specs,        cypressConfig,        devServerEvents      )      return {        port,        close,      }    },  },})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'export default defineConfig({  component: {    async devServer({      specs,      cypressConfig,      devServerEvents,    }: DevServerOptions) {      const { port, close } = await startDevServer(        specs,        cypressConfig,        devServerEvents      )      return {        port,        close,      }    },  },})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Any requests triggered during a test using the `devServerPublicPathRoute` as defined in the `cypressConfig` will be forwarded to your server. Cypress will trigger a request for `[devServerPublicPathRoute]/index.html` when a test is started. Your server needs to reply with the html-file referenced in `cypressConfig.indexHtmlFile` and inject a script to load the support files and the actual test."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "function createServer(cypressConfig, bundleDir, port = 1234) {  const app = express()  // read kickstart script - see below for an example  const clientScript = readFileSync(    path.join(__dirname, './client-script.js'),    'utf8'  )  app.get(    cypressConfig.devServerPublicPathRoute + '/index.html',    async (_req, res) => {      // read custom index.html file      const html = await fs.readFile(        path.join(cypressConfig.repoRoot, cypressConfig.indexHtmlFile),        { encoding: 'utf8' }      )      // inject kickstart-script      const output = html.replace(        '</head>',        `<script type=\"module\">${clientScript}</script></head>`      )      res.send(output)    }  )  // you need to establish some url-to-path-mapping, if your bundler outputs  // the full directory structure you can map this one to one  app.use(cypressConfig.devServerPublicPathRoute, express.static(bundleDir))  app.listen(port)}"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "For a real-world example, you can refer to "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://github.com/cypress-io/cypress/blob/466155c2125476374d9f9549530f67d0c6354a41/npm/vite-dev-server/src/plugins/cypress.ts#L82-L92",
            "children": [
              {
                "type": "text",
                "value": "this loader"
              }
            ]
          },
          {
            "type": "text",
            "value": " used by the Vite Dev Server."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The client script must retrieve information on the currently active test from the Cypress instance of the parent frame and load the corresponding bundle. If a support file is defined, it should be injected at the top of your test bundle or loaded before the test script."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const CypressInstance = (window.Cypress = parent.Cypress)const devServerPublicPathRoute = CypressInstance.config(  'devServerPublicPathRoute')let importPromise = Promise.resolve()// If you do not bundle your support file along with the tests,// you need to add a separate import statement for the support file.const supportFilePath = CypressInstance.config('supportFile')if (supportFilePath) {  const relative = supportFilePath.replace(    CypressInstance.config('projectRoot'),    ''  )  importPromise = importPromise.then(    () => import(`${devServerPublicPathRoute}${relative}`)  )}// load the spec - you can extend the load function to also load cssconst { relative } = CypressInstance.specimportPromise = importPromise.then(  () => import(`${devServerPublicPathRoute}/${relative}`))// trigger loading the importsCypressInstance.onSpecWindow(window, importPromise)// then start the test processCypressInstance.action('app:window:before:load', window)"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "For a more complete example you can check out the "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://github.com/cypress-io/cypress/blob/develop/npm/vite-dev-server/client/initCypressTests.js",
            "children": [
              {
                "type": "text",
                "value": "kickstart script used in the vite-devserver."
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The `devServerEvents` event emitter should be used to notify cypress about finished builds by emitting a `dev-server:compile:success` event and to listen for the `dev-server:specs:changed` event that will notify you about changed entry points."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Spec Pattern for Component Tests"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "By default, Cypress looks for spec files anywhere in your project with an extension of `.cy.js`, `.cy.jsx`, `.cy.ts`, or `.cy.tsx`. However, you can change this behavior for component tests with a custom `specPattern` value. In the following example, we've configured Cypress to look for spec files with those same extensions, but only in the `src` folder or any of its subdirectories."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  component: {    specPattern: 'src/**/*.cy.{js,jsx,ts,tsx}'  }}"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Additional Config"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "For more information on all the available configuration options, see the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/configuration.md",
            "children": [
              {
                "type": "text",
                "value": "configuration reference"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      }
    ]
  },
  "token_estimate": 1063
}