Merge branch '0.x' into 3487391-media-mgmt-implementation

e2e.js

@@ -7,6 +7,17 @@ import '@testing-library/cypress/add-commands';
 
 const drupalMessages = '[data-drupal-messages]';
 
+/**
+ * Helper function to execute a system command in the test environment.
+ *
+ * Commands are run from the Cypress working directory which corresponds to the
+ * $DDEV_DOCROOT directory.
+ *
+ * @param {string} command
+ *   The command to execute.
+ * @returns {Cypress.Chainable}
+ *   The result of the command execution.
+ */
 const runCommand = (command) => {
   const { env, workingDir, user } = Cypress.env('execOptions') || {};
 
@@ -41,6 +52,24 @@ Cypress.Commands.add('dropButtonAction', { prevSubject: true }, (subject, action
     .findByText(actionText, { selector: 'a' });
 });
 
+/**
+ * Apply a Drupal recipe via `php core/scripts/drupal recipe` command.
+ *
+ * @param {string} [path]
+ *   The path to the recipe. If none is provided apply the recipe that contains
+ *   the current spec file.
+ *
+ * @usage
+ * With no arguments, and assuming the file path
+ * /drupal_cms_seo_basic/tests/e2e/spec.cy.js, this will apply the
+ * drupal_cms_seo_basic recipe.
+ *
+ * cy.applyRecipe();
+ *
+ * Specify the path of the recipe to apply.
+ *
+ * cy.applyRecipe('/path/to/recipe');
+ */
 Cypress.Commands.add('applyRecipe', (path, inputs) => {
   path ??= Cypress.spec.absolute.split('/').slice(0, -3);
 
@@ -60,6 +89,15 @@ Cypress.Commands.add('applyRecipe', (path, inputs) => {
   runCommand(`php core/scripts/drupal recipe ${ path.join('/') } ${options} --no-interaction`);
 });
 
+/**
+ * Install Drupal using the `php core/scripts/test-site.php install` command.
+ *
+ * @param {string} [installProfile]
+ *   Optional installation profile to use for Drupal setup.
+ *
+ * @usage
+ * cy.setUp('standard');
+ */
 Cypress.Commands.add('setUp', (installProfile) => {
   let command = `php core/scripts/test-site.php install --json`;
   if (installProfile) {
@@ -81,7 +119,7 @@ Cypress.Commands.add('setUp', (installProfile) => {
     runCommand(command).then((result) => {
       const { db_prefix, user_agent, site_path } = JSON.parse(result.stdout);
 
-      // We'll need this in the `tearDown` command.
+      // Save database prefix for `tearDown` command.
       Cypress.env('dbPrefix', db_prefix);
 
       // Ensure that commands which get the site path from the
@@ -109,7 +147,10 @@ Cypress.Commands.add('setUp', (installProfile) => {
 });
 
 /**
- * Destroys the test site that was created by `setUp()`.
+ * Tear down the Drupal test environment created by setUp().
+ *
+ * @example
+ * cy.tearDown();
  */
 Cypress.Commands.add('tearDown', () => {
   const dbPrefix = Cypress.env('dbPrefix');
@@ -119,7 +160,15 @@ Cypress.Commands.add('tearDown', () => {
 });
 
 /**
- * Logs in as a specific user, identified by their username.
+ * Log in as a specific Drupal user by username.
+ *
+ * Account password is hard-coded to "password". See drupalCreateUser below.
+ *
+ * @param {string} name
+ *   The username to log in with.
+ *
+ * @example
+ * cy.drupalLogin('admin');
  */
 Cypress.Commands.add('drupalLogin', (name) => {
   Cypress.log({
@@ -135,7 +184,10 @@ Cypress.Commands.add('drupalLogin', (name) => {
 });
 
 /**
- * Logs the current user out.
+ * Log out the currently logged-in user.
+ *
+ * @example
+ * cy.drupalLogout();
  */
 Cypress.Commands.add('drupalLogout', () => {
   cy.visit('/user/logout');
@@ -143,7 +195,17 @@ Cypress.Commands.add('drupalLogout', () => {
 });
 
 /**
- * Creates a user account with a specific name and optional set of roles.
+ * Create a new Drupal user account with a specific username and optional roles.
+ *
+ * New account password is hard-coded to "password".
+ *
+ * @param {string} name
+ *   The username for the new account.
+ * @param {Array<string>} [roles=[]]
+ *   An array of role names to assign to the new user.
+ *
+ * @example
+ * cy.drupalCreateUser('testuser', ['editor']);
  */
 Cypress.Commands.add('drupalCreateUser', (name, roles = []) => {
   cy.visit('/admin/people/create');