cypress-validate 1.0.0 → 1.0.2

package/README.md

@@ -8,20 +8,60 @@
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Step-by-Step Guide
+
+### 1. Installation
+In your existing Cypress project, install `cypress-validate` as a dev dependency:
+
+```bash
+npm install --save-dev cypress-validate
+```
+
+### 2. Scaffold Your First Test
+Generate a new spec file using the `generate` command (like `codegen`):
+
+```bash
+npx cypress-validate generate --name login --type spec --url http://localhost:3000
+```
+*This creates `cypress/e2e/login.cy.js` with a boilerplate test.*
+
+### 3. Run Your Tests
+Execute your tests in headless mode with a simple command:
+
+```bash
+npx cypress-validate run
+```
+
+### 4. Debug in UI Mode
+Open the interactive Test Runner to debug failure:
 
 ```bash
-# Run once without installing
-npx cypress-validate --help
+npx cypress-validate open --spec cypress/e2e/login.cy.js
+```
+
+### 5. View the Report
+After a run finishes, view the HTML results instantly:
+
+```bash
+npx cypress-validate show-report
+```
+
+---
+
+## �️ Troubleshooting
 
-# Or install globally
-npm install -g cypress-validate
-cypress-validate --help
+### 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:
+
+```bash
+npm install --save-dev cypress-validate --legacy-peer-deps
 ```
 
 ---
 
-## 📋 Command Reference
+## �📋 Command Reference
 
 ### `run` — Run tests headlessly *(like `npx playwright test`)*
 

package/bin/cypress-validate.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 'use strict';
 
 const { Command } = require('commander');

package/lib/commands/info.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { execa } = require('execa');
+const execa = require('execa');
 const chalk = require('chalk');
 const { logger } = require('../utils/logger');
 const { findProjectRoot } = require('../utils/config-finder');

package/lib/commands/install.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { execa } = require('execa');
+const execa = require('execa');
 const { logger, createSpinner } = require('../utils/logger');
 const { findProjectRoot } = require('../utils/config-finder');
 const chalk = require('chalk');

package/lib/commands/open.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { execa } = require('execa');
+const execa = require('execa');
 const path = require('path');
 const { logger } = require('../utils/logger');
 const { findProjectRoot } = require('../utils/config-finder');
@@ -24,10 +24,8 @@ module.exports = async function openCommand(opts) {
     if (opts.env) args.push('--env', opts.env);
     if (opts.port) args.push('--port', opts.port);
 
-    const cypressBin = path.join(projectRoot, 'node_modules', '.bin', 'cypress');
-
     try {
-        await execa(cypressBin, args, {
+        await execa('npx', ['cypress', ...args], {
             cwd: projectRoot,
             stdio: 'inherit',
         });

package/lib/commands/record.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { execa } = require('execa');
+const execa = require('execa');
 const path = require('path');
 const chalk = require('chalk');
 const { logger } = require('../utils/logger');
@@ -40,10 +40,8 @@ module.exports = async function recordCommand(opts) {
     logger.divider();
     logger.blank();
 
-    const cypressBin = path.join(projectRoot, 'node_modules', '.bin', 'cypress');
-
     try {
-        await execa(cypressBin, args, {
+        await execa('npx', ['cypress', ...args], {
             cwd: projectRoot,
             stdio: 'inherit',
             env: {

package/lib/commands/run.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { execa } = require('execa');
+const execa = require('execa');
 const chalk = require('chalk');
 const fs = require('fs-extra');
 const path = require('path');
@@ -105,11 +105,8 @@ module.exports = async function runCommand(opts) {
     logger.divider();
     logger.blank();
 
-    // Resolve cypress binary
-    const cypressBin = path.join(projectRoot, 'node_modules', '.bin', 'cypress');
-
     try {
-        const proc = execa(cypressBin, args, {
+        const proc = execa('npx', ['cypress', ...args], {
             cwd: projectRoot,
             stdio: 'inherit',
             env: {

package/lib/commands/screenshot.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { execa } = require('execa');
+const execa = require('execa');
 const fs = require('fs-extra');
 const path = require('path');
 const os = require('os');
@@ -9,37 +9,37 @@ const { logger, createSpinner } = require('../utils/logger');
 const { findProjectRoot } = require('../utils/config-finder');
 
 module.exports = async function screenshotCommand(opts) {
-    logger.title('Cypress Validate — Screenshot');
-    logger.divider();
-    logger.step(`URL:      ${chalk.cyan(opts.url)}`);
-    logger.step(`Output:   ${chalk.cyan(opts.output)}`);
-    logger.step(`Browser:  ${chalk.cyan(opts.browser)}`);
-    if (opts.fullPage) logger.step('Full-page: enabled');
-    logger.divider();
-    logger.blank();
+  logger.title('Cypress Validate — Screenshot');
+  logger.divider();
+  logger.step(`URL:      ${chalk.cyan(opts.url)}`);
+  logger.step(`Output:   ${chalk.cyan(opts.output)}`);
+  logger.step(`Browser:  ${chalk.cyan(opts.browser)}`);
+  if (opts.fullPage) logger.step('Full-page: enabled');
+  logger.divider();
+  logger.blank();
 
-    const projectRoot = findProjectRoot();
+  const projectRoot = findProjectRoot();
 
-    // Parse viewport
-    let viewportWidth = 1280;
-    let viewportHeight = 720;
-    if (opts.viewport) {
-        const parts = opts.viewport.split('x');
-        viewportWidth = parseInt(parts[0], 10) || 1280;
-        viewportHeight = parseInt(parts[1], 10) || 720;
-    }
+  // Parse viewport
+  let viewportWidth = 1280;
+  let viewportHeight = 720;
+  if (opts.viewport) {
+    const parts = opts.viewport.split('x');
+    viewportWidth = parseInt(parts[0], 10) || 1280;
+    viewportHeight = parseInt(parts[1], 10) || 720;
+  }
 
-    // Build a temporary spec file
-    const tmpDir = path.join(os.tmpdir(), 'cypress-validate-screenshot');
-    await fs.ensureDir(tmpDir);
-    const specsDir = path.join(tmpDir, 'cypress', 'e2e');
-    await fs.ensureDir(specsDir);
+  // Build a temporary spec file
+  const tmpDir = path.join(os.tmpdir(), 'cypress-validate-screenshot');
+  await fs.ensureDir(tmpDir);
+  const specsDir = path.join(tmpDir, 'cypress', 'e2e');
+  await fs.ensureDir(specsDir);
 
-    const outputAbs = path.resolve(process.cwd(), opts.output);
-    await fs.ensureDir(path.dirname(outputAbs));
+  const outputAbs = path.resolve(process.cwd(), opts.output);
+  await fs.ensureDir(path.dirname(outputAbs));
 
-    const tempSpec = path.join(specsDir, '__screenshot__.cy.js');
-    const specContent = `
+  const tempSpec = path.join(specsDir, '__screenshot__.cy.js');
+  const specContent = `
 /// <reference types="cypress" />
 describe('cypress-validate screenshot', () => {
   it('captures a screenshot of ${opts.url}', () => {
@@ -51,12 +51,12 @@ describe('cypress-validate screenshot', () => {
   });
 });
 `;
-    await fs.writeFile(tempSpec, specContent, 'utf-8');
+  await fs.writeFile(tempSpec, specContent, 'utf-8');
 
-    // Write a temporary cypress config
-    const tmpConfigPath = path.join(tmpDir, 'cypress.config.js');
-    const screenshotDir = path.dirname(outputAbs);
-    await fs.writeFile(tmpConfigPath, `
+  // Write a temporary cypress config
+  const tmpConfigPath = path.join(tmpDir, 'cypress.config.js');
+  const screenshotDir = path.dirname(outputAbs);
+  await fs.writeFile(tmpConfigPath, `
 const { defineConfig } = require('cypress');
 module.exports = defineConfig({
   e2e: {
@@ -67,40 +67,54 @@ module.exports = defineConfig({
 });
 `, 'utf-8');
 
-    const spinner = createSpinner('Taking screenshot...');
-    spinner.start();
+  const spinner = createSpinner('Taking screenshot...');
+  spinner.start();
 
-    const cypressBin = path.join(projectRoot, 'node_modules', '.bin', 'cypress');
+  try {
+    await execa('npx', [
+      'cypress',
+      'run',
+      '--spec', tempSpec,
+      '--config-file', tmpConfigPath,
+      '--browser', opts.browser,
+      '--headless',
+    ], {
+      cwd: tmpDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
 
-    try {
-        await execa(cypressBin, [
-            'run',
-            '--spec', tempSpec,
-            '--config-file', tmpConfigPath,
-            '--browser', opts.browser,
-            '--headless',
-        ], {
-            cwd: tmpDir,
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
+    // Move screenshot to intended output location
+    // Cypress structure: screenshotsFolder/SpecName/SnapshotName.png
+    const possiblePaths = [
+      path.join(screenshotDir, 'cypress-validate screenshot', 'screenshot.png'),
+      path.join(screenshotDir, '__screenshot__.cy.js', 'screenshot.png'),
+    ];
 
-        // Move screenshot to intended output location
-        const generatedScreenshot = path.join(screenshotDir, 'cypress-validate screenshot', 'screenshot.png');
-        if (await fs.pathExists(generatedScreenshot)) {
-            await fs.move(generatedScreenshot, outputAbs, { overwrite: true });
-        }
+    let moved = false;
+    for (const p of possiblePaths) {
+      if (await fs.pathExists(p)) {
+        await fs.move(p, outputAbs, { overwrite: true });
+        moved = true;
+        break;
+      }
+    }
 
-        spinner.succeed(chalk.green('Screenshot saved!'));
-        logger.blank();
-        logger.info(`File: ${chalk.cyan(outputAbs)}`);
-    } catch (err) {
-        spinner.fail(chalk.red('Screenshot failed'));
-        logger.error(err.message);
-        logger.warn('Ensure Cypress is installed: ' + chalk.cyan('npx cypress-validate install'));
-        process.exit(1);
-    } finally {
-        await fs.remove(tmpDir).catch(() => { });
+    if (moved) {
+      spinner.succeed(chalk.green('Screenshot saved!'));
+      logger.blank();
+      logger.info(`File: ${chalk.cyan(outputAbs)}`);
+    } else {
+      spinner.fail(chalk.red('Screenshot captured but could not be located'));
+      logger.warn(`Checked: ${possiblePaths.join(', ')}`);
     }
+  } catch (err) {
+    spinner.fail(chalk.red('Screenshot failed'));
+    logger.error(err.message);
+    logger.warn('Ensure Cypress is installed: ' + chalk.cyan('npx cypress-validate install'));
+    process.exit(1);
+  } finally {
+    await fs.remove(tmpDir).catch(() => { });
+  }
 
-    logger.blank();
+  logger.blank();
 };

package/lib/commands/show-report.js

@@ -42,7 +42,7 @@ module.exports = async function showReportCommand(opts) {
         logger.step(`Port: ${chalk.cyan(port)}`);
         logger.blank();
         try {
-            const { execa } = require('execa');
+            const execa = require('execa');
             logger.info(`Open: ${chalk.cyan(`http://localhost:${port}`)}`);
             logger.blank();
             await execa('npx', ['serve', '-p', port, reportRoot], {

package/lib/commands/verify.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { execa } = require('execa');
+const execa = require('execa');
 const { logger, createSpinner } = require('../utils/logger');
 const { findProjectRoot } = require('../utils/config-finder');
 const chalk = require('chalk');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress-validate",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A Playwright-style CLI for Cypress — run, open, generate, screenshot, report and more via npx cypress-validate",
   "main": "lib/index.js",
   "bin": {
@@ -61,5 +61,11 @@
   },
   "bugs": {
     "url": "https://github.com/mvsaran/cypress-validate/issues"
+  },
+  "devDependencies": {
+    "cypress": "^15.10.0",
+    "mochawesome": "^7.1.4",
+    "mochawesome-merge": "^5.1.1",
+    "mochawesome-report-generator": "^6.3.2"
   }
-}
+}