Cypress Assertion helps us to assert a particular Assertions are validation steps that ensures whether the expected result is equal to the actual result. In test automation, we assert a statement to verify that the test is generating the expected result. If the assertion fails, then the test case fails ensuring that there is a bug. In this article, we will discuss about Cypress Assertion with Handson implementation and examples.

Table of Content

• What is Cypress Assertion?
• Cypress Assert Text
• Cypress Common Assertion
• Cypress Retry Assertion
• Cypress Assertion Examples
• Implicit Assertion in Cypress
• Explicit Assertion in Cypress
• Negative Cypress Assertion
• Cypress Custom Assertion Message
• Cypress Assertion Best Practices

What is Cypress Assertion?

Cypress uses and wraps Chai assertion library and extensions like Sinon and JQuery. Cypress automatically waits and retries until the assertion is resolved. Assertions can be used to describe how the application should look like. We can use Cypress assertions with combination of waits, retry, block until it reaches the desired state.

Cypress Assert Text

In general English, we would describe an assertion something like, I would expect the button to have login text. The same assertion can be written in Cypress as

cy.get('button').should('have.value', 'login')

The above assertion will pass if the button has ‘login’ value.

Cypress Common Assertions

There are a set of common Cypress assertion that we use in our test cases. We will be using them with .should() . Let us look into the use case and examples.

Some of the common Cypress assertion are listed below

1. Length
2. Value
3. Text Context
4. Class
5. Existence
6. CSS
7. Visibility
8. State
9. Disabled Property

Cypress Length Assertion

length() will check if the particular element has length

cy.get('dropdown').should('have.length', 5)

Cypress Value Assertion

The Cypress value will assert if the particular element has the expected value

cy.get('textfield').should('have.value', 'first name')

Cypress Text Context Assertion

Text context will assert if the element has the particular text

cy.get('#user-name').should('have.text', 'John Doe')

Cypress Class Assertion

Asserts whether the class is present or the particular element should have the class

cy.get('form').find('input').should('have.class', 'disabled')

Cypress Existence Assertion

Existence command checks whether the particular element is present or exist in the DOM or not

cy.get('#button').should('exist')

Cypress CSS Assertion

CSS Assertion checks whether the particular elements has a particular property

cy.get('.completed').should('have.css', 'text-decoration', 'line-through')

Cypress Visibility Assertion

Cypress Visibility Assertion asserts whether the DOM element is visible in the UI

cy.get('#form-submit').should('be.visible')

Cypress State Assertion

Asserts the state of the DOM element

cy.get(':radio').should('be.checked')

Cypress Disabled Property Assertion

Cypress Disabled property assertion asserts whether the element is disabled

cy.get('#example-input').should('be.disabled')

Cypress Retry Assertion

A single command followed with an assertion will execute in order. Initially, the command executes and then the assertion will get executed. A single command followed by multiple assertions will also execute in order – first and second assertion respectively. So when the first assertion passes, the first and the second assertion will be executed along with the commands again.

For example, the below command contains both .should() and .and() assertion commands, where .and() is otherwise known as .should()

cy.get('.todo-list li') // command
  .should('have.length', 2) // assertion
  .and(($li) => {
    // 2 more assertions
    expect($li.get(0).textContent, 'first item').to.equal('todo A')
    expect($li.get(1).textContent, 'second item').to.equal('todo B')
  })

Cypress Assertion Examples

In this section, we will discuss on the different types of assertions in Cypress such as

• Implicit Assertion
• Explicit Assertion

We will look into detail on both the types with examples

Implicit Assertion in Cypress

In implicit assertion, we use .should() or .and() commands. These assertion commands apply to the currently yielded subject in the chain of commands. They are dependant on the previously yielded subject.

We will look into an example on how to use .should() or .and() commands

cy.get('button').should('have.class', 'enabled')

With .and() which is an alias of .should() ,we can chain multiple assertions. These commands are more readable.

cy.get('#title')
  .should('have.class', 'active')
  .and('have.attr', 'href', '/post')

The above example is chained with .should() stating it should have the class “active”, followed by .and() is executed against the same command. This is very helpful when we want to assert multiple commands.

Explicit Assertion in Cypress

Passing explicit subject in the assertions falls under the explicit type of Cypress assertion. Here, we will use expect and assert commands as assertion. Explicit assertions are used when we want to use multiple assertions for the same subject. We also use explicit assertion in Cypress when we want to do custom logic prior making the assertion.

We will look into the example for explicit Cypress assertion

expect(true).to.be.true //checks for a boolean
expect(object).to.equal(object)

Negative Cypress Assertion

Similar to positive assertions, there are negative assertion in Cypress. We will be using “not” keyword added to the prefix of the assertion statement. Let us see an example of negative assertion

cy.get('#loading').should('not.be.visible')

Negative assertion is recommended only in cases to verify that a particular condition is no longer available after a specific action is performed by the application.

For example, let us consider that a toggle is checked and verify that it has been removed

// at first the item is marked completed
cy.contains('li.todo', 'Write tests')
  .should('have.class', 'completed')
  .find('.toggle')
  .click()
// the CSS class has been removed
cy.contains('li.todo', 'Write tests').should('not.have.class', 'completed')

Cypress Custom Assertion Message

With Cypress, we can provide additional information or custom message for assertions by using a library of matchers. Matchers comprises of small functions that differentiate values and will throw detailed error message. Chai assertion library will help our code look more readable and test failure very useful

const expect = require('chai').expect
it('checks a number', () => {
  const value = 10
  const expected = 3
  expect(value).to.equal(expected)
})

Cypress Assertion Best Practices

We can write multiple assertions in a single block by using a chain of commands. It is not necessary to write single assertion like in unit tests. Many write assertions like below. It is okay to write in that manner, but it increases the line of code and redundancy.

describe('my form', () => {
  before(() => {
    cy.visit('/users/new')
    cy.get('#first').type('ashok')
  })
  it('has validation attribute', () => {
    cy.get('#first').should('have.attr', 'data-validation', 'required') // asserting whether the #first has required field
  })
  it('has active class', () => {
    cy.get('#first').should('have.class', 'active') // asserting whether the #first has active class
  })
  it('has formatted first name', () => {
    cy.get('#first').should('have.value', 'Ashok') // asserting whether the #first has capitalized first letter
  })
})

As you see above, the same selector and assertion type is getting repeated. Instead, we can chain these commands in one single assertion which performs all the checks in a linear fashion.

describe('my form', () => {
  before(() => {
    cy.visit('/users/new')
  })
  it('validates and formats first name', () => {
    cy.get('#first')
      .type('ashok')
      .should('have.attr', 'data-validation', 'required')
      .and('have.class', 'active')
      .and('have.value', 'Ashok')
  })
})

As mentioned above, we can chain the single selector with multiple assertions! This is one of the recommended best practices of writing assertion in Cypress.

To understand about the Page Object Model in Cypress, click here.

One of the best practices in test automation is separating the test data from the test files. This aspect is one of the primary requirement while designing test framework. Cypress helps us the abilities to separate the test data with Cypress Fixtures. In this topic, we will be discussing about Cypress fixtures with hands-on implementation and real time examples

Table of Contents

• What is a fixture in Cypress?
• How to use Cypress fixtures in tests?
• How to read data from fixtures in Cypress?
• Accessing the values from the fixture file to the test file
• Cypress Multiple fixtures

What is a fixture in Cypress?

Cypress Fixtures can be used source data from external files. Fixtures in Cypress help you to read from or write into files. One of the popular framework in test automation is Data-driven framework where we separate data from the test files. We usually keep the data in external file like Excel and read them using external libraries. Cypress provides us the same feature to read data from files.

Cypress provides us a folder called fixtures, where we can create JSON files and read data from it where we can read those files in multiple test files. We will store the data as key-value pair and access them.

How to use Cypress Fixtures in Tests?

We can access Cypress fixtures via the following syntax given below

cy.fixture(filePath)
cy.fixture(filePath, encoding)
cy.fixture(filePath, options)
cy.fixture(filePath, encoding, options)

We will understand the parameters that can be passed in fixtures

filepath – the path to where you have stored your test data

encoding – The encoding that are used while using a file. Some of the encodings are ascii, base64,hex,binary etc

options – In options, we can pass the timeout response. It is to specify the timeout to resolve cy.fixture()

How to read data from Fixtures in Cypress?

We will be defining the test data in a file under the fixture folder. We will be accessing the test data from the JSON file in the test script using Cypress fixtures.

Now, let us undertand an example for Cypress fixtures. We will be logging in the url using the username and password. So let us store the username and password values in a file.

Let us create a file named credentials.json under the fixture folder. We will be defining the variables in JSON format.

{
    "username" : "[email protected]",
    "password" : "admin",
    "adminUrl" : "https://admin-demo.nopcommerce.com/admin/"
}

Accessing the values from the Fixture file to the test file

Since we have defined our JSON values in the credentials.json file, we will see how we can access them in our test file using Cypress fixtures.

We will access the fixture data using the this keyword in the before hook

describe("Cypress Fixtures Example", function () {
    before(function () {
        cy.fixture('credentials').then(function (testdata) {
            this.testdata = testdata
        })
    })
})

In the above example, we are accessing our JSON file via cy.fixture(‘credentials’). Since our JSON file name is credentials.json, we are passing the file name in cy.fixture(). Now we are using alias concept and defining our data as testdata. With the variable testdata, we can use the values of username and password in our test file

describe("Cypress Fixtures Example", function () {
    before(function () {
        cy.fixture('credentials').then(function (testdata) {
            this.testdata = testdata
        })
    })
    it("Login with valid credentials", function () {
        cy.visit(this.testdata.adminUrl)
        cy.get('[id=Email]').clear()
        cy.get('[id=Email]').type(this.testdata.username)
        cy.get('[id=Password]').clear()
        cy.get('[id=Password]').type(this.testdata.password)
        cy.get('[type=submit]').click();
        cy.url().should('be.equal', this.testdata.adminUrl)
    });
});

As you can see above, in .type() we are passing the value from our credentials.json file as this.testdata.username. Similarly, for password we are accessing the value using this.testdata.password. For the url, we are using the same way as username and password.

When we run the test case, you can see the value getting printed in the dashboard. This way, we have executed our test case using Cypress Fixtures

Cypress Multiple Fixtures

In this section, we will understand how to use Cypress Fixtures with multiple fixture files.

If we want to use different fixture data for the same test file, for example, there are two set of credentials we need to verify for the login page, how can we access the files?

One way is to write multiple it blocks which will replicate the same code again and again. The other way, we can use Cypress fixtures to access different test data in the spec file. Let us see how we can achieve that using Cypress fixtures

We already have a fixture file called credentials.json.

{
    "username" : "[email protected]",
    "password" : "admin",
    "adminUrl" : "https://admin-demo.nopcommerce.com/admin/"
}

Now let us create another fixture file named userData.json where we will use different invalid username and password.

{
    "username" : "[email protected]",
    "password" : "user",
    "adminUrl" : "https://admin-demo.nopcommerce.com/admin/"
}

Now let us see how we can access the two different data in our test file.

We will refactor the same test file using the condition of using two different fixture files.

const testValueFixtures = [
    {
        "name": "credentials",
        "context": "1"
    },
    {
        "name": "userData",
        "context": "2"
    }
]
describe('Automation Test Suite - Fixtures', function () {
    //looping through both the fixtues 
    testValueFixtures.forEach((fixtureData) => {
        describe(fixtureData.context, () => {
            // accessing the test data from the fixture file
            before(function () {
                cy.fixture(fixtureData.name).then(function (testData) {
                    this.testData = testData;
                })
            })
            it("login", function () {
                cy.visit('https://admin-demo.nopcommerce.com/admin/')
                cy.get('[id=Email]').clear()
                cy.get('[id=Email]').type(this.testData.username)
                cy.get('[id=Password]').clear()
                cy.get('[id=Password]').type(this.testData.password)
                cy.get('[type=submit]').click();
                cy.url().should('be.equal', this.testData.adminUrl)
            })
        })
    })
})

Initially, we are creating a variable called testValueFixtures as an array where we are creating the context of two fixture files. In the first context, we are passing the name as ‘credentials‘ and the second as ‘userData‘ , as they represent our JSON file names where we have our value defined.

Secondly, we are looping through the both the fixture variables in describe block. And as we discussed previously, we are accessing the data in before block using .this()

The rest of the code is the same, where we are passing the data in the cy.get()

When we execute our test, it will run in two sets where the first case passes with valid credentials and the second fails due to invalid credentials

As you can see above in the snapshot, the first test case has passed and it has entered the value from the first fixture file credentials.json

As you can see in the above screenshot, the test has failed and the values passed are from the second fixture file userData.json

You can also view how to write Cypress fixtures using the Page Object Model here

Table of Contents

• What is Cypress Commands?
• UI Interaction commands provided by Cypress
• Cypress Right Click Command
• Cypress Double Click Command
• Cypress Click Command
• Cypress Trigger Command
• Cypress Type Command
• Cypress Select Command
• Cypress Check Command
• Cypress Clear Command
• Are Cypress Commands asynchronous?
• Cypress Custom Commands
• Chaining Assertion commands in Cypress
• Overwriting existing Cypress commands
• Cypress Chainable Commands
• Parent Custom Command in Cypress
• Child Custom Command in Cypress
• Dual Custom Command in Cypress
• Cypress Custom Commands with Example
• Cypress Import Commands
• Cypress Custom Command IntelliSense

What is Cypress Commands?

Cypress provides us API’s and methods to interact with the UI of the application. They are known as Cypress Commands and helps with the interaction of the web application. All the commands that are available have in-built methods and we will only invoke the methods in our test cases. The Cypress commands will simulate a similar action to an user trying to perform operations on the application.

UI Interaction Commands provided by Cypress

There are different commands provided by Cypress that interact with the UI. We will look into the list of all the commands in detail.

• .click()
• .dblclick()
• .rightclick()
• .type()
• .clear()
• .check()
• .uncheck()
• .select()
• .trigger()

Cypress Click Command

.click() – This command is to click any element on the DOM.

The following are the syntaxes for click command

.click() 

.click(options) 

.click(position) 

.click(position, options) 

.click(xCoordinate, yCoordinate) 

.click(xCoordinate, yCoordinate, options) 

As you can see above, the click accepts parameters like options, position, and coordinates.

Options

The possible options that can be passed to click are

Option	Default	Description
altKey	false	Switch on the Alternate key (Option Key in Mac), as optionKey
ctrlKey	false	Switch on the control key. Also known as: controlKey.
metaKey	false	Actuates the meta key (Windows key in Windows or command key in Mac). Also: commandKey, cmdKey.
shiftKey	false	Actuates the shift key
log	true	Prints the logs in the command line
force	false	This option forces the action and disables the wait for actionability
multiple	false	Sequentially click multiple elements
timeout	defaultCommandTimeout	Time for .click() wait before resolving the time out
waitForAnimations	waitForAnimations	Option to wait for the elements to complete animating before executing the command

Positions

The different types of positions that can be passed to .click() are

• center (default)
• left
• right
• top
• topLeft
• topRight
• bottom
• bottomLeft
• bottomRight

Example

cy.get('btn').click()  //clicking the button 
cy.get('btn').click({ force: true })  //clicking the button by passing the option 'force' as true
cy.get('btn').click('bottomRight') // clicking the button at the botton right position
cy.get('btn').click(10, 70, { force: true }) // clicking the button with position value and force true

Cypress Double Click Command

Double click can be achieved by using dblclick() syntax in Cypress.

Syntax

.dblclick()
.dblclick(position)
.dblclick(x, y)
.dblclick(options)
.dblclick(position, options)
.dblclick(x, y, options)

Options

.dblclick() accepts all the options that are accepted by .click(). You can find the options in the above section.

Positions

All the possible positions that are specified in .click() are also available for dblclick(). The list of the positions can be found in the above section.

Example

cy.get('button').dblclick() // Double click on button
cy.focused().dblclick() // Double click on element with focus
cy.contains('Home').dblclick() // Double click on first element containing 'Home'
cy.get('button').dblclick('top') // Double click on the button on top position
cy.get('button').dblclick(30, 10) // Double click on the coordinates of 30 and 10

Cypress Right Click Command

This Cypress command, right clicks the DOM element .rightclick() command will not open context menus of the browser.rightclick() is used to test handling of right click related events in the application such as contextmenu.

Syntax

.rightclick()
.rightclick(position)
.rightclick(options)
.rightclick(position, options)
.rightclick(x, y)
.rightclick(x, y, options)

Options

As we saw above, all the options that are accepted by .click() command can be configured with .rightclick() command too.

Positions

All the possible positions that can be passed to the .rightclick() is same as the .click() mentioned above.

Example

cy.get('.welcome').rightclick() // Right click on .welcome
cy.focused().rightclick() // Right click on element with focus
cy.contains('January').rightclick() // Right click on first element containing 'January'
cy.get('button').dblclick('topRight') // Double click on the button on top right position
cy.get('button').dblclick(80, 20) // Double click on the coordinates of 80 and 20

Cypress Type Command

.type() command enters value into a DOM element.

Syntax

.type(text)
.type(text, options)

Arguments

.type() accepts string as an argument. Values passed to .type() can include any of the special character sequences given below.

Sequence	Notes
{{}	Enters the literal { key
{backspace}	Deletes character from right to the left of the cursor
{del}	Removes character from left to the right of the cursor
{downarrow}	Shifts cursor down
{end}	Shifts cursor to the end of the line
{enter}	Types the Enter key
{esc}	Types the Escape key
{home}	Shifts cursor to the start of the line
{insert}	Positions character to the right of the cursor
{leftarrow}	Moves cursor left
{movetoend}	Shifts the cursor to end of typeable element
{movetostart}	Shifts the cursor to the start of typeable element
{pagedown}	Scrolls down
{pageup}	Scrolls up
{rightarrow}	Shifts cursor right
{selectall}	Selects all the text by creating a selection range
{uparrow}	Shifts cursor up

Options

We can pass in the objects as options to modify the default behaviour of .type()

Option	Default	Description
delay	10	Option for Delay in time after each keypress
force	false	Forces the action to execute and disables waiting for actionability
log	true	Displays the logs in the Command log
parseSpecialCharSequences	true	Parse special characters for strings surrounded by {}, such as {esc}. You can set the option to false to enter the literal characters.
release	true	This option allows to enable a modifier stay activated between commands
scrollBehavior	scrollBehavior	Viewport position to where an element to be scrolled before executing any command
timeout	defaultCommandTimeout	Time to wait for .type() command to resolve before time out
waitForAnimations	waitForAnimations	To say whether to wait for elements to finish animating before executing any command.

Example

Let us see examples for .type() command

cy.get('textarea').type('Hey there') // enter value in the text area
cy.get('body').type('{shift}') //enables the shift key
cy.get('body').type('{rightarrow}') //type event right arrow 

Cypress Clear Command

Clear command will clear the values in input area or the text field.

Syntax

The syntax for clear command is a follows.

.clear()
.clear(options)

Options

We will look into the options that can be passed to the .clear() command.

Option	Default	Description
force	false	This will forces the action and disables waiting for actionability to occur
log	true	Shows the command in the Command log
scrollBehavior	scrollBehavior	Viewport position to where an element must be scrolled to before performing the command
timeout	defaultCommandTimeout	This option is the time to wait for .clear() to resolve before time out
waitForAnimations	waitForAnimations	This will wait for elements to complete animating before executing the command.

Example

Let us look into the examples for clear command

cy.get('[type="text"]').clear() // Clear input of type text
cy.get('textarea').type('Welcome!').clear() // Clear textarea 
cy.focused().clear() // Clear focused input/textarea

Cypress Check Command

The check command will check or in simpler words, tick the checkboxes or radio buttons. You can uncheck the checkboxes or radio buttons by using the .uncheck() command.

Syntax

We will understand the syntax for check command in Cypress.

//Syntax for check command
.check()
.check(value)
.check(options)
.check(values, options)

//Syntax for uncheck command
.uncheck()
.uncheck(value)
.uncheck(options)
.uncheck(values, options)

Options

The possible options that can be passed to check/uncheck commands are the options same as the clear command listed above

Example

We will look into the example of how we can use check and uncheck commands.

cy.get('[type="checkbox"]').check() // Check checkbox element
cy.get('[type="radio"]').first().check() // Check first radio element
cy.get('[type="radio"]').check('Male') //Check the radio element which has Male
cy.get('[type="checkbox"]').uncheck() //Uncheck checkbox element
cy.get('[type="radio"]').uncheck()  //Uncheck the first radio element
cy.get('[type="checkbox"]').uncheck('Breakfast') // Uncheck the breakfast element

Cypress Select Command

The select Cypress command allows you to select elements within a <select> tag.

Syntax

The following are the syntax for select command

.select(value)
.select(values)
.select(value, options)
.select(values, options)

Options

We can pass in the options to modify the default behaviour of select command.

Option	Default	Description
force	false	This option forces the action to take place and disables waiting for actionability
log	true	Displays the logs in the Command log and is set as true by default
timeout	defaultCommandTimeout	This option is the time to wait for .select() to resolve before time out

Example

Let us look into examples for the select command

cy.get('select').select('butterfly') // Select the 'butterfly' option
cy.get('select').select(0) // selects the element with 0 index
cy.get('select').select(['parrot', 'peacock']) //selects the parrot and peacock option

Cypress Trigger Command

Trigger command helps to trigger any event on the element.

Syntax

We will look into the syntax for accessing the trigger command

.trigger(eventName)
.trigger(eventName, position)
.trigger(eventName, x, y)
.trigger(eventName, position, options)
.trigger(eventName, options)
.trigger(eventName, x, y, options)

Option

Trigger command accepts all the options that are mentioned for .clear() command. Additionally, there are few options we can configure that are listed below.

Option	Default	Description
bubbles	true	Whether the event should bubble
cancelable	true	Whether the event can be cancelled
eventConstructor	Event	The constructor for creating the event object (e.g. MouseEvent, keyboardEvent)

Example

Let us different ways of using .trigger() in the code.

cy.get('a').trigger('mouseover') // Trigger mouseover event on a link
cy.get('.target').trigger('mousedown', { button: 0 }) //mousedown triggered at button 0
cy.get('button').trigger('mouseup', topRight, { bubbles: false }) //mouseup triggered on topRight position with setting bubble as false

Are Cypress commands async?

All the Cypress commands are asynchronous. They are queued for execution at a later point in time and will not wait for the completion of the commands. Cypress command do not do anything at the time of their invoke,instead they save it for later for execution. You can understand the asynchronous behaviour of Cypress here

Cypress Chainable Commands

In Cypress, we can use a series of commands to interact with elements in DOM. It is imperative to understand how the chaining of commands work internally. If we are chaining commands in a particular line, then Cypress will handle a promise based on the command chain and will yield a command based on the subject to the next command, until the chain of commands end or an error has occurred.

Cypress allows us to click an element or type into elements using the .click() or .type() commands by getting the elements using cy.get() or cy.contains(). Let us see a simple example of chaining commands

cy.get('textarea').type('How are you?')

In the above example, cy.get() is one Cypress command and .type() is another command, where we are chaining the .type() command onto the cy.get() command, telling it to type to the subject that is yielded from the cy.get() element. Similarly, we can chain all the commands that we discussed above.

Chaining Assertion Commands in Cypress

Similar to chaining multiple commands using Cypress, we can also chain assertions with commands. Assertions are commands that let you to describe the expected state or behaviour of the application. Cypress will wait until the elements reach the expected state, and the test will fail if the assertions don’t pass. We will see how we can use chaining commands in asserting an element.

cy.get('button').should('be.disabled') //expect whether the button should be disabled
cy.get('form').should('have.class', 'form-vertical') //expect whether the form should have class as 'form-vertical'
cy.get('input').should('not.have.value', 'Name') // assert whether the input should not have the value 'Name'

As listed above, we are using the cy.get() command and chaining it with the .should() assertion command to expect the behaviour based on the result. This way, we can use chain assertion commands in Cypress.

Cypress Custom Commands

Cypress provides us API’s to create commands based on our requirements. Cypress custom command is similar to the default commands that are pre-existing, except it is user-defined. With custom commands, we can play around with the commands and chain them based on our use case. Cypress custom commands are useful in our workflow if you require reusing them over and over in the tests.

Let us see the syntax for creating a new custom command in Cypress.

Cypress.Commands.add(name, callbackFn)
Cypress.Commands.add(name, options, callbackFn)
Cypress.Commands.overwrite(name, callbackFn)

where the arguments are as follows

name – The name of the command in string that we want to add or overwrite

callbackFn – This function takes an argument passed to the command

options – Pass any options object to define the behaviour of the command

Note : options are supported only for the add commands and do not support for the overwrite commands

Option	Accepts	Default	Description
prevSubject	Boolean, String or Array	false	defines how to handle the previously yielded subject.

The options that prevSubject accepts are as follows

• false – ignore previous subjects (parent command)
• true – accept the previous subjects (child command)
• optional – pass in whether you want to start a new chain or use an existing chain (dual command)

Parent Custom Command in Cypress

We will see how to add a parent custom command in Cypress. Parent command will always begin a new chain of commands, eventhough you have chained off a previous command. The previously chained command will be ignored and a new command will be chained always. Some of the parent commands are cy.visit(), cy.get(), cy.request(),cy.exec(), cy.route()

Example

We will see an example of how to write a parent custom command in Cypress

Cypress.Commands.add('clickLink', (label) => {
  cy.get('a').contains(label).click()
})
//clicking the "Buy Now" link
cy.clickLink('Buy Now')

In the above example, ‘clickLink‘ is the name of our custom command. It will search for the label. In line 2, the command gets ‘a‘, and search for the link which contains label and click the element. cy.clickLink() will execute the action in the test file and clicks the “Buy Now” link.

Child Custom Command in Cypress

Child Custom commands in Cypress are chained off a parent command or another child command. The subject from the previous command will be yielded to the callback function.

Some of the Cypress commands that can be chained as a child command are .click(), .trigger(), .should(), .find(), .as()

Example

We will look into an example on how to chain a child custom command

Cypress.Commands.add('forceClick', {prevSubject: 'element'}, (subject, options) => {
  // wrap the existing subject and do something with it
  cy.wrap(subject).click({force:true})
})
//accessing the forceClick in the test file
cy.get("[data-test='panel-VALUES']").forceClick();

In the above example, we are naming our custom command as ‘forceClick‘. We are passing the prevSubject argument to the element and wrapping the existing subject. With cy.wrap(), we are force clicking the subject. Then in the test file, we are accessing the custom command, ‘forceClick‘ on a cy.get() command.

Dual Custom Commands in Cypress

Dual custom commands are hybrid between a parent and child command. You can begin a new chain of commands or chain off an existing command. Dual commands are helpful if we want our command to work in different ways with or without the existing subject.

Some of the commands that can be used for dual commands are cy.contains(), cy.screenshot(), cy.scrollTo(), cy.wait()

Example

Let us see an example of how to use dual custom commands

Cypress.Commands.add('getButton', {
  prevSubject: 'optional'
}, (subject) => {
  if (subject) {
   cy.get(subject).get('btn').its('button');
  } else {
    cy.get('btn').its('button');
  }
})

In some cases, we will require to get the button of the text using getButton which will acquire all the button of the element. Now we can use getButton to chain the with the parent element or chain the child element, where it can invoke the elements of the parent.

Since the prevSubject is optional, we can either pass the subject as an argument or invoke the command without the subject in the test file as below

cy.getButton() // without the subject
cy.get('#loginBtn').getButton() // with the subject

Overwriting Existing Cypress Commands

We can overwrite the already existing Cypress commands and modify the behaviour in order to avoid creating another command that will try to use the original command at the end.

Some of the original Cypress command that can be overwritten are cy.visit(), cy.type(), cy.screenshot(), cy.contains()

Example

Let us see an example on how we can overwrite the existing Cypress command.

Cypress.Commands.overwrite('contains',
  (originalFn, subject, filter, text, options = {}) => {
    // determine if a filter argument was passed
    if (typeof text === 'object') {
      options = text
      text = filter
      filter = undefined
    }
    options.matchCase = false
    return originalFn(subject, filter, text, options)
  }
)

As we saw above, we are using the Cypress.Commands.overwrite to modify the existing Cypress command. We are naming our custom command as contains and we are passing arguments to determine whether the filter argument has passed.

Cypress Import Commands

In this section, we will understand how to import Cypress Commands.

We must create our Cypress custom commands in the cypress/support/commands.js file. We shall add the custom commands in the command.js file and import in our test case file to use it.

Cypress Custom Commands with Example

We will understand how to create a custom command and use it in our spec file with real-time example.

As we saw above, we have to add new custom commands under the commands.js file. In that file, let us add a custom command for a login function

Cypress.Commands.add("login", (username, password) => {
    //adding a new command named login
    cy.get('[id=Email]').clear();
    cy.get('[id=Email]').type(username);
    cy.get('[id=Password]').clear();
    cy.get('[id=Password]').type(password);
    cy.get('[type=submit]').click();
  });

In the above code, we are naming our custom command as login. Inside the custom command, we have added the steps of clearing the username field and entering value in the textfield. Similarly, we are clearing the field and adding the password in the password field. Later, we are clicking the submit button. This is a simple custom command that accepts two arguments : username and password. We will be passing the value for the username and password in our spec file.

Now let us create a spec file named customCommand.spec.js under integration folder. Our spec file will contain the following code

describe("Custom Commands Example", () => {
    it("should login using the custom commands", () => {
      cy.visit("https://admin-demo.nopcommerce.com/");
      cy.login("[email protected]", "admin");
      cy.url().should('be.equal', 'https://admin-demo.nopcommerce.com/admin/')
    });
  });

As we saw above, we are accessing our custom command as cy.login() ,where we are passing the values of username and password.

Cypress Custom Commands IntelliSense

IntelliSense provides intelligent code suggestions in the IDE or code editor directly while we are writing tests. It helps by showing a popup that displays the command definition, link to the documentation page and code examples. If we are using any modern code editor like Visual Studio Code or IntellJ, then IntelliSense will be very useful.

IntelliSense uses Typescript to understand and displays the syntax. If we write custom commands and provide TypeScript definitions for the custom commands, we can use the triple slashes to display IntelliSense, even if our project uses JavaScript only.

To configure IntelliSense, we need to describe the code in cypress/support/index.d.ts file.

// type definitions for Cypress object "cy"
/// <reference types="cypress" />
declare namespace Cypress {
    interface Chainable<Subject> {
      /**
       * Login with credentials
       * @example
       * cy.login(username,password)
       */
      login(username: String, password: String): Chainable<any>
    }
  }

Now, we should let our spec files know that there are some Typescript definitions in the index.d.ts file. So, at the beginning of our spec file, add the below code to let IntelliSense provide suggestions for us.

// type definitions for custom commands like "login"
// will resolve to "cypress/support/index.d.ts"
// <reference types="../support" />

As we saw above, IntelliSense provides us with the arguement we provided in our command.js file and helps in auto-completing.