How to Use Cypress in Headless Mode

Popular Headless Browsers

The choice of using Cypress in headless mode depends entirely on the specific application requirements you are testing. Headless browser allows you to run the test cases in a headless (i.e., GUI-less) environment, which can be useful for running tests in a Continuous Integration (CI) environment or scripts that don’t require a visible UI.

Here are some commonly used headless browsers (irrespective of whether the framework is being used for automated testing)

• Firefox Headless
• Chrome Headless
• WebKit Headless
• PhantomJS
• HtmlUnit Browsers

Though I have listed all major headless browsers, it is important to note that Cypress supports Firefox, Chrome, and WebKit headless browsers.

Firefox headless mode

Firefox headless mode is a web browser that allows you to test the application without the head. You cannot see anything while accessing any website using a headless browser. The application, however, operates in the background, and you can monitor the execution result once the test cases have finished running.

Firefox headless mode can be an effective option for automating web browsing tasks using Cypress. By running Firefox using Cypress in headless mode, you can interact with the browser as a regular user.

Chrome headless mode

Google’s Chrome team included headless Chrome mode in their browser, making running a Chrome headless browser from the command line easier.

Running tests using Cypress in headless mode makes fast test case execution and eliminates the need for manual interaction with the browser during testing.

WebKit headless mode

WebKit is an open-source web browser engine developed by Apple and used in the Safari browser. The headless mode of WebKit is a feature that allows the engine to run without a browser.

You can run tests on WebKit using Cypress in headless mode. To run Cypress test cases in WebKit, we must do some config settings and add the dependency. Add experimentalWebKitSupport: true in the cypress.config.js file to enable the experiment. Add dependency using the command to install the playwright-webkit NPM package in your repo to acquire WebKit: npm install –save-dev playwright-webkit.

PhantomJS headless mode

PhantomJS is a popular solution for running browser-based unit tests in a headless system like a continuous integration environment since it provides a JavaScript API that enables automated navigation, screenshots, user behavior, and assertions.

Additionally, PhantomJS can be used to automate tasks such as filling out forms, clicking buttons, and navigating pages, which can be useful for functional and regression testing.

Some common use cases include:

• PhantomJS can interact with web pages similarly to a web browser, allowing developers to automate tasks such as filling out forms, clicking buttons, and navigating between pages.
• It can extract data from web pages, such as scraping product prices from an eCommerce site or extracting data from a table on a web page.
• PhantomJS can generate screenshots or PDFs of web pages, which can help create reports or test a website’s appearance on different devices and screen resolutions.

HtmlUnit headless mode

HtmlUnit is a Java-based headless browser that allows developers to automate web page interactions. It can be controlled programmatically, allowing developers to simulate a user navigating a website and interacting with its elements, such as clicking buttons and filling out forms. HtmlUnit supports JavaScript and can work with various web standards, making it a versatile tool for web development and testing.

It can be integrated with popular testing frameworks such as JUnit and TestNG, allowing developers to write tests in Java and run them in HtmlUnit.

Additionally, HtmlUnit can be useful for testing web applications by simulating interactions with the web page and checking the resulting page source or DOM.

​​Use case in software testing using HtmlUnit headless browser:

• Developers could use HtmlUnit to simulate a user logging into a web application by navigating to the login page, filling out the login form, and submitting it.
• You can use HtmlUnit to navigate to various web application pages, interacting with elements such as buttons and links and asserting that the expected results occur.

As mentioned, Cypress supports Firefox, Chrome, and WebKit headless browsers. Hence, I would be demonstrating Cypress headless testing on the said browsers.

Testing with Cypress in Headless Mode

Before explaining how to run the test cases in headless mode in Cypress, let’s set up a Cypress project first.

To explain how we can run test cases in headless mode in Cypress, I will test a typical eCommerce site: TestMu AI eCommerce Playground.

Implementation Test Scenario

In this Cypress tutorial, we are using the below example to run the Cypress test case in a headless browser in Local Grid and TestMu AI Grid.

Test Scenario:

• Open the Site https://ecommerce-playground.lambdatest.io/index.php?route=account/login.
• Enter the email address.
• Enter the password.
• Click on the Login button.
• Click on the ‘All Categories’ drop-down.
• Enter the product to search.
• Search the product.
• Verify the correct product is searched.

Setting up Cypress

You can establish a new Cypress project by following the instructions below:

Step 1: Create a folder and generate package.json.

• Create a project by Cypress_Headless.
• Create a package.json file using the npm init command.

Step 2: Install Cypress

Run this command in the newly created folder to install Cypress.

npm install cypress —save-dev

Or

yarn add cypress --dev

​​Cypress will be installed locally as a dev dependency for your project.

Note: Cypress version 12.3.0 is installed, as shown below. At the time of writing this blog, the most recent version of Cypress is 12.3.0

{
 "name": "cypress_headless",
 "version": "1.0.0",
 "description": "",
 "main": "index.js",
 "scripts": {
   "test": "echo "Error: no test specified" && exit 1"
 },
 "author": "Kailash Pathak",
 "license": "ISC",
 "dependencies": {
   "cypress": "^12.3.0"
 }
}

Different ways to run Cypress tests in a headless browser

There are various ways of executing the Cypress test cases in headless browser mode.

• To run all the test cases of the e2e folder in headless mode, use the yarn cypress run command. This command will run all the test cases under the e2e folder.
• To run the particular .spec file in the headless mode, you can run the command yarn cypress run –spec cypress/e2e/example.cy.js.
• Another way of running the test cases in headless mode is by adding scripts to the package.json. To run all test cases, we must run the command yarn run cy:run in the terminal. This command will execute all the test cases in headless mode.

{
 "name": "cypress_headless",
 "version": "1.0.0",
 "description": "",
 "main": "index.js",
 "scripts": {
   "cy:run": "yarn cypress run"
 },
 "author": "<>",
 "license": "ISC",
 "dependencies": {
   "cypress": "^12.3.0"
 }
}

• To run the test case on a particular browser in headless mode, we can add the script in package.json. To run all test cases in the Chrome browser, use the yarn run cy:run:chrome command in the terminal. To run all test cases in the Firefox browser, use the command yarn run cy:run:firefox in the terminal. To run all test cases in the Electron browser, use the command yarn run cy:run:electron in the terminal.

"name": "cypress_headless",
 "version": "1.0.0",
 "description": "",
 "main": "index.js",
 "scripts": {
  "cy:run:chrome": “yarn cypress run --browser  chrome --headless"
  "cy:run:firefox": “yarn cypress run --browser firefox --headless"
  "cy:run:electron": “yarn cypress run --browser electron --headless"
 },
 "author": "<>",
 "license": "ISC",
 "dependencies": {
   "cypress": "^12.3.0"
 }
}

• Another way to run the Cypress test cases in headless mode is running the test cases in the CI/CD pipeline. Below is an example of GitHub Action. Here, you can see we are executing Cypress test cases in the container with the Chrome browser.

name: Cypress Tests 
on: [push]
jobs:
 cypress-run:
   runs-on: ubuntu-latest
   container: cypress/browsers:node12.18.3-chrome87-ff82
   steps:
     - name: Checkout
       uses: actions/checkout@v2


     # Install NPM
     # and run all Cypress tests
     - name: Cypress run
       uses: cypress-io/github-action@v4
       with:
         # Specify the Browser
         browser: chrome

Folder Structure

The default folder structure for Cypress is displayed below. Under the “e2e” subdirectory, test cases can be created.

Let’s create test cases under the folder Cypress_Headless -> e2e. Create a .spec file with the name login_searchproduct.cy.js.

Create a login_searchproduct.spec.js file with the script below. This includes logging into the application and conducting a product search. Verify the right product should be displayed after the search.

/// <reference types="cypress" />
context("GIVEN Browser is already open  ", { testIsolation: false }, () => {
 it("WHEN User Open the Url", () => {
   cy.visit(
     "https://ecommerce-playground.lambdatest.io/index.php?route=account/login"
   );
 });
 it("AND Login into the application", () => {
   cy.get('[id="input-email"]').type("[email protected]");
   cy.get('[id="input-password"]').type("lambdatest");
   cy.get('[type="submit"]').eq(0).click();
 });
 it("AND Click On All Categories drop down and Search the Product", () => {
   cy.get('[data-toggle="dropdown"]').eq(0).click();
   cy.contains("Laptops").click({ force: true });
   cy.get('[name="search"]').eq(0).type("Apple").should("have.value", "Apple");
   cy.get('[type="submit"]').eq(0).click();
 });
 it("THEN Verify Correct Product with name'iPod Shuffle' should display after Search ", () => {
   cy.contains("iPod Shuffle");
 });
});

Code WalkthroughIn the above code snippet, we have opened the target URL using cy.visit(), and second, it() block is used to log in to the application by entering email and password.

In the third, it() block clicks on the ‘All Categories’ drop down and searches for the product., Finally, the last it() block is used to verify the searched product.

In the below screenshot, you can see how we can inspect the element. We have located the element by id for the email field.

cy.get('[id="input-email"]').type("[email protected]");

Now, let’s run the above test scenario in headless browsers. We will run the test cases first locally, then we will run the same scenario on the TestMu AI Cypress cloud.

Cypress Headless Testing on Local Grid

Running tests on Chrome using Cypress in Headless Mode

Headless Chrome is a web browser that can run automated tests without opening a Chrome window. This empowers you to create tests capable of mimicking user interactions with your web application and verifying that the application functions as intended.

Run the above scenario locally in headless mode using Chrome using the below command.

yarn cypress run --browser chrome --headless

As we run the above command, test cases start executing locally in the Chrome headless mode.

Running tests on Firefox using Cypress in Headless Mode

To run the Cypress test cases in Firefox’s headless browser, you have to run the below command, which will run in the background, and finally, you will get the Pass/Fail result in the form of a report.

Run the above scenario locally in headless mode using Firefox using the below command.

yarn cypress run --browser firefox --headless

As we run the above command, test cases start executing locally in the Firefox headless mode.

Running tests on WebKit using Cypress in Headless Mode

Run the above scenario locally in headless mode using WebKit using the below command

yarn cypress run --browser webkit  --headless

As we run the above command, test cases start executing locally in WebKit headless mode.

Note: Expedite release cycles with Cypress parallel testing. Try TestMu AI Today!

Cypress Headless Testing on Cloud Grid

In this section, you will find how to perform Cypress parallel testing on a cloud grid like TestMu AI.

TestMu AI is an AI-powered test orchestration and execution platform that lets you perform Cypress automation using headless mode across 40+ browser versions on the cloud. You can also run the Cypress test on the cloud parallel to the browser (Chrome, Firefox, and WebKit).

Subscribe to the TestMu AI YouTube Channel for the latest updates on tutorials around Selenium testing, Cypress e2e testing, Appium, and more.

Before running the test case in TestMu AI Grid, we have to do the set-up for TestMu AI. Below are some steps for setup.

Prerequisite to setup TestMu AI for test cases execution

• You already signed up for TestMu AI
• You have an access token to run test cases on TestMu AI.

Setup TestMu AI for Cypress test case execution

Step 1: Install the CLI

Install the TestMu AI using Cypress CLI command via npm. The command-line interface of TestMu AI enables us to execute your Cypress tests on TestMu AI.

npm install -g lambdatest-cypress-cli

Step 2: Generate lambdatest-config.json

Under the root folder, configure the browsers we want to run the tests. Use the init command to generate a sample lambdatest-config.json file or create one from scratch. Use the below command.

lambdatest-cypress init

In the generated lambdatest-config.json file, pass the below information. Fill in the required values in the section lambdatest_auth, browsers, and run_settings to run your tests.

In the below file, you can see we are passing three browsers (Chrome, Firefox, and Electron) and running the test case in two browsers simultaneously.

{
 "lambdatest_auth": {
   "username": "<>",
   "access_key": "<>"
 },
 "browsers": [
   {
     "browser": "Chrome",
     "platform": "Windows 10",
     "versions": ["latest-1"]
   },
   {
     "browser": "Firefox",
     "platform": "Windows 10",
     "versions": ["latest"]
   },
   {
     "browser": "Electron",
     "platform": "Windows 10",
     "versions": ["latest"]
   }
 ],
 "run_settings": {
   "build_name": "Headless Browser Testing build-name",
   "parallels": 2,
   "specs": "./cypress/e2e/*.cy.js",
   "ignore_files": "",
   "network": true,
   "headless": true,
   "npm_dependencies": {
     "cypress": "12.3.0"
   }
 },
 "tunnel_settings": {
   "tunnel": false,
   "tunnel_name": null
 }
}

Run the below command to execute the test case on TestMu AI.

lambdatest-cypress run --sync=true

As we run the above command, test case execution starts locally and parallelly on the TestMu AI platform.

TestMu AI Dashboard

The TestMu AI Dashboard provides a user-friendly interface for users to manage their test sessions, view test results, and access other platform features. It also allows users to perform live interactive testing by providing a live view of the website or web application being tested on a particular browser and operating system combination.

In the below screen, test cases start running in two browsers (Chrome, Electron), and in one other browser (Firefox), test case execution is in queue.

Once the execution of the two test cases mentioned above is completed in either the Chrome or Electron browser, the subsequent test case enters a queue. It initiates its execution in the Firefox browser. This transition is visually represented in the screenshot below.

Here is the console log of executed test cases in the Firefox browser. You can see all test cases are passing in TestMu AI Grid.

Here is the console log of executed test cases in the Chrome browser. You can see all test cases are passing in TestMu AI Grid.

As indicated in the console log displayed below, the test cases have successfully passed when executed in the Electron browser. Furthermore, it’s worth noting that all test cases exhibit successful outcomes within the TestMu AI Grid.

Are you ready to elevate your Cypress automation proficiency? Join the Cypress 101 certification program, crafted for developers and testers seeking to deepen their expertise in Cypress test automation. Gain advanced insights, polish your skills, and unlock many opportunities along your test automation journey.