cypress-validate 1.0.0

package/lib/commands/info.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const { execa } = require('execa');
+const chalk = require('chalk');
+const { logger } = require('../utils/logger');
+const { findProjectRoot } = require('../utils/config-finder');
+
+module.exports = async function infoCommand() {
+    logger.title('Cypress Validate — Info');
+    logger.divider();
+
+    const projectRoot = findProjectRoot();
+
+    // Node & OS info
+    logger.step(`Node.js:  ${chalk.cyan(process.version)}`);
+    logger.step(`Platform: ${chalk.cyan(process.platform)} (${process.arch})`);
+    logger.step(`CWD:      ${chalk.cyan(projectRoot)}`);
+    logger.blank();
+
+    // Cypress version
+    logger.step('Fetching Cypress info...');
+    logger.blank();
+
+    try {
+        const result = await execa('npx', ['cypress', 'info'], {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            reject: false,
+        });
+
+        if (result.exitCode === 0) {
+            const lines = result.stdout.split('\n');
+            lines.forEach((line) => {
+                if (line.trim()) {
+                    if (line.includes('Cypress:')) {
+                        console.log('  ' + chalk.bold.cyan(line));
+                    } else if (line.includes('✔') || line.includes('✓')) {
+                        console.log('  ' + chalk.green(line));
+                    } else if (line.includes('✖') || line.includes('✗')) {
+                        console.log('  ' + chalk.red(line));
+                    } else {
+                        console.log('  ' + chalk.gray(line));
+                    }
+                }
+            });
+        } else {
+            logger.warn('Could not retrieve full Cypress info. Is Cypress installed?');
+            logger.info('Install with: ' + chalk.cyan('npx cypress-validate install'));
+        }
+    } catch (err) {
+        logger.error('Failed to run cypress info: ' + err.message);
+    }
+
+    logger.blank();
+    logger.divider();
+
+    // package.json cypress version
+    try {
+        const pkg = require(`${projectRoot}/package.json`);
+        const cyVersion =
+            (pkg.devDependencies && pkg.devDependencies.cypress) ||
+            (pkg.dependencies && pkg.dependencies.cypress) ||
+            'not found in package.json';
+        logger.info(`Cypress in package.json: ${chalk.cyan(cyVersion)}`);
+    } catch (_) { }
+
+    logger.blank();
+};

package/lib/commands/install.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const { execa } = require('execa');
+const { logger, createSpinner } = require('../utils/logger');
+const { findProjectRoot } = require('../utils/config-finder');
+const chalk = require('chalk');
+
+module.exports = async function installCommand(opts) {
+    logger.title('Cypress Validate — Install');
+    logger.divider();
+
+    const projectRoot = findProjectRoot();
+
+    // Build the npm install command
+    const versionSuffix = opts.version ? `@${opts.version}` : '';
+    const pkg = `cypress${versionSuffix}`;
+    const npmArgs = opts.global
+        ? ['install', '-g', pkg]
+        : ['install', '--save-dev', pkg];
+
+    if (!opts.force) {
+        // Check if cypress is already installed
+        try {
+            const { stdout } = await execa('node', ['-e', "require('cypress')"], {
+                cwd: projectRoot,
+                reject: false,
+            });
+            const spinner2 = createSpinner('Checking existing Cypress installation...');
+            spinner2.start();
+            const result = await execa('npx', ['cypress', 'version'], {
+                cwd: projectRoot,
+                reject: false,
+            });
+            spinner2.stop();
+            if (result.exitCode === 0) {
+                logger.success('Cypress is already installed: ' + chalk.cyan(result.stdout.trim()));
+                logger.info('Use ' + chalk.cyan('--force') + ' to reinstall, or ' + chalk.cyan('cypress-validate verify') + ' to verify the installation.');
+                return;
+            }
+        } catch (_) {
+            // not installed, continue
+        }
+    }
+
+    const spinner = createSpinner(`Installing ${chalk.cyan(pkg)}...`);
+    spinner.start();
+
+    try {
+        await execa('npm', npmArgs, {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        spinner.succeed(chalk.green(`Successfully installed ${pkg}`));
+    } catch (err) {
+        spinner.fail(chalk.red('Installation failed'));
+        logger.error(err.message);
+        process.exit(1);
+    }
+
+    // Run verify after install
+    logger.blank();
+    logger.step('Running ' + chalk.cyan('cypress verify') + ' ...');
+    const verifySpinner = createSpinner('Verifying Cypress...');
+    verifySpinner.start();
+    try {
+        const verifyResult = await execa('npx', ['cypress', 'verify'], {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        verifySpinner.succeed(chalk.green('Cypress verified successfully!'));
+        logger.blank();
+        logger.info(verifyResult.stdout);
+    } catch (err) {
+        verifySpinner.fail('Cypress verification failed');
+        logger.error(err.stderr || err.message);
+        process.exit(1);
+    }
+};

package/lib/commands/open.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const { execa } = require('execa');
+const path = require('path');
+const { logger } = require('../utils/logger');
+const { findProjectRoot } = require('../utils/config-finder');
+const chalk = require('chalk');
+
+module.exports = async function openCommand(opts) {
+    const projectRoot = findProjectRoot();
+
+    logger.title('Cypress Validate — Open (Interactive Test Runner)');
+    logger.divider();
+    logger.step(`Mode:     ${chalk.cyan('Interactive / GUI')}`);
+    if (opts.browser) logger.step(`Browser:  ${chalk.cyan(opts.browser)}`);
+    if (opts.spec) logger.step(`Spec:     ${chalk.cyan(opts.spec)}`);
+    logger.divider();
+    logger.blank();
+
+    const args = ['open'];
+    if (opts.browser) args.push('--browser', opts.browser);
+    if (opts.spec) args.push('--spec', opts.spec);
+    if (opts.config) args.push('--config', opts.config);
+    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, {
+            cwd: projectRoot,
+            stdio: 'inherit',
+        });
+    } catch (err) {
+        if (err.exitCode !== undefined) {
+            logger.error(`Cypress exited with code ${err.exitCode}`);
+        } else {
+            logger.error('Failed to open Cypress: ' + err.message);
+            logger.warn('Make sure Cypress is installed: ' + chalk.cyan('npx cypress-validate install'));
+        }
+        process.exit(err.exitCode || 1);
+    }
+};

package/lib/commands/record.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { execa } = require('execa');
+const path = require('path');
+const chalk = require('chalk');
+const { logger } = require('../utils/logger');
+const { findProjectRoot } = require('../utils/config-finder');
+
+module.exports = async function recordCommand(opts) {
+    logger.title('Cypress Validate — Record');
+    logger.divider();
+
+    const projectRoot = findProjectRoot();
+
+    const recordKey = opts.key || process.env.CYPRESS_RECORD_KEY;
+    if (!recordKey) {
+        logger.error('No Cypress Cloud record key found!');
+        logger.info('Provide it via:');
+        logger.step(chalk.cyan('--key <CYPRESS_RECORD_KEY>'));
+        logger.step('or set env var: ' + chalk.cyan('CYPRESS_RECORD_KEY=<key>'));
+        logger.blank();
+        logger.info('Sign up at: ' + chalk.cyan('https://cloud.cypress.io'));
+        process.exit(1);
+    }
+
+    const args = ['run', '--record', '--key', recordKey];
+
+    if (opts.spec) args.push('--spec', opts.spec);
+    if (opts.browser) args.push('--browser', opts.browser);
+    if (opts.tag) args.push('--tag', opts.tag);
+    if (opts.group) args.push('--group', opts.group);
+    if (opts.parallel) args.push('--parallel');
+    if (opts.ciBuildId) args.push('--ci-build-id', opts.ciBuildId);
+
+    logger.step(`Browser:  ${chalk.cyan(opts.browser || 'electron')}`);
+    if (opts.spec) logger.step(`Spec:     ${chalk.cyan(opts.spec)}`);
+    if (opts.group) logger.step(`Group:    ${chalk.cyan(opts.group)}`);
+    if (opts.parallel) logger.step(`Parallel: ${chalk.cyan('enabled')}`);
+    logger.step(`Key:      ${chalk.cyan('*'.repeat(Math.min(8, recordKey.length)) + '...')}`);
+    logger.divider();
+    logger.blank();
+
+    const cypressBin = path.join(projectRoot, 'node_modules', '.bin', 'cypress');
+
+    try {
+        await execa(cypressBin, args, {
+            cwd: projectRoot,
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                CYPRESS_RECORD_KEY: recordKey,
+            },
+        });
+        logger.blank();
+        logger.success('Run recorded successfully to Cypress Cloud!');
+    } catch (err) {
+        logger.blank();
+        logger.error(`Recording exited with code ${err.exitCode || 1}`);
+        logger.info('View your run at: ' + chalk.cyan('https://cloud.cypress.io'));
+        process.exit(err.exitCode || 1);
+    }
+};

package/lib/commands/run.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const { execa } = require('execa');
+const chalk = require('chalk');
+const fs = require('fs-extra');
+const path = require('path');
+const { logger } = require('../utils/logger');
+const { findProjectRoot, lastRunResultsPath } = require('../utils/config-finder');
+
+/**
+ * Build the cypress run argument list from CLI options
+ */
+function buildArgs(opts) {
+    const args = ['run'];
+
+    if (opts.spec) args.push('--spec', opts.spec);
+    if (opts.browser) args.push('--browser', opts.browser);
+    if (opts.headed) args.push('--headed');
+    if (opts.grep) args.push('--env', `grep=${opts.grep}`);
+    if (opts.config) args.push('--config', opts.config);
+    if (opts.env) args.push('--env', opts.env);
+    if (opts.port) args.push('--port', opts.port);
+    if (opts.record) args.push('--record');
+    if (opts.key) args.push('--key', opts.key);
+    if (opts.tag) args.push('--tag', opts.tag);
+    if (opts.forbidOnly) args.push('--config', 'forbidOnly=true');
+
+    // Reporter
+    if (opts.reporter && opts.reporter !== 'spec') {
+        args.push('--reporter', opts.reporter);
+        if (opts.reporter === 'mochawesome') {
+            args.push('--reporter-options',
+                'reportDir=cypress/reports,overwrite=false,html=true,json=true');
+        }
+    }
+
+    return args;
+}
+
+/**
+ * Load specs that failed in the last run
+ */
+async function getLastFailedSpecs(projectRoot) {
+    const resultsFile = lastRunResultsPath(projectRoot);
+    if (!await fs.pathExists(resultsFile)) {
+        logger.warn('No previous run results found. Running all tests.');
+        return null;
+    }
+    const data = await fs.readJson(resultsFile);
+    if (!data.failedSpecs || data.failedSpecs.length === 0) {
+        logger.success('No failed specs from last run. Nothing to re-run!');
+        process.exit(0);
+    }
+    logger.info(`Re-running ${data.failedSpecs.length} failed spec(s):`);
+    data.failedSpecs.forEach((s) => logger.step(s));
+    return data.failedSpecs.join(',');
+}
+
+/**
+ * Save results summary for --last-failed support
+ */
+async function saveRunResults(projectRoot, exitCode, specPattern) {
+    const resultsDir = path.join(projectRoot, '.cypress-validate');
+    await fs.ensureDir(resultsDir);
+    const resultsFile = lastRunResultsPath(projectRoot);
+
+    // Try to parse mochawesome/junit JSON to extract failed specs
+    const failedSpecs = exitCode !== 0 && specPattern ? [specPattern] : [];
+
+    await fs.writeJson(resultsFile, {
+        timestamp: new Date().toISOString(),
+        exitCode,
+        failedSpecs,
+    }, { spaces: 2 });
+}
+
+module.exports = async function runCommand(opts) {
+    const projectRoot = findProjectRoot();
+
+    logger.title('Cypress Validate — Run');
+    logger.divider();
+
+    // Resolve --last-failed
+    if (opts.lastFailed) {
+        const failed = await getLastFailedSpecs(projectRoot);
+        if (failed) opts.spec = failed;
+    }
+
+    // Build args
+    const args = buildArgs(opts);
+
+    // Handle retry
+    const retryCount = parseInt(opts.retry || '0', 10);
+    if (retryCount > 0) {
+        args.push('--config', `retries=${retryCount}`);
+    }
+
+    // Show summary before running
+    logger.step(`Browser:  ${chalk.cyan(opts.browser || 'electron')}`);
+    if (opts.spec) logger.step(`Spec:     ${chalk.cyan(opts.spec)}`);
+    if (opts.grep) logger.step(`Grep:     ${chalk.cyan(opts.grep)}`);
+    if (opts.headed) logger.step(`Mode:     ${chalk.cyan('headed')}`);
+    else logger.step(`Mode:     ${chalk.cyan('headless (default)')}`);
+    if (retryCount) logger.step(`Retries:  ${chalk.cyan(retryCount)}`);
+    logger.divider();
+    logger.blank();
+
+    // Resolve cypress binary
+    const cypressBin = path.join(projectRoot, 'node_modules', '.bin', 'cypress');
+
+    try {
+        const proc = execa(cypressBin, args, {
+            cwd: projectRoot,
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                CYPRESS_RECORD_KEY: opts.key || process.env.CYPRESS_RECORD_KEY,
+            },
+        });
+
+        const result = await proc;
+        await saveRunResults(projectRoot, result.exitCode, opts.spec);
+        logger.blank();
+        logger.success(chalk.green('All tests passed!'));
+        process.exit(0);
+    } catch (err) {
+        await saveRunResults(projectRoot, err.exitCode || 1, opts.spec);
+        logger.blank();
+        if (err.exitCode !== undefined) {
+            logger.error(`Tests completed with exit code ${err.exitCode}`);
+            logger.info('Run ' + chalk.cyan('cypress-validate show-report') + ' to view the HTML report.');
+        } else {
+            logger.error('Failed to run Cypress: ' + err.message);
+            logger.warn('Make sure Cypress is installed: ' + chalk.cyan('npx cypress-validate install'));
+        }
+        process.exit(err.exitCode || 1);
+    }
+};

package/lib/commands/screenshot.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const { execa } = require('execa');
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const chalk = require('chalk');
+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();
+
+    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;
+    }
+
+    // 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 tempSpec = path.join(specsDir, '__screenshot__.cy.js');
+    const specContent = `
+/// <reference types="cypress" />
+describe('cypress-validate screenshot', () => {
+  it('captures a screenshot of ${opts.url}', () => {
+    cy.viewport(${viewportWidth}, ${viewportHeight});
+    cy.visit(${JSON.stringify(opts.url)});
+    cy.screenshot('screenshot', {
+      capture: ${opts.fullPage ? "'fullPage'" : "'viewport'"},
+    });
+  });
+});
+`;
+    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, `
+const { defineConfig } = require('cypress');
+module.exports = defineConfig({
+  e2e: {
+    supportFile: false,
+    screenshotsFolder: ${JSON.stringify(screenshotDir)},
+    video: false,
+  },
+});
+`, 'utf-8');
+
+    const spinner = createSpinner('Taking screenshot...');
+    spinner.start();
+
+    const cypressBin = path.join(projectRoot, 'node_modules', '.bin', 'cypress');
+
+    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
+        const generatedScreenshot = path.join(screenshotDir, 'cypress-validate screenshot', 'screenshot.png');
+        if (await fs.pathExists(generatedScreenshot)) {
+            await fs.move(generatedScreenshot, outputAbs, { overwrite: true });
+        }
+
+        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(() => { });
+    }
+
+    logger.blank();
+};

package/lib/commands/show-report.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const open = require('open');
+const { logger, createSpinner } = require('../utils/logger');
+const { findProjectRoot } = require('../utils/config-finder');
+
+/**
+ * Recursively find HTML report files inside a directory
+ */
+async function findHtmlReports(dir) {
+    const reports = [];
+    if (!await fs.pathExists(dir)) return reports;
+    const stat = await fs.stat(dir);
+    if (stat.isFile() && dir.endsWith('.html')) return [dir];
+
+    const walk = async (d) => {
+        const entries = await fs.readdir(d, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(d, entry.name);
+            if (entry.isDirectory()) await walk(full);
+            else if (entry.isFile() && entry.name.endsWith('.html')) reports.push(full);
+        }
+    };
+    await walk(dir);
+    return reports;
+}
+
+module.exports = async function showReportCommand(opts) {
+    logger.title('Cypress Validate — Show Report');
+    logger.divider();
+
+    const projectRoot = findProjectRoot();
+    const reportRoot = path.resolve(process.cwd(), opts.path || 'cypress/reports');
+
+    // If --serve, start a local HTTP server
+    if (opts.serve) {
+        const port = opts.port || '9323';
+        logger.step(`Serving report from: ${chalk.cyan(reportRoot)}`);
+        logger.step(`Port: ${chalk.cyan(port)}`);
+        logger.blank();
+        try {
+            const { execa } = require('execa');
+            logger.info(`Open: ${chalk.cyan(`http://localhost:${port}`)}`);
+            logger.blank();
+            await execa('npx', ['serve', '-p', port, reportRoot], {
+                cwd: projectRoot,
+                stdio: 'inherit',
+            });
+        } catch (err) {
+            if (err.exitCode !== undefined && err.exitCode !== 1) {
+                logger.error(`Server exited: ${err.message}`);
+                process.exit(1);
+            }
+        }
+        return;
+    }
+
+    // Otherwise, locate the HTML report and open it
+    const spinner = createSpinner('Looking for HTML report...');
+    spinner.start();
+
+    const reports = await findHtmlReports(reportRoot);
+
+    if (reports.length === 0) {
+        spinner.fail(chalk.red('No HTML report found'));
+        logger.blank();
+        logger.warn(`Searched in: ${chalk.cyan(reportRoot)}`);
+        logger.info('Generate a report by running:');
+        logger.step(chalk.cyan('npx cypress-validate run --reporter mochawesome'));
+        process.exit(1);
+    }
+
+    // Sort by modification time — open the most recent
+    const sorted = await Promise.all(
+        reports.map(async (f) => ({ file: f, mtime: (await fs.stat(f)).mtimeMs }))
+    );
+    sorted.sort((a, b) => b.mtime - a.mtime);
+    const reportFile = sorted[0].file;
+
+    spinner.succeed(chalk.green(`Found: ${path.relative(process.cwd(), reportFile)}`));
+    logger.blank();
+    logger.step(`Opening: ${chalk.cyan(reportFile)}`);
+    logger.blank();
+
+    if (reports.length > 1) {
+        logger.info(`${chalk.gray(`(${reports.length} reports found — opening the most recent)`)}`);
+        logger.blank();
+    }
+
+    await open(reportFile);
+    logger.success('Report opened in your default browser!');
+    logger.blank();
+};

package/lib/commands/verify.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const { execa } = require('execa');
+const { logger, createSpinner } = require('../utils/logger');
+const { findProjectRoot } = require('../utils/config-finder');
+const chalk = require('chalk');
+
+module.exports = async function verifyCommand(opts) {
+    logger.title('Cypress Validate — Verify');
+    logger.divider();
+
+    const projectRoot = findProjectRoot();
+
+    const args = ['cypress', 'verify'];
+    if (opts.force) args.push('--force');
+
+    const spinner = createSpinner('Verifying Cypress installation...');
+    spinner.start();
+
+    try {
+        const result = await execa('npx', args, {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            reject: false,
+        });
+
+        if (result.exitCode === 0) {
+            spinner.succeed(chalk.green('Cypress is installed and verified!'));
+            logger.blank();
+            const lines = result.stdout.split('\n').filter(Boolean);
+            lines.forEach((line) => logger.info(line));
+        } else {
+            spinner.fail(chalk.red('Cypress verification failed'));
+            logger.blank();
+            logger.error(result.stderr || result.stdout || 'Unknown error');
+            logger.warn('Try running: ' + chalk.cyan('npx cypress-validate install'));
+            process.exit(1);
+        }
+    } catch (err) {
+        spinner.fail('Could not run cypress verify');
+        logger.error(err.message);
+        logger.warn('Is Cypress installed? Run: ' + chalk.cyan('npx cypress-validate install'));
+        process.exit(1);
+    }
+};

package/lib/index.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * cypress-validate — Programmatic API
+ * Allows using cypress-validate commands as a Node.js library.
+ *
+ * @example
+ * const { run, open, info } = require('cypress-validate');
+ * await run({ browser: 'chrome', headed: true });
+ */
+module.exports = {
+    run: require('./commands/run'),
+    open: require('./commands/open'),
+    install: require('./commands/install'),
+    verify: require('./commands/verify'),
+    info: require('./commands/info'),
+    generate: require('./commands/generate'),
+    screenshot: require('./commands/screenshot'),
+    showReport: require('./commands/show-report'),
+    record: require('./commands/record'),
+};