cypress-validate

A Playwright-style CLI for Cypress projects — run, open, generate, screenshot, report and more with a single unified command.

🚀 Step-by-Step Guide

1. Installation

In your existing Cypress project, install cypress-validate as a dev dependency:

npm install --save-dev cypress-validate

2. Scaffold Your First Test

Scaffold a new spec file:

npx cypress-validate generate --name login --type spec

This creates cypress/e2e/login.cy.js using your project's baseUrl.

3. Run Your Tests

Run all tests headlessly with a simple command:

npx cypress-validate run

4. Debug in UI Mode

Open the interactive Test Runner to debug failure:

npx cypress-validate open --spec cypress/e2e/login.cy.js

5. View the Report

After a run finishes, view the HTML results instantly:

npx cypress-validate show-report

️ Troubleshooting

Peer Dependency Conflicts (ERESOLVE)

If you see an ERESOLVE could not resolve error during installation, it is usually because another plugin in your project (like @4tw/cypress-drag-drop) has a strict peer dependency on an older version of Cypress (e.g., < 14), while you are using a newer version.

To bypass this and install cypress-validate, use:

npm install --save-dev cypress-validate --legacy-peer-deps

📋 Command Reference

run — Run tests headlessly (like npx playwright test)

npx cypress-validate run [options]

| Flag | Playwright Equivalent | Description | |---|---|---| | --spec <pattern> | playwright test file.spec.ts | Spec file(s) to run | | --browser <name> | --project=chromium | Browser: chrome, firefox, edge, electron | | --headed | --headed | Run with visible browser window | | --grep <pattern> | --grep "pattern" | Filter tests by title/pattern | | --workers <n> | --workers=4 | Parallel worker count (Cypress Cloud) | | --timeout <ms> | --timeout=10000 | Default timeout per test | | --retry <count> | --retries=2 | Number of retries on failure | | --reporter <name> | --reporter=html | Reporter: spec, mochawesome, json, junit | | --last-failed | --last-failed | Re-run only specs that failed last time | | --forbid-only | --forbid-only | Fail if .only() is used in any test | | --record | (cloud) | Record run to Cypress Cloud | | --key <key> | (cloud) | Cypress Cloud record key | | --env <k=v> | (env vars) | Set Cypress environment variables | | --config <json> | (config override) | Override cypress.config.js values |

Examples:

# Run all tests
npx cypress-validate run

# Run specific spec file
npx cypress-validate run --spec cypress/e2e/login.cy.js

# Run in Chrome, headed, retry twice
npx cypress-validate run --browser chrome --headed --retry 2

# Filter tests by name
npx cypress-validate run --grep "should login"

# Run with HTML report
npx cypress-validate run --reporter mochawesome

# Re-run only failed tests from last run
npx cypress-validate run --last-failed

# Run all tests and forbid .only()
npx cypress-validate run --forbid-only

open — Interactive Test Runner (like npx playwright test --ui)

npx cypress-validate open [options]

| Flag | Description | |---|---| | --browser <name> | Browser to open | | --spec <pattern> | Open directly to a specific spec |

npx cypress-validate open
npx cypress-validate open --browser chrome
npx cypress-validate open --spec cypress/e2e/login.cy.js

install — Install Cypress (like npx playwright install)

npx cypress-validate install [options]

| Flag | Description | |---|---| | --version <ver> | Install a specific Cypress version | | --global | Install globally (-g) | | --force | Force reinstall even if already installed |

npx cypress-validate install
npx cypress-validate install --version 13.6.0
npx cypress-validate install --force

verify — Verify installation (like npx playwright install --verify)

npx cypress-validate verify [--force]

info — Print system info (like npx playwright --version + system info)

npx cypress-validate info

Displays: Node.js version, OS, Cypress version, available browsers.

generate — Scaffold Files (like npx playwright codegen)

Scaffold tests, fixtures, page objects, or custom commands interactively.

npx cypress-validate generate                     # Interactive mode
npx cypress-validate generate --name login --type spec

| Flag | Description | |---|---| | --name <name> | File name (without extension) | | --type <type> | spec | fixture | command | page | | --url <url> | Base URL to include in the spec | | --typescript | Generate .cy.ts TypeScript files | | --dir <dir> | Custom output directory |

Generated file types:

| Type | Output path | |---|---| | spec | cypress/e2e/<name>.cy.js | | fixture | cypress/fixtures/<name>.json | | command | cypress/support/commands/<name>.js | | page | cypress/pages/<name>.page.js |

screenshot — Capture URL (like npx playwright screenshot)

Captures a headless screenshot of a URL.

npx cypress-validate screenshot                   # Defaults to project baseUrl
npx cypress-validate screenshot --url https://google.com
npx cypress-validate screenshot --full-page --viewport 1920x1080

show-report — Open HTML report (like npx playwright show-report)

Opens the latest Mochawesome HTML report.

npx cypress-validate show-report
npx cypress-validate show-report --serve  # Serve on local HTTP server

show-trace — Open Trace Viewer (like npx playwright show-trace)

Opens the interactive Cypress Test Runner for the last failed spec, allowing for time-travel debugging.

npx cypress-validate show-trace

record — Record to Cypress Cloud

npx cypress-validate record [options]

| Flag | Description | |---|---| | --key <key> | Record key (or set CYPRESS_RECORD_KEY env) | | --spec <pattern> | Spec pattern | | --browser <name> | Browser to use | | --tag <tags> | Run tags | | --group <name> | Group name | | --parallel | Enable parallel recording | | --ci-build-id <id> | CI build ID for grouping |

npx cypress-validate record --key abc123
CYPRESS_RECORD_KEY=abc123 npx cypress-validate record --parallel --group "CI Run"

🧪 Full Playwright → cypress-validate Mapping

| Playwright CLI | cypress-validate | |---|---| | npx playwright test | npx cypress-validate run | | npx playwright test file.spec.ts | npx cypress-validate run --spec cypress/e2e/file.cy.js | | npx playwright test --headed | npx cypress-validate run --headed | | npx playwright test --project=chromium | npx cypress-validate run --browser chrome | | npx playwright test --grep "pattern" | npx cypress-validate run --grep "pattern" | | npx playwright test --workers=4 | npx cypress-validate run --workers 4 | | npx playwright test --timeout=5000 | npx cypress-validate run --timeout 5000 | | npx playwright test --retries=2 | npx cypress-validate run --retry 2 | | npx playwright test --reporter=html | npx cypress-validate run --reporter mochawesome | | npx playwright test --last-failed | npx cypress-validate run --last-failed | | npx playwright test --forbid-only | npx cypress-validate run --forbid-only | | npx playwright test --ui | npx cypress-validate open | | npx playwright test --debug | npx cypress-validate open --spec <file> | | npx playwright install | npx cypress-validate install | | npx playwright show-report | npx cypress-validate show-report | Open HTML test report | | npx playwright show-trace | npx cypress-validate show-trace | New: Open interactive trace for failed spec | | npx playwright screenshot [url] | npx cypress-validate screenshot | Take a screenshot (optional URL) | | npx playwright codegen | npx cypress-validate generate | Scaffold tests/fixtures/pages | | npx playwright info | npx cypress-validate info | | npx playwright --version | npx cypress-validate --version |

⚙️ Programmatic API

const { run, open, info, generate } = require('cypress-validate');

// Run tests programmatically
await run({ browser: 'chrome', headed: true, spec: 'cypress/e2e/login.cy.js' });

// Open interactive runner
await open({ browser: 'firefox' });

// Generate a spec file
await generate({ name: 'dashboard', type: 'spec', url: 'http://localhost:3000' });

📦 Publishing to npm

# Login to npm
npm login

# Publish publicly
npm publish --access public

🤝 Contributing

Issues and PRs welcome at github.com/mvsaran/cypress-validate.

📄 License

MIT © 2026 cypress-validate contributors