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.