dceky 1.0.0-beta.6 → 1.0.3

package/src/commands/assertNumElements.ts

@@ -0,0 +1,50 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Assert a certain number of elements
+       * @author Yuen Ler Chow
+       * @param opts object containing all arguments
+       * @param opts.item a CSS selector corresponding to the item
+       * @param opts.num the precise number of elements expected
+       */
+      assertNumElements(
+        opts: {
+          item: string,
+          num: number,
+        }
+      ): Chainable<Element>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const assertNumElements = () => {
+  Cypress.Commands.add(
+    'assertNumElements',
+    (
+      opts: {
+        item: string,
+        num: number,
+      },
+    ) => {
+      cy.log(`Assert ${opts.num} elements match ${opts.item}`);
+      cy.get(opts.item).should('have.length', opts.num);
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default assertNumElements;

package/src/commands/extractDataFromClass.ts

@@ -0,0 +1,52 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Obtain data from a class attribute that starts with a specific prefix
+       * and return it
+       * @author Allison Zhang
+       * @param selector the css selector for finding the element
+       * @param classPrefix the prefix to look for in the class attribute
+       * @returns the extracted data
+       * @example cy.extractDataFromClass('.item', 'data-').then((data) => { ... })
+       */
+      extractDataFromClass(
+        selector: string,
+        classPrefix: string,
+      ): Chainable<string[]>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const extractDataFromClass = () => {
+  Cypress.Commands.add('extractDataFromClass', (selector: string, classPrefix: string) => {
+    return (
+      cy
+        .get(selector)
+        .invoke('attr', 'class')
+        .then((classAttr: string) => {
+          const classList = classAttr.split(' ');
+          const data = classList
+            .filter((className) => { return className.startsWith(classPrefix); })
+            .map((className) => { return className.replace(classPrefix, ''); });
+          return data;
+        })
+    );
+  });
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default extractDataFromClass;

package/src/commands/extractDataFromClassByContents.ts

@@ -0,0 +1,55 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Obtain data from a class attribute that starts with a specific prefix
+       * and with specific contents, and return it
+       * @author Allison Zhang
+       * @param contents the contents of the element to find
+       * @param selector the css selector for finding the element
+       * @param classPrefix the prefix to look for in the class attribute
+       * @returns the extracted data
+       * @example cy.extractDataFromClassByContents('Submit', '.button', 'btn-').then((data) => { ... })
+       */
+      extractDataFromClassByContents(
+        contents: string,
+        selector: string,
+        classPrefix: string,
+      ): Chainable<string[]>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const extractDataFromClassByContents = () => {
+  Cypress.Commands.add('extractDataFromClassByContents', (contents: string, selector: string, classPrefix: string) => {
+    return (
+      cy
+        .get(selector)
+        .contains(contents)
+        .invoke('attr', 'class')
+        .then((classAttr: string) => {
+          const classList = classAttr.split(' ');
+          const data = classList
+            .filter((className) => { return className.startsWith(classPrefix); })
+            .map((className) => { return className.replace(classPrefix, ''); });
+          return data;
+        })
+    );
+  });
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default extractDataFromClassByContents;

package/src/commands/getJSON.ts

@@ -0,0 +1,45 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Obtain JSON data from a request and return it.
+       * @author Allison Zhang
+       * @param url the URL to fetch the JSON data from
+       * @returns the JSON data
+       * @example cy.getJSON('https://api.example.com/data').then((data) => { ... })
+       */
+      getJSON(
+        url: string,
+      ): Chainable<any>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const getJSON = () => {
+  Cypress.Commands.add('getJSON', (url: string) => {
+    return (
+      cy
+        .request(url)
+        .its('body')
+        .then((body) => {
+          return body;
+        })
+    );
+  });
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default getJSON;

package/src/commands/getNumElements.ts

@@ -0,0 +1,45 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Get number of elements
+       * @author Yuen Ler Chow
+       * @param selector a CSS selector corresponding to the item to count
+       * @return Cypress chainable containing the number of elements matching the selector
+       */
+      getNumElements(
+        selector: string,
+      ): Chainable<number>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const getNumElements = () => {
+  Cypress.Commands.add(
+    'getNumElements',
+    (
+      selector: string,
+    ) => {
+      cy.log(`Count elements matching ${selector}`);
+      return cy.get(selector).then(($elements: JQuery<HTMLElement>) => {
+        return Cypress.$($elements).length;
+      });
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default getNumElements;

package/src/commands/handleHarvardKey.ts

@@ -0,0 +1,91 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Handle a HarvardKey login page for a user
+       * @author Yuen Ler Chow
+       * @param name the name of the user environment variable
+       * @return Cypress chainable (void) - performs authentication flow, no return value
+       */
+      handleHarvardKey(
+        name: string,
+      ): Chainable<void>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const handleHarvardKey = () => {
+  Cypress.Commands.add(
+    'handleHarvardKey',
+    (
+      name: string,
+    ) => {
+      cy.log('Handling HarvardKey authentication');
+
+      const userInfo = Cypress.env(name);
+      if (!userInfo) {
+        throw new Error(`Could not find ${name} in environment variables`);
+      }
+
+      // Destructure the user info object to get the username and password
+      const { username } = userInfo;
+      const { password } = userInfo;
+
+      // Get the Harvard login URL using originWithKaixa with auto-initialized functions
+      cy.origin('https://apps.cirrusidentity.com', () => {
+        Cypress.require('dceky');
+        // Clicking the button doesn't work for some reason, so we access the href attribute instead
+        return cy.navigateToHref('#idp_1001962798_button');
+      }).then((fullUrl: string) => {
+      // Navigate to the Harvard login page using originWithKaixa
+        cy.origin('https://harvard.idp.cirrusidentity.com', {
+          args: { username, password, fullUrl },
+        }, (args) => {
+          Cypress.require('dceky');
+          const {
+            username: harvardUsername,
+            password: harvardPassword,
+            fullUrl: harvardLoginUrl,
+          } = args;
+
+          cy.on('uncaught:exception', (e: Error) => {
+            // Ignore known HarvardKey errors
+            if (!e.message.includes('ready is not defined')) {
+              throw e;
+            }
+            return false;
+          });
+
+          // Visit the Harvard login page
+          cy.visit(harvardLoginUrl);
+
+          // Wait for and fill in the login form
+          cy.waitForElementVisible('#username');
+          cy.waitForElementVisible('#password');
+
+          cy.typeInto({ item: '#username', text: harvardUsername });
+          cy.typeInto({ item: '#password', text: harvardPassword });
+
+          // Submit the form
+          cy.get('input[type="submit"], button[type="submit"], .btn-primary').click();
+        });
+      });
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default handleHarvardKey;

package/src/commands/launchAs.ts

@@ -0,0 +1,120 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Log into Canvas and launch an LTI app as a specific user from environment variables.
+       * The user should be defined as an environment variable with the following properties:
+       * - accessToken: Canvas access token for the user (required for production mode)
+       * - type: User type ('student', 'ta', 'teacher') for local mode (defaults to 'teacher')
+       * - simIndex: Simulator index for local mode (defaults to '0')
+       * @author Yuen Ler Chow
+       * @param name the name of the user environment variable
+       * @param opts object containing all arguments
+        * @param [opts.courseId] the Canvas ID of the course to launch from
+        * @param [opts.appName] the name of the app as it appears in the course's left-hand nav
+       * @return Cypress chainable (void) - launches the LTI app, no return value
+       */
+      launchAs(
+        name: string,
+        opts?: {
+          courseId?: number,
+          appName?: string,
+        }
+      ): Chainable<void>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const launchAs = () => {
+  Cypress.Commands.add(
+    'launchAs',
+    (
+      name: string,
+      opts: {
+        courseId?: number,
+        appName?: string,
+      } = {},
+    ) => {
+      let { courseId, appName } = opts;
+
+      // Get courseId from environment variables if not provided
+      if (!courseId) {
+        const envCourseId = Cypress.env('courseId');
+        if (!envCourseId) {
+          throw new Error('Could not find courseId in environment variables');
+        }
+        courseId = Number.parseInt(envCourseId, 10);
+      }
+
+      // Get appName from environment variables if not provided
+      appName = appName || Cypress.env('appName');
+      if (!appName) {
+        throw new Error('Could not find appName in environment variables');
+      }
+
+      // Get user info from environment variables
+      const userInfo = Cypress.env(name);
+      if (!userInfo) {
+        throw new Error(`Could not find ${name} in environment variables`);
+      }
+
+      cy.log(`🚀 Launch as ${name}`);
+
+      // Check if this is a local launch
+      const isLocal = Cypress.env('local') === 'true';
+
+      if (isLocal) {
+        // Handle local simulator launch
+        const userType = userInfo.type || 'teacher';
+        const simIndex = userInfo.simIndex || '0';
+        const simLaunchButtonId = `${userType}_${simIndex}-launch-button`;
+
+        cy.log('Local mode: launching simulator');
+        cy.visit('https://localhost:8088/simulator');
+
+        // Handle potential SSL certificate issues
+        cy.get('body').then(($body) => {
+          if ($body.find('.ssl').length > 0) {
+            cy.log('Handling SSL certificate issue');
+            cy.get('#details-button').click();
+            cy.get('#proceed-link').click();
+          }
+        });
+
+        // Launch the app
+        cy.get(`#${simLaunchButtonId}`).click();
+
+        // Click the authorize button
+        cy.get('.authorize-button', { timeout: 1000 }).click();
+
+        return;
+      }
+
+      // Handle production launch with access token
+      const { accessToken } = userInfo;
+
+      if (!accessToken) {
+        throw new Error(`Could not find accessToken for ${name} in environment variables`);
+      }
+
+      // Launch using the access token
+      cy.launchLTIUsingToken(accessToken, { courseId, appName });
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default launchAs;

package/src/commands/launchLTIUsingToken.ts

@@ -0,0 +1,115 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Log into Canvas using an access token and launch an LTI app
+       * @author Yuen Ler Chow
+       * @param accessToken the user's Canvas access token
+       * @param opts object containing all arguments
+       * @param [opts.courseId] the Canvas ID of the course to launch from
+       * @param [opts.appName] the name of the app as it appears in the course's left-hand nav
+       * @return Cypress chainable (void) - launches the LTI app and navigates to it, no return value
+       */
+      launchLTIUsingToken(
+        accessToken: string,
+        opts?: {
+          courseId?: number,
+          appName?: string,
+        }
+      ): Chainable<void>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const launchLTIUsingToken = () => {
+  Cypress.Commands.add(
+    'launchLTIUsingToken',
+    (
+      accessToken: string,
+      opts: {
+        courseId?: number,
+        appName?: string,
+      } = {},
+    ) => {
+      let { courseId, appName } = opts;
+
+      if (!courseId) {
+        const envCourseId = Cypress.env('courseId');
+        if (!envCourseId) {
+          throw new Error('Could not find courseId in environment variables');
+        }
+        courseId = Number.parseInt(envCourseId, 10);
+      }
+
+      appName = appName || Cypress.env('appName');
+      if (!appName) {
+        throw new Error('Could not find appName in environment variables');
+      }
+
+      cy.log(`Launch LTI app "${appName}" in course ${courseId} using access token`);
+
+      // Get the external tools for the course
+      cy.visitCanvasGETEndpoint({
+        path: `/courses/${courseId}/external_tools`,
+        accessToken,
+      }).then((externalTools: { [key: string]: any }[]) => {
+        cy.log(`Found ${externalTools.length} external tools`);
+
+        // Find the external tool of interest
+        const matchingTool = externalTools.find((externalTool) => {
+          // Skip non-nav items
+          if (!externalTool.course_navigation || typeof externalTool.course_navigation !== 'object') {
+            return false;
+          }
+
+          // Skip non-labeled items
+          if (!externalTool.course_navigation.text) {
+            return false;
+          }
+
+          // Skip if the app name does not match the expected name
+          const thisAppName = externalTool.course_navigation.text.trim().toLowerCase();
+          return thisAppName === appName.trim().toLowerCase();
+        });
+
+        const toolId = matchingTool?.id || 0;
+        if (matchingTool) {
+          cy.log(`Found matching app: "${matchingTool.course_navigation.text}" with ID ${toolId}`);
+        }
+
+        // Make sure we found the app
+        if (toolId === 0) {
+          throw new Error(`Could not find any apps named "${appName}" in course ${courseId}`);
+        }
+
+        // Get a sessionless launch URL
+        cy.visitCanvasGETEndpoint({
+          path: `/courses/${courseId}/external_tools/sessionless_launch?id=${toolId}`,
+          accessToken,
+        }).then((sessionlessLaunchInfo) => {
+          const launchURL = sessionlessLaunchInfo.url;
+          cy.log(`Launching LTI app at: ${launchURL}`);
+
+          // Launch the tool
+          cy.visit(launchURL);
+        });
+      });
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default launchLTIUsingToken;

package/src/commands/navigateToHref.ts

@@ -0,0 +1,60 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Navigate to href attribute of Harvard identity provider button
+       * @author Yuen Ler Chow
+       * @param item the CSS selector of interest
+       * @return Cypress chainable containing the full URL string (hostname + href attribute value)
+       */
+      navigateToHref(item: string): Chainable<string>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const navigateToHref = () => {
+  Cypress.Commands.add(
+    'navigateToHref',
+    (
+      item: string,
+    ) => {
+      cy.waitForElementVisible(item);
+
+      return cy
+        .url()
+        // get origin (protocol + '//' + host) from current URL
+        .then((url: string) => {
+          const { protocol, host } = new URL(url);
+          return `${protocol}//${host}`;
+        })
+        .then((origin: string) => {
+          return cy
+            .get(item)
+            .invoke('attr', 'href')
+            .then((href: string) => {
+              // If the href is a relative URL, prepend the hostname
+              if (href.startsWith('/')) {
+                return origin + href;
+              }
+              return href;
+            });
+        });
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default navigateToHref;

package/src/commands/runScript.ts

@@ -0,0 +1,44 @@
+/// <reference types="cypress" />
+
+/*----------------------------------------*/
+/* ---------------- Type ---------------- */
+/*----------------------------------------*/
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Run a script on the page
+       * @author Yuen Ler Chow
+       * @param script the script to run
+       * @return Cypress chainable containing the return value from executing the script
+       */
+      runScript(scriptLines: string): Chainable<any>;
+    }
+  }
+}
+
+/*----------------------------------------*/
+/* --------------- Command -------------- */
+/*----------------------------------------*/
+
+const runScript = () => {
+  Cypress.Commands.add(
+    'runScript',
+    (
+      script: string,
+    ) => {
+      cy.log('Running script');
+      return cy.window().then((win) => {
+        const result = win.eval(script);
+        return cy.wrap(result);
+      });
+    },
+  );
+};
+
+/*----------------------------------------*/
+/* --------------- Export --------------- */
+/*----------------------------------------*/
+
+export default runScript;