# Cypress framework

The **sealights-cypress-plugin** is a custom plugin for the Cypress testing framework that enhances your testing capabilities by providing additional support for various tasks and configurations. This plugin adds support for Sealights, including coverage reporting, test results, and test optimization.

It’s a **non-intrusive setup** — no changes to your Cypress configuration files are required.\
Install the plugin, export your environment variables, and run your Cypress tests using the **SeaLights Cypress Runner**.

{% hint style="warning" %}
For advanced details, you can also refer to <https://www.npmjs.com/package/sealights-cypress-plugin>
{% endhint %}

## Configuration

{% stepper %}
{% step %}

#### Install the Plugin

To install the Sealights Cypress plugin, follow the instructions below.

```bash
npm install --save-dev sealights-cypress-plugin
```

{% endstep %}

{% step %}

#### Set Environment Variables

Define your SeaLights configuration via environment variables — this is the preferred approach for CI/CD systems like GitHub Actions, Jenkins, Tekton, Azure Pipelines, or Kubernetes Pods. The required environment variables must start with a `CYPRESS_` prefix:

{% tabs %}
{% tab title="Linux" %}

```bash
export CYPRESS_SL_TOKEN=<your_token>            # from CI secret or vault
export CYPRESS_SL_ENABLE_REMOTE_AGENT=true
export CYPRESS_SL_TEST_STAGE="Cypress E2E Tests"
export CYPRESS_SL_LAB_ID=<your_labid>  # unique per testing environment
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
$env:CYPRESS_SL_TOKEN = "<your_token>"            # from CI secret or vault
$env:CYPRESS_SL_ENABLE_REMOTE_AGENT = "true"
$env:CYPRESS_SL_TEST_STAGE = "Cypress E2E Tests"
$env:CYPRESS_SL_LAB_ID = "<your_labid>"           # unique per testing environment
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Execute your Cypress tests with SeaLights

Execute your Cypress command through the Sealights runner:

```bash
npx sealights-cypress-plugin npx cypress run --spec 'cypress/e2e/**/*spec.cy'
```

The plugin used as a runner automatically integrates SeaLights with your Cypress project:

* **Backs up** your existing Cypress configuration & support files,
* **Injects** the required Sealights hooks (`registerSealightsTasks` and the support file import)
* Validates that the mandatory environment variables are present and that the Sealights endpoint is reachable before the test run starts.
* **Executes tests** with coverage collection
* Restores original files afterward
  {% endstep %}
  {% endstepper %}

{% hint style="success" %}
When the command and **Cypress tests complete successfully**, a new test stage (with the name you specified) will appear in the Sealights dashboard under the corresponding build. This stage will include the **associated test results and coverage data.**
{% endhint %}

## Additional Runner Usages

You can invoke the runner in two ways:

1. Using **npx** (recommended):

```bash
npx sealights-cypress-plugin npx cypress run --spec test.spec.cy
```

2. Directly from `node_modules`:

```bash
node ./node_modules/.bin/sl-cypress-runner npx cypress run --spec test.spec.cy
```

You may pass any command after the runner – it will be executed verbatim:

```bash
npx sealights-cypress-plugin my-own-cypress-command --headed --browser chrome
```

If you use a glob for the `--spec` pattern, remember to wrap it in quotes so that your shell doesn't expand it:

```bash
npx sealights-cypress-plugin npx cypress run --spec '*.spec.cy'
```

## Logging and Debugging

Additional logging can be enabled using the following environment variable:

```bash
export NODE_DEBUG=sl
```

The default log level with this var on is `info`. To obtain the debug logs, you can set another variable:

```bash
export SL_LOG_LEVEL=debug
```

Using the variable `CYPRESS_SL_ENABLE_BROWSER_DEBUG`, you can enable the dumping of browser network traffic, unhandled exceptions, browser logs, and check the fetch status of the browser agent. All of this will be exported in a folder called `sealights-output`, organized by spec file.

```bash
export CYPRESS_SL_ENABLE_BROWSER_DEBUG=true # default: false
```

## Sample Script

{% tabs %}
{% tab title="Bash" %}

<pre class="language-bash"><code class="lang-bash"># 1. Install dependencies
npm ci

# 2. Install SeaLights Cypress plugin
npm install --save-dev sealights-cypress-plugin

# 3. Set environment variables 
export CYPRESS_SL_TEST_STAGE="cypress e2e" 
export CYPRESS_SL_TOKEN={token}    ## From Secrets/Vault
#export CYPRESS_SL_BUILD_SESSION_ID={bsid}
export CYPRESS_SL_LAB_ID=integ_app_uat1
# export CYPRESS_SL_PROXY="http://proxyuser:proxypass@proxy.example.com:8080"
#export NODE_DEBUG=sl
#export SL_LOG_LEVEL=debug

# 4. Run tests with SeaLights
<strong>npx sealights-cypress-plugin npx cypress run --spec 'cypress/e2e/**/*spec.cy'
</strong></code></pre>

{% endtab %}

{% tab title="PowerShell" %}

```powershell
# 1. Install dependencies
npm ci

# 2. Install SeaLights Cypress plugin
npm install --save-dev sealights-cypress-plugin

# 3. Set environment variables
$env:CYPRESS_SL_TEST_STAGE = "cypress e2e"
$env:CYPRESS_SL_TOKEN = "{token}"    # From Secrets/Vault
# $env:CYPRESS_SL_BUILD_SESSION_ID = "{bsid}"
$env:CYPRESS_SL_LAB_ID = "integ_app_uat1"
# $env:CYPRESS_SL_PROXY = "http://proxyuser:proxypass@proxy.example.com:8080"
# $env:NODE_DEBUG = "sl"
# $env:SL_LOG_LEVEL = "debug"

# 4. Run tests with SeaLights
npx sealights-cypress-plugin npx cypress run --spec 'cypress/e2e/**/*spec.cy'
```

{% endtab %}

{% tab title="GitHub Actions" %}
{% code overflow="wrap" %}

```yaml
jobs:
  cypress-e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install deps
        run: npm ci sealights-cypress-plugin
      - name: Run Cypress with SeaLights
        env:
          CYPRESS_SL_TOKEN: ${{ secrets.SEALIGHTS_AGENT_TOKEN }}
          CYPRESS_SL_LAB_ID: "QA2"
          CYPRESS_SL_TEST_STAGE: "Cypress E2E"
          ##CYPRESS_SL_PROXY: "http://proxyuser:proxypass@proxy.example.com:8080"
        run: npx sealights-cypress-plugin npx cypress run --spec 'cypress/e2e/**/*spec.cy'
```

{% endcode %}
{% endtab %}
{% endtabs %}

✅ Coverage data and test results are uploaded automatically to your SeaLights dashboard.

## Advanced Configuration and Developer Options

{% hint style="warning" %}
For advanced use cases, refer to 👉 [**Advanced Details on npm**](https://www.npmjs.com/package/sealights-cypress-plugin)**, including:**

* Manual configuration for Cypress v9 and v10+ (without the runner)
* Lite Mode configuration
  {% endhint %}

## Common Plugin Parameters

{% hint style="info" %}
Environment variables override the default file-based configuration and are recommended for CI/CD usage.
{% endhint %}

<table data-full-width="true"><thead><tr><th width="366">Environment Variable Equivalent</th><th width="98">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>CYPRESS_SL_TEST_STAGE</code></td><td>✅</td><td>Name of the test stage (“Cypress”, “E2E”, etc.)</td></tr><tr><td><code>CYPRESS_SL_TOKEN</code></td><td>✅</td><td>Authentication token</td></tr><tr><td><code>CYPRESS_SL_LAB_ID</code></td><td>✅</td><td>Test Environment ID shared with the Instrumented AUT (Application Under Test). Optional if the <code>BUILD_SESSION_ID</code> is provided.</td></tr><tr><td><code>CYPRESS_SL_BUILD_SESSION_ID</code></td><td>Optional</td><td>Sealights Build Session ID. Mandatory if LAB_ID is not defined.</td></tr><tr><td><code>CYPRESS_SL_PROXY</code></td><td>Optional</td><td>Proxy configuration (host:port or URL)</td></tr><tr><td><code>CYPRESS_SL_TEST_PROJECT_ID</code></td><td>Optional</td><td>Identifier for the current test project</td></tr><tr><td><code>CYPRESS_SL_TARGET_TEST_PROJECT_ID</code></td><td>Optional</td><td>Target test-project ID (for PR builds / TGA model)</td></tr><tr><td><code>CYPRESS_SL_ENABLE_REMOTE_AGENT</code></td><td>Optional</td><td>Reduce load and test execution times, by skipping download of browser agent and using a remote-agent implementation. Default is <code>true</code></td></tr><tr><td><code>CYPRESS_SL_COLLECTOR_URL</code></td><td>Optional</td><td>HTTP Collector URL</td></tr><tr><td><code>CYPRESS_SL_TIA_DISABLED</code></td><td>Optional</td><td>Disable TIA and enforce a full run. (Default: <code>false</code>.)</td></tr><tr><td><code>CYPRESS_SL_OPTIMIZE_COVERAGE_COLLECTION</code></td><td>Optional</td><td>Reduce large coverage data transfers. Default is <code>false</code></td></tr></tbody></table>