docs(script-sdk): add docs for test, variable, variableList and utils - INS-5589 (#8755)

* chores: add docs for test, utils, variables

* docs: add description for the class

* docs: add docs for varList

packages/insomnia-scripting-environment/src/objects/test.ts

@@ -1,3 +1,4 @@
+/** @ignore */
 export async function test(msg: string, fn: () => Promise<void>, log: (testResult: RequestTestResult) => void) {
   const wrapFn = async () => {
     const started = performance.now();
@@ -30,6 +31,7 @@ export async function test(msg: string, fn: () => Promise<void>, log: (testResul
 }
 
 let testPromises = new Array<Promise<void>>();
+/** ignore */
 export async function waitForAllTestsDone() {
   await Promise.allSettled(testPromises);
   testPromises = [];
@@ -38,6 +40,7 @@ function startTestObserver(promise: Promise<void>) {
   testPromises.push(promise);
 }
 
+/** ignore */
 export async function skip(msg: string, _: () => Promise<void>, log: (testResult: RequestTestResult) => void) {
   log({
     testCase: msg,
@@ -47,8 +50,12 @@ export async function skip(msg: string, _: () => Promise<void>, log: (testResult
   });
 }
 
+/** ignore */
 export type TestStatus = 'passed' | 'failed' | 'skipped';
+/** ignore */
 export type TestCategory = 'unknown' | 'pre-request' | 'after-response';
+
+/** ignore */
 export interface RequestTestResult {
   testCase: string;
   status: TestStatus;
@@ -57,6 +64,7 @@ export interface RequestTestResult {
   category: TestCategory;
 }
 
+/** ignore */
 export interface TestHandler {
   (msg: string, fn: () => Promise<void>): Promise<void>;
   skip?: (msg: string, fn: () => Promise<void>) => void;

packages/insomnia-scripting-environment/src/objects/utils.ts

@@ -1,3 +1,4 @@
+/** ignore */
 export function checkIfUrlIncludesTag(url: string): boolean {
   return /{%/.test(`${url}`) || /%}/.test(`${url}`) || /{{/.test(`${url}`) || /}}/.test(`${url}`);
 }

packages/insomnia-scripting-environment/src/objects/variables.ts

@@ -1,6 +1,16 @@
 import { unsupportedError } from './properties';
 import { Property, PropertyList } from './properties';
 
+/**
+ * Represents the definition of a variable for initializing the {@link Variable} class.
+ *
+ * @property id - (Optional) A unique identifier for the variable.
+ * @property key - The key or identifier for the variable, used for referencing it.
+ * @property name - (Optional) A human-readable name for the variable.
+ * @property value - The value assigned to the variable.
+ * @property type - (Optional) The type of the variable, which can be used for categorization or validation.
+ * @property disabled - (Optional) A flag indicating whether the variable is disabled.
+ */
 export interface VariableDefinition {
   id?: string;
   key: string;
@@ -10,12 +20,38 @@ export interface VariableDefinition {
   disabled?: boolean;
 }
 
+/**
+ * Represents a variable with a unique identifier, value, and type.
+ * This class extends the `Property` class and provides methods to
+ * get and set the variable's value, as well as a utility to cast
+ * a value to its underlying value if it is a `Variable` object.
+ *
+ * @extends Property
+ */
 export class Variable extends Property {
+  /**
+   * Represents the unique identifier for a variable.
+   */
   key: string;
+  /**
+   * Represents the value of a variable, which can be of any type.
+   */
   value: any;
+  /**
+   * The type of the variable, represented as a string.
+   */
   type: string;
+
+  /** @ignore */
   override _kind = 'Variable';
 
+  /**
+   * Constructs a new instance of the class with the provided variable definition.
+   *
+   * @param def - An optional object containing the variable definition. If provided,
+   *              it initializes the instance properties with the values from the object.
+   *              If not provided, default values are used.
+   */
   constructor(def?: VariableDefinition) {
     super();
 
@@ -27,14 +63,21 @@ export class Variable extends Property {
     this.disabled = def ? def.disabled : false;
   }
 
+  /** @ignore */
   static override _index = 'key';
 
   // unknown usage and unsupported
+  /** @ignore */
   static types() {
     throw unsupportedError('types');
   }
 
-  // cast typecasts a value to the Variable.types of this Variable.
+  /**
+   * This method casts the provided value to its underlying value if it is a Variable object.
+   *
+   * @param value - The value to be cast. It can be of any type.
+   * @returns The underlying value of the Variable object if the input is a Variable; otherwise, returns `undefined`.
+   */
   cast(value: any) {
     if ('_kind' in value && value._kind === 'Variable') {
       return value.value;
@@ -42,23 +85,53 @@ export class Variable extends Property {
     return undefined;
   }
 
+  /**
+   * Retrieves the current value of the variable.
+   *
+   * @returns The value of the variable.
+   */
   get() {
     return this.value;
   }
 
+  /**
+   * Sets the value of the variable.
+   *
+   * @param value - The new value to assign to the variable.
+   */
   set(value: any) {
     this.value = value;
   }
 }
 
+/**
+ * A specialized list for managing variables, extending the `PropertyList` class.
+ *
+ * @template T - The type of variable that extends the `Variable` base class.
+ *
+ * @extends PropertyList<T>
+ */
 export class VariableList<T extends Variable> extends PropertyList<T> {
+  /** @ignore */
   override _kind = 'VariableList';
 
+  /**
+   * Constructs a new instance of the class.
+   *
+   * @param parent - The parent `PropertyList` instance, or `undefined` if there is no parent.
+   * @param populate - An array of items of type {@link Variable} used to populate the list.
+   */
   constructor(parent: PropertyList<T> | undefined, populate: T[]) {
     super(Variable, undefined, populate);
     this.parent = parent;
   }
 
+  /**
+   * Determines if the given object is a VariableList.
+   *
+   * @param obj - The object to check.
+   * @returns A boolean indicating whether the object is a VariableList.
+   */
   static isVariableList(obj: any) {
     return '_kind' in obj && obj._kind === 'VariableList';
   }