@mcpher/gas-fakes 1.2.20 → 1.2.21

package/src/services/formapp/fakeform.js

@@ -1,7 +1,16 @@
 import { Proxies } from '../../support/proxies.js';
 import { newFakeFormItem } from './fakeformitem.js';
+import { newFakeFormResponse } from './fakeformresponse.js';
+import { newFakeGridItem } from './fakegriditem.js';
+import { newFakeCheckboxGridItem } from './fakecheckboxgriditem.js';
+import { newFakeSectionHeaderItem } from './fakesectionheaderitem.js';
+import { newFakeScaleItem } from './fakescaleitem.js';
 import './formitems.js'; // Import for side effects (item class registration)
+import { newFakeMultipleChoiceItem } from './fakemultiplechoiceitem.js';
 import { newFakeCheckboxItem } from './fakecheckboxitem.js';
+import { newFakeListItem } from './fakelistitem.js';
+import { newFakePageBreakItem } from './fakepagebreakitem.js';
+import { newFakeTextItem } from './faketextitem.js';
 
 export const newFakeForm = (...args) => {
   return Proxies.guard(new FakeForm(...args));
@@ -17,19 +26,22 @@ export class FakeForm {
    * @param {object} resource the form resource from Forms API
    */
   constructor(resource) {
+    // Store the resource provided at creation as the single source of truth for this instance.
     this.__id = resource.formId;
     this.__file = DriveApp.getFileById(this.__id);
+    // Since the API doesn't allow setting the published state, we'll manage it internally for the fake.
+    // A new form defaults to accepting responses (true).
+    this.__publishedState = resource.settings?.state !== 'INACTIVE';
   }
 
   get __resource() {
     return Forms.Form.get(this.__id);
   }
-
   saveAndClose() {
     // this is a no-op in fake environment since it is stateless
   }
 
-  _addItem(itemResource, itemFactory) {
+  __addItem(itemResource, itemFactory) {
     const createRequest = Forms.newRequest().setCreateItem({
       item: itemResource,
       location: {
@@ -62,16 +74,178 @@ export class FakeForm {
         question: {
           choiceQuestion: {
             type: 'CHECKBOX',
-            // The API requires at least one non-empty option. Live Apps Script creates one with an empty value.
-            // We'll emulate by creating a default "Option 1" in the fake environment.
+            // The API requires at least one option on creation.
             options: [{ value: 'Option 1' }],
           },
         },
       },
     };
-    return this._addItem(itemResource, newFakeCheckboxItem);
+    return this.__addItem(itemResource, newFakeCheckboxItem);
+  }
+
+  /**
+   * Appends a new question item, presented as a grid of columns and rows, that allows the
+   * respondent to select one choice per row from a sequence of radio buttons.
+   * @returns {import('./fakegriditem.js').FakeGridItem} The new grid item.
+   */
+  addGridItem() {
+    const itemResource = {
+      questionGroupItem: {
+        grid: {
+          columns: {
+            type: 'RADIO',
+            // The API requires at least one column
+            options: [{ value: 'Column 1' }],
+          },
+        },
+        // and at least one row
+        questions: [
+          {
+            rowQuestion: {
+              title: 'Row 1',
+            },
+          },
+        ],
+      },
+    };
+    return this.__addItem(itemResource, newFakeGridItem);
+  }
+
+  /**
+   * Appends a new question item, presented as a grid of columns and rows, that allows the
+   * respondent to select multiple choices per row from a sequence of checkboxes.
+   * @returns {import('./fakecheckboxgriditem.js').FakeCheckboxGridItem} The new checkbox grid item.
+   */
+  addCheckboxGridItem() {
+    const itemResource = {
+      questionGroupItem: {
+        grid: {
+          columns: {
+            type: 'CHECKBOX',
+            // The API requires at least one column
+            options: [{ value: 'Column 1' }],
+          },
+        },
+        // and at least one row
+        questions: [
+          {
+            rowQuestion: {
+              title: 'Row 1',
+            },
+          },
+        ],
+      },
+    };
+    // Note: This will require a newFakeCheckboxGridItem factory.
+    return this.__addItem(itemResource, newFakeCheckboxGridItem);
+  }
+
+  /**
+   * Appends a new layout item that marks the beginning of a new page in the form.
+   * @returns {import('./fakepagebreakitem.js').FakePageBreakItem} The new page-break item.
+   */
+  addPageBreakItem() {
+    const itemResource = {
+      pageBreakItem: {},
+    };
+    return this.__addItem(itemResource, newFakePageBreakItem);
+  }
+
+
+  /**
+   * Appends a new question item that allows the respondent to choose one option
+   * from a drop-down list.
+   * @returns {import('./fakelistitem.js').FakeListItem} The new list item.
+   */
+  addListItem() {
+    const itemResource = {
+      questionItem: {
+        question: {
+          choiceQuestion: {
+            type: 'DROP_DOWN',
+            // The API requires at least one option on creation.
+            options: [{ value: 'Option 1' }],
+          },
+        },
+      },
+    };
+    return this.__addItem(itemResource, newFakeListItem);
+  }
+
+
+  /**
+   * Appends a new question item that allows the respondent to choose one option
+   * from a list of choices.
+   * @returns {import('./fakemultiplechoiceitem.js').FakeMultipleChoiceItem} The new multiple choice item.
+   */
+  addMultipleChoiceItem() {
+    const itemResource = {
+      questionItem: {
+        question: {
+          choiceQuestion: {
+            type: 'RADIO',
+            // The API requires at least one option on creation.
+            options: [{ value: 'Option 1' }],
+          },
+        },
+      },
+    };
+    return this.__addItem(itemResource, newFakeMultipleChoiceItem);
+  }
+
+  /**
+   * Appends a new layout item that visually indicates the start of a section.
+   * @returns {import('./fakesectionheaderitem.js').FakeSectionHeaderItem} The new section header item.
+   */
+  addSectionHeaderItem() {
+    const itemResource = {
+      // The API resource for a section header is an item with a title and description.
+      // It is identified by the presence of the `textItem` property.
+      title: '',
+      textItem: {},
+    };
+    return this.__addItem(itemResource, newFakeSectionHeaderItem);
+  }
+
+  /**
+   * Appends a new question item that allows the respondent to choose one option
+   * from a numbered sequence of radio buttons.
+   * @returns {import('./fakescaleitem.js').FakeScaleItem} The new scale item.
+   */
+  addScaleItem() {
+    const itemResource = {
+      questionItem: {
+        question: {
+          scaleQuestion: {
+            low: 1,
+            high: 5,
+          },
+        },
+      },
+    };
+    return this.__addItem(itemResource, newFakeScaleItem);
+  }
+
+  /**
+   * Appends a new question item that allows the respondent to enter a single
+   * line of text.
+   * @returns {import('./faketextitem.js').FakeTextItem} The new text item.
+   */
+  addTextItem() {
+    const itemResource = {
+      questionItem: {
+        question: {
+          textQuestion: {
+            paragraph: false, // false for short-answer
+          },
+        },
+      },
+    };
+    return this.__addItem(itemResource, newFakeTextItem);
   }
 
+
+
   /**
    * Gets the ID of the form.
    * @returns {string} The form ID.
@@ -89,10 +263,17 @@ export class FakeForm {
     if (!this.__resource.items) {
       return null;
     }
-    // The API uses string IDs, but Apps Script often uses numbers.
-    // We'll handle both by converting the input to a string for comparison.
-    const stringId = id.toString();
-    const itemResource = this.__resource.items.find(item => item.itemId === stringId);
+    const isKnownItem = (id, item) => {
+      if (item.itemId === id) return true;
+      if (item.questionItem?.question?.questionId === id) return true;
+      const qgroup = item.questionGroupItem?.questions
+      if (!qgroup) return false
+      const found = qgroup.some(q => q.questionId === id)
+      return found
+    }
+
+    const itemResource = this.__resource.items.find((item) => isKnownItem(id, item));
+
     if (!itemResource) {
       return null;
     }
@@ -101,10 +282,19 @@ export class FakeForm {
 
   /**
    * Gets all items in the form.
+   * @param {import('../enums/formsenums.js').ItemType} [itemType] If provided, only items of this type are returned.
    * @returns {import('./fakeformitem.js').FakeFormItem[]} An array of all items in the form.
    */
-  getItems() {
-    return this.__resource.items?.map((item) => newFakeFormItem(this, item.itemId)) || [];
+  getItems(itemType) {
+    const allItems = this.__resource.items?.map((item) => newFakeFormItem(this, item.itemId)) || [];
+
+    if (itemType) {
+      // The itemType from the enum will be an object, so we compare its string representation
+      // against the string representation of the item's type.
+      return allItems.filter(item => item.getType().toString() === itemType.toString());
+    }
+
+    return allItems;
   }
 
   /**
@@ -114,7 +304,13 @@ export class FakeForm {
   getTitle() {
     return this.__resource.info.title;
   }
-
+  /**
+   * Gets the title of the form.
+   * @returns {string} The form title.
+   */
+  getDescription() {
+    return this.__resource.info.description;
+  }
   /**
    * Gets the name of the form file in Google Drive.
    * @returns {string} The file name.
@@ -123,6 +319,34 @@ export class FakeForm {
     return this.__file.getName();
   }
 
+  /**
+   * Gets all of the form's responses.
+   * @returns {import('./fakeformresponse.js').FakeFormResponse[]} An array of form responses.
+   */
+  getResponses() {
+    // The advanced Forms service is needed here, but it's an implementation detail of the fake.
+    if (!Forms.Form?.Responses) {
+      throw new Error(
+        'The faked Advanced Forms Service (Forms.Form.Responses) must be available to use getResponses().'
+      );
+    }
+    const responseList = Forms.Form.Responses.list(this.getId());
+    const responses = responseList.responses?.map((r) => newFakeFormResponse(this, r)) || [];
+
+    // The live Apps Script getResponses() method returns responses in chronological order.
+    // The API returns them in reverse chronological order, so we must sort them.
+    return responses.sort((a, b) => a.getTimestamp() - b.getTimestamp());
+  }
+
+  /**
+   * Gets whether the form is accepting responses.
+   * @returns {boolean} true if the form is accepting responses; false otherwise.
+   */
+  isPublished() {
+    // ACTIVE is the state for accepting responses. The default if not set is ACTIVE.
+    return this.__publishedState;
+  }
+
   /**
    * Sets the name of the form file in Google Drive.
    * @param {string} name The new file name.
@@ -133,6 +357,79 @@ export class FakeForm {
     return this;
   }
 
+  /**
+   * Deletes the item at the given index.
+   * @param {import('./fakeformitem.js').FakeFormItem | Integer} itemOrIndex The item to delete, or its 0-indexed position.
+   * @returns {FakeForm} The form, for chaining.
+   */
+  deleteItem(itemOrIndex) {
+    let indexToDelete
+    if (typeof itemOrIndex === 'number') {
+      indexToDelete = itemOrIndex
+    } else if (typeof itemOrIndex === 'object' && typeof itemOrIndex.getIndex === 'function') {
+      // It's an Item object, get its index.
+      indexToDelete = itemOrIndex.getIndex()
+    } else {
+      // This handles the case where an invalid object is passed, which can happen during development.
+      // The error from the API ("Starting an object on a scalar field") is because the fake was
+      // passing the whole object into the batchUpdate request instead of an index.
+      // By handling the object case properly, we now get the correct behavior.
+      throw new Error(
+        `The parameters (${typeof itemOrIndex}) don't match the method signature for FormApp.Form.deleteItem.`
+      )
+    }
+    const deleteRequest = Forms.newRequest().setDeleteItem({
+      location: { index: indexToDelete },
+    });
+    return this.__update(deleteRequest);
+  }
+
+  /**
+   * Moves the given form item to the specified index.
+   * @param {import('./fakeformitem.js').FakeFormItem | Integer} itemOrFrom The item to move, or its 0-indexed position.
+   * @param {Integer} toIndex The 0-indexed position to move the item to.
+   * @returns {import('./fakeformitem.js').FakeFormItem} The moved item.
+   */
+  moveItem(itemOrFrom, toIndex) {
+    let fromIndex;
+    if (typeof itemOrFrom === 'number') {
+      fromIndex = itemOrFrom;
+    } else if (typeof itemOrFrom === 'object' && typeof itemOrFrom.getIndex === 'function') {
+      fromIndex = itemOrFrom.getIndex();
+    } else {
+      throw new Error(`The parameters (${typeof itemOrFrom},number) don't match the method signature for FormApp.Form.moveItem.`);
+    }
+
+    const items = this.getItems();
+    if (fromIndex < 0 || fromIndex >= items.length) {
+      throw new Error(`The starting position ${fromIndex} is out of bounds.`);
+    }
+
+    // The item to return is the one at the original 'from' index.
+    const itemToMove = items[fromIndex];
+    const moveRequest = Forms.newRequest().setMoveItem({
+      originalLocation: { index: fromIndex },
+      newLocation: { index: toIndex },
+    });
+    this.__update(moveRequest);
+    return itemToMove;
+  }
+  /**
+   * Sets whether the form is accepting responses.
+   * @param {boolean} enabled true if the form should accept responses; false otherwise.
+   * @returns {FakeForm} The form, for chaining.
+   */
+  setPublished(enabled) {
+    throw new Error('setPublished is not yet implemented in the fake environment.');
+  }
+
+  __update(updateRequest) {
+    const batchRequest = Forms.newBatchUpdateFormRequest()
+      .setRequests([updateRequest])
+    Forms.Form.batchUpdate(batchRequest, this.getId());
+    return this;
+  }
+
   /**
    * Sets the title of the form.
    * @param {string} title The new title for the form.
@@ -145,12 +442,22 @@ export class FakeForm {
         .setInfo(updateInfo)
         .setUpdateMask("title")
     );
-    const batchRequest = Forms.newBatchUpdateFormRequest()
-      .setRequests([updateRequest]);
-
-    Forms.Form.batchUpdate(batchRequest, this.getId());
+    return this.__update(updateRequest)
+  }
 
-    return this;
+  /**
+   * sets the description of the form.
+   * @param {string} description The new title for the form.
+   * @returns {FakeForm} The form, for chaining.
+   */
+  setDescription(description) {
+    const updateInfo = Forms.newFormInfo().setDescription(description);
+    const updateRequest = Forms.newRequest().setUpdateFormInfo(
+      Forms.newUpdateFormInfoRequest()
+        .setInfo(updateInfo)
+        .setUpdateMask("description")
+    );
+    return this.__update(updateRequest)
   }
 
   /**
@@ -161,6 +468,14 @@ export class FakeForm {
     return `https://docs.google.com/forms/d/${this.getId()}/edit`;
   }
 
+  /**
+   * Gets the URL to respond to the form.
+   * @returns {string} The form URL.
+   */
+  getPublishedUrl() {
+    return `https://docs.google.com/forms/d/e/${this.getId()}/viewform`;
+  }
+
   toString() {
     return 'Form';
   }

package/src/services/formapp/fakeformapp.js

@@ -96,7 +96,7 @@ class FakeFormApp {
   openByUrl(url) {
     const id = Url.getIdFromUrl(url);
     if (!id) {
-      throw new Error(`Invalid form URL: ${url}`);
+      throw new Error(`Invalid argument: url`);
     }
     return this.openById(id);
   }

package/src/services/formapp/fakeformitem.js

@@ -61,7 +61,7 @@ export class FakeFormItem {
   asGridItem() { return this.__cast(ItemType.GRID); }
   asImageItem() { return this.__cast(ItemType.IMAGE); }
   asListItem() { return this.__cast(ItemType.LIST); }
-  asMultipleChoiceItem() { return this.__cast(ItemType.MULTIPLE_CHOICE); }
+  asMultipleChoiceItem() { return this.__cast(ItemType.MULTIPLE_CHOICE, true); }
   asPageBreakItem() { return this.__cast(ItemType.PAGE_BREAK); }
   asParagraphTextItem() { return this.__cast(ItemType.PARAGRAPH_TEXT); }
   asScaleItem() { return this.__cast(ItemType.SCALE); }
@@ -114,7 +114,8 @@ export class FakeFormItem {
   }
 
   getId() {
-    return this.__resource.itemId;
+    // Live Apps Script returns IDs as decimal numbers, not the hex strings from the API.
+    return this.__itemId;
   }
 
   getIndex() {
@@ -148,7 +149,8 @@ export class FakeFormItem {
       if (question.scaleQuestion) return ItemType.SCALE;
       if (question.rowQuestion) return ItemType.GRID;
     } else if (item.questionGroupItem) {
-      const gridType = item.questionGroupItem.grid.columns[0].choiceQuestion.type;
+      // For GRID and CHECKBOX_GRID, columns is an object, not an array.
+      const gridType = item.questionGroupItem.grid.columns.type;
       return gridType === 'RADIO' ? ItemType.GRID : ItemType.CHECKBOX_GRID;
     } else if (item.pageBreakItem) {
       return ItemType.PAGE_BREAK;
@@ -161,6 +163,12 @@ export class FakeFormItem {
     }
     throw new Error(`Unknown item type for resource: ${JSON.stringify(item)}`);
   }
+  __update(updateRequest) {
+    const response = this.__form.__update(updateRequest);
+    // The local resource is now stale, so we need to update it.
+    // The response from batchUpdate contains the updated form resource.
+    return this;
+  }
 
   setHelpText(text) {
     const { nargs, matchThrow } = signatureArgs(arguments, 'Item.setHelpText');
@@ -181,10 +189,7 @@ export class FakeFormItem {
       // Crucially, only ask the API to update the description field.
       updateMask: 'description',
     });
-
-    const batchRequest = Forms.newBatchUpdateFormRequest().setRequests([updateRequest]);
-    Forms.Form.batchUpdate(batchRequest, this.__form.getId());
-    return this;
+    return this.__update (updateRequest)
   }
 
   setTitle(title) {
@@ -207,9 +212,56 @@ export class FakeFormItem {
       updateMask: 'title',
     });
 
-    const batchRequest = Forms.newBatchUpdateFormRequest().setRequests([updateRequest]);
-    Forms.Form.batchUpdate(batchRequest, this.__form.getId());
-    return this;
+    return this.__update (updateRequest)
+
+  }
+
+  /**
+   * Determines whether the respondent must answer the question.
+   * @returns {boolean} whether the respondent must answer the question
+   */
+  isRequired() {
+    if (this.__resource.questionItem) {
+      return this.__resource.questionItem.question.required || false;
+    } else if (this.__resource.questionGroupItem) {
+      return this.__resource.questionGroupItem.questions?.some(q => q.required) || false;
+    }
+    return false;
+  }
+
+  /**
+   * Sets whether the respondent must answer the question.
+   * @param {boolean} enabled
+   * @returns {FakeFormItem} the current item (for chaining)
+   */
+  setRequired(enabled) {
+    const { nargs, matchThrow } = signatureArgs(arguments, 'Item.setRequired');
+    if (nargs !== 1 || !is.boolean(enabled)) matchThrow('Invalid arguments');
+
+    let updateMask;
+    const updatedResource = JSON.parse(JSON.stringify(this.__resource));
+
+    if (updatedResource.questionItem) {
+      updatedResource.questionItem.question.required = enabled;
+      updateMask = 'questionItem.question.required';
+    } else if (updatedResource.questionGroupItem) {
+      if (updatedResource.questionGroupItem.questions) {
+        updatedResource.questionGroupItem.questions.forEach(q => {
+          q.required = enabled;
+        });
+      }
+      updateMask = 'questionGroupItem.questions';
+    } else {
+      throw new Error('This item type does not support setRequired.');
+    }
+
+    const updateRequest = Forms.newRequest().setUpdateItem({
+      item: updatedResource,
+      location: { index: this.getIndex() },
+      updateMask: updateMask,
+    });
+
+    return this.__update (updateRequest)
   }
 
   toString() {

package/src/services/formapp/fakeformresponse.js

@@ -0,0 +1,84 @@
+import { Proxies } from '../../support/proxies.js';
+import { newFakeItemResponse } from './fakeitemresponse.js';
+
+export const newFakeFormResponse = (...args) => {
+  return Proxies.guard(new FakeFormResponse(...args));
+};
+
+/**
+ * @class FakeFormResponse
+ * @see https://developers.google.com/apps-script/reference/forms/form-response
+ */
+export class FakeFormResponse {
+  /**
+   *
+   * @param {import('./fakeform.js').FakeForm} form the parent form
+   * @param {object} resource the response resource from the Forms API
+   */
+  constructor(form, resource) {
+    this.__form = form;
+    this.__resource = resource;
+  }
+
+  /**
+   * Gets the email address of the respondent.
+   * @returns {string} the respondent's email
+   */
+  getRespondentEmail() {
+    return this.__resource.respondentEmail || '';
+  }
+
+  /**
+   * Gets the unique ID for this form response.
+   * @returns {string} the unique ID
+   */
+  getId() {
+    return this.__resource.responseId;
+  }
+
+  /**
+   * Gets the date and time the response was submitted.
+   * @returns {Date} the submission timestamp
+   */
+  getTimestamp() {
+    return new Date(this.__resource.lastSubmittedTime);
+  }
+
+  /**
+   * Gets all item responses contained in the form response.
+   * @returns {import('./fakeitemresponse.js').FakeItemResponse[]} an array of item responses
+   */
+  getItemResponses() {
+    if (!this.__resource.answers) {
+      return [];
+    }
+
+    // Create a map to group answers by their parent form item. This is crucial for grid items,
+    // where each row is a separate answer in the API response but should be consolidated
+    // into a single ItemResponse in Apps Script.
+    const groupedAnswers = new Map();
+
+    for (const [questionId, answer] of Object.entries(this.__resource.answers)) {
+      const item = this.__form.getItemById(questionId);
+
+      if (item) {
+        const itemId = item.getId(); // Use the unique item ID as the key.
+        if (!groupedAnswers.has(itemId)) {
+          // Store the item itself along with an array for its answers.
+          groupedAnswers.set(itemId, { item, answers: [] });
+        }
+        // Add the raw answer object from the API response to the item's answer list.
+        // This correctly groups all row answers for a grid under the same parent item.
+        groupedAnswers.get(itemId).answers.push(answer);
+      }
+    }
+
+    // Now, create one FakeItemResponse for each grouped item.
+    const itemResponses = Array.from(groupedAnswers.values()).map(({ item, answers }) => {
+      return newFakeItemResponse(item, answers);
+    });
+
+    // Finally, sort the responses based on the item's index in the form.
+    return itemResponses.sort((a, b) => a.getItem().getIndex() - b.getItem().getIndex());
+  }
+}