cypress/docs/source/api/commands/exec.md

title, comments, description

title	comments	description
exec	true

Allows you to execute a system command. The system command can be anything you would normally run on the command line, such as npm run build, rake db:seed, etc.

cy.exec provides an escape hatch for running arbitrary system commands, so you can take actions necessary for your test, but outside the scope of Cypress. This is great for running build scripts, seeding your test database, starting or killing processes, etc.

cy.exec does not support commands that don't exit, such as rails server, a task that runs a watch, or any process that needs to be manually interrupted to stop. A command must exit within the timeout or Cypress will kill the command's process and fail the current test.

We don't recommend executing commands that take a long time to exit. Cypress will not continue running any other commands until cy.exec has finished, so a long-running command will drastically slow down your test cycle.

The current working directory is set to the project root (the directory that contains cypress.json).

Returns	an object with the exit code, the stdout, and the stderr
Timeout	cy.exec will allow the command to execute for the duration of the execTimeout

cy.exec( command )

Execute a system command.

Options

Pass in an options object to change the default behavior of cy.exec.

cy.exec( command, options )

Option	Default	Notes
log	true	whether to display command in command log
timeout	execTimeout	Total time to allow the command to execute
failOnNonZeroExit	true	Fail if the command exits with a non-zero code
env	{}	Object of environment variables to set before the command executes (e.g. { USERNAME: 'johndoe' }). Will be merged with existing system environment variables

Usage

Run a build command

cy
  .exec('npm run build')
  .then(function (result) {
    // subject is now the result object
    // {
    //   code: 0,
    //   stdout: "Files successfully built",
    //   stderr: ""
    // }
  })

Seed the database and assert it was successful

cy.exec('rake db:seed').its('code').should('eq', 0)

Run an arbitrary script and assert its output

cy.exec('npm run my-script').its('stdout').should('contain', 'Done running the script')

Change the timeout

// will fail if script takes longer than 20 seconds to finish
cy.exec('npm run build', { timeout: 20000 });

Choose not to fail on non-zero exit and assert on code and stderr

cy
  .exec('man bear pig', { failOnNonZeroExit: false })
  .its('code').should('eq', 1)
  .its('stderr').should('contain', 'No manual entry for bear')

Specify environment variables

cy
  .exec('echo $USERNAME', { env: { USERNAME: 'johndoe' } })
  .its('stdout').should('contain', 'johndoe')

Write to a file to create a fixture from response body

cy
  .server()
  .route('POST', '/comments').as('postComment')
  .get('.add-comment').click()
  .wait('@postComment').then(function(xhr){
    cy
      .exec(`echo ${JSON.stringify(xhr.responseBody)} >cypress/fixtures/comment.json`)
      .fixture('comment.json').should('deep.eq', xhr.responseBody)
  })

Command Log

List the contents of cypress.json

cy.exec('cat cypress.json')

The command above will display in the command log as:

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