GitHub Actions integration in Cypress - Framework Patterns

Framework Mode - GitHub Actions integration

Folder Structure

  cypress/
  ├── e2e/                  # Test specs
  │   └── example.cy.js
  ├── fixtures/             # Test data files
  │   └── example.json
  ├── support/              # Custom commands and utilities
  │   ├── commands.js
  │   └── e2e.js
  cypress.config.js         # Cypress configuration file
  .github/
  └── workflows/
      └── cypress.yml       # GitHub Actions workflow for Cypress tests
  package.json              # Project dependencies and scripts
  

Test Framework Layers

• Test Specs (cypress/e2e): Contains the actual test files written in Cypress syntax.
• Fixtures (cypress/fixtures): Holds static test data like JSON files to use in tests.
• Support (cypress/support): Includes reusable commands and setup code that runs before tests.
• Configuration (cypress.config.js): Defines test settings like base URL, viewport, and environment variables.
• CI Workflow (.github/workflows/cypress.yml): Automates running tests on GitHub Actions on code push or pull requests.

Configuration Patterns

Use cypress.config.js to set base URLs and environment variables for different environments.

Example snippet in cypress.config.js:

  import { defineConfig } from 'cypress'

  export default defineConfig({
    e2e: {
      baseUrl: process.env.BASE_URL || 'http://localhost:3000',
      env: {
        username: process.env.CYPRESS_USERNAME || 'testuser',
        password: process.env.CYPRESS_PASSWORD || 'password123'
      },
      setupNodeEvents(on, config) {
        // implement node event listeners here
      }
    }
  })
  

In GitHub Actions workflow, set environment variables securely using secrets for credentials.

Test Reporting and CI/CD Integration

GitHub Actions workflow cypress.yml runs tests on push or pull request events.

Example cypress.yml workflow snippet:

  name: Cypress Tests

  on:
    push:
      branches: [main]
    pull_request:
      branches: [main]

  jobs:
    cypress-run:
      runs-on: ubuntu-latest

      steps:
        - uses: actions/checkout@v3
        - name: Setup Node.js
          uses: actions/setup-node@v3
          with:
            node-version: '18'
        - name: Install dependencies
          run: npm ci
        - name: Run Cypress tests
          uses: cypress-io/github-action@v5
          with:
            start: npm start
            wait-on: 'http://localhost:3000'
            wait-on-timeout: 60
          env:
            CYPRESS_USERNAME: ${{ secrets.CYPRESS_USERNAME }}
            CYPRESS_PASSWORD: ${{ secrets.CYPRESS_PASSWORD }}
  

The workflow uploads test results and screenshots automatically for review in GitHub.

Best Practices

• Keep test data separate in fixtures for easy maintenance and reusability.
• Use environment variables and GitHub Secrets to keep credentials secure and configurable.
• Run tests on multiple events like push and pull requests to catch issues early.
• Use the official cypress-io/github-action for reliable and simple CI integration.
• Keep the workflow fast by caching dependencies and waiting for the app to be ready before tests.

Self Check

Where in this folder structure would you add a new test spec file for a login feature?

Key Result

Organize Cypress tests with clear folder layers and automate runs using GitHub Actions workflows with secure environment variables.

Practice

1. What is the main purpose of integrating Cypress tests with GitHub Actions?

easy

A. To manually trigger tests only when needed

B. To automatically run tests on code changes and catch bugs early

C. To deploy the application to production

D. To write Cypress test scripts inside GitHub

Solution

1. Step 1: Understand GitHub Actions role

   GitHub Actions automates tasks like running tests when code changes.

2. Step 2: Connect Cypress testing purpose

   Cypress tests run automatically to find bugs early without manual effort.

3. Final Answer:

   To automatically run tests on code changes and catch bugs early -> Option B

4. Quick Check:

   Automation of tests = A [OK]

Hint: GitHub Actions automates tasks on code changes [OK]

Common Mistakes:

• Thinking GitHub Actions only deploys code
• Believing tests run manually only
• Confusing test writing with test running

2. Which YAML key is used to specify the event that triggers a GitHub Actions workflow for Cypress tests?

easy

A. jobs

B. run

C. steps

D. on

Solution

1. Step 1: Identify trigger key in GitHub Actions YAML

   The on key defines events like push or pull_request that start the workflow.

2. Step 2: Differentiate from other keys

   run is used inside steps, steps lists commands, jobs groups tasks.

3. Final Answer:

   on -> Option D

4. Quick Check:

   Trigger event key = on [OK]

Hint: Triggers use 'on' key in GitHub Actions YAML [OK]

Common Mistakes:

• Confusing 'run' with trigger event
• Mixing 'steps' with event triggers
• Using 'jobs' as trigger key

3. Given this GitHub Actions snippet, what will happen when code is pushed to the main branch?

on:
  push:
    branches:
      - main
jobs:
  cypress-run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Cypress tests
        run: npx cypress run

medium

A. Cypress tests run automatically on push to main branch

B. Tests run only if manually triggered

C. Workflow fails due to missing trigger

D. Tests run on every branch push

Solution

1. Step 1: Analyze trigger event

   The workflow triggers on push to the main branch only.

2. Step 2: Understand job steps

   It checks out code and runs Cypress tests with npx cypress run.

3. Final Answer:

   Cypress tests run automatically on push to main branch -> Option A

4. Quick Check:

   Push to main triggers tests = C [OK]

Hint: Push to main triggers workflow with Cypress run [OK]

Common Mistakes:

• Assuming manual trigger needed
• Thinking tests run on all branches
• Believing workflow lacks trigger

4. You wrote this GitHub Actions workflow but Cypress tests never run:

on:
  push:
    branches:
      - main
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Run tests
        run: cypress run

What is the most likely error?

medium

A. Missing 'npx' before 'cypress run' command

B. Wrong branch name under 'push' event

C. Missing 'uses' for Cypress action

D. Incorrect 'runs-on' value

Solution

1. Step 1: Check Cypress run command syntax

   The command should be npx cypress run to run Cypress installed locally.

2. Step 2: Verify other parts

   Branch name 'main' is correct, 'runs-on' is valid, and Cypress action is optional if using CLI.

3. Final Answer:

   Missing 'npx' before 'cypress run' command -> Option A

4. Quick Check:

   Run command needs 'npx' prefix = B [OK]

Hint: Use 'npx cypress run' to execute tests in GitHub Actions [OK]

Common Mistakes:

• Running 'cypress run' without 'npx'
• Changing branch name incorrectly
• Expecting Cypress action is mandatory
• Misconfiguring runner OS

5. You want to run Cypress tests on both push and pull request events but only for the 'develop' branch. Which YAML snippet correctly configures this?

hard

A. on:
push:
branches:
- main
pull_request:
branches:
- main

B. on:
push:
branches:
- main
pull_request:
branches:
- develop

C. on:
push:
branches:
- develop
pull_request:
branches:
- develop

D. on:
push:
branches:
- develop
pull_request:
branches:
- main

Solution

1. Step 1: Identify required events and branches

   Tests must run on both push and pull_request events targeting the 'develop' branch only.

2. Step 2: Match YAML configuration

   on: push: branches: - develop pull_request: branches: - develop correctly lists both events with 'develop' branch under each.

3. Final Answer:

   on: push: branches: - develop pull_request: branches: - develop -> Option C

4. Quick Check:

   Both events on 'develop' branch = D [OK]

Hint: List both events with same branch under 'on' key [OK]

Common Mistakes:

• Mixing branch names between events
• Listing only one event
• Using wrong branch name