Using Cypress

Reference page on how to use Cypress to manage E2E testing

Overview

This page provides step-by-step instructions for Cypress usage, covering key functionalities and actions to kickstart or enhance your testing experience. Practical examples and tips are included for a streamlined and effective learning process.

Get started

Once your system is installed and set up, follow the steps below to begin using Cypress.

If you haven't completed the initial setup, start here.

Step 1: Start Cypress

Open Cypress by using the npx command:

npx cypress open

You can open Cypress only using the command line interface

Step 2: Add project to Cypress

Choose the folder e2e-test-scripts folder from the jenkins-custom directory in your workspace.

Add Cypress Project

Ensure that the E2E Testing button displays a green "Configured" status, indicating successful folder selection and detection of the Cypress Config file

Step 3: Select Testing Type

Choose E2E Testing by clicking on the tile.

Correct project folder was added. Select E2E Testing

Step 4: Choose a browser for testing

Choose a browser to start testing. This will create a new browser window for testing purposes. Cypress will switch to the testing browser view, offering a space for executing and overseeing all your E2E tests.

Browser selection for E2E testing

---

Cypress may trigger a warning if the server is inaccessible. If you encounter this warning, please launch your Servoy Cloud application and try again.

Unavailable server Cypress warning when Servoy Cloud application is not running

Step 5: Run E2E test

Choose the spec that includes the tests you intend to run. This action will trigger the execution of all tests within the specified spec file.

---

Create a new spec

In Cypress, test files are referred to as specs, and each spec can contain one or more E2E tests.

To create a new spec file, you can do the following:

1. Manually

   • Generate a new file with the extension cy.js and add it to the jenkins-custom folder in your workspace ( refer to the Cypress workspace structure)
2. Using Cypress UI

   • Click the "+" button on top of the Spec list tab column on the left

   • Choose "Create new spec"

   • Modify the default spec name to have the .cy.js file extension (supported by Servoy Cloud).

   • Click the "Create spec" tile

   • Use the buttons to run the created spec or create another spec

When writing your Cypress tests, target your elements using the Cypress data tags and not randomly generated IDs. To enable them see Step 1: Enable testing mode and generate Cypress data tags

• TiNG: data-cy="formname.elementname"

• NG1: data-svy-name="formname.elementname"

---

Add new test

You can add a new test to a spec file in different ways:

1. Using an external editor

   • Write the test in one of the already existing spec files.

   • If no spec file exists, refer to the section on how to create a spec.

   This will prompt Cypress to run the modified file.

2. If Cypress Studio is enabled, using the Cypress UI :

   • Select the spec where you want to add the test from the Spec list.

   • Hover over the spec file name in the Spec details tab column on the left to define your test.

   • Interact with your Servoy Cloud application displayed on the right to record commands.

   • Once all commands are recorded, use the actions in the Spec details tab to save, copy your code, or cancel the entire process.

Add New Test in spec file

When writing your Cypress tests, target your elements using the Cypress data tags and not randomly generated IDs. To enable them see Step 1: Enable testing mode and generate Cypress data tags

• TiNG: data-cy="formname.elementname"

• NG1: data-svy-name="formname.elementname"

---

Edit test

To edit a test, follow these steps:

1. To add commands to a test, refer to the Add commands to test section
2. To make changes to existing commands, use an external editor and update the test file. Cypress does not support inline editing.

To open files in external editor, in the Spec Details column, you can do either of the following:

• Click on the spec file name to "Open in IDE"

• Hover over the TEST BODY of a test and click "Open in IDE"

---

Add commands to test

You can extend a test by adding commands through the following methods:

1. Using an external editor

   • Add commands directly to the test file using an external editor.

2. If Cypress Studio is enabled, using the Cypress UI:

   • Select the spec where you wish to add the test from the Spec list.

   • Hover over the test name in the Spec details tab on the left and choose "Add commands to test."

   • Interact with your Servoy Cloud application displayed on the right to record commands.

   • Once all commands are recorded, use the actions in the Spec details tab or the top bar of the application window to save, copy your code, or cancel the entire process.

Add commands to Test

---

Add Cypress commands (custom functions)

You can extend Cypress with reusable functions that can simplify and clean up your test code.

Define the custom Cypress function

Define the custom logic in the cypress/support/commands.js (see Step 2: Workspace structure for where to find this file)

Cypress automatically loads this file before every test run, so any custom commands defined here are globally available across your test suite.

// Define the custom command

Cypress.Commands.add('login', (username, password) => {
  cy.visit('solution/mySolutionName/index.html#loginForm')
  cy.get("[data-cy='formNameLogin.fc_username$containedForm$input']").type(username)
  cy.get("[data-cy='formNameLogin.fc_password$containedForm$input']").type(password, { log: false });
  cy.get('button[type="submit"]').click()
})

When writing your Cypress tests, target your elements using the Cypress data tags and not randomly generated IDs. To enable them see Step 1: Enable testing mode and generate Cypress data tags

• TiNG: data-cy="formname.elementname"

• NG1: data-svy-name="formname.elementname"

Implement it in the Cypress test

describe('Login Tests', () => {
   it('Test Login', () => {
    // Reload the page for the first test
    cy.login(Cypress.env('username'), Cypress.env('password'));
    cy.get("div.toast.toast-warning")
      .should('be.visible')
      .contains('Login Error');
  });
});

Configure External Editor

Cypress relies on an external editor for code editing since it does not support inline editing.

To configure the external editor, navigate to Settings > Device settings > External Editor

The sidebar menu is only available in the Testing browser view

Cypress Test Example

Here is an example of a login flow written with Cypress:

describe("LoginFlow CCC", () => {
  it("LoginFlow CCC", () => {
    cy.visit("solution/svyCloud/index.html");
    //Login into solution
    cy.get("[data-cy='svyCloudLogin\\.fc_UserName\\$containedForm\\$input']").click();
    cy.get("[data-cy='svyCloudLogin\\.fc_UserName\\$containedForm\\$input']").type(Cypress.env('username'));
    cy.get("[data-cy='svyCloudLogin\\.fc_password\\$containedForm\\$input']").type(Cypress.env('password'), { log: false });
    cy.get("[data-cy='svyCloudLogin\\.buttonLogin']").click();
    cy.wait(5000);
    cy.get("[data-cy='topbar\\.caret']").click();
    cy.wait(500);
    cy.get("[data-cy='mainUserMenu\\.btn_Logout']").click();
  });
});

Notes

• The values username and password are custom properties created by the user in the job configuration.
• Ensure that the URL provided does not include the http/https part but only the last part starting from solution.

Tips and tricks

Target elements in Cypress test

To ensure reliable and maintainable Cypress tests, elements on the page should be targeted using consistent and stable selectors.

Use Data Attributes Instead of Dynamic IDs

Dynamic component IDs can change between deployments or UI re-renders, leading to broken tests.

In contrast, data attributes (like data-cy or data-svy-name) are static, predictable, and intended for testing purposes. See Step 1: Enable testing mode and generate Cypress data tags on how to set them up locally when writing your tests.

Target high-level containers

Avoid targeting deeply nested child components. This reduces test fragility when the internal UI structure changes.

Delay execution of test command

In Servoy Cloud applications, pages might have extended load times, and Cypress tests may fail if elements on the page are not yet available.

To avoid this, use the Cypress method cy.wait(ms) which is similar to the Servoy method application.sleep(ms)

This ensures that the Cypress test waits for a given time in milliseconds before executing the next command, providing time for the page to load.