{"id":19176988,"url":"https://github.com/joomcode/create-locator","last_synced_at":"2026-02-06T04:03:01.422Z","repository":{"id":131543853,"uuid":"611653759","full_name":"joomcode/create-locator","owner":"joomcode","description":"Creates HTML element locators for tests 📌","archived":false,"fork":false,"pushed_at":"2025-01-10T04:23:54.000Z","size":509,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-19T11:41:38.556Z","etag":null,"topics":["autotest","e2e","locator","selector","testid"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joomcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-09T09:15:06.000Z","updated_at":"2025-01-10T04:25:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"f57b622b-3c8e-422a-be24-2eeecaf2b169","html_url":"https://github.com/joomcode/create-locator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/joomcode/create-locator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joomcode%2Fcreate-locator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joomcode%2Fcreate-locator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joomcode%2Fcreate-locator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joomcode%2Fcreate-locator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joomcode","download_url":"https://codeload.github.com/joomcode/create-locator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joomcode%2Fcreate-locator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29149594,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T02:39:25.012Z","status":"ssl_error","status_checked_at":"2026-02-06T02:37:22.784Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autotest","e2e","locator","selector","testid"],"created_at":"2024-11-09T10:31:31.037Z","updated_at":"2026-02-06T04:03:01.399Z","avatar_url":"https://github.com/joomcode.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# create-locator 📌\n\n[![NPM version][npm-image]][npm-url]\n[![dependencies: none][dependencies-none-image]][dependencies-none-url]\n[![minzipped size][size-image]][size-url]\n[![code style: prettier][prettier-image]][prettier-url]\n[![Conventional Commits][conventional-commits-image]][conventional-commits-url]\n[![License MIT][license-image]][license-url]\n\nThe `create-locator` 📌 library allows you to mark HTML elements with locators and\nfind these elements by their locators in tests.\n\nMarking an HTML element with a locator in the application code looks like this (example in JSX):\n\n```tsx\nexport const Foo = () =\u003e {\n  return \u003cdiv {...locator('foo')}\u003eHello👋 world!\u003c/div\u003e;\n};\n```\n\nIn the browser, this element will render into the following DOM structure:\n\n```tsx\n\u003cdiv data-testid=\"foo\"\u003eHello👋 world!\u003c/div\u003e\n```\n\nIn tests you can use locators in this way (example in [Playwright](https://playwright.dev/)):\n\n```tsx\nawait locator('foo').click();\n```\n\n## Install\n\n```sh\nnpm install create-locator\n```\n\n## Usage\n\nThe first argument of the locator function is called the locator's `testId`.\nTypically, it’s a unique string that allows you to find the element marked by the locator in tests.\n\nThe locator can also have an optional set of arbitrary parameters (only the line with the locator is shown):\n\n```tsx\n\u003cdiv {...locator('foo', {bar: 'baz'})}\u003e\n```\n\nThis element with the locator will render into the following DOM structure:\n\n```tsx\n\u003cdiv data-testid=\"foo\" data-test-bar=\"baz\"\u003e\n```\n\nThe values of the parameters can also be numbers and boolean values:\n\n```tsx\n\u003cdiv {...locator('foo', {bar: true, baz: 12})}\u003e\n```\n\nThis will render as:\n\n```tsx\n\u003cdiv data-testid=\"foo\" data-test-bar=\"true\" data-test-baz=\"12\"\u003e\n```\n\nParameters with `null` and `undefined` values will be omitted:\n\n```tsx\n\u003cdiv {...locator('foo', {bar: null, baz: undefined, qux: false})}\u003e\n```\n\nThis will render as:\n\n```tsx\n\u003cdiv data-testid=\"foo\" data-test-qux=\"false\"\u003e\n```\n\nThe `testId` of the locator can consist of multiple parts, including numbers and boolean values:\n\n```tsx\n\u003cdiv {...locator('foo', 'qux', 3)}\u003e\n```\n\nThis will render as:\n\n```tsx\n\u003cdiv data-testid=\"foo-qux-3\"\u003e\n```\n\nAn object with parameters can also follow several parts of the `testId`:\n\n```tsx\n\u003cdiv {...locator('foo', 'qux', 3, {bar: true, baz: 12})}\u003e\n```\n\nThis will render as:\n\n```tsx\n\u003cdiv data-testid=\"foo-qux-3\" data-test-bar=\"true\" data-test-baz=\"12\"\u003e\n```\n\nThe ability to specify a `testId` composed of multiple parts is useful for dynamic components,\nwhich can accept an optional `testId` string property in their props:\n\n```tsx\ntype Properties = {testId?: string};\n\nexport const Button = ({testId}: Properties) =\u003e (\n  \u003clabel {...locator(testId, 'label')}\u003e\n    \u003cbutton {...locator(testId, 'button')}\u003e{/* ... */}\u003c/button\u003e\n  \u003c/label\u003e\n);\n```\n\nFor example, with `testId=\"submitButton\"`, this will render into the following DOM structure:\n\n```tsx\n\u003clabel data-testid=\"submitButton-label\"\u003e\n  \u003cbutton data-testid=\"submitButton-button\"\u003e{/* ... */}\u003c/button\u003e\n\u003c/label\u003e\n```\n\n## Initialization\n\nTo create `locator` function, first define the attributes options in a separate file\n(since you will import them in both your application code and your test code):\n\n```ts\n// app/attributesOptions.ts\n\nimport type {AttributesOptions} from 'create-locator';\n\nexport const attributesOptions: AttributesOptions = {\n  parameterAttributePrefix: 'data-test-',\n  testIdAttribute: 'data-testid',\n  testIdSeparator: '-',\n};\n```\n\nThen create `locator` function and additional `getTestId` function in application code using these options\nand the boolean parameter `isProduction` (if `isProduction` is `true`, no one locator attributes are rendered):\n\n```ts\n// app/locator.ts\n\nimport {createSimpleLocator} from 'create-locator';\nimport {attributesOptions} from './attributesOptions';\n\nconst isProduction: boolean = /* ... */;\n\nexport const {locator, getTestId} = createSimpleLocator({attributesOptions, isProduction});\n```\n\nIn test code, create `locator` function and additional `getSelector` and `getTestId` functions in a similar manner\n(using the example of the [Playwright](https://playwright.dev/),\nwhere `getPage` is the function of getting the current Playwright page):\n\n```ts\n// tests/locator.ts\n\nimport {createTestLocator} from 'create-locator';\nimport {attributesOptions} from '../app/attributesOptions';\nimport {getPage} from './getPage';\n\nexport const {locator, getSelector, getTestId} = createTestLocator({\n  attributesOptions,\n  createLocatorByCssSelector: (selector) =\u003e getPage().locator(selector),\n  supportWildcardsInCssSelectors: true,\n});\n```\n\n## License\n\n[MIT][license-url]\n\n[conventional-commits-image]: https://img.shields.io/badge/Conventional_Commits-1.0.0-yellow.svg 'The Conventional Commits specification'\n[conventional-commits-url]: https://www.conventionalcommits.org/en/v1.0.0/\n[dependencies-none-image]: https://img.shields.io/badge/dependencies-none-success.svg 'No dependencies'\n[dependencies-none-url]: https://github.com/joomcode/create-locator/blob/main/package.json\n[license-image]: https://img.shields.io/badge/license-MIT-blue.svg 'The MIT License'\n[license-url]: LICENSE\n[npm-image]: https://img.shields.io/npm/v/create-locator.svg 'create-locator'\n[npm-url]: https://www.npmjs.com/package/create-locator\n[prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg 'Prettier code formatter'\n[prettier-url]: https://prettier.io/\n[size-image]: https://img.shields.io/bundlephobia/minzip/create-locator 'create-locator'\n[size-url]: https://bundlephobia.com/package/create-locator\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoomcode%2Fcreate-locator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoomcode%2Fcreate-locator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoomcode%2Fcreate-locator/lists"}