Leaflink repository to manage test utilities to be shared across front-end applications.
npm install --save-dev @leaflink/dom-testing-utils
In your test files you can import utility functions.
import {
waitForLoading,
cleanupDropdowns,
assertAndDismissNoty,
cleanupNoty,
createFixtureGenerator,
} from '@leaflink/dom-testing-utils';
it('...', () => {
cleanupNoty();
});
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.
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.
Helper method to remove all noty alerts from the DOM.
Parameters: None
Returns: void
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.
Helper method to remove all floating Stash Dropdown elements from the DOM.
Parameters: None
Returns: void
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
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.
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.
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.
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.
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 })
// ...
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:
- mock{VERB}Data - mocks response with a singular data object
- 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' });
}
});