task

Improve this doc

Execute code in Node.js via the task plugin event.

Anti-Pattern

We do not recommend starting a web server using cy.task(). Read about best practices here.

Syntax

cy.task(event)
cy.task(event, arg)
cy.task(event, arg, options)

Usage

Correct Usage

// in test
cy.task('log', 'This will be output to the terminal')
// in plugins file
on('task', {
  log (message) {
    console.log(message)

    return null
  }
})

Arguments

event (String)

An event name to be handled via the task event in the pluginsFile.

arg (Object)

An argument to send along with the event. This can be any value that can be serialized by JSON.stringify(). Unserializable types such as functions, regular expressions, or symbols will be omitted to null.

options (Object)

Pass in an options object to change the default behavior of cy.task().

Option Default Description
log true Displays the command in the Command log
timeout taskTimeout Time to wait for cy.task() to resolve before timing out

Yields

cy.task() yields the value returned or resolved by the task event in the pluginsFile.

Examples

Command

cy.task() provides an escape hatch for running arbitrary Node code, so you can take actions necessary for your tests outside of the scope of Cypress. This is great for:

  • Seeding your test database.
  • Storing state in Node that you want persisted between spec files.
  • Performing parallel tasks, like making multiple http requests outside of Cypress.
  • Running an external process.

In the task plugin event, the command will fail if undefined is returned. This helps catch typos or cases where the task event is not handled.

If you do not need to return a value, explicitly return null to signal that the given event has been handled.

Read a JSON file’s contents

Note: this serves as a demonstration only. We recommend using cy.fixture() or cy.readFile() for a more robust implementation of reading a file in your tests.

// in test
cy.task('readJson', 'cypress.json').then((data) => {
  // data equals:
  // {
  //   projectId: '12345',
  //   ...
  // }
})
// in plugins/index.js file
on('task', {
  readJson: (filename) => {
    // reads the file relative to current working directory
    return fsExtra.readJson(path.join(process.cwd(), filename)
  }
})

Seed a database

// in test
describe('e2e', () => {
  beforeEach(() => {
    cy.task('defaults:db')
    cy.visit('/')
  })

  it('displays article values', () => {
    cy.get('.article-list')
      .should('have.length', 10)
  })
})
// in plugins/index.js file
// we require some code in our app that
// is responsible for seeding our database
const db = require('../../server/src/db')

module.exports = (on, config) => {
  on('task', {
    'defaults:db': () => {
      return db.seed('defaults')
    }
  })
}

Options

Change the timeout

You can increase the time allowed to execute the task, although we do not recommend executing tasks that take a long time to exit.

Cypress will not continue running any other commands until cy.task() has finished, so a long-running command will drastically slow down your test runs.

// will fail if seeding the database takes longer than 20 seconds to finish
cy.task('seedDatabase', null, { timeout: 20000 })

Notes

Tasks must end

Tasks that do not end are not supported

cy.task() does not support tasks that do not end, such as:

  • Starting a server.
  • A task that watches for file changes.
  • Any process that needs to be manually interrupted to stop.

A task must end within the taskTimeout or Cypress will fail the current test.

Rules

Requirements

  • cy.task() requires being chained off of cy.

  • cy.task() requires the task to eventually end.

Assertions

  • cy.task() will only run assertions you've chained once, and will not retry.

Timeouts

  • cy.task() can time out waiting for the task to end.

Command Log

List the contents of cypress.json

cy.task('readJson', 'cypress.json')

The command above will display in the Command Log as:

Command Log task

When clicking on the task command within the command log, the console outputs the following:

console.log task

See also