create-locator 📌

The create-locator 📌 library allows you to mark HTML elements with locators and find these elements by their locators in tests.

Marking an HTML element with a locator in the application code looks like this (example in JSX):

export const Foo = () => {
  return <div {...locator('foo')}>Hello👋 world!</div>;
};

In the browser, this element will render into the following DOM structure:

<div data-testid="foo">Hello👋 world!</div>

In tests you can use locators in this way (example in Playwright):

await locator('foo').click();

Install

npm install create-locator

Usage

The first argument of the locator function is called the locator's testId. Typically, it’s a unique string that allows you to find the element marked by the locator in tests.

The locator can also have an optional set of arbitrary parameters (only the line with the locator is shown):

<div {...locator('foo', {bar: 'baz'})}>

This element with the locator will render into the following DOM structure:

<div data-testid="foo" data-test-bar="baz">

The values of the parameters can also be numbers and boolean values:

<div {...locator('foo', {bar: true, baz: 12})}>

This will render as:

<div data-testid="foo" data-test-bar="true" data-test-baz="12">

Parameters with null and undefined values will be omitted:

<div {...locator('foo', {bar: null, baz: undefined, qux: false})}>

This will render as:

<div data-testid="foo" data-test-qux="false">

The testId of the locator can consist of multiple parts, including numbers and boolean values:

<div {...locator('foo', 'qux', 3)}>

This will render as:

<div data-testid="foo-qux-3">

An object with parameters can also follow several parts of the testId:

<div {...locator('foo', 'qux', 3, {bar: true, baz: 12})}>

This will render as:

<div data-testid="foo-qux-3" data-test-bar="true" data-test-baz="12">

The ability to specify a testId composed of multiple parts is useful for dynamic components, which can accept an optional testId string property in their props:

type Properties = {..., testId?: string};

export const Button = ({..., testId}: Properties) => (
  <label {...locator(testId, 'label')}>
    <button {...locator(testId, 'button')}>{/* ... */}</button>
  </label>
)

For example, with testId="submitButton", this will render into the following DOM structure:

<label data-testid="submitButton-label">
  <button data-testid="submitButton-button">{/* ... */}</button>
</label>

License

MIT