Aqua Help

Cypress Custom Commands

Custom Commands provide a way to reuse certain methods or functions across the Cypress test suite. For example, you can write a command to log in the user and reuse it within your project whenever applicable.

Aqua supports Custom Commands, meaning that all coding assistance features, such as renaming, navigation, code completion, and inspections are available right away.

Custom Commands coding assistance

Cypress-specific inspections

Cypress utilizes a chaining mechanism that allows you to write a sequence of commands where information is passed from one command to the next until the chain ends or an error occurs.

However, this mechanism has some specifics. For example, any action command must always be placed at the end of the chain and used only once.

In this example, the chain contains two action commands placed one after another, which is prohibited. The execution of this test will result in an error.

it('Click the search button and type Cypress', () => { cy.get("button[data-test='search-button']") .click() .type('Cypress') })

In this example, the chain is split in two, so each chain contains only one action command. This test will be executed without an issue.

it('Click the search button and type Cypress', () => { cy.get("button[data-test='search-button']").click() cy.get("input[data-test$='inner']").type('Cypress') })

Validation of the command chain is not performed in JavaScript/TypeScript, and in Cypress it is performed only at runtime, which may lead to issues during the test execution. Aqua, in its turn, provides an inspection for chained commands, highlighting incorrect usages.

Inspection for an incorrect chained command

Function-specific inspections

Aqua performs function-specific code inspections that detect and correct abnormal code in your project.

For example, if you provide an incorrect number or type of arguments for the command, the erroneous code gets highlighted. You can hover the mouse over the highlighted code to see the description of the error.

Aqua ts function specific inspections

For more information, refer to Code inspections.

Renaming

If you need to rename the command, you can use the Rename refactoring. To do this:

  1. Highlight the command that you want to rename.

    Highlighted command
  2. Press Shift+F6 and provide a new name for the command.

    Rename the command
  3. (Optional) Configure additional search options and define scope.

  4. Click Refactor.

For more information, refer to Rename refactorings.

Creating a Custom Command

To create a Custom Command, you have to first write the command, and then create a TypeScript declaration for it. To do this:

  1. Write your command in the code editor.

    Custom Command written in TypeScript
    Custom Command written in TypeScript
  2. Hover the mouse over the highlighted code and click Create missing TypeScript declaration.

    Alternatively, place the caret at the highlighted code, press Alt+Enter, and select Create missing TypeScript declaration.

    Creating the TypeScript declaration
    Creating the JavaScript declaration

As a result, the TypeScript declaration is generated and added to the cypress/support/index.d.ts file.

Generated TypeScript declaration

You might want to navigate between the command implementation and the corresponding TypeScript declaration:

  • To navigate to the TypeScript declaration, click App client expui gutter implementing method in the gutter near the command implementation.

    Navigate to TypeScript declaration
  • To navigate back to the command implementation, click App client expui gutter implemented method in the gutter near the TypeScript declaration.

    Navigate to command implementation

Using Custom Commands

Once you have created a custom command, you can use it in your code. To do this:

  • In your test, type cy. followed by the name of the custom command.

    Custom login command
    Custom login command usage

Changing the location of the command file

By default, the file that contains the generated TypeScript declaration is located at cypress/support/commands.ts. If you want to change the location:

  1. Press Control+Alt+S to open the IDE settings and then select Languages & Frameworks | Cypress.

  2. In the TypeScript file to store TS declarations of custom commands field, specify a new path.

    Specify a new path

  3. Apply the changes and close the dialog.

Last modified: 12 January 2024