@vardot/varbase-e2e 2.0.0

package/bin/generate-reports.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const reporter = require('cucumber-html-reporter');
+
+const THEMES = new Set(['bootstrap', 'hierarchy', 'foundation', 'simple']);
+const FORMATS = new Set(['html', 'pdf', 'all']);
+const PDF_FORMATS = new Set(['Letter', 'Legal', 'Tabloid', 'Ledger', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6']);
+
+function capitalize(s) {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    metadata: {},
+    scenarioTimestamp: true,
+    reportSuiteAsScenarios: true,
+    failedSummaryReport: true,
+    launchReport: false,
+    noInlineScreenshots: false,
+    storeScreenshots: false,
+    ignoreBadJsonFile: false,
+    formats: [],
+    pdfFormat: 'A4',
+    pdfLandscape: false,
+    pdfMargin: '20mm',
+    pdfPrintBackground: true,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    switch (a) {
+      case '-h':
+      case '--help':          opts.help = true; break;
+      case '--json':          opts.jsonFile = next(); break;
+      case '--out':
+      case '--output':        opts.output = next(); break;
+      case '--theme':         opts.theme = next(); break;
+      case '--title':         opts.brandTitle = next(); break;
+      case '--name':          opts.name = next(); break;
+      case '--launch':        opts.launchReport = true; break;
+      case '--layout':        opts.columnLayout = Number(next()); break;
+      case '--no-scenario-timestamp':    opts.scenarioTimestamp = false; break;
+      case '--no-suite-as-scenarios':    opts.reportSuiteAsScenarios = false; break;
+      case '--no-failed-summary':        opts.failedSummaryReport = false; break;
+      case '--no-inline-screenshots':    opts.noInlineScreenshots = true; break;
+      case '--store-screenshots':        opts.storeScreenshots = true; break;
+      case '--screenshots-dir':          opts.screenshotsDirectory = next(); break;
+      case '--ignore-bad-json':          opts.ignoreBadJsonFile = true; break;
+      case '--app-version':   opts.metadata['App Version'] = next(); break;
+      case '--env':           opts.metadata['Test Environment'] = next(); break;
+      case '--browser':       opts.metadata['Browser'] = next(); break;
+      case '--platform':      opts.metadata['Platform'] = next(); break;
+      case '--parallel':      opts.metadata['Parallel'] = next(); break;
+      case '--executed':      opts.metadata['Executed'] = next(); break;
+      case '--format': {
+        const f = (next() || '').toLowerCase();
+        if (!FORMATS.has(f)) {
+          console.error(`[varbase-e2e] Unknown format "${f}". Use: ${[...FORMATS].join(', ')}`);
+          process.exit(1);
+        }
+        if (f === 'all') opts.formats.push('html', 'pdf');
+        else opts.formats.push(f);
+        break;
+      }
+      case '--pdf-out':            opts.pdfOut = next(); break;
+      case '--pdf-format':         opts.pdfFormat = next(); break;
+      case '--pdf-landscape':      opts.pdfLandscape = true; break;
+      case '--pdf-margin':         opts.pdfMargin = next(); break;
+      case '--pdf-no-background':  opts.pdfPrintBackground = false; break;
+      case '--pdf-header':         opts.pdfHeaderTemplate = next(); break;
+      case '--pdf-footer':         opts.pdfFooterTemplate = next(); break;
+      case '--pdf-scale':          opts.pdfScale = Number(next()); break;
+      case '--metadata': {
+        const kv = next() || '';
+        const eq = kv.indexOf('=');
+        if (eq > 0) opts.metadata[kv.slice(0, eq)] = kv.slice(eq + 1);
+        break;
+      }
+      default:
+        if (a.startsWith('--')) {
+          console.error(`[varbase-e2e] Unknown option: ${a}`);
+          opts.help = true;
+        }
+    }
+  }
+  if (opts.formats.length === 0) opts.formats = ['html'];
+  return opts;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'Usage: generate-reports [options]',
+      '',
+      'Generate HTML / PDF report from cucumber JSON output.',
+      '',
+      'Input / Output:',
+      '  --json <path>         JSON input  (env VARBASE_E2E_REPORT_JSON,',
+      '                        default: tests/reports/cucumber_report.json)',
+      '  --out <path>          HTML output (env VARBASE_E2E_REPORT_OUT,',
+      '                        default: tests/reports/cucumber_report.html)',
+      '  --format <kind>       html | pdf | all  (repeatable)',
+      '                        default: html',
+      '',
+      'PDF options (require --format pdf or all):',
+      '  --pdf-out <path>      PDF output (default: <out>.pdf)',
+      '  --pdf-format <name>   Letter | Legal | A3 | A4 | A5 | …  (default: A4)',
+      '  --pdf-landscape       Landscape orientation',
+      '  --pdf-margin <css>    Margin all sides (default: 20mm)',
+      '  --pdf-no-background   Disable print background colors / images',
+      '  --pdf-header <html>   Header template HTML',
+      '  --pdf-footer <html>   Footer template HTML',
+      '  --pdf-scale <n>       Scale factor 0.1-2.0',
+      '',
+      'Format:',
+      '  --theme <name>        bootstrap | hierarchy | foundation | simple',
+      '                        (env VARBASE_E2E_REPORT_THEME, default: bootstrap)',
+      '  --title <s>           Brand title (env VARBASE_E2E_REPORT_TITLE)',
+      '  --name <s>            Report name',
+      '  --layout <1|2>        Column layout (default: 1)',
+      '  --launch              Launch report in browser after generation',
+      '  --no-scenario-timestamp   Hide per-scenario timestamp',
+      '  --no-suite-as-scenarios   Report suites instead of scenarios',
+      '  --no-failed-summary       Hide failed-scenarios summary',
+      '  --no-inline-screenshots   Link screenshots instead of embedding',
+      '  --store-screenshots       Copy screenshots into report dir',
+      '  --screenshots-dir <dir>   Source screenshots directory',
+      '  --ignore-bad-json         Do not fail on malformed JSON entries',
+      '',
+      'Metadata:',
+      '  --app-version <s>     App Version         (env VARBASE_E2E_REPORT_APP_VERSION)',
+      '  --env <s>             Test Environment    (env VARBASE_E2E_REPORT_ENV)',
+      '  --browser <s>         Browser             (env BROWSER)',
+      '  --platform <s>        Platform            (default: process.platform)',
+      '  --parallel <s>        Parallel            (default: Scenarios)',
+      '  --executed <s>        Executed            (env VARBASE_E2E_REPORT_EXECUTED)',
+      '  --metadata key=value  Arbitrary key/value (repeatable)',
+      '',
+      '  -h, --help            Show this help',
+      '',
+      'Examples:',
+      '  generate-reports',
+      '  generate-reports --format pdf --pdf-format Letter --pdf-landscape',
+      '  generate-reports --format all --launch',
+      '',
+    ].join('\n')
+  );
+}
+
+async function generatePdf(htmlPath, pdfPath, args) {
+  let chromium;
+  try {
+    ({ chromium } = require('playwright'));
+  } catch (err) {
+    throw new Error(
+      'PDF generation requires "playwright". Run `npm install playwright` and try again.\n' +
+      `Original error: ${err.message}`
+    );
+  }
+  if (!PDF_FORMATS.has(args.pdfFormat)) {
+    throw new Error(`Unknown --pdf-format "${args.pdfFormat}". Use: ${[...PDF_FORMATS].join(', ')}`);
+  }
+  const browser = await chromium.launch();
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const fileUrl = 'file://' + path.resolve(htmlPath);
+    // The cucumber-html-reporter output references CDN scripts that may
+    // never settle; use `domcontentloaded` and add a short render delay.
+    // `commit` returns once navigation accepts; safer than domcontentloaded
+    // when the report references third-party CDN assets that may stall.
+    await page.goto(fileUrl, { waitUntil: 'commit', timeout: 60000 });
+    await page.waitForLoadState('domcontentloaded', { timeout: 30000 }).catch(() => {});
+    await page.waitForTimeout(2500);
+
+    // Render exactly what is shown on screen (preserves badges, panels,
+    // gradients). The `print` media flips to greyscale on many themes.
+    await page.emulateMedia({ media: 'screen' });
+
+    // Force-expand every collapsed feature/scenario block and apply
+    // print-friendly styles so the PDF shows ALL steps without clipping.
+    await page.addStyleTag({ content: `
+      /* Preserve every color (status badges, panels, charts) when printing. */
+      *, *::before, *::after {
+        -webkit-print-color-adjust: exact !important;
+        print-color-adjust: exact !important;
+        color-adjust: exact !important;
+      }
+      @media print {
+        .collapse, .panel-collapse, [aria-expanded="false"] + .collapse,
+        .collapse.in, .collapse.show, .collapsing {
+          display: block !important;
+          visibility: visible !important;
+          height: auto !important;
+          max-height: none !important;
+          overflow: visible !important;
+          opacity: 1 !important;
+        }
+        .feature, .feature-container, .scenario, .scenario-container,
+        .row.steps, .step, .features-summary { page-break-inside: avoid; }
+        .feature, .feature-container { page-break-before: auto; }
+        details { display: block !important; } details > * { display: block !important; }
+        a[href]:after { content: ""; }
+        .btn, button.collapse-toggle, .toggle-icon, .glyphicon-chevron-right,
+        .glyphicon-chevron-down { display: none !important; }
+        pre, code { white-space: pre-wrap !important; word-wrap: break-word !important; }
+        img { max-width: 100% !important; height: auto !important; }
+      }
+      .collapse { display: block !important; height: auto !important; }
+      .collapsing { transition: none !important; }
+      details:not([open]) { }
+    ` });
+
+    // Flatten the report: kill every script, expand every panel, neutralise
+    // every collapse trigger so the resulting PDF is static. No JS runs at
+    // PDF time — what you see is exactly what gets rendered.
+    await page.evaluate(() => {
+      document.querySelectorAll('script').forEach(s => s.remove());
+      document.querySelectorAll('[data-toggle], [data-bs-toggle]').forEach(el => {
+        el.removeAttribute('data-toggle');
+        el.removeAttribute('data-bs-toggle');
+        el.removeAttribute('data-target');
+        el.removeAttribute('data-bs-target');
+        el.removeAttribute('href');
+        el.style.cursor = 'default';
+      });
+      document.querySelectorAll('.collapse, .panel-collapse, [class*="collapse"]').forEach(el => {
+        el.classList.add('in', 'show');
+        el.classList.remove('collapsing');
+        el.style.cssText += ';height:auto !important;display:block !important;visibility:visible !important;opacity:1 !important;';
+        el.setAttribute('aria-expanded', 'true');
+      });
+      document.querySelectorAll('[aria-expanded]').forEach(el => el.setAttribute('aria-expanded', 'true'));
+      document.querySelectorAll('details').forEach(el => el.setAttribute('open', ''));
+      document.querySelectorAll('.glyphicon-chevron-right').forEach(el => {
+        el.classList.remove('glyphicon-chevron-right');
+        el.classList.add('glyphicon-chevron-down');
+      });
+    });
+    await page.waitForTimeout(300);
+    const opts = {
+      path: pdfPath,
+      format: args.pdfFormat,
+      landscape: !!args.pdfLandscape,
+      printBackground: args.pdfPrintBackground,
+      margin: {
+        top: args.pdfMargin,
+        right: args.pdfMargin,
+        bottom: args.pdfMargin,
+        left: args.pdfMargin,
+      },
+    };
+    if (args.pdfHeaderTemplate || args.pdfFooterTemplate) {
+      opts.displayHeaderFooter = true;
+      if (args.pdfHeaderTemplate) opts.headerTemplate = args.pdfHeaderTemplate;
+      if (args.pdfFooterTemplate) opts.footerTemplate = args.pdfFooterTemplate;
+    }
+    if (Number.isFinite(args.pdfScale)) opts.scale = args.pdfScale;
+    await page.pdf(opts);
+  } finally {
+    await browser.close();
+  }
+}
+
+async function run(argv) {
+  const args = parseArgs(argv);
+  if (args.help) return printHelp();
+
+  const cwd = process.cwd();
+  const jsonFile = path.resolve(
+    cwd,
+    args.jsonFile ||
+      process.env.VARBASE_E2E_REPORT_JSON ||
+      'tests/reports/cucumber_report.json'
+  );
+  const output = path.resolve(
+    cwd,
+    args.output ||
+      process.env.VARBASE_E2E_REPORT_OUT ||
+      'tests/reports/cucumber_report.html'
+  );
+
+  const theme =
+    args.theme || process.env.VARBASE_E2E_REPORT_THEME || 'bootstrap';
+  if (!THEMES.has(theme)) {
+    console.error(
+      `[varbase-e2e] Unknown theme "${theme}". Use one of: ${[...THEMES].join(', ')}`
+    );
+    process.exit(1);
+  }
+
+  const metadata = {
+    'App Version':
+      args.metadata['App Version'] ||
+      process.env.VARBASE_E2E_REPORT_APP_VERSION ||
+      '2.0.0',
+    'Test Environment':
+      args.metadata['Test Environment'] ||
+      process.env.VARBASE_E2E_REPORT_ENV ||
+      'development',
+    Browser:
+      args.metadata['Browser'] ||
+      (process.env.BROWSER ? capitalize(process.env.BROWSER) : 'Chromium'),
+    Platform: args.metadata['Platform'] || process.platform,
+    Parallel: args.metadata['Parallel'] || 'Scenarios',
+    Executed:
+      args.metadata['Executed'] ||
+      process.env.VARBASE_E2E_REPORT_EXECUTED ||
+      'Remote',
+  };
+  for (const [k, v] of Object.entries(args.metadata)) {
+    metadata[k] = v;
+  }
+
+  const wantHtml = args.formats.includes('html');
+  const wantPdf  = args.formats.includes('pdf');
+  const needsHtmlForExport = wantPdf;
+
+  const options = {
+    theme,
+    jsonFile,
+    output,
+    reportSuiteAsScenarios: args.reportSuiteAsScenarios,
+    scenarioTimestamp: args.scenarioTimestamp,
+    launchReport: args.launchReport && wantHtml,
+    brandTitle:
+      args.brandTitle || process.env.VARBASE_E2E_REPORT_TITLE || 'Test Report',
+    name: args.name || process.env.VARBASE_E2E_REPORT_NAME,
+    columnLayout: args.columnLayout || 1,
+    noInlineScreenshots: args.noInlineScreenshots,
+    storeScreenshots: args.storeScreenshots,
+    screenshotsDirectory: args.screenshotsDirectory,
+    ignoreBadJsonFile: args.ignoreBadJsonFile,
+    failedSummaryReport: args.failedSummaryReport,
+    metadata,
+  };
+
+  if (wantHtml || needsHtmlForExport) {
+    reporter.generate(options);
+    console.log(`[varbase-e2e] HTML report → ${output}`);
+  }
+
+  if (wantPdf) {
+    const pdfOut = path.resolve(cwd, args.pdfOut || output.replace(/\.html?$/i, '') + '.pdf');
+    await generatePdf(output, pdfOut, args);
+    console.log(`[varbase-e2e] PDF report  → ${pdfOut}`);
+  }
+
+}
+
+if (require.main === module) {
+  Promise.resolve(run(process.argv.slice(2))).catch(err => {
+    console.error(`[varbase-e2e] ${err.message || err}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { run };

package/bin/init-varbase-e2e.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const packagePath = path.join(__dirname, '..');
+
+const CUCUMBER_JS = `module.exports = {
+  default: {
+    timeout: 30000,
+    requireModule: ['ts-node/register'],
+    require: [
+      'node_modules/@vardot/varbase-e2e/tests/step-definitions/**/*.js',          // Varbase E2E core step definitions (auto HTML report on exit; disable: VARBASE_E2E_REPORT_DISABLE=1).
+      'tests/step-definitions/**/*.js',                                  // Your custom step definitions.
+    ],
+    paths: ['tests/features/**/*.feature'],
+    format: [
+      '@cucumber/pretty-formatter',
+      'json:tests/reports/cucumber_report.json',
+    ],
+    formatOptions: {
+      colorsEnabled: true,
+      theme: {
+        'feature keyword': ['bold', 'blue'],
+        'feature name': ['blue', 'underline'],
+        'feature description': ['blueBright'],
+        'scenario keyword': ['bold', 'magenta'],
+        'scenario name': ['magenta', 'underline'],
+        'step keyword': ['bold', 'green'],
+        'step text': ['greenBright', 'italic'],
+      },
+    },
+    worldParameters: {
+      launchUrl: process.env.LAUNCH_URL || 'http://localhost:8080',
+      minWaitTime: {
+        page: 3000,
+        before_scenario: 0,
+        after_scenario: 0,
+        before_step: 0,
+        after_step: 0,
+      },
+      selectors: {
+        css: {},
+        xpath: {},
+        filesPath: './tests/selectors/',
+        files: [],
+        offset: 60,
+        breakpoints: {
+          xs:   { width: 375,  height: 667  },
+          sm:   { width: 576,  height: 800  },
+          md:   { width: 768,  height: 1024 },
+          lg:   { width: 992,  height: 768  },
+          xl:   { width: 1200, height: 900, default: true },
+          xxl:  { width: 1400, height: 900  },
+          xxxl: { width: 1920, height: 1080 },
+        },
+      },
+      screenshot: {
+        dir: './screenshots',
+        purge: false,
+        onFailed: true,
+        onEveryStep: false,
+        alwaysFullscreen: false,
+        failedPrefix: 'failed_',
+        filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}',
+        filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
+        infoTypes: '',
+      },
+    },
+  },
+};
+`;
+
+const PLAYWRIGHT_CONFIG_TS = `import type { LaunchOptions, BrowserContextOptions } from 'playwright';
+
+type BrowserName = 'chromium' | 'firefox' | 'webkit';
+
+const browser = (process.env.BROWSER || 'chromium') as BrowserName;
+
+const chromiumArgs: string[] = [
+  '--no-sandbox',
+  '--disable-dev-shm-usage',
+  '--disable-setuid-sandbox',
+  '--disable-web-security',
+  '--ignore-certificate-errors',
+  '--disable-extensions',
+  '--incognito',
+  '--disable-infobars',
+];
+
+interface PlaywrightConfig {
+  browser: BrowserName;
+  launchOptions: LaunchOptions;
+  contextOptions: BrowserContextOptions;
+}
+
+const config: PlaywrightConfig = {
+  browser,
+  launchOptions: {
+    headless: true,
+    slowMo: 300,
+    args: browser === 'chromium' ? chromiumArgs : [],
+  },
+  contextOptions: {
+    viewport: { width: 1600, height: 1200 },
+    ignoreHTTPSErrors: true,
+  },
+};
+
+export = config;
+`;
+
+const TSCONFIG_JSON = {
+  compilerOptions: {
+    target: 'ES2020',
+    module: 'CommonJS',
+    strict: true,
+    esModuleInterop: true,
+    types: ['node'],
+  },
+  'ts-node': {
+    ignore: ['node_modules/(?!@vardot/varbase-e2e/)'],
+  },
+};
+
+const FEATURE_SAMPLE = `Feature: Check the home page
+  As a nonymouse user
+  I want to be able to visit the home page
+  So that I know that the site is working
+
+  Scenario: Check homepage
+    Given I am on the homepage
+    Then I should see "Love to help in speeding up the work of having Automated Functional Acceptance Testing for products to ship websites in a swift way."
+`;
+
+const CUSTOM_STEP_JS = `const { Given, When, Then } = require('@cucumber/cucumber');
+const playwrightConfig = require(require('path').join(process.cwd(), 'playwright.config'));
+
+// Add your custom step definitions here.
+`;
+
+const TEXT_ASSETS = {
+  'cucumber.js': CUCUMBER_JS,
+  'playwright.config.ts': PLAYWRIGHT_CONFIG_TS,
+  'tests/features/README.md': '# Features\n',
+  'tests/features/check-homepage.feature': FEATURE_SAMPLE,
+  'tests/reports/README.md': '# Reports\n',
+  'tests/step-definitions/README.md': '# Step Definitions\n',
+  'tests/step-definitions/custom.js': CUSTOM_STEP_JS,
+};
+
+const TEST_SCRIPTS = {
+  test: 'cucumber-js --config cucumber.js',
+  'test:chromium': 'BROWSER=chromium cucumber-js --config cucumber.js',
+  'test:firefox': 'BROWSER=firefox cucumber-js --config cucumber.js',
+  'test:webkit': 'BROWSER=webkit cucumber-js --config cucumber.js',
+  'generate-reports': 'generate-reports',
+};
+
+const DEFAULT_PKG = {
+  name: 'project-name',
+  version: '2.0.0',
+  description: '',
+  main: 'index.js',
+  author: '',
+  license: 'MIT',
+  private: false,
+  scripts: {},
+  homepage: 'https://github.com/Vardot/varbase-e2e',
+  dependencies: {},
+};
+
+function parseArgs(argv) {
+  const opts = { force: false, skipBrowsers: false, help: false, cwd: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--force' || a === '-f') opts.force = true;
+    else if (a === '--skip-browsers') opts.skipBrowsers = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--cwd') opts.cwd = argv[++i];
+  }
+  return opts;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'Usage: init-varbase-e2e [options]',
+      '',
+      'Scaffold a varbase-e2e project: cucumber.js, playwright.config.ts,',
+      'tsconfig.json, tests/ tree, and package.json scripts.',
+      'Idempotent — safe to run multiple times.',
+      '',
+      'Options:',
+      '  -f, --force          Overwrite existing files',
+      '      --skip-browsers  Skip `playwright install chromium`',
+      '      --cwd <dir>      Target directory (default: $INIT_CWD or cwd)',
+      '  -h, --help           Show this help',
+      '',
+    ].join('\n')
+  );
+}
+
+function writeFileIfMissing(destPath, content, { force }) {
+  if (!force && fs.existsSync(destPath)) return false;
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  fs.writeFileSync(destPath, content, 'utf8');
+  return true;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readPkgVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(packagePath, 'package.json'), 'utf8')
+    );
+    const major = String(pkg.version).split('.')[0] || '2';
+    return `~${major}.0.0`;
+  } catch {
+    return '~2.0.0';
+  }
+}
+
+function writeTextAssets(projectPath, opts) {
+  const results = [];
+  for (const [rel, content] of Object.entries(TEXT_ASSETS)) {
+    const dest = path.join(projectPath, rel);
+    const written = writeFileIfMissing(dest, content, opts);
+    results.push({ file: rel, written });
+  }
+  return results;
+}
+
+function writeTsconfig(projectPath, opts) {
+  const dest = path.join(projectPath, 'tsconfig.json');
+  if (!opts.force && fs.existsSync(dest)) return false;
+  fs.writeFileSync(dest, JSON.stringify(TSCONFIG_JSON, null, 2) + '\n', 'utf8');
+  return true;
+}
+
+function ensurePackageJson(projectPath, opts) {
+  const pkgPath = path.join(projectPath, 'package.json');
+  const existed = fs.existsSync(pkgPath);
+
+  let pkg;
+  if (existed) {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  } else {
+    pkg = { ...DEFAULT_PKG };
+  }
+
+  pkg.scripts = pkg.scripts || {};
+  for (const [name, cmd] of Object.entries(TEST_SCRIPTS)) {
+    if (opts.force || !pkg.scripts[name]) {
+      pkg.scripts[name] = cmd;
+    }
+  }
+
+  pkg.dependencies = pkg.dependencies || {};
+  if (opts.force || !pkg.dependencies['@vardot/varbase-e2e']) {
+    pkg.dependencies['@vardot/varbase-e2e'] = readPkgVersion();
+  }
+
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  return { created: !existed };
+}
+
+function installBrowsers(projectPath) {
+  console.log('\n  [varbase-e2e] Installing Playwright browsers...\n');
+  const res = spawnSync(
+    'npx',
+    ['playwright', 'install', '--with-deps', 'chromium'],
+    { cwd: projectPath, stdio: 'inherit', shell: true }
+  );
+  return res.status === 0;
+}
+
+function run(argv) {
+  const opts = parseArgs(argv);
+  if (opts.help) return printHelp();
+
+  const projectPath = path.resolve(
+    opts.cwd || process.env.INIT_CWD || process.cwd()
+  );
+
+  if (
+    projectPath === packagePath ||
+    projectPath.startsWith(path.join(packagePath, 'node_modules'))
+  ) {
+    console.log('  [varbase-e2e] Skipping init inside varbase-e2e itself.');
+    return;
+  }
+
+  console.log(`\n  [varbase-e2e] Initializing project at ${projectPath}\n`);
+
+  ensureDir(projectPath);
+  ensureDir(path.join(projectPath, 'tests', 'features'));
+  ensureDir(path.join(projectPath, 'tests', 'reports'));
+  ensureDir(path.join(projectPath, 'tests', 'step-definitions'));
+  ensureDir(path.join(projectPath, 'tests', 'selectors'));
+  ensureDir(path.join(projectPath, 'screenshots'));
+
+  const assetResults = writeTextAssets(projectPath, opts);
+  const tsconfigWritten = writeTsconfig(projectPath, opts);
+  const pkgResult = ensurePackageJson(projectPath, opts);
+
+  for (const r of assetResults) {
+    console.log(`  [${r.written ? 'wrote ' : 'kept  '}] ${r.file}`);
+  }
+  console.log(`  [${tsconfigWritten ? 'wrote ' : 'kept  '}] tsconfig.json`);
+  console.log(
+    `  [${pkgResult.created ? 'wrote ' : 'merged'}] package.json`
+  );
+
+  if (!opts.skipBrowsers) installBrowsers(projectPath);
+
+  console.log('\n  [varbase-e2e] Setup complete!\n');
+}
+
+if (require.main === module) {
+  run(process.argv.slice(2));
+}
+
+module.exports = { run };