Merge pull request #102 from joomcode/fix/use-testId-instead-of-locat…

…orId

fix: rename `locatorId` to `testId` everywhere

.eslintrc.yaml

@@ -15,7 +15,7 @@ parserOptions:
   sourceType: module
 plugins: [simple-import-sort, typescript-sort-keys]
 root: true
-ignorePatterns: [bin/forks/*/package, build, local]
+ignorePatterns: [build, local]
 rules:
   class-methods-use-this: off
   complexity: [error, {max: 10}]
@@ -74,7 +74,7 @@ rules:
   import/no-unassigned-import: error
   import/no-unresolved:
     - error
-    - {commonjs: true, ignore: [autotests, e2ed/testcafe]}
+    - {commonjs: true, ignore: [autotests]}
   import/no-unused-modules:
     - error
     - ignoreExports:
@@ -109,7 +109,7 @@ rules:
     - ':not(MethodDefinition, Property) > FunctionExpression'
   no-return-await: off
   no-shadow: off
-  no-underscore-dangle: [error, {allow: [_onConfigureResponse]}]
+  no-underscore-dangle: error
   no-unused-expressions: off
   no-useless-constructor: off
   no-use-before-define: off

LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2021-2024 SIA Joom
+Copyright (c) 2021-2025 SIA Joom
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

autotests/packs/allTests.ts

@@ -1,7 +1,7 @@
 /**
  * @file Pack file (file with configuration of pack).
  * Do not import anything (from `utils`, etc) into this file other than
- * the types and values from `../configurator`, `e2ed/configurator`, `e2ed/constants`
+ * the types and values from `../configurator`, `e2ed/configurator`
  * or other packs (because the pack is compiled separately from the tests themselves
  * and has separate TypeScript scope).
  */

autotests/packs/local.example.ts

@@ -1,3 +1,11 @@
+/**
+ * @file Pack for local development.
+ * Do not import anything (from `utils`, etc) into this file other than
+ * the types and values from `../configurator`, `e2ed/configurator`
+ * or other packs (because the pack is compiled separately from the tests themselves
+ * and has separate TypeScript scope).
+ */
+
 import {pack as allTestsPack} from './allTests';
 
 import type {Pack} from 'autotests/configurator';

autotests/pageObjects/pages/E2edReportExample/E2edReportExample.ts

@@ -28,8 +28,7 @@ export class E2edReportExample extends Page<CustomPageParams> {
   /**
    * Button tabs in navigation bar with test retries.
    */
-  readonly navigationRetriesButton: Selector =
-    this.navigationRetries.findByLocatorId('RetryButton');
+  readonly navigationRetriesButton: Selector = this.navigationRetries.findByTestId('RetryButton');
 
   /**
    * Selected button tab in navigation bar with test retries.
@@ -52,7 +51,7 @@ export class E2edReportExample extends Page<CustomPageParams> {
   /**
    * Test run button.
    */
-  readonly testRunButton: Selector = this.testRunsList.findByLocatorId('TestRunButton');
+  readonly testRunButton: Selector = this.testRunsList.findByTestId('TestRunButton');
 
   /**
    * List of test runs of retry.

autotests/pageObjects/pages/E2edReportExample/TestRunButton.ts

@@ -1,4 +1,4 @@
-import {cssSelector} from 'autotests/selectors';
+import {getCssSelector} from 'autotests/selectors';
 
 import type {Selector} from 'e2ed/types';
 
@@ -8,7 +8,7 @@ const testId = 'TestRunButton';
  * `TestRun` button.
  */
 export class TestRunButton {
-  static readonly parameters: string = cssSelector(testId, 'parameters');
+  static readonly parameters: string = getCssSelector(testId, 'parameters');
 
   readonly selector: Selector;
 

autotests/selectors/createSelector.ts

@@ -1,20 +1,9 @@
+import {attributesOptions} from 'autotests/constants';
 import {createSelectorFunction} from 'e2ed/selectors';
 
 import type {CreateSelector} from 'e2ed/types';
 
 /**
- * Main functions for creating selectors and working with selectors.
+ * Main function for creating selectors and working with selectors.
  */
-export const createSelector: CreateSelector = createSelectorFunction({
-  getLocatorAttributeName: (parameter) => {
-    if (parameter === 'id') {
-      return 'data-testid';
-    }
-
-    if (parameter === 'runhash') {
-      return 'data-runhash';
-    }
-
-    return `data-test-${parameter}`;
-  },
-});
+export const createSelector: CreateSelector = createSelectorFunction(attributesOptions);

autotests/selectors/index.ts

@@ -1,4 +1,4 @@
 export {createSelector} from './createSelector';
 export {htmlElementSelector} from './htmlElementSelector';
 export {inputSelector} from './inputSelector';
-export {cssSelector, locator, testId} from './locator';
+export {getCssSelector, getTestId, locator} from './locator';

autotests/selectors/locator.ts

@@ -1,15 +1,16 @@
 import {attributesOptions} from 'autotests/constants';
-import {createTestUtils} from 'e2ed/createLocator';
+import {createTestLocator} from 'e2ed/createLocator';
 
 import {createSelector} from './createSelector';
 
 import type {LocatorFunction} from 'create-locator';
 import type {Selector} from 'e2ed/types';
 
 /**
- * Test utils, that produce `Selector`, CSS selector string and `testId` string.
+ * Locator kit with `locator` function, that produce `Selector`,
+ * and additional `getSelector` and `getTestId` functions.
  */
-const utils = createTestUtils({
+const locatorKit = createTestLocator({
   attributesOptions,
   createLocatorByCssSelector: (selector) =>
     createSelector(selector.replace('data-test-runhash', 'data-runhash')),
@@ -19,14 +20,14 @@ const utils = createTestUtils({
 /**
  * Locator, that produce `Selector`.
  */
-export const locator: LocatorFunction<Selector> = utils.locator;
+export const locator: LocatorFunction<Selector> = locatorKit.locator;
 
 /**
- * Locator, that produce CSS selector string.
+ * Get CSS selector string.
  */
-export const cssSelector: LocatorFunction<string> = utils.selector;
+export const getCssSelector: LocatorFunction<string> = locatorKit.getSelector;
 
 /**
- * Locator, that produce `testId` string.
+ * Get `testId` string.
  */
-export const testId: LocatorFunction<string> = utils.testId;
+export const getTestId: LocatorFunction<string> = locatorKit.getTestId;

autotests/tests/e2edReportExample/selectorCustomMethods.ts

@@ -54,7 +54,7 @@ test('selector custom methods', {meta: {testId: '15'}}, async () => {
     reportPage.navigationRetriesButtonSelected.getDescription(),
     'selector has apropriate description',
   ).eql(
-    '[data-testid="RetriesButtons"].findByLocatorId(RetryButton).filterByLocatorParameter(selected, true)',
+    '[data-testid="RetriesButtons"].findByTestId(RetryButton).filterByLocatorParameter(selected, true)',
   );
 
   await click(reportPage.navigationRetriesButton.nth(0));

autotests/tests/internalTypeTests/selectors.skip.ts

@@ -3,46 +3,46 @@ import {createSelector, htmlElementSelector, locator} from 'autotests/selectors'
 import type {Selector} from 'e2ed/types';
 
 // @ts-expect-error: wrong number of arguments
-htmlElementSelector.findByLocatorId();
+htmlElementSelector.findByTestId();
 // @ts-expect-error: wrong type of arguments
-htmlElementSelector.findByLocatorId(0);
+htmlElementSelector.findByTestId(0);
 // ok
-htmlElementSelector.findByLocatorId('id') satisfies Selector;
+htmlElementSelector.findByTestId('id') satisfies Selector;
 // ok
-htmlElementSelector.findByLocatorId('id').findByLocatorId('id2') satisfies Selector;
+htmlElementSelector.findByTestId('id').findByTestId('id2') satisfies Selector;
 // ok
-htmlElementSelector.findByLocatorId('id').find('.test-children') satisfies Selector;
+htmlElementSelector.findByTestId('id').find('.test-children') satisfies Selector;
 // ok
-htmlElementSelector.find('body').findByLocatorId('id') satisfies Selector;
+htmlElementSelector.find('body').findByTestId('id') satisfies Selector;
 
 // ok
-createSelector('id').findByLocatorId('id').find('body').findByLocatorId('id') satisfies Selector;
+createSelector('id').findByTestId('id').find('body').findByTestId('id') satisfies Selector;
 
 // ok
-locator('id').findByLocatorId('id').find('body').findByLocatorId('id') satisfies Selector;
+locator('id').findByTestId('id').find('body').findByTestId('id') satisfies Selector;
 
 // @ts-expect-error: wrong number of arguments
 locator();
 
 // ok
-htmlElementSelector.filterByLocatorId('id') satisfies Selector;
+htmlElementSelector.filterByTestId('id') satisfies Selector;
 
 // ok
 htmlElementSelector.filterByLocatorParameter('prop', 'value') satisfies Selector;
 // ok
 htmlElementSelector.findByLocatorParameter('prop', 'value') satisfies Selector;
 
 // ok
-void htmlElementSelector.getLocatorId();
+void htmlElementSelector.getTestId();
 
 // @ts-expect-error: wrong number of arguments
-void htmlElementSelector.getLocatorId('id');
+void htmlElementSelector.getTestId('id');
 
 // @ts-expect-error: TODO: should be ok
-void htmlElementSelector.hasLocatorId() satisfies Promise<boolean>;
+void htmlElementSelector.hasTestId() satisfies Promise<boolean>;
 
 // @ts-expect-error: wrong number of arguments
-void htmlElementSelector.hasLocatorId('id');
+void htmlElementSelector.hasTestId('id');
 
 // @ts-expect-error: wrong number of arguments
 void htmlElementSelector.hasLocatorParameter();

package.json

@@ -26,13 +26,13 @@
   },
   "dependencies": {
     "@playwright/test": "1.49.1",
-    "create-locator": "0.0.25",
+    "create-locator": "0.0.27",
     "get-modules-graph": "0.0.11",
     "globby": "11.1.0"
   },
   "devDependencies": {
     "@playwright/browser-chromium": "1.49.1",
-    "@types/node": "22.10.2",
+    "@types/node": "22.10.5",
     "@typescript-eslint/eslint-plugin": "7.18.0",
     "@typescript-eslint/parser": "7.18.0",
     "assert-modules-support-case-insensitive-fs": "1.0.1",
@@ -45,7 +45,7 @@
     "eslint-plugin-typescript-sort-keys": "3.3.0",
     "husky": "9.1.7",
     "prettier": "3.4.2",
-    "typescript": "5.7.2"
+    "typescript": "5.7.3"
   },
   "peerDependencies": {
     "@types/node": ">=20",

src/constants/attributesOptions.ts

@@ -4,8 +4,8 @@ import type {AttributesOptions} from 'create-locator';
  * Attributes options for locators.
  * @internal
  */
-export const attributesOptions = {
+export const attributesOptions: AttributesOptions = {
   parameterAttributePrefix: 'data-test-',
   testIdAttribute: 'data-testid',
   testIdSeparator: '-',
-} as const satisfies AttributesOptions;
+};

src/createLocator.ts

@@ -1,7 +1,7 @@
 // eslint-disable-next-line no-restricted-syntax
 export * from 'create-locator';
 // eslint-disable-next-line import/no-internal-modules
-export {createTestUtils} from 'create-locator/createTestUtils';
+export {createTestLocator} from 'create-locator/createTestLocator';
 export type {PARAMETERS} from 'create-locator/oldTypes';
 // eslint-disable-next-line import/no-internal-modules
 export {getCssSelectorFromAttributesChain} from 'create-locator/getCssSelectorFromAttributesChain';

src/selectors/createSelectorFunction.ts

@@ -1,19 +1,25 @@
-import {setCustomInspectOnFunction} from '../utils/fn';
+import {DESCRIPTION_KEY} from '../constants/internal';
 import {generalLog} from '../utils/generalLog';
-import {createSelectorCreator} from '../utils/selectors';
+import {createCustomMethods, createGetTrap, Selector as SelectorClass} from '../utils/selectors';
+import {setReadonlyProperty} from '../utils/setReadonlyProperty';
 
-import type {CreateSelector, CreateSelectorFunctionOptions} from '../types/internal';
+import type {CreateSelector, CreateSelectorFunctionOptions, Selector} from '../types/internal';
 
 /**
  * Creates `createSelector` function.
  */
-export const createSelectorFunction = ({
-  getLocatorAttributeName,
-}: CreateSelectorFunctionOptions): CreateSelector => {
-  setCustomInspectOnFunction(getLocatorAttributeName);
-  generalLog('Create selector functions', {getLocatorAttributeName});
+export const createSelectorFunction = (
+  attributesOptions: CreateSelectorFunctionOptions,
+): CreateSelector => {
+  generalLog('Create selector function', {attributesOptions});
 
-  const createSelector = createSelectorCreator(getLocatorAttributeName);
+  const customMethods = createCustomMethods(attributesOptions);
 
-  return createSelector;
+  return (locator) => {
+    const selector = new SelectorClass(locator) as unknown as Selector;
+
+    setReadonlyProperty(selector, DESCRIPTION_KEY, locator);
+
+    return new Proxy(selector, {get: createGetTrap(customMethods)});
+  };
 };