# Cypress

Cypress commands and utilities for customizations.

## Installation

```yarn
yarn add @commercetools-frontend/cypress
```

```npm
npm --save install @commercetools-frontend/cypress 
```

## Usage

This package extends Cypress' `cy` command.

Define the task in the plugins file:

```js title="cypress/plugins/index.js"
const customApplications = require('@commercetools-frontend/cypress/task');

module.exports = (on, config) => {
  on('task', {
    ...customApplications,
  });
};
```

The configuration has changed for Cypress version >= `10.0.0`. See the [migration guide](https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0).

Define the task in the `cypress.config.ts` file.

```ts title="cypress.config.ts"
import { defineConfig } from 'cypress';
import { customApplicationConfig } from '@commercetools-frontend/cypress/task';

export default defineConfig({
  retries: 1,
  video: false,
  e2e: {
    async setupNodeEvents(on, cypressConfig) {
      on('task', {
        customApplicationConfig,
      });
      return cypressConfig;
    },
    baseUrl: 'http://localhost:3001',
  },
}); 
```

Extend the Cypress commands:

```js title="cypress/support/commands.js"
import '@commercetools-frontend/cypress/add-commands';
```

## Commands

### Custom Applications

#### cy.loginToMerchantCenter

This command performs the user login to the Merchant Center. It automatically detects whether the application is running on localhost or production and chooses the appropriate login mechanism.

- When the application runs locally, the same mechanism used in the `cy.loginByOidc` is used.
- When the application runs on production, a normal login flow is used where the user enters the credentials into the login form.

##### Usage

```ts
it('should render page 1', () => {
  cy.loginToMerchantCenter({
    entryPointUriPath: 'my-app',
    initialRoute: `/${Cypress.env('PROJECT_KEY')}/my-app/page-1`,
  });
});
it('should render page 2', () => {
  cy.loginToMerchantCenter({ entryPointUriPath: 'my-app' });
  cy.visit(`/${Cypress.env('PROJECT_KEY')}/my-app/page-2`);
});
```

##### Options

Available options are:

- `entryPointUriPath` (**required**): The application entry point URI path is used to identify the correct application config.
- `dotfiles` (optional): A list of dotenv files to load when the `custom-application-config.json` is loaded (in case you're using an environment placeholder). By default the following dotenv files are loaded: `.env` and `.env.local`. You can also define the values using paths relative to the application folder.
- `initialRoute` (optional): The route to open after login. If not defined, make sure to call `cy.visit` yourself.
- `projectKey` (optional): The project key to access the user session. The session token is valid for one project key at a time. Defaults to `Cypress.env('PROJECT_KEY')`.
- `onBeforeLoad` (optional): The function to call before the page has loaded all of its resources. Use this as a chance to interact, for example, with the browser storage.
- `login` (optional): An object with the user login credentials `email` and `password`. If not provided, the `email` defaults to `Cypress.env('LOGIN_EMAIL') || Cypress.env('LOGIN_USER')` and the `password` defaults to `Cypress.env('LOGIN_PASSWORD')`.
- `disableCacheAcrossSpecs` (optional): Turn off caching the session across specs. This is only relevant for Cypress version >= `10.9.0`.

The command also requires loading the `custom-application-config.json` (automatically done via the Cypress task), so it may need to load environment variables in case the application config uses environment placeholders.
The `.env` and `.env.local` files are loaded by default from the application folder. You can pass a `dotfiles` option to provide a list of names/paths relative to the application folder in case the files in the project have a different name/location.

Ensure that the following environment variables are available if the related options aren't provided explicitly: `PROJECT_KEY`, `LOGIN_USER`, `LOGIN_PASSWORD`.

##### Session

The login command attempts to use the [cy.session](https://docs.cypress.io/api/commands/session) command, which caches and restores the user session between test runs.

This ultimately results in subsequent tests running much faster (by restoring the previous session) and making the test behave as if the user is authenticated.

The `cy.session` command is enabled by default in Cypress v12. If you are using older versions make sure to have the option `experimentalSessionAndOrigin` turned on (in your Cypress config).

#### cy.loginByOidc

This command is **deprecated**. We recommend using the more generic `cy.loginToMerchantCenter` command as it automatically detects which login mechanism to use.

### Custom Views

#### cy.loginToMerchantCenterForCustomView

This command performs the user login to the Merchant Center to test a Custom View. Testing Custom Views is expected to occur on `localhost`.

##### Usage

```ts
it('should render page 1', () => {
  cy.loginToMerchantCenterForCustomView();
});
```

##### Options

Available options are:

- `packageName` (optional): The package name as specified in the Custom View's `package.json`. If not provided, it defaults to `Cypress.env('PACKAGE_NAME').`
- `dotfiles` (optional): A list of dotenv files to load when the `custom-view-config.mjs` is loaded (in case you're [using variable placeholders](/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#use-variable-placeholders)). By default the following dotenv files are loaded: `.env` and `.env.local`. You can also define the values using paths relative to the Custom View folder.
- `projectKey` (optional): The project key to access the user session. The session token is valid for one project key at a time. Defaults to `Cypress.env('PROJECT_KEY')`.
- `onBeforeLoad` (optional): The function to call before the page has loaded all of its resources. Use this as a chance to interact, for example, with the browser storage.
- `login` (optional): An object with the user login credentials `email` and `password`. If not provided, the `email` defaults to `Cypress.env('LOGIN_EMAIL') || Cypress.env('LOGIN_USER')` and the `password` defaults to `Cypress.env('LOGIN_PASSWORD')`.
- `disableCacheAcrossSpecs` (optional): Turn off caching the session across specs. This is only relevant for Cypress version >= `10.9.0`.

The command also requires loading the `custom-view-config.mjs` (automatically done via the Cypress task), so it may need to load environment variables in case the Custom View config uses environment placeholders.
The `.env` and `.env.local` files are loaded by default from the Custom View folder. You can pass a `dotfiles` option to provide a list of names/paths relative to the Custom View folder in case the files in the project have a different name/location.

Ensure that the following environment variables are available if the related options aren't provided explicitly: `PROJECT_KEY`, `LOGIN_USER`, `LOGIN_PASSWORD`, `PACKAGE_NAME`.

##### Session

The login command attempts to use the [cy.session](https://docs.cypress.io/api/commands/session) command, which caches and restores the user session between test runs.

This ultimately results in subsequent tests running much faster (by restoring the previous session) and making the test behave as if the user is authenticated.

The `cy.session` command is enabled by default in Cypress v12. If you are using older versions make sure to have the option `experimentalSessionAndOrigin` turned on (in your Cypress config).

## Related pages

- [Area overview page with navigation](/merchant-center-customizations.md)
- [Previous page: Constants](/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-constants.md)
- [Next page: Jest](/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-jest-preset-mc-app.md)
- [Search documentation and API specs](/search.md)