dceky 1.0.0-beta.6 → 1.0.2

package/src/genConfiguration/helpers/splitEnv.ts

@@ -0,0 +1,30 @@
+// Import shared types
+import type GlobalsOrProfile from '../types/GlobalsOrProfile';
+import type DependentValue from '../types/DependentValue';
+import type SplitEnv from '../types/SplitEnv';
+
+/**
+ * Split one map into basic and dependent values
+ * @author Gardenia Liu
+ * @param map to split
+ * @returns split basic and dependent values map
+ */
+const splitEnv = (map: GlobalsOrProfile): SplitEnv => {
+  const basic: GlobalsOrProfile = {};
+  const dependent: { [k: string]: DependentValue } = {};
+
+  Object.entries(map).forEach(([k, v]) => {
+    // If entry has dependsOn relationship, add it to dependent dictionary
+    if (typeof v === 'object' && 'dependsOn' in v) {
+      dependent[k] = v as DependentValue;
+    // Otherwise, add it to basic dictionary
+    } else {
+      basic[k] = v;
+    }
+  });
+
+  // Returns separated basic and dependent values
+  return { basic, dependent };
+};
+
+export default splitEnv;

package/src/genConfiguration/index.ts

@@ -0,0 +1,94 @@
+/* eslint-disable no-console */
+/* eslint-disable global-require */
+/* eslint-disable import/no-dynamic-require */
+import path from 'path';
+
+// Import cypress
+import { defineConfig } from 'cypress';
+
+// Import external libraries
+import deepmerge from 'deepmerge';
+
+// Import helpers
+import splitEnv from './helpers/splitEnv';
+import resolveDependents from './helpers/resolveDependents';
+
+// Import types
+import type SplitEnv from './types/SplitEnv';
+import type GlobalsOrProfile from './types/GlobalsOrProfile';
+
+// Determine project directory
+const CWD = path.join(__dirname, '../..');
+
+/**
+ * Generate Cypress configuration based on global credentials,
+ * variables, resources, and profiles
+ * @author Gardenia Liu
+ * @author Gabe Abrams
+ */
+const genConfiguration = () => {
+  // Define paths
+  const GLOBALS_PATH = path.join(CWD, '/cypress/globals');
+  const PROFILES_PATH = path.join(CWD, '/cypress/profiles');
+
+  // Import global env var objects
+  const GlobalCredentials: GlobalsOrProfile = require(path.join(GLOBALS_PATH, '/GlobalCredentials'));
+  const GlobalResources: GlobalsOrProfile = require(path.join(GLOBALS_PATH, '/GlobalResources'));
+  const GlobalValues: GlobalsOrProfile = require(path.join(GLOBALS_PATH, '/GlobalValues'));
+
+  // Determine profile file name (default is stage)
+  const profileName = process.env.CYPRESS_PROFILE || 'stage';
+
+  // Load in chosen profile configuration
+  let profileModules: GlobalsOrProfile = {};
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const mod = require(path.join(PROFILES_PATH, `/${profileName}.Profile`));
+    profileModules = (mod?.default ?? mod ?? {}) as GlobalsOrProfile;
+  } catch (e) {
+    console.warn(`[cypress.config] Could not load profile '${profileName}.Profile'`, e);
+    process.exit(1);
+  }
+
+  // NOTE: Order matters (later overrides earlier)
+  const sources: GlobalsOrProfile[] = [GlobalCredentials, GlobalResources, GlobalValues, profileModules];
+
+  // Split all sources into basic and dependent
+  const splits: SplitEnv[] = sources.map((source) => {
+    return splitEnv(source);
+  });
+
+  // Extract basic and dependent values from splits
+  const basicValues = splits.map((s) => {
+    return s.basic;
+  });
+  const dependentValues = splits.map((s) => {
+    return s.dependent;
+  });
+
+  // Merge all of the basics
+  const basics: GlobalsOrProfile = deepmerge.all<GlobalsOrProfile>(basicValues);
+
+  // Resolve dependencies
+  const dependents: GlobalsOrProfile = resolveDependents(dependentValues, basics);
+
+  // Add basics, depends, and profileName into the final env
+  const finalEnv: GlobalsOrProfile = {
+    ...basics,
+    ...dependents,
+    profileName,
+  };
+
+  const baseUrl = finalEnv.baseURL;
+
+  // Return the configuration object
+  return defineConfig({
+    e2e: {
+      experimentalOriginDependencies: true,
+      baseUrl,
+      env: finalEnv,
+    },
+  });
+};
+
+export default genConfiguration;

package/src/genConfiguration/types/DependentValue.ts

@@ -0,0 +1,14 @@
+/**
+ * Value for a dependent entry
+ * @author Gardenia Liu
+ */
+type DependentValue = {
+  dependsOn: string,
+} & {
+  // Environment, global variables, profile values, etc.
+  [k: string]: any,
+  // Default value if the dependsOn value is not found
+  default?: any,
+};
+
+export default DependentValue;

package/src/genConfiguration/types/GlobalsOrProfile.ts

@@ -0,0 +1,12 @@
+/**
+ * Object containing global variables, profile values, etc.
+ * @author Gardenia Liu
+ */
+type GlobalsOrProfile = {
+  // Base URL to prefix all paths with
+  baseURL?: string,
+  // Environment, global variables, profile values, etc.
+  [k: string]: any,
+};
+
+export default GlobalsOrProfile;

package/src/genConfiguration/types/SplitEnv.ts

@@ -0,0 +1,18 @@
+// Import shared types
+import type GlobalsOrProfile from './GlobalsOrProfile';
+import type DependentValue from './DependentValue';
+
+/**
+ * Env type where basic and dependent entries are separated
+ * @author Gardenia Liu
+ */
+type SplitEnv = {
+  // Basic entries
+  basic: GlobalsOrProfile,
+  // Dependent entries
+  dependent: {
+    [k: string]: DependentValue,
+  },
+};
+
+export default SplitEnv;

package/src/index.ts

@@ -1,11 +1,14 @@
+// Import helpers
 import init from './init';
 import genConfiguration from './genConfiguration';
 
-// Automatically initialize upon importing the library
-init();
+// Automatically initialize upon importing the library, only run in Cypress context
+if (typeof Cypress !== 'undefined') {
+  init();
+}
 
-// Exports
 export {
-  genConfiguration,
+  // Helpers
   init,
+  genConfiguration,
 };

package/src/init.ts

@@ -1,22 +1,41 @@
-/// <reference types="cypress" />
-
-// Add type declarations to Cypress namespace
-declare global {
-  namespace Cypress {
-    interface Chainable {
-      /**
-       * Custom command to click an element by selector
-       * @example cy.clickSomething('.my-button')
-       */
-      clickSomething(selector: string): Chainable<Element>;
-    }
-  }
-}
+// Import all commands
+import assertDoesNotHaveClass from './commands/assertDoesNotHaveClass';
+import assertHasClass from './commands/assertHasClass';
+import assertNumElements from './commands/assertNumElements';
+import extractDataFromClass from './commands/extractDataFromClass';
+import extractDataFromClassByContents from './commands/extractDataFromClassByContents';
+import getJSON from './commands/getJSON';
+import getNumElements from './commands/getNumElements';
+import handleHarvardKey from './commands/handleHarvardKey';
+import launchAs from './commands/launchAs';
+import launchLTIUsingToken from './commands/launchLTIUsingToken';
+import navigateToHref from './commands/navigateToHref';
+import runScript from './commands/runScript';
+import typeInto from './commands/typeInto';
+import visitCanvasGETEndpoint from './commands/visitCanvasGETEndpoint';
+import waitForElementVisible from './commands/waitForElementVisible';
 
+/**
+ * Initialize custom commands
+ * @author Gabe Abrams
+ */
 const init = () => {
-  Cypress.Commands.add('clickSomething', (selector: string) => {
-    cy.get(selector).click();
-  });
+  // Execute each command adder
+  assertDoesNotHaveClass();
+  assertHasClass();
+  assertNumElements();
+  getNumElements();
+  handleHarvardKey();
+  launchAs();
+  launchLTIUsingToken();
+  navigateToHref();
+  runScript();
+  typeInto();
+  visitCanvasGETEndpoint();
+  waitForElementVisible();
+  extractDataFromClass();
+  extractDataFromClassByContents();
+  getJSON();
 };
 
 export default init;

package/start/constants/AVAILABLE_BROWSERS.ts

@@ -0,0 +1,28 @@
+/**
+ * Available browsers for Cypress tests
+ * @author Yuen Ler Chow
+ */
+const AVAILABLE_BROWSERS: {
+  name: string,
+  tag: string,
+}[] = [
+  {
+    name: 'chrome',
+    tag: 'C',
+  },
+  {
+    name: 'firefox',
+    tag: 'F',
+  },
+  {
+    name: 'edge',
+    tag: 'E',
+  },
+  {
+    name: 'safari',
+    tag: 'S',
+  },
+];
+
+// Export only the browser names in lowercase
+export default AVAILABLE_BROWSERS;

package/start/helpers/exec.ts

@@ -0,0 +1,17 @@
+import { execSync } from 'child_process';
+
+/**
+ * Execute a command
+ * @author Gabe Abrams
+ * @param command the command to execute
+ * @param printToStdOut if true, print to standard out instead of returning
+ */
+const exec = (command: string, printToStdOut?: boolean): string => {
+  if (printToStdOut) {
+    execSync(command, { stdio: 'inherit' });
+    return '';
+  }
+  return execSync(command).toString();
+};
+
+export default exec;

package/start/helpers/extractArgValue.ts

@@ -0,0 +1,42 @@
+/**
+ * Extract CLI argument value or check if flag exists
+ * @author Gardenia Liu
+ * @author Yuen Ler Chow
+ * @param args array of CLI arguments
+ * @param argName the argument name to look for (e.g., '--profile' or '--headless')
+ * @returns the argument value if found, empty string if flag exists without value, undefined otherwise
+ */
+const extractArgValue = (args: string[], argName: string): string | undefined => {
+  let matchedValue: string | undefined;
+  args.some((rawArg, index) => {
+    const normalizedArg = rawArg.toLowerCase();
+
+    // Case 1: flag and value combined, e.g. "--profile=stage"
+    if (normalizedArg.startsWith(`${argName}=`)) {
+      const [, value] = rawArg.split('=');
+      matchedValue = value;
+      return true; // stop scanning
+    }
+
+    // Case 2: flag by itself, possibly followed by a separate value
+    if (normalizedArg === argName) {
+      const nextArg = args[index + 1];
+
+      // If the next token exists and isn't another flag, treat it as the value
+      if (nextArg && !nextArg.startsWith('--')) {
+        matchedValue = nextArg;
+      } else {
+        // Flag exists but no value given (boolean-style flag) (e.g. "--headless")
+        matchedValue = '';
+      }
+
+      return true; // stop scanning
+    }
+
+    return false;
+  });
+
+  return matchedValue;
+};
+
+export default extractArgValue;

package/start/helpers/findProfilesByNames.ts

@@ -0,0 +1,39 @@
+/**
+ * Find profiles by names
+ * @author Gardenia Liu
+ * @author Yuen Ler Chow
+ * @param names array of profile names to find
+ * @param profiles array of available profiles
+ * @returns array of found profiles
+ */
+const findProfilesByNames = (
+  names: string[],
+  profiles: Array<{ file: string; profileName: string }>,
+): Array<{ file: string; profileName: string }> => {
+  const found: Array<{ file: string; profileName: string }> = [];
+  const notFound: string[] = [];
+
+  names.forEach((name) => {
+    const target = name.toLowerCase();
+
+    // Find matching profile (case-insensitive)
+    const match = profiles.find((p) => {
+      return p.profileName.toLowerCase() === target;
+    });
+    if (match) {
+      found.push(match);
+    } else {
+      notFound.push(name);
+    }
+  });
+
+  if (notFound.length > 0) {
+    // eslint-disable-next-line no-console
+    console.error(`Profile(s) not found: ${notFound.join(', ')}. Available profiles: ${profiles.map((p) => { return p.profileName; }).join(', ')}`);
+    process.exit(1);
+  }
+
+  return found;
+};
+
+export default findProfilesByNames;

package/start/helpers/parseCommaSeparated.ts

@@ -0,0 +1,23 @@
+/**
+ * Parse comma-separated values into an array
+ * @author Yuen Ler Chow
+ * @param commaSeparatedString the comma-separated string to parse
+ * @returns array of trimmed, non-empty values
+ */
+const parseCommaSeparated = (commaSeparatedString?: string): string[] => {
+  if (!commaSeparatedString) {
+    return [];
+  }
+  return (
+    commaSeparatedString
+      .split(',')
+      .map((value) => {
+        return value.trim();
+      })
+      .filter((value) => {
+        return value.length > 0;
+      })
+  );
+};
+
+export default parseCommaSeparated;

package/start/helpers/print.ts

@@ -0,0 +1,155 @@
+/* eslint-disable no-console */
+
+/**
+ * Get the left buffer for a centered message
+ * @author Gabe Abrams
+ * @param message message to print
+ * @param padding amount of padding to add
+ * @returns number of chars in the buffer
+ */
+const leftBuffer = (message: string, padding: number): number => {
+  return (Math.floor(process.stdout.columns / 2) - padding - Math.ceil(message.length / 2));
+};
+
+/**
+ * Get the right buffer for a centered message
+ * @author Gabe Abrams
+ * @param message message to print
+ * @param padding amount of padding to add
+ * @returns number of chars in the buffer
+ */
+const rightBuffer = (message: string, padding: number): number => {
+  return (Math.ceil(process.stdout.columns / 2) - padding - Math.floor(message.length / 2));
+};
+
+/**
+ * Surround text with a border and spaces
+ * @author Gabe Abrams
+ * @param str text to print
+ * @param border single character to use as a border
+ * @returns text to print
+ */
+const surroundWithBuffer = (str: string, border: string): string => {
+  return (
+    border
+    + ' '.repeat(leftBuffer(str, border.length))
+    + str
+    + ' '.repeat(rightBuffer(str, border.length))
+    + border
+  );
+};
+
+/**
+ * Surround text with a character as the buffer
+ * @author Gabe Abrams
+ * @param str text to print
+ * @param char character to place as the buffer
+ * @returns text to print
+ */
+const surroundWithChars = (str: string, char: string): string => {
+  if (str.length > process.stdout.columns) {
+    return str;
+  }
+  if (str.length === process.stdout.columns - 1) {
+    return char + str;
+  }
+  if (str.length === process.stdout.columns - 2) {
+    return char + str + char;
+  }
+  return (
+    char.repeat(leftBuffer(str, 1))
+    + ' '
+    + str
+    + ' '
+    + char.repeat(rightBuffer(str, 1))
+  );
+};
+
+// Prompt instance
+let cachedPrompt: any;
+
+const print = {
+  /**
+   * Print a title
+   * @author Gabe Abrams
+   * @param str text to print
+   */
+  title: (str: string) => {
+    if (str.length > process.stdout.columns) {
+      return console.log(str);
+    }
+    console.log('\u2554' + '\u2550'.repeat(process.stdout.columns - 2) + '\u2557');
+    console.log(surroundWithBuffer(str, '\u2551'));
+    console.log('\u255A' + '\u2550'.repeat(process.stdout.columns - 2) + '\u255D');
+  },
+  /**
+   * Print a sub title (subheading)
+   * @author Gabe Abrams
+   * @param str text to print
+   */
+  subtitle: (str: string) => {
+    if (str.length > process.stdout.columns) {
+      return console.log(str);
+    }
+    console.log(surroundWithChars(str, '\u257C'));
+  },
+  /**
+   * Print centered text
+   * @author Gabe Abrams
+   * @param str text to print
+   */
+  centered: (str: string) => {
+    const lines = [];
+    let index = 0;
+    while (index < str.length) {
+      lines.push(str.substring(index, Math.min(index + process.stdout.columns, str.length)));
+      index += process.stdout.columns;
+    }
+    lines.forEach((line, lineIndex) => {
+      if (lineIndex !== lines.length - 1) {
+        // No need to center: fills whole line
+        console.log(line);
+      } else {
+        // This line needs to be centered
+        console.log(surroundWithChars(line, ' '));
+      }
+    });
+  },
+  /**
+   * Print a fatal error message
+   * @author Gabe Abrams
+   * @param err error message
+   */
+  fatalError: (err: string) => {
+    console.log('\n');
+    const errLine1 = err.substring(0, process.stdout.columns - 6);
+    const errLine2 = err.substring(process.stdout.columns - 6);
+    console.log('\u2554' + '\u2550'.repeat(3) + '\u2557 ');
+    console.log(`\u2551 ! \u2551 ${errLine1}`);
+    console.log('\u255A' + '\u2550'.repeat(3) + '\u255D ' + errLine2);
+    process.exit(0);
+  },
+  /**
+   * Save a copy of the prompt instance
+   * @author Gabe Abrams
+   * @param promptInstance instance of prompt-sync
+   */
+  savePrompt: (promptInstance: any) => {
+    cachedPrompt = promptInstance;
+  },
+  /**
+   * Ask the user to press enter before continuing
+   * @author Gabe Abrams
+   */
+  enterToContinue: () => {
+    const res = cachedPrompt(
+      surroundWithChars('enter to continue, ctrl+c to quit', '\u257C'),
+      true,
+    );
+    if (res === null) {
+      process.exit(0);
+    }
+  },
+};
+
+export default print;

package/start/helpers/prompt.ts

@@ -0,0 +1,23 @@
+import initPrompt from 'prompt-sync';
+import print from './print';
+
+const promptSync = initPrompt();
+
+/**
+ * Ask the user a question
+ * @param title title of the question
+ * @param notRequired true if question is not required
+ * @returns response
+ */
+const prompt = (title: string, notRequired?: boolean): string => {
+  const val = promptSync(title);
+  if (val === null || (!notRequired && !val)) {
+    process.exit(0);
+  }
+  return val;
+};
+
+// Save the prompt for use later
+print.savePrompt(prompt);
+
+export default prompt;