We will discuss the JSON structure, examples, and detailed hands-on experience to write JSON in our code. But, first, let’s dive into our article!

What is Cypress Json: Example, Schema, Detailed Hands-On Analysis

In our previous article, we discussed variables and aliases and how to write our first test case. Now, we will discuss Cypress JSON and how to incorporate it into our code.

Table of Contents

• Cypress JSON File
• Default JSON Options
• Global Options
• Cypress JSON Timeout
• Cypress Read JSON File
• Screenshot and Video Options
• Viewport and Actionability
• Cypress JSON Example
• Cypress Fixture JSON Array
• Cypress env JSON
• Cypress JSON Reporter
• Cypress package-lock.json

Cypress JSON File

As we saw earlier, the first time we open our Cypress Test Runner, it creates a cypress.json file. This file is used to pass any configuration values we require. So first, we will look into the options that we can pass in our cypress.json file.

Default JSON Options

Certain options are set by default in Cypress. However, we can customize them according to our project. To identify the default values set by Cypress, navigate to the Settings folder in our Cypress Test Runner. From there, expand the Configuration option to view the default options set by Cypress.

The options are the default configurations provided by Cypress.

{
animationDistanceThreshold:5
baseUrl:null
blockHosts:null
browsers:Chrome, Firefox, Electron
chromeWebSecurity:true
component:{}
componentFolder:"cypress/component"
defaultCommandTimeout:4000
downloadsFolder:"cypress/downloads"
e2e:{}
env:null
execTimeout:60000
experimentalFetchPolyfill:false
experimentalInteractiveRunEvents:false
experimentalSourceRewriting:false
experimentalStudio:false
fileServerFolder:""
firefoxGcInterval:runMode, openMode
fixturesFolder:"cypress/fixtures"
hosts:null
ignoreTestFiles:".hot-update.js" includeShadowDom:false integrationFolder:"cypress/integration" modifyObstructiveCode:true nodeVersion:"default" numTestsKeptInMemory:50 pageLoadTimeout:60000 pluginsFile:"cypress/plugins" port:null projectId:"hpcsem" redirectionLimit:20 reporter:"spec" reporterOptions:null requestTimeout:5000 responseTimeout:30000 retries:runMode, openMode screenshotOnRunFailure:true screenshotsFolder:"cypress/screenshots" scrollBehavior:"top" supportFile:"cypress/support" taskTimeout:60000 testFiles:"/.*"
trashAssetsBeforeRuns:true
userAgent:null
video:true
videoCompression:32
videosFolder:"cypress/videos"
videoUploadOnPasses:true
viewportHeight:660
viewportWidth:1000
waitForAnimations:true
watchForFileChanges:true
}

Options

We can change the default options of Cypress by passing any arguments that are compatible with our project. As the name suggests, cypress.json is a JSON file, so we have to pass our arguments in JSON format. In our VS code, you could see that the cypress.json is empty with no arguments passed to it. Now let us see the different options that we can pass in our JSON file.

Global Options

We can pass the global options to arguments that need to be accessed globally. For example, in the table below, the Options column represents the keyword we will be passing in our JSON file; Default indicates the default value of the particular option set by Cypress, and Description indicates the meaning of the option.

Option	Default	Description
baseUrl	null	We can set the URL globally instead of passing in each file. It can be used for cy.visit() or cy.request() commands
clientCertificates	[]	You can use this option for configuring client certificates on a URL basis
env	{}	You can pass any environment variables as a value. This option will be useful if we are testing our application in different environments like staging or production.
watchForFileChanges	true	This option checks whether Cypress watches and restarts tests on any file changes are made.
port	null	We can pass the port number on hosting Cypress. A random port is generated, but we can add the port number we require.
numTestsKeptInMemory	50	This option is the number of test snapshots and commands data that are stored in memory. If there is high memory consumption in the browser during a test run, we can reduce the number.
retries	{ "runMode": 0, "openMode": 0 }	This option is to specify the number of times to retry a test that is failing. We can configure it separately for cypress run and cypress open.
redirectionLimit	20	We can configure the limit for the number of times the application can be redirected before an error occurs.
includeShadowDom	false	The ability to navigate inside the Shadow DOM to interact with elements. By default, it is set to false. If our application has any element requiring shadow root navigation, you can set it to true.

Cypress JSON Timeout

Timeout is one of the most important concepts in any automation framework. Cypress provides a variety of options that helps in handling timeouts in our scripts. First, we will look into the options that we can configure.

Option	Default	Description
defaultCommandTimeout	4000	This option is to wait for the DOM Elements-based commands to load. This is in milliseconds.
requestTimeout	5000	Time, in milliseconds, to wait until the request of cy.wait() command to go timeout.
responseTimeout	30000	This timeout is to wait until a response in a series of commands such as  cy.request(), cy.wait(), cy.fixture(), cy.getCookie(),  cy.getCookies(), cy.setCookie(), cy.clearCookie(), cy.clearCookies(), and cy.screenshot() commands
taskTimeout	60000	Timeout, in milliseconds, for the completion for the execution of cy.task() command
execTimeout	60000	This time in milliseconds is to wait to finish execution of the cy.exec() command, which is the completion of the system command
pageLoadTimeout	60000	This timeout waits for page navigation events or commands that interact with the pages like cy.visit(), cy.go(), cy.reload()

Cypress Read JSON File

Sometimes, we will require to interact with the folders or files in our project. To interact, we have to set certain options in our cypress.json file to manipulate the files. So, first, let us look into the options available in our folders/ files configuration.

Option	Default	Description
downloadsFolder	cypress/downloads	This is the path where the files are downloaded and stored during a test run
fixturesFolder	cypress/fixtures	This is the path to the folder that contains the fixture files. We can pass false to disable storing the files.
ignoreTestFiles*.hot-update.jsYou can pass this as a string or array of global patterns to ignore test files for the test run. However, it would be displayed in the test files.
integrationFolder	cypress/integration	Integration test files are stored in this path to the folder.
pluginsFile	cypress/plugins/index.js	This path is where the plugins are stored. You can pass the argument as false to disable this configuration.
screenshotsFoldercypress/screenshotsScreenshots from the execution of cy.screenshot() command and test failure during cypress run are stored in this foldersupportFilecypress/support/index.jsHere the test files that load before the test are stored. You have the option to disable by passing false
testFiles	**/*.*	Path to the test files that need to be loaded. It is either a string or array of global patterns.
videosFolder	cypress/videos	Folder path which will store videos during test execution

Screenshots and Video Options

We can configure our snapshots and videos in our cypress.json() file, and Cypress provides us some options to customize our configuration.

Option	Default	Description
screenshotOnRunFailure	true	Option to set to either true or false whether Cypress takes a screenshot during test failure when cypress runs. It is set to true by default
trashAssetsBeforeRuns	true	This option is to trash assets in the videosFolder, downloadsFolder and screenshotsFolder before every cypress run
videoCompression	32	This option is the quality of the video compression measured in the Constant Rate Factor(CRF). By passing false, you can also disable this option. You can pass values from 0 to 51, where the lowest value gives better quality.
videosFolder	cypress/videos	The folder where the video of the tests is saved.
video	true	Boolean value to capture the video of the test execution with cypress run.
videoUploadOnPasses	true	This option is to upload the videos to the Dashboard when all the test cases in a spec file are passing.

Viewport and Actionability

You can configure and pass values to change the viewport height and width with the options provided by Cypress. Actionability options can also be configured.

Option	Default	Description
viewportHeight	660	This is to provide the default height for the application in pixels. We can override this command with cy.viewport()
viewportWidth	1000	Option for the viewport width in pixels for the application. Can be overridden with cy.viewport() command.
animationDistanceThreshold	5	The threshold value for the distance measured in pixels where an element must exceed considering the time for animating.
waitForAnimations	true	Option to wait for the elements to complete the animation before performing any commands.
scrollBehavior	top	This is a viewport option that must scroll to an element just before performing any commands. Available options are 'center', 'top', 'bottom', 'nearest', or false, wherein false disables the scrolling.

Cypress JSON Example

Earlier, we saw the different configurations we can pass in our cypress.json file. Now, we will look into an example of how to use them in our project.

Overriding default values in the cypress.json file

In our VS code, open the cypress.json file. We will override the defaultCommandTimeout command to 8000.

{
    "defaultCommandTimeout" : 8000
}

This is how it looks in our VS code project.

By changing the cypress.json file, it applies to the whole framework. We can verify by navigating to our Cypress settings. It has changed from a default value of 4000 to 8000

Overriding default values via the test script

We can manipulate the default values via our test script too. Instead of passing in the cypress.json file, we will pass it in our test file.

//Changing the timeout from 4 seconds to 8 seconds
Cypress.config('defaultCommandTimeout',8000)

// Test code
cy.get('#username').type(users.email)
cy.get('#pswd').type(users.password)
cy.get('#login_btn').click()

This way, we can override default values in our test file. However, this does not impact any configuration changes on the framework level. Cypress gives priority to the values in cypress.json. Lastly, it takes up the global configurations.

Cypress Fixture JSON Array

Cypress cy.fixture() is a function that loads a fixed set of data in a file. We can use the fixture as a JSON to load any values or array in the JSON file. First, let’s understand how to access the JSON file in our project.

My JSON file has two properties: username and password. My JSON file name is examples.json.

{
"email": "[email protected]",
"password" : test123
}

In our spec file, we will access our fixture with the cy.fixture() command and the concept of aliases.

 cy.fixture('example.json').as('example')

 //Using the alias name to this keyword, So we can use globally  
        const userObj = this.userData
//looping our .json data with a new variable users
         cy.get(userData).each((users) => 
         {
              //Write the test code.
        cy.get('#username').type(users.email)
        cy.get('#pswd').type(users.password)
          }       

Cypress env JSON

Environment variables are used across many projects in organizations. We use environment variables

• when values are dynamic across different machines
• when we want to test under different environments such as staging, testing, development, production/live

These cases require us to define environment variables. However, if we set an env variable in one spec file, it is not reflected across other spec files. This is because Cypress runs each spec files independently. This way, we will need to configure env variables separately.

We access our environment files from our Cypress JSON file, i.e., cypress.json file. So we will be required to assign the option in our cypress.json file and used it across our spec file. So let us dive into our example.

We can set our environment variables in our configuration file or cypress.env.json file.

Setting environment variable in cypress.json file

We set the env property by a key-value pair. Any values passed under the keyword env fall under environment variables, and Cypress takes the argument from the env keyword. The syntax looks like the below.

{
  "env": {
    "key1": "value1",
    "key2": "value2"
  }
}

If we want to access the env variable in our spec file, we assign them as mentioned below.

Cypress.env() //returns both the key1,value1 and key2, value2

Cypress.env(key1) //returns only the value1

We will add the env configuration in our project and will access them in our spec file. In our cypress.json file, add the following configuration. We are setting our URL property and assigning them to our URL. Here, URL is the key, and https://themachine.science/technology/ is the value.

{
  "env" : {
      "url" : "https://themachine.science/technology/"
    }
}

As we have declared the configuration, we will access them in our spec file. It looks something like below. As mentioned above, we will be using Cypress.env() method to access the env variable.

// type definitions for Cypress object "cy"
// <reference types="cypress" />

describe('Cypress Example ', function () {

    it('accessing the environment variable', function () {

        //Calling URL from cypress.json
        cy.visit(Cypress.env('url'));

    })
})

Setting environment variable in cypress.env.json file

We can assign our environment variable in our cypress env JSON file. For that, we should create a new file called cypress.env.json at the root of the project. We will not require the env keyword; instead, we can directly access them by passing the key-value pair.

{
    "key1": "value1",
    "key2": "value2"
}

Let us look into how to assign them in our cypress.env.json file.

{
    "url" : "https://themachine.science/",
    "urlTechnology" : "https://themachine.science/technology/"
}

As you see above, we have created a new file, cypress.env.json, and added our URL properties. The way of accessing the environment variables would be the same as mentioned above in the previous section.

Cypress JSON Reporter

As we know, Cypress is built on top of Mocha; any reporters that are built for Mocha can be used. We can configure reporter in our JSON file globally in our cypress.json file.

reporter	spec	Here, you can specify the reporter that should generate during the cypress run. It is set to spec as the default reporter.
reporterOptions	null	This is to specify the supported options for the reporter.

The options mentioned above are the configurations set in reporter by default. In addition, the spec reporter is set by default. Thus, in the reporter, we can set any reporter that is compatible with Mocha. reporterOptions is to specify the supported options depending on the reporter we are configuring.

Let’s see how to configure the reporter in our cypress.json file.

Let us consider the multi reporter mochawesome as our reporter. We will first install the reporter and add them to our cypress.json file.

npm install --save-dev mocha cypress-multi-reporters mochawesome

Install the reporter by passing the above command in the command line. Now, in our cypress.json file, add the following property.

"reporter": "cypress-multi-reporters",
  "reporterOptions": {
      "reportDir": "cypress/reports/multireports",
      "overwrite": false,
      "html": false,
      "json": true
    }

We will understand each of the properties in detail.

reporter: The name of the reporter which we are configuring in our project

reportDir: The directory where we are going to output our results.

overwrite: This flag asks for overwriting the previous reports.

html: Generates the report on the completion of the test.

json: Whether to generate a JSON file on test completion.

Cypress package-lock.json

The package-lock.json file is created automatically for any operations when npm modifies the node modules or the package.json file. When we add any options or install any new dependencies to our Cypress package JSON file, then Cypress package-lock.json gets updated automatically.

Cypess package.lock JSON file traces every package and its version so that the installs are maintained and updated on every npm install globally. So in our Cypress package JSON file, when we update the version or add any dependency, package-lock.json also gets updated, and we don’t want to make any alterations to it.