## Applitools Eyes SDK for [Cypress](https://www.cypress.io/)

The Cypress SDK allows you to leverage the Applitools [Ultrafast Grid](https://applitools.com/tutorials/concepts/test-execution/ultrafast-grid) to automatically run tests across all major browsers.

For general information about working with Cypress, see [Cypress Testing Framework](https://applitools.com/learn/frameworks/cypress-testing/) on the Applitools website.

## Installing Eyes Cypress

Run the following
```bash
npm i --save @applitools/eyes-cypress
```

or
```bash
yarn add @applitools/eyes-cypress
```


## Setting up the project

On the project, run the following:

```bash
npx eyes-setup
```

### Modifying the configuration file

If `npx eyes-setup` did not run successfully, modify the configuration file as follows:

#### Cypress version 10 or later

Add the following to the `cypress.config.js` file:

```js
const { defineConfig } = require('cypress')
const eyesPlugin = require('@applitools/eyes-cypress')
module.exports = eyesPlugin(defineConfig({
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
    }
  }
}))
```

#### Cypress version earlier than version 10:

In the `pluginsFile` file, add the following **after** the definition of `module.exports`:

```js
require('@applitools/eyes-cypress')(module)
```

### IntelliSense code completion

You can add Eyes-Cypress IntelliSense to your tests using one of the following methods:

* [Triple slash directives](#slash)
* [Reference type declarations via `tsconfig`](#reference)


### Triple slash directives {#slash}

The simplest way to see IntelliSense when typing an Eyes-Cypress command is to add a [triple-slash](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) directive to the head of your JavaScript or TypeScript testing file. This will turn the IntelliSense on a per file basis:

```
  /// <reference types="@applitools/eyes-cypress" />
```

### Reference type declarations via `tsconfig` {#reference}

Eyes-Cypress ships with official type declarations for TypeScript. This allows you to add eyes commands to your TypeScript tests.
If you do not have TypeScript, for example you use JavaScript, you can add IntelliSense declarations to the project using one of the following:

- Add  the path to your [`tsconfig`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file:

```json
{
  "compileroptions": {
    "types": ["@applitools/eyes-cypress", "cypress", "node"]
   }
}
```

- In the `cypress/support` folder, create a file `index.d.ts`  that contains:
```js
import "@applitools/eyes-cypress"
```

Normally, this is `cypress/plugins/index.js`. For details, see the [Cypress documentation](https://docs.cypress.io/guides/references/configuration.html#Folders-Files).



#### Configure custom commands manually

Eyes-Cypress exposes new commands to your tests. This means that additional methods will be available on the `cy` object.
If `npx eyes-setup` does not work, you need to configure these custom commands. As with the plugin, there is no automatic way to configure this in Cypress, so you need to manually add the following code to your `supportFile`:

```js
import '@applitools/eyes-cypress/commands'
```

### Entering the Applitools API key{#API}

To authenticate via the Applitools server and run tests, you need to set the environment variable `APPLITOOLS_API_KEY` to the API key provided from Applitools Eyes. For details how to retrieve your API key, see [the Applitools documentation](https://applitools.com/tutorials/getting-started/retrieve-api-key).


#### Entering the API Key on Linux or a Mac

```bash
export APPLITOOLS_API_KEY=<API_key>
npx cypress open
```

#### Entering the API Key on Windows

```bash
set APPLITOOLS_API_KEY=<API_key>
npx cypress open
```

### Eyes server URL {#URL}

If the Eyes server is not deployed in `https://eyes.applitools.com`, you need to set the Server URL in the environment variable `APPLITOOLS_SERVER_URL`  before running tests.

The server URL of your Applitools Eyes dashboard is in the format `https://<MY_COMPANY>.applitools.com`

#### Entering the server URL on Linux or a Mac

```bash
export APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>
```

#### Entering the server URL on Windows

```bash
set APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>
```
## Further information

For further information, see:

* [Quickstart](https://applitools.com/tutorials/sdks/cypress/quickstart)
* [Overview](https://applitools.com/tutorials/sdks/cypress)
* [Changelog](https://applitools.com/tutorials/sdks/cypress/changelog)