dceky 1.0.5-beta.ky-declarations.13 → 1.0.5

package/src/commands/waitForAtLeastOneElementPresent.ts

@@ -0,0 +1,64 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Wait for any element in a list to be present (check every tenth
+       * of a second for status)
+       * @author Gardenia Liu
+       * @param opts object containing all arguments
+       * @param opts.items list of CSS selectors of interest
+       * @param [opts.timeoutSec] the number of seconds to wait before
+       * timing out
+       * @returns the selector of the item that was found first, ties
+       * broken by which item shows up in the list first
+       */
+      waitForAtLeastOneElementPresent(
+        opts: {
+          items: string[],
+          timeoutSec?: number,
+        }
+      ): Chainable<string>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const waitForAtLeastOneElementPresent = () => {
+  Cypress.Commands.add(
+    'waitForAtLeastOneElementPresent',
+    (opts: { items: string[], timeoutSec?: number }) => {
+      const { items, timeoutSec } = opts;
+      // Set timeout seconds to 10 if not specified
+      const timeoutMs = (timeoutSec || 10) * 1000;
+
+      // Combined selector for all items
+      const combinedSelector = items.join(', ');
+
+      // Wait for any of the elements to be visible
+      return (
+        cy
+          .get(combinedSelector, { timeout: timeoutMs })
+          .should(($els) => { return expect($els.is(':visible'), `at least one of [${combinedSelector}] visible`).to.be.true; })
+          .then(($els) => {
+            const $firstVisible = $els.filter(':visible').first();
+            return items.find((sel) => { return $firstVisible.is(sel); });
+          })
+      );
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default waitForAtLeastOneElementPresent;

package/start/constants/DEFAULT_THREADS_PER_COMBO.ts

@@ -0,0 +1,7 @@
+/**
+ * Default number of threads per combo
+ * @author Yuen Ler Chow
+ */
+const DEFAULT_THREADS_PER_COMBO = 2;
+
+export default DEFAULT_THREADS_PER_COMBO;

package/start/helpers/collectPngFiles.ts

@@ -0,0 +1,25 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Collect all PNG files recursively from a directory
+ * @author Yuen Ler Chow
+ * @param dir - Directory to search
+ * @param prefix - Path prefix for relative paths
+ * @returns Array of relative file paths
+ */
+const collectPngFiles = (dir: string, prefix = ''): string[] => {
+  const files: string[] = [];
+  const dirEntries = fs.readdirSync(dir, { withFileTypes: true });
+  dirEntries.forEach((entry) => {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectPngFiles(fullPath, path.join(prefix, entry.name)));
+    } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.png')) {
+      files.push(path.join(prefix, entry.name));
+    }
+  });
+  return files;
+};
+
+export default collectPngFiles;

package/start/helpers/executeAllHeadlessCombinations.ts

@@ -0,0 +1,92 @@
+/* eslint-disable no-console */
+import fs from 'fs';
+import path from 'path';
+
+// Import helpers
+import runCypressHeadless from './runCypressHeadless';
+import getDateLabeledDir from './getDateLabeledDir';
+import generateReportHomepage from './generateReportHomepage';
+import mergeAllReportsAndGenerateHtml from './mergeAllReportsAndGenerateHtml';
+
+// Import shared types
+import Profile from '../types/Profile';
+
+/**
+ * Execute all headless Cypress test combinations in parallel
+ * @author Yuen Ler Chow
+ * @param opts - object of arguments
+ * @param opts.selectedProfiles - Array of selected profiles
+ * @param opts.selectedBrowsers - Array of selected browsers
+ * @param [opts.threadsPerCombo] - Number of parallel threads per combo (default: 2)
+ */
+const executeAllHeadlessCombinations = async (
+  opts: {
+    selectedProfiles: Profile[],
+    selectedBrowsers: string[],
+    threadsPerCombo?: number,
+  },
+): Promise<void> => {
+  const { selectedProfiles, selectedBrowsers, threadsPerCombo } = opts;
+
+  // Create date-labeled output directory
+  const outputDir = getDateLabeledDir();
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  console.log(`📁 Results will be saved to: ${outputDir}\n`);
+
+  // Generate all Profile+Browser combinations
+  const combinations: { profileName: string; browser: string }[] = [];
+  selectedProfiles.forEach((profile) => {
+    selectedBrowsers.forEach((browser) => {
+      combinations.push({
+        profileName: profile.profileName,
+        browser,
+      });
+    });
+  });
+
+  console.log(`🔄 Running ${combinations.length} test combination(s) in parallel...\n`);
+
+  // Run all combinations in parallel
+  const runPromises = combinations.map((combo) => {
+    return runCypressHeadless({
+      profileName: combo.profileName,
+      browser: combo.browser,
+      outputDir,
+      numThreads: threadsPerCombo,
+    });
+  });
+  const results = await Promise.all(runPromises);
+
+  // Generate combined HTML report across all profile+browser combinations
+  mergeAllReportsAndGenerateHtml(outputDir, results);
+
+  // Generate report homepage
+  const reportInfos = results.map((result) => {
+    return {
+      profileName: result.profileName,
+      browser: result.browser,
+      reportPath: result.reportPath || '',
+      success: result.success,
+      timestamp: new Date().toLocaleString(),
+    };
+  });
+
+  generateReportHomepage(reportInfos, outputDir);
+
+  // Print summary
+  const passed = results.filter((r) => { return r.success; }).length;
+  const failed = results.filter((r) => { return !r.success; }).length;
+
+  console.log('\n═══════════════════════════════════════════════════════════');
+  console.log('📊 Execution Summary:');
+  console.log(`   Total: ${results.length}`);
+  console.log(`   ✅ Passed: ${passed}`);
+  console.log(`   ❌ Failed: ${failed}`);
+  console.log(`   📄 Report homepage: file://${path.join(outputDir, 'index.html')}`);
+  console.log('═══════════════════════════════════════════════════════════\n');
+};
+
+export default executeAllHeadlessCombinations;

package/start/helpers/executeCypress.ts

@@ -0,0 +1,66 @@
+/* eslint-disable no-console */
+
+// Import shared types
+import Profile from '../types/Profile';
+
+// Import helpers
+import runCypressVisible from './runCypressVisible';
+import executeAllHeadlessCombinations from './executeAllHeadlessCombinations';
+
+// Import constants
+import DEFAULT_THREADS_PER_COMBO from '../constants/DEFAULT_THREADS_PER_COMBO';
+
+/**
+ * Execute Cypress tests in either headless or visible mode
+ * @author Yuen Ler Chow
+ * @param opts - object of arguments
+ * @param opts.selectedProfiles - Array of selected profiles
+ * @param opts.selectedBrowsers - Array of selected browsers
+ * @param opts.isHeadless - Whether to run in headless mode
+ * @param [opts.threadsPerCombo] - Number of parallel threads per combo (default: 2)
+ */
+const executeCypress = async (
+  opts: {
+    selectedProfiles: Profile[],
+    selectedBrowsers: string[],
+    isHeadless: boolean,
+    threadsPerCombo?: number,
+  },
+): Promise<void> => {
+  const {
+    selectedProfiles,
+    selectedBrowsers,
+    isHeadless,
+    threadsPerCombo,
+  } = opts;
+
+  console.log('\n═══════════════════════════════════════════════════════════');
+  console.log('Starting Cypress with the following configuration:');
+  console.log(`Profile(s): ${selectedProfiles.map((p) => { return p.profileName; }).join(', ')}`);
+  console.log(`Browser(s): ${selectedBrowsers.join(', ')}`);
+  console.log(`Headless: ${isHeadless}`);
+  if (isHeadless) {
+    console.log(`Threads per combo: ${threadsPerCombo ?? DEFAULT_THREADS_PER_COMBO}`);
+  }
+  console.log('═══════════════════════════════════════════════════════════\n');
+
+  try {
+    if (!isHeadless) {
+      // Visible mode: run with single profile
+      const { profileName } = selectedProfiles[0];
+      await runCypressVisible(profileName);
+    } else {
+      // Headless mode: run parallel instances for each Profile+Browser combination
+      await executeAllHeadlessCombinations({
+        selectedProfiles,
+        selectedBrowsers,
+        threadsPerCombo,
+      });
+    }
+  } catch (error) {
+    console.error('\n❌ Error during execution:', error);
+    process.exit(1);
+  }
+};
+
+export default executeCypress;

package/start/helpers/generateHtmlReport.ts

@@ -0,0 +1,71 @@
+/* eslint-disable no-console */
+import { execSync } from 'child_process';
+import path from 'path';
+import { existsSync } from 'fs';
+import getRootPath from './getRootPath';
+
+/**
+ * Generate HTML report from merged JSON report using mochawesome-report-generator (marge)
+ * @author Yuen Ler Chow
+ * @param opts - object of arguments
+ * @param opts.resultsDir - Results directory
+ * @param opts.profileName - Profile name
+ * @param opts.browserName - Browser name
+ */
+const generateHtmlReport = (
+  opts: {
+    resultsDir: string;
+    profileName: string;
+    browserName: string;
+  },
+): void => {
+  const { resultsDir, profileName, browserName } = opts;
+
+  const reportDataPath = path.join(
+    resultsDir,
+    `${profileName}-${browserName}`,
+    'report-data.json',
+  );
+  const reportDir = path.join(
+    resultsDir,
+    `${profileName}-${browserName}`,
+    'report',
+  );
+  const expectedHtmlPath = path.join(reportDir, 'report-data.html');
+
+  console.log(`\n📄 Generate HTML Report Debug for ${profileName} + ${browserName}:`);
+  console.log(`   Report data path: ${reportDataPath}`);
+  console.log(`   Report output dir: ${reportDir}`);
+
+  if (!existsSync(reportDataPath)) {
+    const errorMsg = `❌ ERROR: Report data JSON does not exist: ${reportDataPath}`;
+    console.error(errorMsg);
+    throw new Error(errorMsg);
+  }
+
+  try {
+    const command = `npx marge "${reportDataPath}" --reportDir "${reportDir}"`;
+
+    console.log(`   Running: ${command}`);
+    console.log(`Generating HTML report for ${profileName} + ${browserName}...`);
+
+    execSync(command, {
+      stdio: 'inherit',
+      cwd: getRootPath(),
+    });
+
+    // Verify the HTML report was created
+    if (!existsSync(expectedHtmlPath)) {
+      const errorMsg = `❌ ERROR: HTML report was not created at: ${expectedHtmlPath}`;
+      console.error(errorMsg);
+      throw new Error(errorMsg);
+    }
+
+    console.log(`   ✅ HTML report generated successfully at: ${expectedHtmlPath}`);
+  } catch (e) {
+    console.error(`Error generating HTML report for ${profileName} + ${browserName}:`, e);
+    throw e;
+  }
+};
+
+export default generateHtmlReport;

package/start/helpers/generateReportHomepage.ts

@@ -0,0 +1,148 @@
+/* eslint-disable no-console */
+import fs from 'fs';
+import path from 'path';
+import ejs from 'ejs';
+
+// Import helpers
+import collectPngFiles from './collectPngFiles';
+
+// Import types
+import ReportInfo from '../types/ReportInfo';
+import ScreenshotInfo from '../types/ScreenshotInfo';
+import TemplateReportInfo from '../types/TemplateReportInfo';
+
+/**
+ * Generate an HTML homepage that links to all reports
+ * @author Yuen Ler Chow
+ * @param reports - Array of report information
+ * @param outputDir - The directory where the homepage should be created
+ */
+const generateReportHomepage = (
+  reports: ReportInfo[],
+  outputDir: string,
+): void => {
+  const homepagePath = path.join(outputDir, 'index.html');
+  const combinedReportPath = path.join(outputDir, 'all-runs.html');
+  const combinedJsonPath = path.join(outputDir, 'all-report-data.json');
+
+  const hasCombinedReport = fs.existsSync(combinedReportPath);
+
+  // Try to read combined stats from all-report-data.json
+  let combinedTotalTests: number | null = null;
+  let combinedPassedTests: number | null = null;
+  if (fs.existsSync(combinedJsonPath)) {
+    try {
+      const raw = fs.readFileSync(combinedJsonPath, 'utf-8');
+      const data = JSON.parse(raw);
+      const stats = (data && data.stats) || null;
+      if (stats && typeof stats.tests === 'number' && typeof stats.passes === 'number') {
+        combinedTotalTests = stats.tests;
+        combinedPassedTests = stats.passes;
+      }
+    } catch (err) {
+      // File exists but couldn't be read/parsed - log warning
+      console.warn('⚠️ Could not read combined stats:', err);
+    }
+  }
+
+  // Try to read per-combination stats from each combo's report-data.json
+  reports.forEach((report) => {
+    const comboJsonPath = path.join(
+      outputDir,
+      `${report.profileName}-${report.browser}`,
+      'report-data.json',
+    );
+    if (!fs.existsSync(comboJsonPath)) {
+      return;
+    }
+    try {
+      const raw = fs.readFileSync(comboJsonPath, 'utf-8');
+      const data = JSON.parse(raw);
+      const stats = (data && data.stats) || null;
+      if (stats && typeof stats.tests === 'number' && typeof stats.passes === 'number') {
+        // eslint-disable-next-line no-param-reassign
+        report.totalTests = stats.tests;
+        // eslint-disable-next-line no-param-reassign
+        report.passedTests = stats.passes;
+      }
+    } catch (err) {
+      // File exists but couldn't be read/parsed - log warning
+      console.warn(`⚠️ Could not read stats for ${report.profileName}-${report.browser}:`, err);
+    }
+  });
+
+  // Sort reports by profile name, then browser
+  const sortedReports = [...reports].sort((a, b) => {
+    if (a.profileName !== b.profileName) {
+      return a.profileName.localeCompare(b.profileName);
+    }
+    return a.browser.localeCompare(b.browser);
+  });
+
+  // Prepare reports with computed fields for the template
+  const templateReports: TemplateReportInfo[] = sortedReports.map((report) => {
+    // Compute relative report path
+    let relativeReportPath: string | null = null;
+    if (report.reportPath && fs.existsSync(report.reportPath)) {
+      relativeReportPath = path.relative(outputDir, report.reportPath).replace(/\\/g, '/');
+    }
+
+    // Collect screenshots
+    const screenshots: ScreenshotInfo[] = [];
+    const comboScreenshotsDir = path.join(
+      outputDir,
+      `${report.profileName}-${report.browser}`,
+      'screenshots',
+    );
+    if (fs.existsSync(comboScreenshotsDir)) {
+      const pngFiles = collectPngFiles(comboScreenshotsDir);
+      pngFiles.forEach((rel) => {
+        const href = path
+          .relative(outputDir, path.join(comboScreenshotsDir, rel))
+          .replace(/\\/g, '/');
+        screenshots.push({ href, name: rel });
+      });
+    }
+
+    return {
+      ...report,
+      relativeReportPath,
+      screenshots,
+    };
+  });
+
+  // Group by profile
+  const reportsByProfile: { [key: string]: TemplateReportInfo[] } = {};
+  templateReports.forEach((report) => {
+    if (!reportsByProfile[report.profileName]) {
+      reportsByProfile[report.profileName] = [];
+    }
+    reportsByProfile[report.profileName].push(report);
+  });
+
+  // Calculate summary stats
+  const totalRuns = reports.length;
+  const passedRuns = reports.filter((r) => { return r.success; }).length;
+  const failedRuns = reports.filter((r) => { return !r.success; }).length;
+  const profileCount = Object.keys(reportsByProfile).length;
+
+  // Load and render EJS template
+  const templatePath = path.join(__dirname, 'reportHomepage.ejs');
+  const templateFile = fs.readFileSync(templatePath, 'utf-8');
+  const html = ejs.render(templateFile, {
+    hasCombinedReport,
+    combinedTotalTests,
+    combinedPassedTests,
+    totalRuns,
+    passedRuns,
+    failedRuns,
+    profileCount,
+    reportsByProfile,
+  });
+
+  // Write the HTML file
+  fs.writeFileSync(homepagePath, html, 'utf-8');
+  console.log(`\n📄 Report homepage generated: ${homepagePath}`);
+};
+
+export default generateReportHomepage;

package/start/helpers/generateReporterConfig.ts

@@ -0,0 +1,39 @@
+import path from 'path';
+import MochawesomeReporterConfig from '../types/MochawesomeReporterConfig';
+
+/**
+ * Generate inline reporter configuration for cypress-multi-reporters
+ * that produces granular mochawesome JSON per spec
+ * @author Yuen Ler Chow
+ * @param opts - object of arguments
+ * @param opts.resultsDir - Base directory for results
+ * @param opts.profileName - Profile name
+ * @param opts.browserName - Browser name
+ * @returns Reporter config object
+ */
+const generateReporterConfig = (opts: {
+  resultsDir: string;
+  profileName: string;
+  browserName: string;
+}): MochawesomeReporterConfig => {
+  const { resultsDir, profileName, browserName } = opts;
+
+  const granularResultsDir = path.join(
+    resultsDir,
+    `${profileName}-${browserName}`,
+    'granular-results',
+  );
+
+  return {
+    reporterEnabled: 'mochawesome',
+    mochawesomeReporterOptions: {
+      reportDir: granularResultsDir,
+      reportFilename: 'test-[name]',
+      overwrite: false,
+      html: false,
+      json: true,
+    },
+  };
+};
+
+export default generateReporterConfig;

package/start/helpers/getDateLabeledDir.ts

@@ -0,0 +1,43 @@
+import path from 'path';
+import getRootPath from './getRootPath';
+
+/**
+ * Get a date-labeled directory path for results using Eastern Time
+ * @author Yuen Ler Chow
+ * @returns path to date-labeled directory (e.g., cypress-results/2024-1-15_3-05pm)
+ */
+const getDateLabeledDir = (): string => {
+  const root = getRootPath();
+  const now = new Date();
+
+  // Format date in Eastern Time
+  const str = now.toLocaleString(
+    'en-US', // Using US encoding (it's the only one installed on containers)
+    { timeZone: 'America/New_York' }, // Force EST timezone
+  );
+
+  // Parse the string for the date/time info
+  const [dateStr, timeStr] = str.split(', '); // Format: MM/DD/YYYY, HH:MM:SS AM
+  const [monthStr, dayStr, yearStr] = dateStr.split('/'); // Format: MM/DD/YYYY
+  const [hourStr, minStr, ending] = timeStr.split(':'); // Format: HH:MM:SS AM
+
+  // Create all time numbers
+  const year = Number.parseInt(yearStr, 10);
+  const month = Number.parseInt(monthStr, 10);
+  const day = Number.parseInt(dayStr, 10);
+  const minute = Number.parseInt(minStr, 10);
+  const hour12 = Number.parseInt(hourStr, 10);
+
+  // Determine AM/PM
+  const isAM = ending.toLowerCase().includes('am');
+
+  // Pad minute with leading zero if needed
+  const minutePadded = minute.toString().padStart(2, '0');
+
+  // Build formatted date string: YYYY-M-D_H-MMam/pm (no spaces for shell compatibility)
+  const formattedDate = `${year}-${month}-${day}_${hour12}-${minutePadded}${isAM ? 'am' : 'pm'}`;
+
+  return path.join(root, 'cypress-results', formattedDate);
+};
+
+export default getDateLabeledDir;