{
  "doc": {
    "id": "api/commands/task",
    "title": "cy.task()",
    "description": "Run Node.js code from Cypress tests with cy.task() to seed databases, work with files, run CLIs, and share state between specs.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/task.md",
    "version": "c4ad6f88c531de58221c73dd91a75af7138334b8",
    "updated_at": "2026-11-10T01:15:02.829Z",
    "headings": [
      {
        "id": "api/commands/task#task",
        "text": "task",
        "level": 1
      },
      {
        "id": "api/commands/task#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/task#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/task#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/task#yields",
        "text": "Yields",
        "level": 3
      },
      {
        "id": "api/commands/task#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/task#read-and-clean-up-files-on-disk-with-cy-task",
        "text": "Read and clean up files on disk with cy.task()",
        "level": 3
      },
      {
        "id": "api/commands/task#read-a-file-that-might-not-exist-with-cy-task",
        "text": "Read a file that might not exist with cy.task()",
        "level": 4
      },
      {
        "id": "api/commands/task#count-the-files-in-a-folder-with-cy-task",
        "text": "Count the files in a folder with cy.task()",
        "level": 4
      },
      {
        "id": "api/commands/task#clean-up-and-verify-downloaded-files-with-cy-task",
        "text": "Clean up and verify downloaded files with cy.task()",
        "level": 4
      },
      {
        "id": "api/commands/task#manage-test-data-and-state-with-cy-task",
        "text": "Manage test data and state with cy.task()",
        "level": 3
      },
      {
        "id": "api/commands/task#seed-a-database-before-each-test-with-cy-task",
        "text": "Seed a database before each test with cy.task()",
        "level": 4
      },
      {
        "id": "api/commands/task#query-a-mysql-database-from-a-cypress-test",
        "text": "Query a MySQL database from a Cypress test",
        "level": 4
      },
      {
        "id": "api/commands/task#share-state-between-spec-files-with-cy-task",
        "text": "Share state between spec files with cy.task()",
        "level": 4
      },
      {
        "id": "api/commands/task#keep-a-variable-across-origins-with-cy-task",
        "text": "Keep a variable across origins with cy.task()",
        "level": 4
      },
      {
        "id": "api/commands/task#run-processes-outside-the-browser-with-cy-task",
        "text": "Run processes outside the browser with cy.task()",
        "level": 3
      },
      {
        "id": "api/commands/task#run-an-external-command-or-cli-with-cy-task",
        "text": "Run an external command or CLI with cy.task()",
        "level": 4
      },
      {
        "id": "api/commands/task#wait-for-an-email-or-background-job-with-cy-task",
        "text": "Wait for an email or background job with cy.task()",
        "level": 4
      },
      {
        "id": "api/commands/task#write-cy-task-handlers-in-setupnodeevents",
        "text": "Write cy.task() handlers in setupNodeEvents",
        "level": 3
      },
      {
        "id": "api/commands/task#return-a-promise-from-an-async-cy-task-handler",
        "text": "Return a promise from an async cy.task() handler",
        "level": 4
      },
      {
        "id": "api/commands/task#type-the-value-cy-task-yields-in-typescript",
        "text": "Type the value cy.task() yields in TypeScript",
        "level": 4
      },
      {
        "id": "api/commands/task#run-node-js-code-before-each-cypress-test",
        "text": "Run Node.js code before each Cypress test",
        "level": 4
      },
      {
        "id": "api/commands/task#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/task#cy-task-doesnt-support-long-running-processes",
        "text": "cy.task() doesn't support long-running processes",
        "level": 3
      },
      {
        "id": "api/commands/task#change-the-cy-task-timeout-for-a-command-or-suite",
        "text": "Change the cy.task() timeout for a command or suite",
        "level": 3
      },
      {
        "id": "api/commands/task#errors-thrown-in-a-cy-task-handler-fail-the-test",
        "text": "Errors thrown in a cy.task() handler fail the test",
        "level": 3
      },
      {
        "id": "api/commands/task#cypress-merges-every-on-task-registration",
        "text": "Cypress merges every on('task') registration",
        "level": 3
      },
      {
        "id": "api/commands/task#access-secrets-at-runtime-with-cy-task",
        "text": "Access secrets at runtime with cy.task()",
        "level": 3
      },
      {
        "id": "api/commands/task#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/task#requirements",
        "text": "Requirements",
        "level": 3
      },
      {
        "id": "api/commands/task#assertions",
        "text": "Assertions",
        "level": 3
      },
      {
        "id": "api/commands/task#timeouts",
        "text": "Timeouts",
        "level": 3
      },
      {
        "id": "api/commands/task#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/task#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/task#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "task"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.task()` runs code in "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://nodejs.org",
            "children": [
              {
                "type": "text",
                "value": "Node.js"
              }
            ]
          },
          {
            "type": "text",
            "value": " from your test, through the `task` event you register in "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin",
            "children": [
              {
                "type": "text",
                "value": "setupNodeEvents"
              }
            ]
          },
          {
            "type": "text",
            "value": ". It handles the work a browser can't do on its own:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Seed or query a database."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Read, clean up, and inspect files on disk."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Run a CLI or another external command."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Wait for something that happens outside the browser, such as an email."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Keep state between spec files."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Your test runs in the browser and your task handler runs in Node.js, so the argument and the return value are both serialized as they cross between the two:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Anti-Pattern"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Don't start a web server with `cy.task()`. Start it before Cypress instead, as described in "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/best-practices.md#Web-Servers",
            "children": [
              {
                "type": "text",
                "value": "Best Practices"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task(event)\ncy.task(event, arg)\ncy.task(event, arg, options)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Usage"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Correct Usage"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "log.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('log', 'This will be output to the terminal')"
      },
      {
        "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')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        log(message) {\n          console.log(message)\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        log(message) {\n          console.log(message)\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The `task` plugin event handler can return a value or a promise. The command fails if the handler returns `undefined` or the promise resolves with `undefined`. This catches typos and events that no handler covers."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you don't need to return a value, return `null` to signal that the event was handled."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Incorrect Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// Errors, the event name is required\ncy.task()"
      },
      {
        "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')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        // Errors, the handler returns undefined\n        log(message) {\n          console.log(message)\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        // Errors, the handler returns undefined\n        log(message) {\n          console.log(message)\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Arguments"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "event (String)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "An event name to be handled via the `task` event in 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."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "arg (Object)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "An argument to send along with the event. This can be any value that can be serialized by "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify",
            "children": [
              {
                "type": "text",
                "value": "JSON.stringify()"
              }
            ]
          },
          {
            "type": "text",
            "value": ", and the handler receives it the way `JSON.stringify()` would serialize it:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Functions, symbols, and `undefined` are dropped from object properties and become `null` inside arrays."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Regular expressions, `Map`, and `Set` become empty objects (`{}`)."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`Date` objects become ISO date strings. Rebuild one in the handler with `new Date(value)`."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "An argument with circular references can't be serialized, so the command fails."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When you omit `arg`, the handler receives `undefined`, so a default parameter value in the handler applies."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To pass multiple values, put them in an object and destructure it in the handler:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "hello.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('hello', { greeting: 'Hello', name: 'World' })"
      },
      {
        "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')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        // destructure the individual properties\n        hello({ greeting, name }) {\n          console.log('%s, %s', greeting, name)\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        // destructure the individual properties\n        hello({ greeting, name }) {\n          console.log('%s, %s', greeting, name)\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "options (Object)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Pass in an options object to change the default behavior of `cy.task()`."
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Option"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Default"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Description"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`log`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`true`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Displays the command in the "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/open-mode.md#Command-Log",
                    "children": [
                      {
                        "type": "text",
                        "value": "Command log"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`timeout`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md#Timeouts",
                    "children": [
                      {
                        "type": "text",
                        "value": "`taskTimeout`"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Time to wait for `cy.task()` to resolve before "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "#Timeouts",
                    "children": [
                      {
                        "type": "text",
                        "value": "timing out"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Yields"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.task()` yields the value returned or resolved by the `task` event in "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin",
            "children": [
              {
                "type": "text",
                "value": "setupNodeEvents"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Read and clean up files on disk with `cy.task()`"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Read a file that might not exist with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/readfile.md",
            "children": [
              {
                "type": "text",
                "value": "cy.readFile()"
              }
            ]
          },
          {
            "type": "text",
            "value": " assumes the file exists. To read a file that might not exist, use a task."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "read-file.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('readFileMaybe', 'my-file.txt').then((textOrNull) => { ... })"
      },
      {
        "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')\nconst fs = require('fs')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        readFileMaybe(filename) {\n          if (fs.existsSync(filename)) {\n            return fs.readFileSync(filename, 'utf8')\n          }\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nimport fs from 'fs'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        readFileMaybe(filename) {\n          if (fs.existsSync(filename)) {\n            return fs.readFileSync(filename, 'utf8')\n          }\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Count the files in a folder with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "count-files.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('countFiles', 'cypress/downloads').then((count) => { ... })"
      },
      {
        "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')\nconst fs = require('fs')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        countFiles(folderName) {\n          return new Promise((resolve, reject) => {\n            fs.readdir(folderName, (err, files) => {\n              if (err) {\n                return reject(err)\n              }\n\n              resolve(files.length)\n            })\n          })\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nimport fs from 'fs'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        countFiles(folderName) {\n          return new Promise((resolve, reject) => {\n            fs.readdir(folderName, (err, files) => {\n              if (err) {\n                return reject(err)\n              }\n\n              resolve(files.length)\n            })\n          })\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Clean up and verify downloaded files with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Tasks are a good fit for file system work, such as emptying the downloads folder between tests and then finding the file the test just downloaded. `config.downloadsFolder` is the resolved absolute path, so the task keeps working if the project overrides "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/configuration.md#Downloads",
            "children": [
              {
                "type": "text",
                "value": "`downloadsFolder`"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "downloads.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('clearDownloads')\n\ncy.task('latestDownload').then((filepath) => {\n  expect(filepath).to.be.a('string')\n  cy.readFile(filepath)\n})"
      },
      {
        "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')\nconst fs = require('fs')\nconst path = require('path')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      const downloads = config.downloadsFolder\n\n      on('task', {\n        clearDownloads() {\n          fs.rmSync(downloads, { recursive: true, force: true })\n          fs.mkdirSync(downloads, { recursive: true })\n\n          return null\n        },\n\n        latestDownload() {\n          const files = fs\n            .readdirSync(downloads)\n            .map((name) => ({\n              name,\n              time: fs.statSync(path.join(downloads, name)).mtimeMs,\n            }))\n            .sort((a, b) => b.time - a.time)\n\n          return files.length ? path.join(downloads, files[0].name) : null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nimport fs from 'fs'\nimport path from 'path'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      const downloads = config.downloadsFolder\n\n      on('task', {\n        clearDownloads() {\n          fs.rmSync(downloads, { recursive: true, force: true })\n          fs.mkdirSync(downloads, { recursive: true })\n\n          return null\n        },\n\n        latestDownload() {\n          const files = fs\n            .readdirSync(downloads)\n            .map((name) => ({\n              name,\n              time: fs.statSync(path.join(downloads, name)).mtimeMs,\n            }))\n            .sort((a, b) => b.time - a.time)\n\n          return files.length ? path.join(downloads, files[0].name) : null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress already trashes the downloads folder before `cypress run` when "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/configuration.md#trashAssetsBeforeRuns",
            "children": [
              {
                "type": "text",
                "value": "`trashAssetsBeforeRuns`"
              }
            ]
          },
          {
            "type": "text",
            "value": " is enabled, which it is by default. A `clearDownloads` task is for clearing the folder between tests within a run."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Manage test data and state with `cy.task()`"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Seed a database before each test with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "articles.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "describe('e2e', () => {\n  beforeEach(() => {\n    cy.task('defaults:db')\n    cy.visit('/')\n  })\n\n  it('displays article values', () => {\n    cy.get('.article-list').should('have.length', 10)\n  })\n})"
      },
      {
        "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')\n// the module in your app that seeds the database,\n// with a path relative to the Cypress config file\nconst db = require('./server/db')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        async 'defaults:db'() {\n          await db.seed('defaults')\n\n          // seed() may resolve with undefined, so signal success explicitly\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n// the module in your app that seeds the database,\n// with a path relative to the Cypress config file\nimport db from './server/db'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        async 'defaults:db'() {\n          await db.seed('defaults')\n\n          // seed() may resolve with undefined, so signal success explicitly\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Query a MySQL database from a Cypress test"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Pass the query and the name of the database to run it against in one object, then destructure it in the handler. This example uses the "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://www.npmjs.com/package/mysql2",
            "children": [
              {
                "type": "text",
                "value": "mysql2"
              }
            ]
          },
          {
            "type": "text",
            "value": " client."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "query-users.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const dbName = 'stagingA'\nconst query = 'SELECT * FROM users'\n\ncy.task('queryDatabase', { dbName, query })"
      },
      {
        "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')\nconst mysql = require('mysql2/promise')\n\n// the connection details for each database could\n// come from environment variables\nconst connections = {\n  stagingA: {\n    host: 'staging.my.co',\n    user: 'test',\n    password: '***',\n    database: 'users',\n  },\n  stagingB: {\n    host: 'staging-b.my.co',\n    user: 'test',\n    password: '***',\n    database: 'users',\n  },\n}\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        // destructure the argument into the individual fields\n        async queryDatabase({ dbName, query }) {\n          const connectionInfo = connections[dbName]\n\n          if (!connectionInfo) {\n            throw new Error(`No database connection named ${dbName}`)\n          }\n\n          const connection = await mysql.createConnection(connectionInfo)\n\n          try {\n            const [rows] = await connection.query(query)\n\n            return rows\n          } finally {\n            await connection.end()\n          }\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nimport mysql from 'mysql2/promise'\n\n// the connection details for each database could\n// come from environment variables\nconst connections: Record<string, mysql.ConnectionOptions> = {\n  stagingA: {\n    host: 'staging.my.co',\n    user: 'test',\n    password: '***',\n    database: 'users',\n  },\n  stagingB: {\n    host: 'staging-b.my.co',\n    user: 'test',\n    password: '***',\n    database: 'users',\n  },\n}\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        // destructure the argument into the individual fields\n        async queryDatabase({ dbName, query }) {\n          const connectionInfo = connections[dbName]\n\n          if (!connectionInfo) {\n            throw new Error(`No database connection named ${dbName}`)\n          }\n\n          const connection = await mysql.createConnection(connectionInfo)\n\n          try {\n            const [rows] = await connection.query(query)\n\n            return rows\n          } finally {\n            await connection.end()\n          }\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Share state between spec files with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The config process keeps running for the whole run, so a value stored in a variable there is still available to later spec files."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "create-org.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('setValue', { key: 'orgId', value: 42 })"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "view-org.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('getValue', 'orgId').should('eq', 42)"
      },
      {
        "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')\nconst store = {}\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        setValue({ key, value }) {\n          store[key] = value\n\n          return null\n        },\n        getValue(key) {\n          // return null rather than undefined when the key is missing\n          return store[key] ?? null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nconst store: Record<string, unknown> = {}\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        setValue({ key, value }) {\n          store[key] = value\n\n          return null\n        },\n        getValue(key) {\n          // return null rather than undefined when the key is missing\n          return store[key] ?? null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Keep these behaviors in mind:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "The store starts empty each time the config process starts, such as at the beginning of every `cypress run`."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Machines running specs in parallel each have their own config process, so they don't share values."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "A spec that reads a value another spec wrote only passes when the specs run in that order. Use a store for values you can recreate when they're missing, and "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/session.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.session()`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " for caching logins."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Keep a variable across origins with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When a test visits a different origin, Cypress reloads the spec to "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/guides/cross-origin-testing.md",
            "children": [
              {
                "type": "text",
                "value": "switch to the new origin"
              }
            ]
          },
          {
            "type": "text",
            "value": ", which resets the variables in your spec file. A task keeps the value in Node.js, where the reload doesn't reach it."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "href.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "describe('Href visit', () => {\n  it('captures href', () => {\n    cy.visit('https://example.cypress.io')\n    cy.get('a')\n      .invoke('attr', 'href')\n      .then((href) => {\n        // href is not same-origin as current url\n        // like https://www.cypress-dx.com\n        cy.task('setHref', href)\n      })\n  })\n\n  it('visit href', () => {\n    cy.task('getHref').then((href) => {\n      // visit non same-origin url https://www.cypress-dx.com\n      cy.visit(href)\n    })\n  })\n})"
      },
      {
        "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')\nlet href\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        setHref: (val) => {\n          return (href = val)\n        },\n        getHref: () => {\n          return href\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nlet href: string\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        setHref: (val) => {\n          return (href = val)\n        },\n        getHref: () => {\n          return href\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Run processes outside the browser with `cy.task()`"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Run an external command or CLI with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When setup depends on a tool that isn't a Node module, such as a Docker container, a database CLI, or a cloud provider's command line tool, spawn it from the task with "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://nodejs.org/api/child_process.html#child_processexecfilesynccommand-args-options",
            "children": [
              {
                "type": "text",
                "value": "`child_process.execFileSync()`"
              }
            ]
          },
          {
            "type": "text",
            "value": ". Passing the arguments as an array avoids the shell entirely, so quoting and `PATH` resolution behave the same way on every platform."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "database.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('resetDatabase')"
      },
      {
        "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')\nconst { execFileSync } = require('child_process')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        resetDatabase() {\n          execFileSync('docker', ['exec', 'db', 'reset-script'], {\n            stdio: 'pipe',\n          })\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nimport { execFileSync } from 'child_process'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        resetDatabase() {\n          execFileSync('docker', ['exec', 'db', 'reset-script'], {\n            stdio: 'pipe',\n          })\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "A task can also return the command's output to the test:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "bucket.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('listBucket', 's3://my-test-bucket').should('have.length', 3)"
      },
      {
        "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')\nconst { execFileSync } = require('child_process')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        listBucket(bucket) {\n          const output = execFileSync('aws', ['s3', 'ls', bucket], {\n            encoding: 'utf8',\n          })\n\n          return output.split('\\n').filter(Boolean)\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nimport { execFileSync } from 'child_process'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        listBucket(bucket) {\n          const output = execFileSync('aws', ['s3', 'ls', bucket], {\n            encoding: 'utf8',\n          })\n\n          return output.split('\\n').filter(Boolean)\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Wait for an email or background job with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.task()` runs the handler once and doesn't retry it. To wait for something that happens outside the browser, such as an email arriving or a background job finishing, poll inside the handler and resolve once the result is ready."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "signup.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task(\n  'waitForEmail',\n  { to: 'new-user@example.com', timeout: 30000 },\n  { timeout: 40000 }\n)\n  .its('subject')\n  .should('eq', 'Welcome to the app')"
      },
      {
        "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')\n// findEmail comes from your email testing service's client\nconst { findEmail } = require('./mail-client')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        async waitForEmail({ to, timeout }) {\n          const deadline = Date.now() + timeout\n\n          while (Date.now() < deadline) {\n            const email = await findEmail(to)\n\n            if (email) {\n              return email\n            }\n\n            await new Promise((resolve) => setTimeout(resolve, 1000))\n          }\n\n          throw new Error(`No email to ${to} arrived within ${timeout}ms`)\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n// findEmail comes from your email testing service's client\nimport { findEmail } from './mail-client'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        async waitForEmail({ to, timeout }) {\n          const deadline = Date.now() + timeout\n\n          while (Date.now() < deadline) {\n            const email = await findEmail(to)\n\n            if (email) {\n              return email\n            }\n\n            await new Promise((resolve) => setTimeout(resolve, 1000))\n          }\n\n          throw new Error(`No email to ${to} arrived within ${timeout}ms`)\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Give the `cy.task()` `timeout` option a few seconds more than the handler's own deadline. The handler then gives up first, and the test fails with its message instead of a generic timeout."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Write `cy.task()` handlers in `setupNodeEvents`"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Return a promise from an async `cy.task()` handler"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "pause.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('pause', 1000)"
      },
      {
        "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')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        pause(ms) {\n          return new Promise((resolve) => {\n            // tasks should not resolve with undefined\n            setTimeout(() => resolve(null), ms)\n          })\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        pause(ms) {\n          return new Promise((resolve) => {\n            // tasks should not resolve with undefined\n            setTimeout(() => resolve(null), ms)\n          })\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Type the value `cy.task()` yields in TypeScript"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "In TypeScript, `cy.task()` yields `unknown` unless you pass a type parameter describing what the task returns. Cypress doesn't check the type at runtime, so keep it in step with the handler."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "users.cy.ts"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "type User = { id: number; name: string }\n\ncy.task<User[]>('getUsers').then((users) => {\n  // users is typed as User[]\n  expect(users[0].name).to.eq('Ada')\n})"
      },
      {
        "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')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        getUsers() {\n          return [\n            { id: 1, name: 'Ada' },\n            { id: 2, name: 'Grace' },\n          ]\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        getUsers() {\n          return [\n            { id: 1, name: 'Ada' },\n            { id: 2, name: 'Grace' },\n          ]\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Run Node.js code before each Cypress test"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "There is no `setupNodeEvents` event for each test. To run Node.js code before every test, call `cy.task()` from a global `beforeEach` in your "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file",
            "children": [
              {
                "type": "text",
                "value": "support file"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "cypress/support/e2e.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "beforeEach(function () {\n  cy.task('logTestStart', this.currentTest.fullTitle())\n})"
      },
      {
        "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')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        logTestStart(title) {\n          console.log(`Starting: ${title}`)\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        logTestStart(title) {\n          console.log(`Starting: ${title}`)\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Notes"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "`cy.task()` doesn't support long-running processes"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.task()` doesn't support tasks that keep running, such as:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Starting a server."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Watching for file changes."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Any process that needs to be interrupted to stop."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "A task must end within the "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Change-the-cytask-timeout-for-a-command-or-suite",
            "children": [
              {
                "type": "text",
                "value": "timeout"
              }
            ]
          },
          {
            "type": "text",
            "value": ", or Cypress fails the current test."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Change the `cy.task()` timeout for a command or suite"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.task()` waits up to "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/configuration.md#Timeouts",
            "children": [
              {
                "type": "text",
                "value": "`taskTimeout`"
              }
            ]
          },
          {
            "type": "text",
            "value": ", 60 seconds by default. Keep tasks short where you can: Cypress doesn't run any other commands until `cy.task()` finishes, so a long task slows down every test that calls it."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To give one command more time, pass the `timeout` option:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// fails if seeding the database takes longer than 20 seconds\ncy.task('seedDatabase', null, { timeout: 20000 })"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To change it for a suite or test, set `taskTimeout` in the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/configuration.md#Test-Configuration",
            "children": [
              {
                "type": "text",
                "value": "test configuration"
              }
            ]
          },
          {
            "type": "text",
            "value": ". The value applies while that suite or test runs, then returns to the previous value."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "describe('has data available from database', { taskTimeout: 90000 }, () => {\n  before(() => {\n    cy.task('seedDatabase')\n  })\n\n  // tests\n\n  after(() => {\n    cy.task('resetDatabase')\n  })\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To change it for the rest of the spec file, set it with "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/cypress-api/config.md",
            "children": [
              {
                "type": "text",
                "value": "Cypress.config()"
              }
            ]
          },
          {
            "type": "text",
            "value": ":"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "Cypress.config('taskTimeout', 30000)\nCypress.config('taskTimeout') // => 30000"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Errors thrown in a `cy.task()` handler fail the test"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When a handler throws or returns a rejected promise, `cy.task()` fails the test with the error's message."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Return `null` when \"not found\" is an answer the test can act on, and throw when the test can't continue:"
          }
        ]
      },
      {
        "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')\nconst users = [{ email: 'ada@example.com', name: 'Ada' }]\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        // a missing user is an expected answer, so return null\n        findUser(email) {\n          return users.find((user) => user.email === email) ?? null\n        },\n        // a test that deletes a missing user has bad setup, so throw\n        deleteUser(email) {\n          const index = users.findIndex((user) => user.email === email)\n\n          if (index === -1) {\n            throw new Error(`No user with email ${email}`)\n          }\n\n          users.splice(index, 1)\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nconst users = [{ email: 'ada@example.com', name: 'Ada' }]\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        // a missing user is an expected answer, so return null\n        findUser(email) {\n          return users.find((user) => user.email === email) ?? null\n        },\n        // a test that deletes a missing user has bad setup, so throw\n        deleteUser(email) {\n          const index = users.findIndex((user) => user.email === email)\n\n          if (index === -1) {\n            throw new Error(`No user with email ${email}`)\n          }\n\n          users.splice(index, 1)\n\n          return null\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "users.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('deleteUser', 'grace@example.com')"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "CypressError: `cy.task('deleteUser')` failed with the following error:\n\n> No user with email grace@example.com\n\nhttps://on.cypress.io/api/task"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "In the Cypress App, the error points to the `cy.task()` line in your spec. Expand Stack trace to find the `From Node.js Internals` section, which shows where your handler threw."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Cypress merges every `on('task')` registration"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress merges every `on('task')` object you register, so you can split your tasks into modules by area. Each module exports an object of handlers, like this `state.ts`:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "JavaScript"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "TypeScript"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/tasks/state.ts\nconst store = {}\n\nmodule.exports.stateTasks = {\n  setValue({ key, value }) {\n    store[key] = value\n\n    return null\n  },\n  getValue(key) {\n    return store[key] ?? null\n  },\n}"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/tasks/state.ts\nconst store: Record<string, unknown> = {}\n\nexport const stateTasks = {\n  setValue({ key, value }: { key: string; value: unknown }) {\n    store[key] = value\n\n    return null\n  },\n  getValue(key: string) {\n    return store[key] ?? null\n  },\n}"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Then register each module, here alongside a `users.ts` module built the same way:"
          }
        ]
      },
      {
        "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')\nconst { stateTasks } = require('./cypress/tasks/state')\nconst { userTasks } = require('./cypress/tasks/users')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', stateTasks)\n      on('task', userTasks)\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\nimport { stateTasks } from './cypress/tasks/state'\nimport { userTasks } from './cypress/tasks/users'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', stateTasks)\n      on('task', userTasks)\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Plugins that export their own tasks merge the same way, alongside yours."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Duplicate task keys"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If multiple task objects use the same key, the later registration overwrites that particular key, the same way merging multiple objects with duplicate keys overwrites the first one. Cypress prints a warning in the terminal that names each duplicated task."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Access secrets at runtime with `cy.task()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.task()` reads secrets at runtime, which suits values from an external secret manager or an API that isn't available at configuration time. For secrets that are available at configuration time, use "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/env.md",
            "children": [
              {
                "type": "text",
                "value": "cy.env()"
              }
            ]
          },
          {
            "type": "text",
            "value": " instead."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "secrets.cy.js"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// executes at runtime\ncy.task('getSecret', 'API_KEY', { log: false }).then((apiKey) => {\n  cy.request({\n    method: 'POST',\n    url: 'https://api.example.com/data',\n    headers: {\n      Authorization: `Bearer ${apiKey}`,\n    },\n    log: false,\n  })\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Pass `{ log: false }` to both commands. Otherwise the Command Log shows the `cy.task()` call, its console output shows the secret it yields, and the `cy.request()` console output shows the `Authorization` header. With `log: false`, neither command appears in the Command Log."
          }
        ]
      },
      {
        "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')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      // Task definition - executes when cy.task() is called in tests\n      on('task', {\n        getSecret(secretName) {\n          // This reads from process.env at runtime, not at configuration time\n          // Useful when secrets are fetched dynamically or only needed conditionally\n          const secret = process.env[secretName]\n\n          if (!secret) {\n            throw new Error(`Secret ${secretName} is not set`)\n          }\n\n          return secret\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      // Task definition - executes when cy.task() is called in tests\n      on('task', {\n        getSecret(secretName: string) {\n          // This reads from process.env at runtime, not at configuration time\n          // Useful when secrets are fetched dynamically or only needed conditionally\n          const secret = process.env[secretName]\n\n          if (!secret) {\n            throw new Error(`Secret ${secretName} is not set`)\n          }\n\n          return secret\n        },\n      })\n    },\n  },\n})"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Rules"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Requirements"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.task()` requires being chained off of `cy`."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.task()` requires a non-empty string as its first argument."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.task()` requires the `task` event to be registered in "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin",
                    "children": [
                      {
                        "type": "text",
                        "value": "setupNodeEvents"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": ", with a handler for the given event name."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.task()` requires being invoked from the spec file or support file in end-to-end tests."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.task()` requires the task to eventually end."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Assertions"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.task()` runs the assertions you chain once and doesn't "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/core-concepts/retry-ability.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "retry"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " them."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Timeouts"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.task()` can time out waiting for the task to end."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Command Log"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This example uses the "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Count-the-files-in-a-folder-with-cytask",
            "children": [
              {
                "type": "text",
                "value": "Count the files in a folder with cy.task()"
              }
            ]
          },
          {
            "type": "text",
            "value": " task defined above."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.task('countFiles', 'cypress/e2e')"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The command above displays in the Command Log as:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When you click the `task` command in the Command Log, the console shows the following:"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "History"
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Version"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Changes"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#5-6-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "5.6.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added a type parameter for the value `cy.task()` yields"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#5-3-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "5.3.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "A task called without an argument receives `undefined` instead of `null`"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#4-4-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "4.4.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "The error for a task that resolves `undefined` names the resolution value it needs"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#3-0-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "3.0.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.task()` command added"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "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/app/core-concepts/writing-and-organizing-tests.md#Choosing-how-to-load-test-data-in-Cypress",
                    "children": [
                      {
                        "type": "text",
                        "value": "Guide: Choosing how to load test data"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin",
                    "children": [
                      {
                        "type": "text",
                        "value": "Guide: Using a plugin in setupNodeEvents"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/fixture.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.fixture()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/readfile.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.readFile()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/request.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.request()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/session.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.session()`"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 6212
}