Running Cypress Tests in Headless Mode

Learn how to run Cypress tests in headless mode

One of the important things to consider when writing tests is being able to test things in a way like the people using your application are actually using them.  

Test automation tool Cypress makes this easy. With its framework, we’re able to run commands that test our applications directly in the same browsers that our users are using them in.

One of the issues though is we don’t always have access to environments that are able to display and open the browser in a traditional way. When using Continuous Integration tools, we don’t have the ability to actually use browser interfaces and spin up a browser like we would on our local computer. 

Instead, we need to find a way to run our tests headlessly to avoid requiring that actual browser interface. When using Cypress locally with this interface, we’re using the open command. This allows us to select whatever test we want and run it directly on our local environment.

But Cypress actually has another command called run where with it we can run these tests without that Cypress environment. 

Headless Mode with Cypress Using Electron Browser

If we now run that command as npm run cy:run, which is going to run this cypress run command, we can see that as it starts up that, instead of Cypress actually opening up that little interface for us to select our tests, it’s going to go through and run all of our tests that we have in our suite without actually spitting up a new browser. 

We can see inside of our Cypress logs that Cypress used the Electron browser, where it did so headlessly. We can see on the Cypress documentation that whenever we run cypress run, by default, as long as we’re using that Electron browser, it’s going to run headlessly.

Now, to point this out again it only does this if we’re running the Electron browser. 

What if we wanted to provide a different browser, such as Chrome or Firefox, so that we can still run it headlessly? 

Running Tests Headlessly with Chrome in Cypress

To try this out, if we add –browser chrome at the end of our cypress run command. When we try to run that again, we can see this time as the logs pop up, it’s going to say that we’re running the Chrome browser. 

We can even see that it’s going to spin up a new instance of Chrome to run those tests, which if we’re running it on Continuous Integration, that’s not going to work. What we can do is include the headless flag, so Cypress knows to still run that browser headlessly. 

So, at the end of our run command, we’re going to add –headless. 

Now when we run our tests again, we can see that we’re passing in that headless flag and Chrome is going to load headlessly. It’s not going to actually try to open up a browser when running the tests.

Running Tests Headlessly with Firefox in Cypress

We can even see this work similarly if we change Chrome to Firefox. If we now run the cypress run command, we can see this time we’re going to try to run Firefox headlessly. 

As Cypress is running these tests, it’s going to use Firefox this time and still run headlessly. 

Summing It Up – Running Headless Modes with Cypress

In review, when we’re running our tests, we don’t always have access to an actual browser UI. So, we can run our tests headlessly, where if we’re running our default Cypress settings with the Electron browser, we can simply run cypress run. 

But if we want to specify a different browser, such as Chrome or Firefox, we can additionally pass in the –headless flag. And we can be sure that Cypress is going to run all those tests headlessly.

Resources

• Git Repo – login.spec.js
• Git Repo – cypress/package.json
• Cypres Docs – cypress run
• Electron Browser