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

package/src/commands/listSelectLabels.ts

@@ -0,0 +1,47 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Get the labels of all the options within a select element
+       * @author Allison Zhang
+       * @param selector the CSS selector of the select element
+       * @returns an array of strings representing the labels of the options
+       */
+      listSelectLabels(
+        selector: string,
+      ): Chainable<String[]>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const listSelectLabels = () => {
+  Cypress.Commands.add('listSelectLabels', (selector: string) => {
+    const labels: string[] = [];
+    return (
+      cy
+        .get(`${selector} option`)
+        .each((option) => {
+          labels.push(option.attr('label') || option.text());
+        })
+        .then(() => {
+          return labels;
+        })
+    );
+  });
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default listSelectLabels;

package/src/commands/listSelectValues.ts

@@ -0,0 +1,50 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Get the values of all the options within a select element
+       * @author Allison Zhang
+       * @param selector the CSS selector of the select element
+       * @returns an array of strings representing the values of the options
+       */
+      listSelectValues(
+        selector: string,
+      ): Chainable<String[]>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const listSelectValues = () => {
+  Cypress.Commands.add('listSelectValues', (selector: string) => {
+    const vals: string[] = [];
+    return (
+      cy
+        .get(`${selector} option`)
+        .each((option) => {
+          cy.wrap(option).invoke('attr', 'value')
+            .then((value) => {
+              vals.push(value || option.text());
+            });
+        })
+        .then(() => {
+          return vals;
+        })
+    );
+  });
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default listSelectValues;

package/src/commands/padWithZeros.ts

@@ -0,0 +1,53 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Pads a number with leading zeros to a user-defined length.
+       * @author Allison Zhang
+       * @param opts options object
+       * @param opts.length the desired total length of the output string, must be larger than the length of the number
+       * @param opts.number the number to be padded with leading zeros
+       * @returns padded string with leading zeros
+       */
+      padWithZeros(opts: {
+        length: number,
+        number: number,
+      }): Chainable<string>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const padWithZeros = () => {
+  Cypress.Commands.add('padWithZeros', (opts: { length: number, number: number }) => {
+    const {
+      length,
+      number,
+    } = opts;
+    return (
+      cy
+        .then(() => {
+          let numberString = number.toString();
+          while (numberString.length < length) {
+            numberString = `0${numberString}`;
+          }
+          return numberString;
+        })
+    );
+  });
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default padWithZeros;

package/src/commands/uniquify.ts

@@ -0,0 +1,49 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Makes a string unique by appending a timestamp and a counter.
+       * @author Allison Zhang
+       * @param text the original string
+       * @returns the uniquified string
+       */
+      uniquify(text: string): string;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Helpers -------------- */
+/*----------------------------------------*/
+
+let uniqueCounter = 1;
+
+const shorten = (num: number): string => {
+  return Number(num).toString(36);
+};
+
+const id = shorten(Math.floor(Math.random() * 10000));
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const uniquify = () => {
+  Cypress.Commands.add('uniquify', (text: string) => {
+    const thisCounter = uniqueCounter;
+    uniqueCounter += 1;
+    return `${text} [${shorten(Number.parseInt(`${Date.now()}${thisCounter}${id}`, 10))}]`;
+  });
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default uniquify;

package/src/commands/visitCanvasEndpoint.ts

@@ -0,0 +1,75 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Send a request to a Canvas API endpoint.
+       * @author Allison Zhang
+       * @param opts options object
+       * @param opts.method the HTTP method (e.g., 'GET', 'POST', 'DELETE')
+       * @param opts.path the API endpoint path excluding 'https://canvas.harvard.edu', (e.g., '/api/v1/courses/123')
+       * @param opts.accessToken the access token for authentication
+       * @param opts.params the request params (if any)
+       * @returns Cypress chainable containing the Canvas API response body
+       */
+      visitCanvasEndpoint(
+        opts: {
+          method: string,
+          path: string,
+          accessToken: string,
+          params?: { [k: string]: any },
+        },
+      ): Chainable<any>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const visitCanvasEndpoint = () => {
+  Cypress.Commands.add('visitCanvasEndpoint', (
+    opts: {
+      method: string,
+      path: string,
+      accessToken: string,
+      params: {
+        [k: string]: any
+      }
+    },
+  ) => {
+    const {
+      method,
+      path,
+      accessToken,
+      params,
+    } = opts;
+    cy.log(`Visiting Canvas ${method} endpoint`);
+    cy.log(`Canvas API: ${path}`);
+
+    return (
+      cy
+        .request({
+          method,
+          url: `https://canvas.harvard.edu${path}`,
+          body: {
+            ...(params || {}),
+            access_token: accessToken,
+          },
+        })
+        .its('body')
+    );
+  });
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default visitCanvasEndpoint;

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;