# E2E Cypress 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.

{% hint style="warning" %}
The previous E2E tests based on Protractor are no longer supported.
{% endhint %}

Servoy Cloud now uses Cypress to run the E2E tests.

{% hint style="info" %}
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.
{% endhint %}

## 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.

<pre class="language-javascript"><code class="lang-javascript"><strong>function onSolutionOpen(arg, queryParams) {
</strong>	if(scopes.svyCloud.getCurrentEnvironment() == scopes.svyCloud.CLOUD_ENVIRONMENT_TYPES.E2E){
		scopes.svyDataSeed.runDataseedFromMedia();
	}
}
</code></pre>

This enables Servoy Cloud to prepare test data for E2E tests. For local setup, see the [Local setup](#id-3.-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:

```bash
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](https://docs.servoy.com/reference/servoy-cloud/using-cypress#create-a-new-spec) (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](https://docs.servoy.com/reference/servoy-cloud/using-cypress#add-cypress-commands-custom-functions "mention") 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).

## 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](https://docs.servoy.com/reference/servoy-cloud/cloud-control-center/application-overview/applications/pipelines/jobs/job-configuration) or in the `cypress.env.json` file.

{% hint style="warning" %}
It is not recommended to store passwords or other sensitive data in the `cypress.env.json` file (see [Use Locally](#use-locally) for more details)
{% endhint %}

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](https://docs.servoy.com/reference/servoy-cloud/using-cypress#cypress-test-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`

{% hint style="warning" %}
Click the **"Save settings"** button and restart your Servoy Cloud application for changes to take effect.
{% endhint %}

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

{% hint style="warning" %}
**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"`
  {% endhint %}

#### 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"](#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](https://docs.servoy.com/reference/cloud-control-center/application-overview/applications/pipelines/jobs/job-configuration/build-and-deploy-or-build#customization).

**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.

{% hint style="warning" %}
**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.
> {% endhint %}

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**](#cypress-studio-beta) for E2E tests

## Cypress Studio BETA

[**Cypress Studio**](https://docs.cypress.io/guides/references/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](#cypress-config-file) attribute to `false` in the [Cypress Config file](#cypress-config-file)