Cypress Cloud Runner

Run your JavaScript-based automation and testing scripts built with Cypress framework on the cloud. Automate and schedule your runs in Apify Console and connect them to other platforms and services to make your workflow even more efficient.

Features

• 🚀 Cloud Execution: Run Cypress tests on Apify's cloud infrastructure
• 📊 Multiple Browsers: Support for Chrome, Firefox, Edge, and Electron
• 📸 Artifact Collection: Automatically save videos and screenshots
• 🔄 Scheduled Runs: Schedule tests using Apify Console
• 🪝 Webhook Integration: Send notifications to Slack, Teams, or custom endpoints
• 📦 Monorepo Support: Run tests from subdirectories
• ⚙️ Flexible Configuration: Override Cypress config and environment variables
• 🧰 App Startup Support: Build and start your app before tests and wait for readiness

Quick Start

1. Basic Usage

{
  "gitUrl": "https://github.com/your-username/cypress-tests.git",
  "branch": "main",
  "testCommand": "npx cypress run",
  "browser": "chrome"
}

2. Advanced Configuration

{
  "gitUrl": "https://github.com/your-username/monorepo.git",
  "branch": "develop",
  "projectPath": "packages/e2e-tests",
  "installCommand": "npm ci",
  "testCommand": "npm run test:e2e",
  "browser": "firefox",
  "spec": "cypress/e2e/auth/*.cy.js",
  "env": {
    "CYPRESS_BASE_URL": "https://staging.example.com",
    "CYPRESS_API_KEY": "staging-key"
  },
  "config": {
    "baseUrl": "https://staging.example.com",
    "defaultCommandTimeout": 10000,
    "video": true,
    "screenshotOnRunFailure": true
  },
  "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
}

Input Parameters

Parameter	Type	Required	Description
gitUrl	string	✅	Git repository URL (HTTPS or SSH)
branch	string		Branch, tag, or commit (default: "main")
projectPath	string		Path to Cypress project within repo
installCommand	string		Command to install dependencies (default: "npm ci")
testCommand	string		Command to run tests (default: "npx cypress run")
browser	string		Browser: chrome, firefox, electron, edge (default: "electron")
spec	string		Specific spec pattern to run
env	object		Environment variables for Cypress
config	object		Cypress configuration overrides
saveArtifacts	boolean		Save videos/screenshots (default: true)
buildCommand	string		Command to build app before starting
startCommand	string		Command to start app server
startReadyUrl	string		Comma-separated URL(s) to wait for after start
startReadyTimeoutSecs	integer		Readiness timeout in seconds (default: 60)
gracefulShutdownSecs	integer		Graceful shutdown wait for server (default: 10)
killSignal	string		Signal to stop server (default: SIGTERM)
strictBaseUrlCheck	boolean		Fail fast if baseUrl is bad
webhookUrl	string		URL for test result notifications

Output

The actor provides comprehensive test results:

Dataset Output

Each run creates a dataset entry with:

• status: "passed", "failed", or "error"
• exitCode: Cypress exit code
• duration: Test execution time in milliseconds
• timestamp: ISO timestamp of test completion
• repository: Git repository URL
• branch: Git branch/tag used
• browser: Browser used for testing
• spec: Spec pattern executed
• output: Full Cypress console output
• artifacts: Links to saved videos/screenshots

Key-Value Store

Artifacts are saved in the Key-Value store:

• video_*.mp4: Test execution videos
• screenshot_*_*.png: Failure screenshots
• OUTPUT: Complete test results JSON

Scheduling Tests

Using Apify Console

1. Go to your actor in Apify Console
2. Click "Schedule" tab
3. Set your desired schedule (cron format)
4. Configure input parameters
5. Save the schedule

Example Schedules

• Daily at 2 AM: 0 2 * * *
• Every hour: 0 * * * *
• Weekdays at 9 AM: 0 9 * * 1-5

Webhook Integration

Slack Webhook

{
  "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
}

Custom Webhook Payload

{
  "text": "Cypress tests passed",
  "repository": "https://github.com/example/repo.git",
  "branch": "main",
  "status": "passed",
  "duration": "45s",
  "exitCode": 0
}

CI/CD Integration

GitHub Actions Example

name: Run E2E Tests on Apify

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM
  workflow_dispatch:

jobs:
  cypress-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Run Cypress on Apify
        uses: apify/actor-action@v2
        with:
          token: ${{ secrets.APIFY_TOKEN }}
          actor-id: your-actor-id
          input: |
            {
              "gitUrl": "${{ github.repository }}",
              "branch": "${{ github.ref_name }}",
              "browser": "chrome",
              "webhookUrl": "${{ secrets.SLACK_WEBHOOK }}"
            }

Supported Browsers

Browser	Description
chrome	Google Chrome (latest stable)
firefox	Mozilla Firefox (latest stable)
edge	Microsoft Edge (latest stable)
electron	Headless Electron (default, fastest)

Environment Variables

Common Cypress environment variables:

• CYPRESS_BASE_URL: Base URL for tests
• CYPRESS_API_KEY: API keys for testing
• CYPRESS_USERNAME: Test user credentials
• CYPRESS_PASSWORD: Test user passwords

Troubleshooting

Common Issues

Git Authentication

• Use HTTPS URLs with tokens: https://token@github.com/user/repo.git
• Or SSH with proper key setup

Dependency Installation

• For private packages, use .npmrc in your repository
• Consider using npm ci for faster, reproducible installs

Test Failures

• Check the output log for detailed error messages
• Download screenshots and videos from Key-Value store
• Verify environment variables and configuration

App server not ready

• Provide startCommand and a startReadyUrl that returns 2xx/3xx when ready (for example /healthz).
• Increase startReadyTimeoutSecs for slower cold starts.
• You can set strictBaseUrlCheck to fail fast if config.baseUrl is invalid.

Starting a Local App Before Tests

If your tests require a running app, configure the actor to build, start, and wait for readiness:

{
  "gitUrl": "https://github.com/your-username/app-repo.git",
  "branch": "main",
  "projectPath": ".",
  "installCommand": "npm ci",
  "buildCommand": "npm run build",
  "startCommand": "npm start",
  "startReadyUrl": "http://localhost:3000/healthz",
  "startReadyTimeoutSecs": 90,
  "config": { "baseUrl": "http://localhost:3000" },
  "browser": "chrome",
  "saveArtifacts": true
}

For static sites, you can serve a folder:

{
  "startCommand": "npx http-server dist -p 8080",
  "startReadyUrl": "http://localhost:8080",
  "config": { "baseUrl": "http://localhost:8080" }
}

Browser Issues

• Start with electron for fastest execution
• Use chrome for most realistic browser testing
• firefox and edge for cross-browser validation

Performance Tips

1. Use specific spec patterns to run only necessary tests
2. Disable video recording for faster execution if not needed
3. Use shallow git clones (automatically done)
4. Cache dependencies between runs when possible

Example Repositories

Test the actor with these example repositories:

1. Basic Cypress Tests: cypress-io/cypress-example-kitchensink
2. Real World App: cypress-io/cypress-realworld-app

Support

• 📧 Email: kontakt@barrierefix.de
• 🌐 Website: https://www.barrierefix.de/
• 📚 Cypress Documentation: https://docs.cypress.io/

License

MIT License - see package.json for details.