{ "doc": { "id": "api/node-events/before-run-api", "title": "Before Run Event | Cypress Node Events", "description": "The before:run event fires before a run starts in Cypress.", "section": "api", "source_path": "/llm/markdown/api/node-events/before-run-api.md", "version": "524ff5211e60b5d53e55d6ad976d83966f66e7cd", "updated_at": "2026-04-30T14:20:05.396Z", "headings": [ { "id": "api/node-events/before-run-api#before-run-event", "text": "Before Run Event", "level": 1 }, { "id": "api/node-events/before-run-api#syntax", "text": "Syntax", "level": 2 }, { "id": "api/node-events/before-run-api#usage", "text": "Usage", "level": 2 }, { "id": "api/node-events/before-run-api#log-the-browser-and-the-number-of-specs-that-will-be-run", "text": "Log the browser and the number of specs that will be run", "level": 3 }, { "id": "api/node-events/before-run-api#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Before Run Event" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `before:run` event fires before a run starts. When running cypress via `cypress open`, the event will fire when opening a project." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The event will fire each time `cypress run` executes. As a result, if running your specs in " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md", "children": [ { "type": "text", "value": "parallel" } ] }, { "type": "text", "value": ", the event will fire once for each machine on which the tests are run." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Syntax" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "⚠️ This code is part of the " }, { "type": "link", "title": null, "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin", "children": [ { "type": "text", "value": "setupNodeEvents" } ] }, { "type": "text", "value": " function and thus executes in the Node environment. You cannot call `Cypress` or `cy` commands in this function, but you do have the direct access to the file system and the rest of the operating system." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "⚠️ When running via `cypress open`, the `before:run` event only fires if the " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/experiments.md#Configuration", "children": [ { "type": "text", "value": "experimentalInteractiveRunEvents flag" } ] }, { "type": "text", "value": " is enabled." } ] }, { "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({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { on('before:run', (details) => { /* ... */ }) }, },})" }, { "type": "code", "lang": null, "meta": null, "value": "import { defineConfig } from 'cypress'export default defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { on('before:run', (details) => { /* ... */ }) }, },})" }, { "type": "paragraph", "children": [ { "type": "text", "value": "details (Object)" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Details of the run, including the project config, system information, and the version of Cypress. More details are included when running via `cypress run`." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Usage" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "You can return a promise from the `before:run` event handler and it will be awaited before Cypress proceeds running your specs." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Log the browser and the number of specs that will be run" } ] }, { "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({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { on('before:run', (details) => { // details will look something like this when run via `cypress run`: // { // config: { // projectId: '12345', // baseUrl: 'http://example.com/', // viewportWidth: 1000, // viewportHeight: 660, // // ...more properties... // }, // browser: { // name: 'electron', // version: '59.0.3071.115', // // ...more properties... // }, // system: { // osName: 'darwin', // osVersion: '16.7.0', // } // cypressVersion: '6.1.0', // specs: [ // { // name: 'login_cy.js', // relative: 'cypress/e2e/login_cy.js', // absolute: '/Users/janelane/app/cypress/e2e/login_cy.js', // }, // // ... more specs // ], // specPattern: [ // '**/*.cy.{js,jsx,ts,tsx}' // ], // parallel: false, // group: 'group-1', // tag: 'tag-1' // } // details will look something like this when run via `cypress open`: // { // config: { // projectId: '12345', // baseUrl: 'http://example.com/', // viewportWidth: 1000, // viewportHeight: 660, // // ...more properties... // }, // system: { // osName: 'darwin', // osVersion: '16.7.0', // } // cypressVersion: '7.0.0' // } if (details.specs && details.browser) { // details.specs and details.browser will be undefined in interactive mode console.log( 'Running', details.specs.length, 'specs in', details.browser.name ) } }) }, },})" }, { "type": "code", "lang": null, "meta": null, "value": "import { defineConfig } from 'cypress'export default defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { on('before:run', (details) => { // details will look something like this when run via `cypress run`: // { // config: { // projectId: '12345', // baseUrl: 'http://example.com/', // viewportWidth: 1000, // viewportHeight: 660, // // ...more properties... // }, // browser: { // name: 'electron', // version: '59.0.3071.115', // // ...more properties... // }, // system: { // osName: 'darwin', // osVersion: '16.7.0', // } // cypressVersion: '6.1.0', // specs: [ // { // name: 'login_cy.js', // relative: 'cypress/e2e/login_cy.js', // absolute: '/Users/janelane/app/cypress/e2e/login_cy.js', // }, // // ... more specs // ], // specPattern: [ // '**/*.cy.{js,jsx,ts,tsx}' // ], // parallel: false, // group: 'group-1', // tag: 'tag-1' // } // details will look something like this when run via `cypress open`: // { // config: { // projectId: '12345', // baseUrl: 'http://example.com/', // viewportWidth: 1000, // viewportHeight: 660, // // ...more properties... // }, // system: { // osName: 'darwin', // osVersion: '16.7.0', // } // cypressVersion: '7.0.0' // } if (details.specs && details.browser) { // details.specs and details.browser will be undefined in interactive mode console.log( 'Running', details.specs.length, 'specs in', details.browser.name ) } }) }, },})" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "See also" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/node-events/after-run-api.md", "children": [ { "type": "text", "value": "After Run API" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/node-events/before-spec-api.md", "children": [ { "type": "text", "value": "Before Spec API" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/node-events/after-spec-api.md", "children": [ { "type": "text", "value": "After Spec API" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/app/plugins/plugins-guide.md", "children": [ { "type": "text", "value": "How to use Plugins" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/node-events/overview.md", "children": [ { "type": "text", "value": "Node Events Overview" } ] } ] } ] } ] } ] }, "token_estimate": 959 }