dceky 1.0.0-beta.6 → 1.0.3

package/src/commands/typeInto.ts

@@ -0,0 +1,88 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Type text into an element. This function first removes the previous text in the element
+       * @author Yuen Ler Chow
+       * @param opts object containing all arguments
+       * @param opts.item the CSS selector of interest
+       * @param opts.text the text to type
+       * @param [opts.pressEnter] if true, after typing into the text field, simulate pressing enter
+       * @param [opts.append] if true, append the text to the end of the existing text in the element instead of replacing it
+       * @return Cypress chainable containing the input element that text was typed into
+       */
+      typeInto(
+        opts: {
+          item: string,
+          text: string,
+          pressEnter?: boolean,
+          append?: boolean,
+        },
+      ): Chainable<Element>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const typeInto = () => {
+  Cypress.Commands.add(
+    'typeInto',
+    (
+      opts: {
+        item: string,
+        text: string,
+        pressEnter?: boolean,
+        append?: boolean,
+      },
+    ) => {
+      const {
+        item, text, pressEnter, append,
+      } = opts;
+      // Check if the text contains an enter key press
+      const enterAtEndOfText = text.charAt(text.length - 1) === '\n';
+      const willPressEnter = pressEnter || enterAtEndOfText;
+
+      const action = append ? 'Append' : 'Type';
+      const enterSuffix = willPressEnter ? ' and then press enter' : '';
+      cy.log(`${action} "${text}" into ${item}${enterSuffix}`);
+
+      // Type the text without a trailing enter if there was one
+      const textWithoutTrailingEnter = (
+        enterAtEndOfText
+          ? text.substring(0, text.length - 1)
+          : text
+      );
+
+      if (append) {
+        cy
+          .get(item)
+          .type(textWithoutTrailingEnter);
+      } else {
+        cy
+          .get(item)
+          .clear()
+          .type(textWithoutTrailingEnter);
+      }
+
+      // Press enter if explicitly requested or if text ended with newline
+      if (willPressEnter) {
+        cy.get(item).type('{enter}');
+      }
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default typeInto;

package/src/commands/visitCanvasGETEndpoint.ts

@@ -0,0 +1,61 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Makes a GET request to Canvas API endpoint
+       * @author Yuen Ler Chow
+       * @param opts object containing all arguments
+       * @param opts.path The API path (e.g., '/courses', '/users/self')
+       * @param opts.accessToken The Canvas access token
+       * @return Cypress chainable containing the Canvas API response body
+       */
+      visitCanvasGETEndpoint(
+        opts: {
+          path: string,
+          accessToken: string,
+        }
+      ): Chainable<any>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const visitCanvasGETEndpoint = () => {
+  Cypress.Commands.add(
+    'visitCanvasGETEndpoint',
+    (
+      opts: {
+        path: string,
+        accessToken: string,
+      },
+    ) => {
+      cy.log('Visiting Canvas GET endpoint');
+      const { path, accessToken } = opts;
+
+      cy.log(`Canvas API: ${path}`);
+      return cy.request({
+        method: 'GET',
+        url: `https://canvas.harvard.edu/api/v1${path}`,
+        qs: {
+          per_page: 200,
+          access_token: accessToken,
+        },
+      }).its('body');
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default visitCanvasGETEndpoint;

package/src/commands/waitForElementVisible.ts

@@ -0,0 +1,49 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Wait for an element to be visible
+       * @author Yuen Ler Chow
+       * @param item the CSS selector of interest
+       * @param [timeoutSec=10] the number of seconds to wait before timing out
+       * @return Cypress chainable containing the visible element
+       */
+      waitForElementVisible(
+        item: string,
+        timeoutSec?: number,
+      ): Chainable<JQuery<HTMLElement>>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const waitForElementVisible = () => {
+  Cypress.Commands.add(
+    'waitForElementVisible',
+    (
+      item: string,
+      timeoutSec?: number,
+    ) => {
+      cy.log('Waiting for element to be visible');
+
+      const timeoutMs = (timeoutSec || 10) * 1000;
+      cy.log(`Wait for ${item} to be visible`);
+      return cy.get(item, { timeout: timeoutMs }).should('be.visible');
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default waitForElementVisible;

package/src/genConfiguration/helpers/getRootPath.ts

@@ -0,0 +1,13 @@
+import path from 'path';
+
+/**
+ * Get the root path of the project
+ * @author Yuen Ler Chow
+ * @returns the root path of the project
+ */
+const getRootPath = () => {
+  const root = path.join(__dirname, '../../../../../../');
+  return root;
+};
+
+export default getRootPath;

package/src/genConfiguration/helpers/resolveDependents.ts

@@ -0,0 +1,46 @@
+// Import shared types
+import type GlobalsOrProfile from '../types/GlobalsOrProfile';
+import type DependentValue from '../types/DependentValue';
+
+/**
+ * Resolve all dependent values using already-merged basics.
+ * @author Gardenia Liu
+ * @param dependentMaps with dependencies on basics
+ * @param basics entries
+ * @returns env with all dependent values resolved
+ */
+const resolveDependents = (
+  dependentMaps: { [k: string]: DependentValue }[],
+  basics: GlobalsOrProfile,
+): GlobalsOrProfile => {
+  const resolved: GlobalsOrProfile = {};
+
+  // Loop through all of the dependency maps
+  dependentMaps.forEach((depMap) => {
+    // Loop through all entries within dependency map
+    Object.entries(depMap).forEach(([k, depVal]) => {
+      // Get basic selector the value depends on
+      const selector = basics[depVal.dependsOn];
+
+      // Create table of values selector can be
+      const { dependsOn, ...table } = depVal as { [k: string]: unknown };
+
+      // Get the selector's picked value
+      const picked = table[selector];
+
+      if (picked !== undefined) {
+        resolved[k] = picked;
+      } else if ('default' in table) {
+        resolved[k] = table.default;
+      } else {
+        // eslint-disable-next-line max-len
+        console.warn(`[cypress.config] Could not resolve ${k}, dependsOn=${dependsOn}, selector=${String(selector)}`);
+        process.exit(1);
+      }
+    });
+  });
+
+  return resolved;
+};
+
+export default resolveDependents;

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,95 @@
+/* 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 getRootPath from './helpers/getRootPath';
+
+// Import types
+import type SplitEnv from './types/SplitEnv';
+import type GlobalsOrProfile from './types/GlobalsOrProfile';
+
+// Determine project directory
+const CWD = getRootPath();
+
+/**
+ * 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/getRootPath.ts

@@ -0,0 +1,13 @@
+import path from 'path';
+
+/**
+ * Get the root path of the project
+ * @author Yuen Ler Chow
+ * @returns the root path of the project
+ */
+const getRootPath = () => {
+  const root = path.join(__dirname, '../../../../');
+  return root;
+};
+
+export default getRootPath;

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;