# <img align=center src="PDE_logo_black.png" width="250px"/> Cypress Test Automation Framework

## Quick Start

If you have a choice, it is strongly suggested that you use macOS for
Cypress tests.

1. Fork and clone this repo.
2. Change directory to the cucumber-cypress-tests repo.

### macOS

#### Install Node and npm via Homebrew

`brew update`

`brew install node`

#### Install dependencies

`npm install --global yarn`

`yarn install`

### Ubuntu Linux

#### Install Node and npm

`sudo apt update`

`sudo apt install nodejs`

`sudo apt install npm`

Use `n` module from npm in order to upgrade node and install `yarn`:

`sudo npm cache clean -f`

`sudo npm install -g n`

`sudo n stable`

#### Install Dependencies

`npm install --global yarn`

`yarn install`

### Downloading Secrets

Check with DevOps team that you have access to PDE's `AWS secrets manager`. Then run the following command on root folder of the forked project:

`yarn check:env`

This will fetch the `cypress.env.json` file from AWS sSecrets manager (`prod` environment, `region us_east-1`)
The user data for the relevant environment and file will be fetched from AWS secrets manager at runtime and stored in
memory.

These files will not be fetched from AWS once downloaded unless forced. You can refresh them by running:

`make refresh_secrets`

You can add new secrets or update existing ones by running:

`make update_secrets`

**_If you are facing issues with AWS credentials you should ensure you have Awsume configured (https://awsu.me/) and used to get the proper temporary creds_**

**_If you still cannot have access to secrets manager service you can always fill in the `cypress.env.json.shadow` file and remove the `.shadow` from the filename._**

## Application configuration files

Application specific variables should be placed in
`cypress/config/qa.json`

`cypress/config/prod.json`

`cypress/config/dev.json`

## Running Cypress tests locally

### To run Cypress tests using Cypress GUI client:

**In QA Environment (default):**

`yarn cy:open`

**In Prod Environment:**

`yarn cy:open --env configFile=prod`

**In Dev Environment:**

1. Add your local `frontendHost` value to `/cypress/config/dev.json` file:
   ```json
    "publishing": {
      "frontendHost": "http://localhost:8080"
    }
   ```
2. Run tests in Cypress GUI client:

   `yarn cy:local:open`

### Running Cypress tests in parallel on Jenkins

On Jenkins, Cypress tests are split by Feature, each Feature file will run in parallel as AWS ECS Task using Docker container.

For more details refer to the following [Notion doc](https://www.notion.so/Cypress-Parallel-Execution-using-aws-ECS-ee77236a558b4635821abe75138d13e0)

## Adding new application from the Orchard Suite

### Configuration

Add application configuration options in
`cypress/config/qa.json`
`cypress/config/prod.json`
`cypress/config/dev.json`

as follows:

```json
{
 "env": {
   ...
   "<APP_NAME>": {
     "frontendHost": "https://<app_name>.qaorch.com/",
   },
   ...
 }
}
```

## Adding Test Users Fixtures

Use the make command `make update_secrets` and select option 2. Then select your application name and environment. The
relevant secret will be downloaded and you can add your test users in the relevant section.

```json
{
  ...
  "<APP_NAME>": {
    "label_31273": {
      "username": "",
      "password": ""
    }
  },
  ...
}
```

- `<APP_NAME>` defines the application name
- `label_31273` defines the unique user to search for

If you need to add a new application, update the e2e-test-secrets variables in terraform to create a secret in the
relevant environment. The name of the secret will need to match the application name in the directory structure
following
the pattern laid out.

### For any other kind of fixtures you should add a new file called `<APP_NAME>.json` under the same folder in `cypress/fixtures`

- Access fixture file by calling this in your code

```javascript
  cy.fixture('<APP_NAME>').then(<APP_NAME> => {
    ...
    <YOUR_CODE>
    ...
  })
```

### Environment paths for applications

Sometimes we need to navigate through different paths inside the same application. Use the `cypress/fixtures/environment-paths.json` fixture in this case.

### Test Data & Media assets for applications

Located in the `cypress/fixtures/` folder

## Page Objects

All page objects files should be added under `cypress/pages/<APP_NAME>/` folder

## Step definitions

All feature files with scenarios should be added under `cypress/steps/<APP_NAME>/` folder

## Cucumber Feature Files

All feature files with scenarios should be added under `cypress/e2e/<APP_NAME>/` folder

## Common Page Objects

### `LoginPage.js`

Handles Login flow to the app, by passing the `user` and the `application` name in a test scenario:

```gherkin
...
Given an orchard employee <USER> for <APP_NAME>
When I log in to <APP_NAME>
...
```

### `HomePage.js`

HomePage is the main page object that contains common logic that shared between all Orchard Applications.

## Common Step Definitions

Common steps that are shared between all Orchard Applications defined in `cypress/steps/common/common-steps.js`

## Testing the tests

To run unit and smoke tests for the Cypress tests, use:

`make unit_test`

`make framework_smoke_test`

## Style Guide

1. We use [Prettier](https://prettier.io/docs/en/) for code and Gherkin formatting. The configuration is specified in the [.prettierrc](.prettierrc) file
   1. To apply formatting to a file, run: `yarn prettier --write "path/to/file"`
   2. To apply formatting to all your changes, run `git add . && yarn lint-staged`, and then commit your changes
   3. The code formatting check is integrated into our Jenkins CI/CD pipeline. Please make sure the build is green before merging your changes.
2. Our Gherkin style guide can be found [here](https://github.com/theorchard/docs/blob/master/styleguides/gherkin.md)
3. Our JavaScript style guide can be found [here](https://github.com/theorchard/docs/blob/master/styleguides/javascript.md)

## Adding ID tags to Scenarios

Each scenario must have an ID tag. These will be auto-generated by a pre-commit hook. To enable this run:

`make configure_husky_hooks`

If you wish to manually run the id generator, you can run using a specific file or directory using either of the below:

`node framework/src/tagScenariosWithIds.js --dir path/to/dir`

`node framework/src/tagScenariosWithIds.js --files path/to/file`

The `--files` option supports multiple files seperated by a space

## Abacus Suite

### DB normalization

Abacus suite is dependent on `art_relations.vendor` table be normalized with `royalty_accounting.account`

If you encounter situation when created abacus account fixture name doesn't match the expectation then run

`node ./scripts/normalizeVendorTable.js`