ItemEngine EdgeEx Cypress Test Automation

This repository contains Cypress tests for the ItemEngine EdgeEx application. These tests validate functionality across various environments (DEV, QA, Stage, PROD) and components of the EdgeEx application.

Table of Contents

• Prerequisites
• Installation
• Running Tests Locally
  • Using npm Scripts
  • Using Cypress UI
  • Test Filtering Options
• Running Tests on Argo
• Test Structure
• Configuration
• Environment Variables
• Troubleshooting

Prerequisites

• Node.js 20.x or higher
• npm or yarn
• Chrome browser (for running tests)

Installation

1. Clone the repository:

   git clone https://github.com/ImagineLearning/itemengine-edgeex-cypress.git
   cd itemengine-edgeex-cypress

2. Install dependencies:

   npm install

Running Tests Locally

Using npm Scripts

The following npm scripts are available for running tests locally:

# Run all tests against QA environment
npm run local

# Run only untagged tests against QA environment
npm run local:untagged

# Run smoke tests against QA environment
npm run local:smoke

Using Cypress UI

You can open the Cypress UI to run and debug tests interactively:

# Open Cypress UI with Stage environment
npm run cy:open

# Open Cypress UI for specific environments
npm run cy:prod     # Production environment with cosmos tag
npm run cy:qa       # QA environment with cosmos tag
npm run cy:dev      # Dev environment with cosmos tag
npm run cy:stage    # Stage environment with cosmos tag
npm run cy:ugcqa    # UGC QA environment with ugc tag
npm run cy:ugcdev   # UGC Dev environment with ugc tag
npm run cy:cosmosStage  # Cosmos Stage environment with cosmos tag

Test Filtering Options

You can filter tests by specifying tags:

• Use grepTags to run tests with specific tags:

  # Run smoke tests, excluding css and a11y tagged tests
  npm run local -- --env fileConfig=qa,theme=ngie,grepTags=smoke+-css+-a11y

• Use grepUntagged to run only tests without tags:

  npm run local -- --env fileConfig=qa,theme=ngie,grepUntagged=true

Running Tests on Argo

Tests can be run on Argo using the CI/CD pipeline. The configuration is defined in the deploy/e2e/service.yaml and deploy/regression/service.yaml files.

To run tests on Argo:

1. The tests are automatically triggered by the CI/CD pipeline when code is pushed to the repository.
2. The pipeline uses the entrypoint.sh script to run the tests.
3. Tests are run in parallel based on the configuration in service.yaml.

Argo Environment Configuration

The service.yaml file defines the test execution parameters for each environment:

• DEV: Tests run against the dev environment
• QA: Tests run against the QA environment
• Staging: Tests run against the staging environment
• Prod: Tests run against the production environment

Setting Up Argo Environment Variables

The environment variables for Argo are configured in the service.yaml file under the env and namespaces sections:

# Global environment variables (apply to all environments)
env:
  - name: CYPRESS_API_URL
    value: "https://cypress-director.imaginelearning.tech/"
  - name: THEME
    value: "ngie"
  - name: GREP_TAGS
    value: "smoke+-css+-a11y"
  - name: GREP_UNTAGGED
    value: ""
  - name: SPEC_PATTERN
    value: "cypress/e2e/FreeResponse/**/*.smoke.js"

# Environment-specific variables
namespaces:
  dev:
    env:
      - name: STAGE
        value: "dev"
      - name: FILE_CONFIG
        value: "dev"
  qa:
    env:
      - name: STAGE
        value: "qa"
      - name: FILE_CONFIG
        value: "qa"
  # ... other environments

To modify the environment variables for Argo tests:

1. Edit the appropriate section in the deploy/e2e/service.yaml or deploy/regression/service.yaml file
2. Commit and push the changes
3. The next pipeline run will use the updated environment variables

Test Structure

cypress/
├── config-files/       # Environment configuration files
├── downloads/         # Downloaded files during test execution
├── e2e/               # End-to-end test files
│   ├── FreeResponse/  # Tests for free response features
│   ├── Gzip/          # Tests for Gzip features
│   ├── Rubric Engine/ # Tests for rubric engine features
│   └── Timeline Creator/ # Tests for timeline creator features
├── fixtures/          # Test data and constants
├── pages/             # Page object models
├── screenshots/       # Test failure screenshots
├── support/           # Support files and custom commands
└── videos/            # Test execution videos

Configuration

Environment-specific configuration files are located in the cypress/config-files/ directory:

• dev.json: Configuration for DEV environment
• qa.json: Configuration for QA environment
• stage.json: Configuration for Staging environment
• prod.json: Configuration for Production environment
• cosmosStage.json: Configuration for Cosmos Stage environment
• ugcdev.json: Configuration for UGC Dev environment
• ugcqa.json: Configuration for UGC QA environment

Environment Setup

Environment Variables

The following environment variables can be used to configure test execution:

• CYPRESS_API_URL: URL for the Cypress Director API (default: "https://cypress-director.imaginelearning.tech/")
• THEME: Theme to use for tests (e.g., ngie, ugc)
• GREP_TAGS: Tags to include/exclude in test execution (e.g., "smoke+-css+-a11y")
• GREP_UNTAGGED: Whether to run only untagged tests (set to "true" to run only untagged tests)
• SPEC_PATTERN: Pattern to match specific test files (e.g., "cypress/e2e/FreeResponse/**/*.smoke.js")
• STAGE: Environment to test against (dev, qa, stage, prod)
• FILE_CONFIG: Environment to test against (dev, qa, stage, prod)

Setting Up Environment Variables

Method 1: Using .env File

Create a .env file in the root directory with your environment variables:

CYPRESS_API_URL=https://cypress-director.imaginelearning.tech/
THEME=ngie
GREP_TAGS=smoke+-css+-a11y
STAGE=qa
FILE_CONFIG=qa

Method 2: Command Line (Temporary)

Set environment variables before running the tests:

# For Linux/Mac
export STAGE=qa
export THEME=ngie
export GREP_TAGS=smoke
npm run local

# For Windows (Command Prompt)
set STAGE=qa
set THEME=ngie
set GREP_TAGS=smoke
npm run local

# For Windows (PowerShell)
$env:STAGE="qa"
$env:THEME="ngie"
$env:GREP_TAGS="smoke"
npm run local

Method 3: Inline Environment Variables

Specify environment variables inline with the command:

# For Linux/Mac
STAGE=qa THEME=ngie GREP_TAGS=smoke npm run local

# For Windows (PowerShell)
$env:STAGE="qa"; $env:THEME="ngie"; $env:GREP_TAGS="smoke"; npm run local

Environment Configuration Files

Each environment has its own configuration file in the cypress/config-files/ directory. These files contain environment-specific settings such as base URLs, API endpoints, and credentials.

Here's an example of what might be in these configuration files:

{
  "baseUrl": "https://test.com",
  "apiUrl": "https://test-api-qa.imaginelearning.com",
  "credentials": {
    "username": "test-user",
    "password": "password-placeholder"
  }
}

Environment Selection in Tests

When running tests, you can specify which environment configuration to use:

# Using npm scripts
npm run local -- --env fileConfig=qa,theme=ngie

# Using Cypress directly
npx cypress run --env fileConfig=qa,theme=ngie

The fileConfig parameter determines which configuration file from the cypress/config-files/ directory is used.

Troubleshooting

Common Issues

1. Tests failing with timeout errors

   • Check network connectivity to the target environment
   • Increase the default timeout in the Cypress configuration

2. Element not found errors

   • Check if the application UI has changed
   • Update the selectors in the page object models

3. Authentication issues

   • Ensure the correct environment configuration is being used
   • Check if authentication tokens are valid

Getting Help

For additional help or to report issues, please create an issue in the GitHub repository.