@leaflink/dom-testing-utils

Leaflink repository to manage test utilities to be shared across front-end applications.

• Installation
• Usage
  • Setup file
  • Global setup
• Utilities
  • cleanupNoty
  • waitForLoading
  • cleanupDropdowns
  • assertAndDismissNoty
  • getByDescriptionTerm
  • getAllByDescriptionTerm
  • getSelectedOption
  • getSelectedOptions
  • createFixtureGenerator
  • Mocking API Endpoints

Installation

npm install --save-dev @leaflink/dom-testing-utils

Usage

In your test files you can import utility functions.

import {
  waitForLoading,
  cleanupDropdowns,
  assertAndDismissNoty,
  cleanupNoty,
  createFixtureGenerator,
} from '@leaflink/dom-testing-utils';

it('...', () => {
  cleanupNoty();
});

Setup file

Import @leaflink/dom-testing-utils/setup-env once (for instance in your tests setup file) and you're good to go:

Note: @testing-library/jest-dom is auto-imported from @leaflink/dom-testing-utils so you don't have to.

// In your own setup-env.ts (or any other name)
import '@leaflink/dom-testing-utils/setup-env'
// DON'T import `@testing-library/jest-dom` is auto imported from dom-testing-utils

// In vite.config.ts add (if you haven't already)
setupFiles: ['tests/setup-env.js'],

// In jest.config.js add (if you haven't already)
setupFilesAfterEnv: ['<rootDir>/tests/setup-env.js']

This will be run once before each test file. See https://vitest.dev/config/#setupfiles.

Global setup

Add the following import to your test config:

// In vite.config.ts add
globalSetup: ['node_modules/@leaflink/dom-testing-utils/dist/global-setup.js'],

// In jest.config.js add
globalSetup: ['<rootDir>/node_modules/@leaflink/dom-testing-utils/dist/global-setup.js']

This will run once before everything. See https://vitest.dev/config/#globalsetup.

Utilities

cleanupNoty

Helper method to remove all noty alerts from the DOM.

Parameters: None

Returns: void

waitForLoading

Utility that waits for all loading elements to be removed from the DOM. The data-test argument defaults to ll-loading or loading-spinner if testId is not specified.

Parameters	Type	Default	Summary
testId	string	ll-loading && loading-spinner	The data test ID to target.
timeout	number	2000	How long to wait for loading elements to be removed
failIfNull	boolean	false	Throws an error if no loading elements are found

Returns: Promise<void>

Will resolve if the loaders get removed before the timeout. Otherwise, will throw an error if the loaders are still in the DOM by the end of the timeout.

Setting failIfNull to true will cause an error to be thrown if no loading spinners are initially found in the DOM.

cleanupDropdowns

Helper method to remove all floating Stash Dropdown elements from the DOM.

Parameters: None

Returns: void

assertAndDismissNoty

Helper to assert and manually dismiss a notification. This is useful in scenarios where cleanupNoty() does not work as expected, such as when validating error messages in test suites.

Parameters	Type	Default	Summary
text	string	Required	Expected notification text.

Returns: void

getByDescriptionTerm

Finds the first HTML element with the role "definition" (DD) that matches the specified text for the description term.

Parameters	Type	Default	Summary
text	string | RegExp	Required	Expected description term text or regex

Returns: HTMLElement | undefined - The first matching description detail element or undefined if no match is found.

getAllByDescriptionTerm

Queries and returns an array of HTML elements with the role "definition" (DD) that matches the specified text of a description term.

Parameters	Type	Default	Summary
textMatch	string | RegExp	Required	The text to match within the HTML elements. It can be a string or a regular expression.

Returns: HTMLElement[] - An array of HTML description detail elements that match the given text.

getSelectedOption

Finds the first selected HTML element with the role "definition" (LI) "listitem" inside the specified select element.

Parameters	Type	Default	Summary
element	HTMLSelectElement	Required	Stash Select element to be checked.
selectedClass	string	'is-selected'	Selected class added on selected items
options	ByRoleOptions	null	getAllByRole() options values using ByRoleOptions type

Returns: HTMLElement | undefined - The first selected HTML listitem element or undefined if no match is found.

getSelectedOptions

Finds all the selected HTML elements with the role "definition" (LI) "listitem" inside the specified select element.

Parameters	Type	Default	Summary
element	HTMLSelectElement	Required	Stash Select element to be checked.
selectedClass	string	'is-selected'	Selected class added on selected items
options	ByRoleOptions	null	getAllByRole() options values using ByRoleOptions type

Returns: HTMLElement[] - An array of selected HTML listitem elements.

createFixtureGenerator

Higher order function that takes a method whose responsibility is to create a single data fixture object and returns a new generator function that allows you to create 1 or more of those fixtures. Fixture generator function that's returned supports passing optional num and overrides params.

Parameters	Type	Default	Summary
fixtureFn	function	Required	Method that generates and returns a single data object.

Returns

(num?, overrides?) => Array<{[key: string]: any}> | {[key: string]: any}
// OR
(overrides?) => {[key: string]: any}

A new generator function that accepts a number & overrides where:

• num = The number of fake data objects to generate. Defaults to 1
• overrides = Specific attributes you want to override in each data fixture object.

When calling the returned function, you'll get an array OR object of fixture data (It will be a ** single object** if num = 1).

Examples

Quick example:

const generateInvoice = (overrides) => ({ id: uuid(), balance: 15799, classification: "Adult Use", ...overrides});
const generateInvoices = createFixtureGenerator(generateInvoice);

generateInvoices()
// => Single invoice object

generateInvoices(1)
// => Single invoice object

generateInvoices(1, { foo: 'bar' })
// => Single invoice object, override `foo` to equal `'bar'`

generateInvoices({ foo: 'bar' })
// => Single invoice object, override `foo` to equal `'bar'`

generateInvoices(10)
// => Array of 10 invoice objects

generateInvoices(10, { foo: 'bar' })
// => Array of 10 invoice objects, override `foo` to equal `'bar'` in each

Full example:

// tests/fixtures/products.ts
import { faker } from '@faker-js/faker';
import { createFixtureGenerator } from '@leaflink/dom-testing-utils';

export const generateProduct = (overrides = {}) => ({
  sku: git.commitSha(),
  name: faker.commerce.productName(),
  quantity: faker.random.number(100),
  cases: faker.random.number(10),
  ...overrides,
});

export default createFixtureGenerator(generateProduct);

// services/api/products.ts
import generateProducts from '@/tests/fixtures/products';

// ...
const mockProducts = generateProducts(10, { cases: 25 })
// ...

Mocking API Endpoints

In order to mock API endpoints that your tests interact with, you can get a set of mocking functions from createMockApiUtils.

import { createMockApiUtils } from '@leaflink/dom-testing-utils';
import yourServer from './server.ts';

const {
  mockGetData,
  mockGetEndpoint,
  mockPatchData,
  // etc.
} = createMockApiUtils(yourServer);

There are two flavors of mocking utility functions:

1. mock{VERB}Data - mocks response with a singular data object
2. mock{VERB}Endpoint - mocks a response endpoint with a function like msw's Response Resolver

To mock an endpoint with simple return data

  mockGetData('/relative-url', myMockObj);

or you can customize the response

  mockGetEndpoint('/relative-url', (req, res, ctx) => {
    if (someConditional()) {
      HttpResponse.json({ foo: 'bar' });
    } else {
      HttpResponse.json({ foo: 'baz' });
    }
  });