dceky 1.0.0-beta-yuenler.2 → 1.0.0-beta-auto-import.1

package/src/commands/assertDoesNotHaveClass.ts

@@ -9,15 +9,18 @@ declare global {
     interface Chainable {
       /**
        * Assert that an element does not have a specific className
+       * @author Yuen Ler Chow
        * @param opts object containing all arguments
        * @param opts.item the css selector for finding the element
        * @param opts.className the className to check for
-       * @example cy.assertDoesNotHaveClass({ item: '.my-button', className: 'disabled' })
+       * @return Cypress chainable containing the element that was checked
        */
-      assertDoesNotHaveClass(opts: {
-        item: string;
-        className: string;
-      }): Chainable<JQuery<HTMLElement>>;
+      assertDoesNotHaveClass(
+        opts: {
+          item: string,
+          className: string,
+        },
+      ): Chainable<JQuery<HTMLElement>>;
     }
   }
 }
@@ -27,10 +30,18 @@ declare global {
 /*----------------------------------------*/
 
 const assertDoesNotHaveClass = () => {
-  Cypress.Commands.add('assertDoesNotHaveClass', (opts: { item: string; className: string }) => {
-    cy.log(`Assert ${opts.item} does not have class ${opts.className}`);
-    return cy.get(opts.item).should('not.have.class', opts.className);
-  });
+  Cypress.Commands.add(
+    'assertDoesNotHaveClass',
+    (
+      opts: {
+        item: string,
+        className: string,
+      },
+    ) => {
+      cy.log(`Assert ${opts.item} does not have class ${opts.className}`);
+      return cy.get(opts.item).should('not.have.class', opts.className);
+    },
+  );
 };
 
 /*----------------------------------------*/

package/src/commands/assertHasClass.ts

@@ -9,15 +9,18 @@ declare global {
     interface Chainable {
       /**
        * Assert that an element has a specific className
+       * @author Yuen Ler Chow
        * @param opts object containing all arguments
        * @param opts.item the css selector for finding the element
        * @param opts.className the className to check for
-       * @example cy.assertHasClass({ item: '.my-button', className: 'active' })
+       * @return Cypress chainable containing the element that was checked
        */
-      assertHasClass(opts: {
-        item: string;
-        className: string;
-      }): Chainable<JQuery<HTMLElement>>;
+      assertHasClass(
+        opts: {
+          item: string,
+          className: string,
+        },
+      ): Chainable<JQuery<HTMLElement>>;
     }
   }
 }
@@ -27,10 +30,18 @@ declare global {
 /*----------------------------------------*/
 
 const assertHasClass = () => {
-  Cypress.Commands.add('assertHasClass', (opts: { item: string; className: string }) => {
-    cy.log(`Assert ${opts.item} has class ${opts.className}`);
-    return cy.get(opts.item).should('have.class', opts.className);
-  });
+  Cypress.Commands.add(
+    'assertHasClass',
+    (
+      opts: {
+        item: string,
+        className: string,
+      },
+    ) => {
+      cy.log(`Assert ${opts.item} has class ${opts.className}`);
+      return cy.get(opts.item).should('have.class', opts.className);
+    },
+  );
 };
 
 /*----------------------------------------*/

package/src/commands/assertNumElements.ts

@@ -9,12 +9,18 @@ declare global {
     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
-       * @example cy.assertNumElements({ item: '.list-item', num: 5 })
+       * @return Cypress chainable
        */
-      assertNumElements(opts: { item: string; num: number }): Chainable<Element>;
+      assertNumElements(
+        opts: {
+          item: string,
+          num: number,
+        }
+      ): Chainable<Element>;
     }
   }
 }
@@ -24,10 +30,18 @@ declare global {
 /*----------------------------------------*/
 
 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);
-  });
+  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);
+    },
+  );
 };
 
 /*----------------------------------------*/

package/src/commands/getNumElements.ts

@@ -9,11 +9,13 @@ declare global {
     interface Chainable {
       /**
        * Get number of elements
-       * @param item a CSS selector corresponding to the item
-       * @returns the number of elements on the page
-       * @example cy.getNumElements('.list-item').then((count) => { ... })
+       * @author Yuen Ler Chow
+       * @param selector a CSS selector corresponding to the item
+       * @return Cypress chainable containing the number of elements matching the selector
        */
-      getNumElements(item: string): Chainable<JQuery<any>>;
+      getNumElements(
+        selector: string,
+      ): Chainable<number>;
     }
   }
 }
@@ -23,12 +25,17 @@ declare global {
 /*----------------------------------------*/
 
 const getNumElements = () => {
-  Cypress.Commands.add('getNumElements', (selector: string) => {
-    cy.log(`Count elements matching ${selector}`);
-    return cy.get(selector).then(($elements: any) => {
-      return cy.wrap($elements.length);
-    });
-  });
+  Cypress.Commands.add(
+    'getNumElements',
+    (
+      selector: string,
+    ) => {
+      cy.log(`Count elements matching ${selector}`);
+      return cy.get(selector).then(($elements: JQuery<HTMLElement>) => {
+        return Cypress.$($elements).length;
+      });
+    },
+  );
 };
 
 /*----------------------------------------*/

package/src/commands/handleHarvardKey.ts

@@ -9,10 +9,18 @@ declare global {
     interface Chainable {
       /**
        * Handle a HarvardKey login page for a user
-       * @param url the URL to visit for HarvardKey authentication
-       * @example cy.handleHarvardKey('https://canvas.harvard.edu/login/saml')
+       * @author Yuen Ler Chow
+       * @param opts object containing all arguments
+       * @param opts.url the URL to visit for HarvardKey authentication
+       * @param opts.name the name of the user environment variable
+       * @return Cypress chainable (void) - performs authentication flow, no return value
        */
-      handleHarvardKey(url: string): Chainable<void>;
+      handleHarvardKey(
+        opts: {
+          url: string,
+          name: string,
+        }
+      ): Chainable<void>;
     }
   }
 }
@@ -22,62 +30,69 @@ declare global {
 /*----------------------------------------*/
 
 const handleHarvardKey = () => {
-  Cypress.Commands.add('handleHarvardKey', (url: string) => {
-    cy.log('Handling HarvardKey authentication');
-    
-    // Get credentials from environment variables
-    const username = (window as any).Cypress.env('HARVARD_USERNAME');
-    const password = (window as any).Cypress.env('HARVARD_PASSWORD');
-    
-    if (!username) {
-      throw new Error(`HARVARD_USERNAME environment variable is not set`);
-    }
-    
-    if (!password) {
-      throw new Error(`HARVARD_PASSWORD environment variable is not set`);
-    }
+  Cypress.Commands.add(
+    'handleHarvardKey',
+    (
+      opts: {
+        url: string,
+        name: string,
+      },
+    ) => {
+      const { url, name } = opts;
+      cy.log('Handling HarvardKey authentication');
 
-    cy.visit(url);
+      const userInfo = Cypress.env(name);
+      if (!userInfo) {
+        throw new Error(`Could not find ${name} in environment variables`);
+      }
 
-    // Get the Harvard login URL using originWithKaixa with auto-initialized functions
-    cy.origin('https://apps.cirrusidentity.com', () => {
-      Cypress.require('dceky');
+      // Destructure the user info object to get the username and password
+      const { username } = userInfo;
+      const { password } = userInfo;
 
-      return cy.navigateToHref({
-         item: '#idp_1001962798_button', 
-         domain: 'https://apps.cirrusidentity.com'
-        });
-    }).then((fullUrl: any) => {
-      // Navigate to the Harvard login page using originWithKaixa
-      cy.origin('https://harvard.idp.cirrusidentity.com', { 
-        args: { username, password, fullUrl } 
-      }, (args) => {
+      cy.visit(url);
+
+      // Get the Harvard login URL using originWithKaixa with auto-initialized functions
+      cy.origin('https://apps.cirrusidentity.com', () => {
         Cypress.require('dceky');
-        const { username, password, fullUrl } = args;
-        
-        cy.on('uncaught:exception', (e: any) => {
-          // Ignore known HarvardKey errors
-          if (!e.message.includes('ready is not defined')) {
-            throw e;
-          }
-          return false;
+        // 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();
         });
-        
-        cy.visit(fullUrl.toString());
-        
-        // Wait for and fill in the login form using enhanced functions
-        cy.waitForElementVisible('#username');
-        cy.waitForElementVisible('#password');
-        
-        // Add credentials using enhanced functions
-        cy.typeInto({ item: '#username', text: username });
-        cy.typeInto({ item: '#password', text: password });
-        
-        // Submit the form using clickWithRetry
-        cy.clickWithRetry('input[type="submit"], button[type="submit"], .btn-primary');
       });
-    });
-  });
+    },
+  );
 };
 
 /*----------------------------------------*/

package/src/commands/launchAs.ts

@@ -9,19 +9,24 @@ declare global {
     interface Chainable {
       /**
        * Log into Canvas and launch an LTI app as a specific user from environment variables.
-       * The user should be defined as environment variables with the following properties:
-       * - {name}_ACCESS_TOKEN: Canvas access token for the user
-       * - {name}_USERNAME: Username (if no access token)
-       * - {name}_PASSWORD: Password (if using username)
-       * - {name}_IS_XID: Set to 'true' if using XID login
-       * - {name}_TYPE: User type ('student', 'ta', 'teacher') for local mode
-       * - {name}_SIM_INDEX: Simulator index for local mode
-       * @param name the name of the user (used as prefix for environment variables)
-       * @param courseId the Canvas ID of the course to launch from (uses COURSE_ID env var if not provided)
-       * @param appName the name of the app as it appears in the course's left-hand nav (uses APP_NAME env var if not provided)
-       * @example cy.launchAs('student1', 12345, 'My LTI App')
+       * 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, courseId?: number, appName?: string): Chainable<void>;
+      launchAs(
+        name: string,
+        opts?: {
+          courseId?: number,
+          appName?: string,
+        }
+      ): Chainable<void>;
     }
   }
 }
@@ -31,70 +36,81 @@ declare global {
 /*----------------------------------------*/
 
 const launchAs = () => {
-  Cypress.Commands.add('launchAs', (name: string, courseId?: number, appName?: string) => {
-    cy.log(`🚀 Launch as ${name}`);
-
-    // Get default values from environment variables if not provided
-    if (!courseId) {
-      const envCourseId = Cypress.env('COURSE_ID');
-      if (!envCourseId) {
-        throw new Error('courseId parameter is required or COURSE_ID environment variable must be set');
+  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);
       }
-      courseId = parseInt(envCourseId, 10);
-    }
 
-    if (!appName) {
-      appName = Cypress.env('APP_NAME');
+      // Get appName from environment variables if not provided
+      appName = appName || Cypress.env('appName');
       if (!appName) {
-        throw new Error('appName parameter is required or APP_NAME environment variable must be set');
+        throw new Error('Could not find appName in environment variables');
       }
-    }
 
-    // Check if this is a local launch
-    const isLocal = Cypress.env('LOCAL') === 'true';
+      // Get user info from environment variables
+      const userInfo = Cypress.env(name);
+      if (!userInfo) {
+        throw new Error(`Could not find ${name} in environment variables`);
+      }
 
-    if (isLocal) {
-      // Handle local simulator launch
-      const userType = Cypress.env(`${name}_TYPE`) || 'teacher';
-      const simIndex = Cypress.env(`${name}_SIM_INDEX`) || '0';
-      const simLaunchButtonId = `${userType}_${simIndex}-launch-button`;
+      cy.log(`🚀 Launch as ${name}`);
 
-      cy.log('Local mode: launching simulator');
-      cy.visit('https://localhost:8088/simulator');
+      // Check if this is a local launch
+      const isLocal = Cypress.env('local') === 'true';
 
-      // 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();
-        }
-      });
+      if (isLocal) {
+        // Handle local simulator launch
+        const userType = userInfo.type || 'teacher';
+        const simIndex = userInfo.simIndex || '0';
+        const simLaunchButtonId = `${userType}_${simIndex}-launch-button`;
 
-      // Launch the app
-      cy.get(`#${simLaunchButtonId}`).click();
+        cy.log('Local mode: launching simulator');
+        cy.visit('https://localhost:8088/simulator');
 
-      // Check for authorization screen
-      cy.wait(1000);
-      cy.get('body').then(($body) => {
-        if ($body.find('.authorize-button').length > 0) {
-          cy.get('.authorize-button').click();
-        }
-      });
+        // 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();
+          }
+        });
 
-      return;
-    }
+        // Launch the app
+        cy.get(`#${simLaunchButtonId}`).click();
 
-    // Handle production launch with access token
-    const accessToken = Cypress.env(`${name}_ACCESS_TOKEN`);
-    
-    if (!accessToken) {
-      throw new Error(`${name}_ACCESS_TOKEN environment variable is required for user "${name}"`);
-    }
+        // 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);
-  });
+      // Launch using the access token
+      cy.launchLTIUsingToken(accessToken, { courseId, appName });
+    },
+  );
 };
 
 /*----------------------------------------*/

package/src/commands/launchLTIUsingToken.ts

@@ -9,12 +9,20 @@ declare global {
     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 courseId the Canvas ID of the course to launch from
-       * @param appName the name of the app as it appears in the course's left-hand nav
-       * @example cy.launchLTIUsingToken('your_access_token', 12345, 'My LTI App')
+       * @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, courseId: number, appName: string): Chainable<void>;
+      launchLTIUsingToken(
+        accessToken: string,
+        opts?: {
+          courseId?: number,
+          appName?: string,
+        }
+      ): Chainable<void>;
     }
   }
 }
@@ -24,57 +32,80 @@ declare global {
 /*----------------------------------------*/
 
 const launchLTIUsingToken = () => {
-  Cypress.Commands.add('launchLTIUsingToken', (accessToken: string, courseId: number, appName: string) => {
-    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: accessToken
-    }).then((externalTools: any[]) => {
-      cy.log(`Found ${externalTools.length} external tools`);
-
-      // Find the external tool of interest
-      let toolId = 0;
-      
-      for (const externalTool of externalTools) {
-        // Skip non-nav items
-        if (!externalTool.course_navigation || typeof externalTool.course_navigation !== 'object') {
-          continue;
-        }
-
-        // Skip non-labeled items
-        if (!externalTool.course_navigation.text) {
-          continue;
-        }
+  Cypress.Commands.add(
+    'launchLTIUsingToken',
+    (
+      accessToken: string,
+      opts: {
+        courseId?: number,
+        appName?: string,
+      } = {},
+    ) => {
+      let { courseId, appName } = opts;
 
-        // Check if this app matches the name
-        const thisAppName = externalTool.course_navigation.text.trim().toLowerCase();
-        if (thisAppName === appName.trim().toLowerCase()) {
-          toolId = externalTool.id;
-          cy.log(`Found matching app: "${externalTool.course_navigation.text}" with ID ${toolId}`);
-          break;
+      if (!courseId) {
+        const envCourseId = Cypress.env('courseId');
+        if (!envCourseId) {
+          throw new Error('Could not find courseId in environment variables');
         }
+        courseId = Number.parseInt(envCourseId, 10);
       }
 
-      // Make sure we found the app
-      if (toolId === 0) {
-        throw new Error(`Could not find any apps named "${appName}" in course ${courseId}`);
+      appName = appName || Cypress.env('appName');
+      if (!appName) {
+        throw new Error('Could not find appName in environment variables');
       }
 
-      // Get a sessionless launch URL
+      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/sessionless_launch?id=${toolId}`,
-        accessToken: accessToken
-      }).then((sessionlessLaunchInfo: any) => {
-        const launchURL = sessionlessLaunchInfo.url;
-        cy.log(`Launching LTI app at: ${launchURL}`);
-        
-        // Launch the tool
-        cy.visit(launchURL);
+        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);
+        });
       });
-    });
-  });
+    },
+  );
 };
 
 /*----------------------------------------*/