E2E Cypress Testing

Reference documentation for setting up Servoy Cloud End-to-end(E2E) Testing

Overview

This page provides step-by-step instructions on how to set up Cypress and make it work within the Servoy Cloud system.

Get started with Cypress

End-to-end (E2E) testing is a type of software testing that assesses flows in the application from start to finish. E2E testing is valuable for detecting issues related to the integration of different components, catching bugs in the user interface, and ensuring that the application functions correctly in a real-world scenario.

The previous E2E tests based on Protractor are no longer supported.

Servoy Cloud now uses Cypress to run the E2E tests.

In Cypress, test files are referred to as "specs." Each spec can include one or more E2E tests, offering a flexible and efficient way to organize and run tests.

Requirements

To set up Cypress testing, please read the documentation below and follow each step accordingly.

Step 1: Set up test data

When using Servoy Cloud E2E Testing, you are required to have test data which you can run your tests against.

To create your test data, follow these steps:

1. Create Dataseed file

• Generate a dataseed file using svyDataSeed by calling scopes.svyDataSeed.createDataSeedFiles()

• The file will be stored in your workspace under svyCloudUtils/medias/dataseeds

2. Create post-import hook module

In Servoy Developer:

1. Right-click on Modules and select "Create new module."

2. Create a new module with Solution Type set to "Post-import hook module."

3. Create an onSolutionOpen method in the post-import module to run your dataseed.

function onSolutionOpen(arg, queryParams) {
	if(scopes.svyCloud.getCurrentEnvironment() == scopes.svyCloud.CLOUD_ENVIRONMENT_TYPES.E2E){
		scopes.svyDataSeed.runDataseedFromMedia();
	}
}

This enables Servoy Cloud to prepare test data for E2E tests. For local setup, see the Local setup section.

3. Local setup

For local test data setup, run the dataseed from the command console or add the following method to a button on a page:

scopes.svyDataSeed.runDataseedFromMedia()

Step 2: Workspace structure

To facilitate E2E testing with Cypress, Servoy Cloud provides a specific workspace structure:

jenkins-custom
|── e2e-test-scripts
    ├── cypress
        ├── e2e
            ├── loginFlow.cy.js
            ├── resetPasswordFlow.cy.js
        ├── support
            ├── commands.js
            ├── e2e.js (This is where commands.js is imported)
    ├── cypress.config.js
    ├── cypress.env.json (Optional, see section "Use Locally" on this page)

Refer to the documentation for any of the Cypress specific files or on how to add spec files (e.g loginFlow.cy.js)

Cypress commands.js file

The cypress/support/commands.js file is where you define custom Cypress functions (known as commands). These commands extend Cypress with reusable functions that can simplify and clean up your test code.

By default, Cypress auto-imports this file (via support/e2e.js), so any commands defined here are available globally in all your tests.

See Add Cypress commands (custom functions) for how to use them

Step 3: Install Cypress

To install Cypress, use the following npm command:

npm install cypress -g

You are now ready to start using Cypress. To use Custom data, such as usernames and passwords, refer to the section Custom Data.

Custom data

Servoy Cloud allows you to define dynamic test data (e.g., usernames, urls, and passwords) for Cypress tests in a flexible way. These values can be specified either in the job configuration or in the cypress.env.json file.

It is not recommended to store passwords or other sensitive data in the cypress.env.json file (see Use Locally for more details)

Follow the steps below to define and use custom data:

Define in Servoy Cloud

Follow these steps if you want to use custom data in your cypress tests:

1. Navigate to Job Configuration

2. Create a custom property of type E2E with a specified name and value

3. Save the configuration

Now, your E2E custom properties are ready for use in Cypress tests (see example)

Use Locally

To use the E2E properties when running the tests locally, additional steps must be followed:

Step 1: Enable testing mode and generate Cypress data tags

To enable testing mode for local use (to replicate server behavior) and generate Cypress data tags on elements:

1. Navigate to the Admin page using the button in the Help menu > Servoy Admin page in the Servoy Developer

2. Set the property servoy.ngclient.testingMode to true

Click the "Save settings" button and restart your Servoy Cloud application for changes to take effect.

This enables generation of static data tags for test targeting unlike randomly generated element IDs.

Do not use random IDs — always use these tags when available to tag elements in your tests:

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

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

Step 2: Set up env file for custom data

1. Create a file named cypress.env.json in the e2e-test-scripts folder

2. Add custom properties in JSON format. If not defined, refer to "Define in Servoy Cloud"

Example cypress.env.json:

{
    "username": "myTestUsername",
    "password": "myTestPassword123!"
}

where username and password are the the E2E custom properties defined in the job configuration.

Behavior:

• When a cypress.env.json file exists in the repository, it is merged with the environment parameters provided in the job configuration.

  • The properties defined in cypress.env.json file, that are not specified in job configuration, won't be overriden by the job.

  • If a parameter exists in both the cypress.env.json file and the job configuration, the value from the job configuration will be used.

• If cypress.env.json does not exist, but parameters are provided in the job, the job will generate the file automatically during runtime.

Security Note:

Even though the file can be committed to the repository, do not include real passwords or secrets in it. Treat it like any other sensitive file.

This mechanism allows for easier reuse of commonly used environment variables without having to manually configure them in every job or test case.

---

Cypress Config file

The Cypress configuration file cypress.config.js is where Cypress config properties are defined.

Example cypress.config.js:

module.exports = {
    "video": true,
    "screenshotOnRunFailure": true,
    "screenshotsFolder": "cypress/screenshots",
    "videosFolder": "cypress/videos",
    "fixturesFolder": "cypress/fixtures",
    "viewportWidth": 1920,
    "viewportHeight": 1080,
    "chromeWebSecurity": false,
  e2e: {
    baseUrl: "http://localhost:8183",
    specPattern: "**/*.{cy.js, spec.js, test.js}",
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
    experimentalStudio: true
  },
};

Config attributes

baseUrl

Stores the localhost URL with the port. Update if the localhost port is changed.

experimentalStudio

Enables the use of Cypress Studio for E2E tests

Cypress Studio BETA

Cypress Studio is an experimental feature designed to enhance your testing experience. It provides a visual way to generate E2E tests within Cypress, by recording interactions against the application under test.

By default, Cypress Studio is enabled in Servoy Cloud but can be disabled by setting the experimentalStudio attribute to false in the Cypress Config file