@leaflink/dom-testing-utils 0.0.0-PR-140--ed3e542 → 0.0.0-PR-143--b0c0342

package/dist/utils/assertSelectElementItems.d.ts

@@ -0,0 +1,46 @@
+export interface AssertSelectElementItemsArgs {
+    /** The select element to check. If omitted, `label` is used to find it. */
+    element?: HTMLSelectElement;
+    /** Accessible name of the select element; used when `element` is not provided. */
+    label?: string;
+    /** Expected selected value or array of values. */
+    values: string | string[];
+    /** Root container to scope the query; defaults to document.body. */
+    withinElement?: HTMLElement;
+}
+/**
+ * Asserts that the selected values of a <select> element match the expected values.
+ *
+ * @example
+ * ```ts
+ * // single value
+ * assertSelectElementItems({
+ *   label: 'Fruits',
+ *   values: 'apple',
+ *   withinElement: container,
+ * });
+ *
+ * // multiple values
+ * assertSelectElementItems({
+ *   label: 'Fruits',
+ *   values: ['apple', 'banana'],
+ *   withinElement: container,
+ * });
+ *
+ * // using element directly
+ * const select = container.querySelector<HTMLSelectElement>('#fruit-select');
+ * assertSelectElementItems({
+ *   element: selectElement,
+ *   values: ['apple', 'banana'],
+ *   withinElement: container,
+ * });
+ * ```
+ *
+ * @param options                      Options for assertion.
+ * @param [options.element]            The select element to check. If omitted, `label` is used to find it.
+ * @param [options.label]              Accessible name of the select element; used when `element` is not provided.
+ * @param options.values               Expected selected value or array of values.
+ * @param [options.withinElement]      Root container to scope the query; defaults to document.body.
+ * @returns void
+ */
+export default function assertSelectElementItems({ element, label, values, withinElement, }: AssertSelectElementItemsArgs): void;

package/dist/utils/assertSelectElementItems.js

@@ -0,0 +1,43 @@
+import getSelectElementItems from './getSelectElementItems';
+/**
+ * Asserts that the selected values of a <select> element match the expected values.
+ *
+ * @example
+ * ```ts
+ * // single value
+ * assertSelectElementItems({
+ *   label: 'Fruits',
+ *   values: 'apple',
+ *   withinElement: container,
+ * });
+ *
+ * // multiple values
+ * assertSelectElementItems({
+ *   label: 'Fruits',
+ *   values: ['apple', 'banana'],
+ *   withinElement: container,
+ * });
+ *
+ * // using element directly
+ * const select = container.querySelector<HTMLSelectElement>('#fruit-select');
+ * assertSelectElementItems({
+ *   element: selectElement,
+ *   values: ['apple', 'banana'],
+ *   withinElement: container,
+ * });
+ * ```
+ *
+ * @param options                      Options for assertion.
+ * @param [options.element]            The select element to check. If omitted, `label` is used to find it.
+ * @param [options.label]              Accessible name of the select element; used when `element` is not provided.
+ * @param options.values               Expected selected value or array of values.
+ * @param [options.withinElement]      Root container to scope the query; defaults to document.body.
+ * @returns void
+ */
+export default function assertSelectElementItems({ element, label, values, withinElement, }) {
+    const selectedValues = getSelectElementItems({ element, label, withinElement });
+    const expectedValues = typeof values === 'string' ? [values] : values;
+    // Assert the selectedOptions match exactly
+    expect(selectedValues).toEqual(expectedValues);
+}
+//# sourceMappingURL=assertSelectElementItems.js.map

package/dist/utils/assertSelectElementItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertSelectElementItems.js","sourceRoot":"src/","sources":["utils/assertSelectElementItems.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,MAAM,yBAAyB,CAAC;AAa5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAAC,EAC/C,OAAO,EACP,KAAK,EACL,MAAM,EACN,aAAa,GACgB;IAC7B,MAAM,cAAc,GAAG,qBAAqB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;IAChF,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAEtE,2CAA2C;IAC3C,MAAM,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;AACjD,CAAC"}

package/dist/utils/getRandomItemsFromArray.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Retrieves multiple items from an array without selecting the same element twice.
+ *
+ * @param arr                   The array to pick items from.
+ * @param numOfItemsToSelect    Number of unique items to select.
+ * @returns An array of selected items.
+ */
+export default function getRandomItemsFromArray<T>(arr: T[], numOfItemsToSelect: number): T[];

package/dist/utils/getRandomItemsFromArray.js

@@ -0,0 +1,23 @@
+/**
+ * Retrieves multiple items from an array without selecting the same element twice.
+ *
+ * @param arr                   The array to pick items from.
+ * @param numOfItemsToSelect    Number of unique items to select.
+ * @returns An array of selected items.
+ */
+export default function getRandomItemsFromArray(arr, numOfItemsToSelect) {
+    if (arr.length < numOfItemsToSelect) {
+        throw new Error(`Cannot select ${numOfItemsToSelect} unique items from an array that only has ${arr.length} items`);
+    }
+    const copiedArray = [...arr];
+    const selectedItems = [];
+    while (selectedItems.length < numOfItemsToSelect) {
+        // Get a random index
+        const index = Math.floor(Math.random() * copiedArray.length);
+        // Remove the item from the array so we don't select it again
+        const itemSelected = copiedArray.splice(index, 1);
+        selectedItems.push(itemSelected[0]);
+    }
+    return selectedItems;
+}
+//# sourceMappingURL=getRandomItemsFromArray.js.map

package/dist/utils/getRandomItemsFromArray.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRandomItemsFromArray.js","sourceRoot":"src/","sources":["utils/getRandomItemsFromArray.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAAI,GAAQ,EAAE,kBAA0B;IACrF,IAAI,GAAG,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,iBAAiB,kBAAkB,6CAA6C,GAAG,CAAC,MAAM,QAAQ,CAAC,CAAC;IACtH,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;IAE7B,MAAM,aAAa,GAAQ,EAAE,CAAC;IAC9B,OAAO,aAAa,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACjD,qBAAqB;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QAE7D,6DAA6D;QAC7D,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAClD,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/utils/getSelectElementByLabel.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Retrieves a <select> element by its associated label text.
+ *
+ * @param label               The text of the label to find the select element.
+ * @param [withinElement]     Root container to scope the query; defaults to document body.
+ * @returns The matched select element or null.
+ */
+export default function getSelectElementByLabel(label: string, withinElement?: HTMLElement): HTMLSelectElement | null;

package/dist/utils/getSelectElementByLabel.js

@@ -0,0 +1,38 @@
+import { within } from '@testing-library/vue';
+/**
+ * Retrieves a <select> element by its associated label text.
+ *
+ * @param label               The text of the label to find the select element.
+ * @param [withinElement]     Root container to scope the query; defaults to document body.
+ * @returns The matched select element or null.
+ */
+export default function getSelectElementByLabel(label, withinElement) {
+    if (!label) {
+        throw new Error('a select element or its associated label is required.');
+    }
+    let selectElement;
+    const scope = {
+        ...within(withinElement || document.body),
+        element: withinElement || document.body,
+    };
+    if (scope.queryAllByLabelText(label, { selector: 'select', exact: false }).length === 1) {
+        selectElement = scope.queryByLabelText(label, { selector: 'select', exact: false });
+    }
+    else {
+        // Escapes metacharacters in the provided regular expression
+        const escapedLabel = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').trim();
+        // Multiple elements could have the label (like a placeholder)
+        const elementsWithLabelText = scope.getAllByText(new RegExp(`^${escapedLabel.replace(/\s/g, '\\s')}$`, 'i'));
+        // Find the label within the matching elements
+        const selectLabel = elementsWithLabelText.find((e) => e.tagName.toLowerCase() === 'label');
+        if (!selectLabel) {
+            throw new Error(`Could not find label with text ${label}`);
+        }
+        const labelFor = selectLabel.getAttribute('for');
+        // LL Select is a huge pain to get selected correctly.  Using query selectors for now
+        // eslint-disable-next-line testing-library/no-node-access
+        selectElement = scope.element.querySelector(`#${labelFor}`);
+    }
+    return selectElement;
+}
+//# sourceMappingURL=getSelectElementByLabel.js.map

package/dist/utils/getSelectElementByLabel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSelectElementByLabel.js","sourceRoot":"src/","sources":["utils/getSelectElementByLabel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAAC,KAAa,EAAE,aAA2B;IACxF,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,aAAuC,CAAC;IAE5C,MAAM,KAAK,GAAG;QACZ,GAAG,MAAM,CAAC,aAAa,IAAI,QAAQ,CAAC,IAAI,CAAC;QACzC,OAAO,EAAE,aAAa,IAAI,QAAQ,CAAC,IAAI;KACxC,CAAC;IAEF,IAAI,KAAK,CAAC,mBAAmB,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxF,aAAa,GAAG,KAAK,CAAC,gBAAgB,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtF,CAAC;SAAM,CAAC;QACN,4DAA4D;QAC5D,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAEzE,8DAA8D;QAC9D,MAAM,qBAAqB,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,IAAI,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAE7G,8CAA8C;QAC9C,MAAM,WAAW,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,CAAC;QAE3F,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,kCAAkC,KAAK,EAAE,CAAC,CAAC;QAC7D,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAEjD,qFAAqF;QACrF,0DAA0D;QAC1D,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAoB,IAAI,QAAQ,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/utils/getSelectElementItems.d.ts

@@ -0,0 +1,18 @@
+export interface GetSelectElementItemsArgs {
+    /** The select element to query. */
+    element?: HTMLSelectElement;
+    /** Accessible name to find the select element. */
+    label?: string;
+    /** Root container to scope the query; defaults to document.body. */
+    withinElement?: HTMLElement;
+}
+/**
+ * Returns the selected option values from a <select> element.
+ *
+ * @param args                    Options for retrieving selected items.
+ * @param [args.element]          The select element to query.
+ * @param [args.label]            Accessible name to find the select element.
+ * @param [args.withinElement]    Root container to scope the query; defaults to document.body.
+ * @returns The array of selected option values.
+ */
+export default function getSelectElementItems({ element, label, withinElement }: GetSelectElementItemsArgs): string[];

package/dist/utils/getSelectElementItems.js

@@ -0,0 +1,19 @@
+import getSelectElementOptions from './getSelectElementOptions';
+/**
+ * Returns the selected option values from a <select> element.
+ *
+ * @param args                    Options for retrieving selected items.
+ * @param [args.element]          The select element to query.
+ * @param [args.label]            Accessible name to find the select element.
+ * @param [args.withinElement]    Root container to scope the query; defaults to document.body.
+ * @returns The array of selected option values.
+ */
+export default function getSelectElementItems({ element, label, withinElement }) {
+    const options = getSelectElementOptions({
+        element,
+        label,
+        withinElement,
+    });
+    return options.filter(({ selected }) => Boolean(selected)).map(({ value }) => value);
+}
+//# sourceMappingURL=getSelectElementItems.js.map

package/dist/utils/getSelectElementItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSelectElementItems.js","sourceRoot":"src/","sources":["utils/getSelectElementItems.ts"],"names":[],"mappings":"AAAA,OAAO,uBAAuB,MAAM,2BAA2B,CAAC;AAWhE;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAA6B;IACxG,MAAM,OAAO,GAAG,uBAAuB,CAAC;QACtC,OAAO;QACP,KAAK;QACL,aAAa;KACd,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;AACvF,CAAC"}

package/dist/utils/getSelectElementOptions.d.ts

@@ -0,0 +1,24 @@
+export interface GetSelectElementOptionsArgs {
+    /** Accessible name to find the select element. */
+    label?: string;
+    /** The select element to query. */
+    element?: HTMLSelectElement;
+    /** Root container to scope the query; defaults to document.body. */
+    withinElement?: HTMLElement;
+    /** Exclude disabled options if true. */
+    excludeDisabled?: boolean;
+    /** Exclude empty-value options if true. */
+    excludeEmpty?: boolean;
+}
+/**
+ * Returns the array of <option> elements from a <select> element.
+ *
+ * @param args                    Options for retrieving select element options.
+ * @param [args.element]          The select element to query.
+ * @param [args.label]            Accessible name to find the select element.
+ * @param [args.withinElement]    Root container to scope the query; defaults to document.body.
+ * @param [args.excludeDisabled]  Exclude disabled options if true.
+ * @param [args.excludeEmpty]     Exclude empty-value options if true.
+ * @returns The array of option elements.
+ */
+export default function getSelectElementOptions({ element, label, withinElement, excludeDisabled, excludeEmpty, }?: GetSelectElementOptionsArgs): HTMLOptionElement[];

package/dist/utils/getSelectElementOptions.js

@@ -0,0 +1,38 @@
+import { within } from '@testing-library/vue';
+import getSelectElementByLabel from './getSelectElementByLabel';
+/**
+ * Returns the array of <option> elements from a <select> element.
+ *
+ * @param args                    Options for retrieving select element options.
+ * @param [args.element]          The select element to query.
+ * @param [args.label]            Accessible name to find the select element.
+ * @param [args.withinElement]    Root container to scope the query; defaults to document.body.
+ * @param [args.excludeDisabled]  Exclude disabled options if true.
+ * @param [args.excludeEmpty]     Exclude empty-value options if true.
+ * @returns The array of option elements.
+ */
+export default function getSelectElementOptions({ element, label, withinElement, excludeDisabled = false, excludeEmpty = true, } = {}) {
+    let selectElement = null;
+    if (element) {
+        selectElement = element;
+    }
+    else if (label) {
+        selectElement = getSelectElementByLabel(label, withinElement);
+    }
+    else {
+        throw new Error('a select element or its associated label is required.');
+    }
+    if (!selectElement) {
+        throw new Error('Could not find select element');
+    }
+    const options = within(selectElement)
+        .getAllByRole('option')
+        .filter((opt) => {
+        if (excludeDisabled && opt.disabled) {
+            return false;
+        }
+        return (excludeEmpty && opt.value !== '') || true;
+    });
+    return options;
+}
+//# sourceMappingURL=getSelectElementOptions.js.map

package/dist/utils/getSelectElementOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSelectElementOptions.js","sourceRoot":"src/","sources":["utils/getSelectElementOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,uBAAuB,MAAM,2BAA2B,CAAC;AAehE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAAC,EAC9C,OAAO,EACP,KAAK,EACL,aAAa,EACb,eAAe,GAAG,KAAK,EACvB,YAAY,GAAG,IAAI,MACY,EAAE;IACjC,IAAI,aAAa,GAA6B,IAAI,CAAC;IAEnD,IAAI,OAAO,EAAE,CAAC;QACZ,aAAa,GAAG,OAAO,CAAC;IAC1B,CAAC;SAAM,IAAI,KAAK,EAAE,CAAC;QACjB,aAAa,GAAG,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC;SAClC,YAAY,CAAoB,QAAQ,CAAC;SACzC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;QACd,IAAI,eAAe,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC;IACpD,CAAC,CAAC,CAAC;IAEL,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/getSelectElementValues.d.ts

@@ -0,0 +1,14 @@
+import { type GetSelectElementOptionsArgs } from './getSelectElementOptions';
+export type GetSelectElementValuesArgs = GetSelectElementOptionsArgs;
+/**
+ * Returns the values of options from a <select> element.
+ *
+ * @param args                    Options for retrieving select element values.
+ * @param [args.element]          The select element to query.
+ * @param [args.label]            Accessible name to find the select element.
+ * @param [args.withinElement]    Root container to scope the query; defaults to document.body.
+ * @param [args.excludeDisabled]  Exclude disabled options if true.
+ * @param [args.excludeEmpty]     Exclude empty-value options if true.
+ * @returns The array of option values.
+ */
+export default function getSelectElementValues({ element, label, withinElement, excludeDisabled, excludeEmpty, }?: GetSelectElementValuesArgs): string[];

package/dist/utils/getSelectElementValues.js

@@ -0,0 +1,23 @@
+import getSelectElementOptions from './getSelectElementOptions';
+/**
+ * Returns the values of options from a <select> element.
+ *
+ * @param args                    Options for retrieving select element values.
+ * @param [args.element]          The select element to query.
+ * @param [args.label]            Accessible name to find the select element.
+ * @param [args.withinElement]    Root container to scope the query; defaults to document.body.
+ * @param [args.excludeDisabled]  Exclude disabled options if true.
+ * @param [args.excludeEmpty]     Exclude empty-value options if true.
+ * @returns The array of option values.
+ */
+export default function getSelectElementValues({ element, label, withinElement, excludeDisabled = false, excludeEmpty = true, } = {}) {
+    const options = getSelectElementOptions({
+        element,
+        label,
+        withinElement,
+        excludeDisabled,
+        excludeEmpty,
+    });
+    return options.map(({ value }) => value);
+}
+//# sourceMappingURL=getSelectElementValues.js.map

package/dist/utils/getSelectElementValues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSelectElementValues.js","sourceRoot":"src/","sources":["utils/getSelectElementValues.ts"],"names":[],"mappings":"AAAA,OAAO,uBAA6D,MAAM,2BAA2B,CAAC;AAItG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,OAAO,UAAU,sBAAsB,CAAC,EAC7C,OAAO,EACP,KAAK,EACL,aAAa,EACb,eAAe,GAAG,KAAK,EACvB,YAAY,GAAG,IAAI,MACW,EAAE;IAChC,MAAM,OAAO,GAAG,uBAAuB,CAAC;QACtC,OAAO;QACP,KAAK;QACL,aAAa;QACb,eAAe;QACf,YAAY;KACb,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC"}

package/dist/utils/setSelectElementItems.d.ts

@@ -0,0 +1,21 @@
+export interface SetSelectElementItemsArgs {
+    /** The select element to target. If omitted, `label` is used to find it. */
+    element?: HTMLSelectElement;
+    /** Accessible name of the select element; used when `element` is not provided. */
+    label?: string;
+    /** Array of values to select. */
+    selectedOptionValues: string[];
+    /** Root container to scope the query. */
+    withinElement?: HTMLElement;
+}
+/**
+ * Sets the selected option values on a <select> element.
+ *
+ * @param args                     Options for setting select items.
+ * @param [args.element]           The select element to target. If omitted, `label` is used to find it.
+ * @param [args.label]             Accessible name of the select element; used when `element` is not provided.
+ * @param args.selectedOptionValues Array of values to select.
+ * @param [args.withinElement]     Root container to scope the query; defaults to document.body.
+ * @returns Promise<void>
+ */
+export default function setSelectElementItems({ element, label, selectedOptionValues, withinElement, }: SetSelectElementItemsArgs): Promise<void>;

package/dist/utils/setSelectElementItems.js

@@ -0,0 +1,29 @@
+import userEvent from '@testing-library/user-event';
+import getSelectElementByLabel from './getSelectElementByLabel';
+/**
+ * Sets the selected option values on a <select> element.
+ *
+ * @param args                     Options for setting select items.
+ * @param [args.element]           The select element to target. If omitted, `label` is used to find it.
+ * @param [args.label]             Accessible name of the select element; used when `element` is not provided.
+ * @param args.selectedOptionValues Array of values to select.
+ * @param [args.withinElement]     Root container to scope the query; defaults to document.body.
+ * @returns Promise<void>
+ */
+export default async function setSelectElementItems({ element, label, selectedOptionValues, withinElement, }) {
+    let selectElement = null;
+    if (element) {
+        selectElement = element;
+    }
+    else if (label) {
+        selectElement = getSelectElementByLabel(label, withinElement);
+    }
+    else {
+        throw new Error('a select element or its associated label is required.');
+    }
+    if (!selectElement) {
+        throw new Error('Could not find select element');
+    }
+    await userEvent.selectOptions(selectElement, selectedOptionValues);
+}
+//# sourceMappingURL=setSelectElementItems.js.map

package/dist/utils/setSelectElementItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setSelectElementItems.js","sourceRoot":"src/","sources":["utils/setSelectElementItems.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,6BAA6B,CAAC;AAEpD,OAAO,uBAAuB,MAAM,2BAA2B,CAAC;AAahE;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,qBAAqB,CAAC,EAClD,OAAO,EACP,KAAK,EACL,oBAAoB,EACpB,aAAa,GACa;IAC1B,IAAI,aAAa,GAA6B,IAAI,CAAC;IAEnD,IAAI,OAAO,EAAE,CAAC;QACZ,aAAa,GAAG,OAAO,CAAC;IAC1B,CAAC;SAAM,IAAI,KAAK,EAAE,CAAC;QACjB,aAAa,GAAG,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,SAAS,CAAC,aAAa,CAAC,aAAa,EAAE,oBAAoB,CAAC,CAAC;AACrE,CAAC"}

package/dist/utils/setSelectElementRandomItems.d.ts

@@ -0,0 +1,21 @@
+export interface SetSelectElementRandomItemsArgs {
+    /** The select element to target. If omitted, `label` is used to find it. */
+    element?: HTMLSelectElement;
+    /** Accessible name of the select element; used when element is not provided. */
+    label?: string;
+    /** Number of items to randomly select. */
+    numOfItems: number;
+    /** Root container to scope the query; defaults to document.body. */
+    withinElement?: HTMLElement;
+}
+/**
+ * Sets a random selection of options on a <select> element.
+ *
+ * @param args                   Options for random selection.
+ * @param [args.element]         The select element to target. If omitted, `label` is used to find it.
+ * @param [args.label]           Accessible name of the select element; used when element is not provided.
+ * @param args.numOfItems        Number of items to randomly select.
+ * @param [args.withinElement]   Root container to scope the query; defaults to document.body.
+ * @returns The array of selected option values.
+ */
+export default function setSelectElementRandomItems({ element, label, numOfItems, withinElement, }: SetSelectElementRandomItemsArgs): Promise<HTMLOptionElement[]>;

package/dist/utils/setSelectElementRandomItems.js

@@ -0,0 +1,41 @@
+import userEvent from '@testing-library/user-event';
+import getRandomItemsFromArray from './getRandomItemsFromArray';
+import getSelectElementByLabel from './getSelectElementByLabel';
+import getSelectElementOptions from './getSelectElementOptions';
+/**
+ * Sets a random selection of options on a <select> element.
+ *
+ * @param args                   Options for random selection.
+ * @param [args.element]         The select element to target. If omitted, `label` is used to find it.
+ * @param [args.label]           Accessible name of the select element; used when element is not provided.
+ * @param args.numOfItems        Number of items to randomly select.
+ * @param [args.withinElement]   Root container to scope the query; defaults to document.body.
+ * @returns The array of selected option values.
+ */
+export default async function setSelectElementRandomItems({ element, label, numOfItems, withinElement, }) {
+    let selectElement = null;
+    if (element) {
+        selectElement = element;
+    }
+    else if (label) {
+        selectElement = getSelectElementByLabel(label, withinElement);
+    }
+    else {
+        throw new Error('a select element or its associated label is required.');
+    }
+    if (!selectElement) {
+        throw new Error('Could not find select element');
+    }
+    // Clear the drop down
+    await userEvent.deselectOptions(selectElement, [...selectElement.selectedOptions].map(({ value }) => value));
+    // Exclude empty option from our available value choices
+    const availableOptions = getSelectElementOptions({ element, label, withinElement, excludeEmpty: true });
+    // Make sure we have enough options
+    if (availableOptions.length < numOfItems) {
+        throw new Error(`Not enough options to select ${numOfItems} from the select element`);
+    }
+    const selectedOptionValues = getRandomItemsFromArray(availableOptions, numOfItems);
+    await userEvent.selectOptions(selectElement, selectedOptionValues);
+    return selectedOptionValues;
+}
+//# sourceMappingURL=setSelectElementRandomItems.js.map

package/dist/utils/setSelectElementRandomItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setSelectElementRandomItems.js","sourceRoot":"src/","sources":["utils/setSelectElementRandomItems.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,6BAA6B,CAAC;AAEpD,OAAO,uBAAuB,MAAM,2BAA2B,CAAC;AAChE,OAAO,uBAAuB,MAAM,2BAA2B,CAAC;AAChE,OAAO,uBAAuB,MAAM,2BAA2B,CAAC;AAahE;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,2BAA2B,CAAC,EACxD,OAAO,EACP,KAAK,EACL,UAAU,EACV,aAAa,GACmB;IAChC,IAAI,aAAa,GAA6B,IAAI,CAAC;IAEnD,IAAI,OAAO,EAAE,CAAC;QACZ,aAAa,GAAG,OAAO,CAAC;IAC1B,CAAC;SAAM,IAAI,KAAK,EAAE,CAAC;QACjB,aAAa,GAAG,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IAED,sBAAsB;IACtB,MAAM,SAAS,CAAC,eAAe,CAC7B,aAAa,EACb,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAC7D,CAAC;IAEF,wDAAwD;IACxD,MAAM,gBAAgB,GAAG,uBAAuB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAExG,mCAAmC;IACnC,IAAI,gBAAgB,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,gCAAgC,UAAU,0BAA0B,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,oBAAoB,GAAG,uBAAuB,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;IACnF,MAAM,SAAS,CAAC,aAAa,CAAC,aAAa,EAAE,oBAAoB,CAAC,CAAC;IAEnE,OAAO,oBAAoB,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leaflink/dom-testing-utils",
-  "version": "0.0.0-PR-140--ed3e542",
+  "version": "0.0.0-PR-143--b0c0342",
   "description": "Frontend DOM testing utilities",
   "engines": {
     "node": ">=18",
@@ -46,7 +46,7 @@
     "@vitest/coverage-v8": "^3.0.9",
     "eslint": "^8.49.0",
     "eslint-config-leaflink": "^3.5.0",
-    "jsdom": "^26.1.0",
+    "jsdom": "^22.1.0",
     "typescript": "^5.8.2",
     "vite": "^6.2.2",
     "vitest": "^3.0.9"