FI-494: add selectors with custom methods

autotests/tests/internalTypeTests/selectors.skip.ts

@@ -0,0 +1,63 @@
+import {
+  createSelector,
+  createSelectorByCss,
+  htmlElementSelector,
+  locatorIdSelector,
+} from 'e2ed/selectors';
+
+// @ts-expect-error: wrong number of arguments
+htmlElementSelector.findByTestId();
+// @ts-expect-error: wrong type of arguments
+htmlElementSelector.findByTestId(0);
+// ok
+htmlElementSelector.findByTestId('id');
+// ok
+htmlElementSelector.findByTestId('id').findByTestId('id2');
+// ok
+htmlElementSelector.findByTestId('id').find('.test-children');
+// ok
+htmlElementSelector.find('body').findByTestId('id');
+
+// ok
+createSelector('id').findByTestId('id').find('body').findByTestId('id');
+// ok
+createSelectorByCss('id').findByTestId('id').find('body').findByTestId('id');
+// ok
+locatorIdSelector('id').findByTestId('id').find('body').findByTestId('id');
+
+// ok
+htmlElementSelector.filterByTestId('id');
+// ok
+htmlElementSelector.parentByTestId('id');
+// ok
+htmlElementSelector.childByTestId('id');
+// ok
+htmlElementSelector.siblingByTestId('id');
+// ok
+htmlElementSelector.nextSiblingByTestId('id');
+// ok
+htmlElementSelector.prevSiblingByTestId('id');
+
+// ok
+htmlElementSelector.filterByTestProp('prop', 'value');
+// ok
+htmlElementSelector.findByTestProp('prop', 'value');
+// ok
+htmlElementSelector.parentByTestProp('prop', 'value');
+// ok
+htmlElementSelector.childByTestProp('prop', 'value');
+// ok
+htmlElementSelector.siblingByTestProp('prop', 'value');
+// ok
+htmlElementSelector.nextSiblingByTestProp('prop', 'value');
+// ok
+htmlElementSelector.prevSiblingByTestProp('prop', 'value');
+
+// ok
+void htmlElementSelector.getTestProp('prop');
+// ok
+void htmlElementSelector.hasTestProp('prop');
+
+// ok
+declare function testStringOrUndefined(val: string | undefined): void;
+testStringOrUndefined(htmlElementSelector.getDescription());

src/actions/asserts/viewport/assertSelectorEntirelyInViewport.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../../../constants/internal';
 import {expect} from '../../../expect';
-import {getDescriptionFromSelector} from '../../../utils/locators';
 import {log} from '../../../utils/log';
 import {isSelectorEntirelyInViewport} from '../../../utils/viewport';
 
@@ -12,7 +11,7 @@ import type {Selector} from '../../../types/internal';
  */
 export const assertSelectorEntirelyInViewport = async (selector: Selector): Promise<void> => {
   const isEntirelyInViewport = await isSelectorEntirelyInViewport(selector);
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
   const message = 'selector is entirely in the viewport';
 
   log(`Asserts that ${message}`, {locator}, LogEventType.InternalAssert);

src/actions/asserts/viewport/assertSelectorInViewport.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../../../constants/internal';
 import {expect} from '../../../expect';
-import {getDescriptionFromSelector} from '../../../utils/locators';
 import {log} from '../../../utils/log';
 import {isSelectorInViewport} from '../../../utils/viewport';
 
@@ -12,7 +11,7 @@ import type {Selector} from '../../../types/internal';
  */
 export const assertSelectorInViewport = async (selector: Selector): Promise<void> => {
   const isInViewport = await isSelectorInViewport(selector);
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
   const message = 'selector is in the viewport';
 
   log(`Asserts that ${message}`, {locator}, LogEventType.InternalAssert);

src/actions/clearUpload.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import type {Selector, TestCafeSelector} from '../types/internal';
@@ -9,7 +8,7 @@ import type {Selector, TestCafeSelector} from '../types/internal';
  * Removes all file paths from the specified file upload input.
  */
 export const clearUpload = (selector: Selector): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log('Remove all file paths from file upload input', {locator}, LogEventType.InternalAction);
 

src/actions/click.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -16,7 +15,7 @@ export const click = async (
   selector: Selector,
   {stabilizationInterval, ...options}: Options = {},
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
   const withLocator = locator ? ` with locator ${locator}` : '';
 
   log(

src/actions/dispatchEvent.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -17,7 +16,7 @@ export const dispatchEvent = async (
   eventName: string,
   {stabilizationInterval, ...options}: Options = {},
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log(
     'Dispatches an event over a specified element',

src/actions/doubleClick.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -16,7 +15,7 @@ export const doubleClick = async (
   selector: Selector,
   {stabilizationInterval, ...options}: Options = {},
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
   const withLocator = locator ? ` with locator ${locator}` : '';
 
   log(

src/actions/drag.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -19,7 +18,7 @@ export const drag = async (
   {stabilizationInterval, ...options}: Options = {},
   // eslint-disable-next-line max-params
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log(
     'Drag an element by an offset',

src/actions/dragToElement.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -17,8 +16,8 @@ export const dragToElement = async (
   destinationSelector: Selector,
   {stabilizationInterval, ...options}: Options = {},
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
-  const destinationLocator = getDescriptionFromSelector(destinationSelector);
+  const locator = selector.getDescription();
+  const destinationLocator = destinationSelector.getDescription();
 
   log(
     'Drag an element onto another one',

src/actions/hover.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -16,7 +15,7 @@ export const hover = async (
   selector: Selector,
   {stabilizationInterval, ...options}: Options = {},
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log(
     'Hover the mouse pointer over an element',

src/actions/rightClick.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -16,7 +15,7 @@ export const rightClick = async (
   selector: Selector,
   {stabilizationInterval, ...options}: Options = {},
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
   const withLocator = locator ? ` with locator ${locator}` : '';
 
   log(

src/actions/scroll.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import type {Inner} from 'testcafe-without-typecheck';
@@ -26,7 +25,7 @@ type Scroll = ((posX: number, posY: number) => Promise<void>) &
  */
 // @ts-expect-error: e2ed Selector type is incompatible with TS Selector
 export const scroll: Scroll = (...args) => {
-  const locator = getDescriptionFromSelector(args[0] as Selector);
+  const locator = (args[0] as Selector)?.getDescription();
   const printedArgs = [...args];
 
   if (typeof args[0] === 'object') {

src/actions/scrollBy.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import type {Inner} from 'testcafe-without-typecheck';
@@ -15,7 +14,7 @@ type ScrollBy = ((x: number, y: number) => Promise<void>) &
  */
 // @ts-expect-error: e2ed Selector type is incompatible with TS Selector
 export const scrollBy: ScrollBy = (...args) => {
-  const locator = getDescriptionFromSelector(args[0] as Selector);
+  const locator = (args[0] as Selector)?.getDescription();
   const printedArgs = [...args];
 
   if (typeof args[0] === 'object') {

src/actions/scrollIntoView.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import type {Selector, TestCafeSelector} from '../types/internal';
@@ -11,7 +10,7 @@ type Options = Parameters<typeof testController.scrollIntoView>[1];
  * Scrolls the specified element into view.
  */
 export const scrollIntoView = (selector: Selector, options?: Options): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log('Scroll the specified element into view', {locator, options}, LogEventType.InternalAction);
 

src/actions/selectText.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import type {Selector, TestCafeSelector} from '../types/internal';
@@ -17,7 +16,7 @@ export const selectText = (
   options?: Options,
   // eslint-disable-next-line max-params
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log(
     `Select text in input element, from ${startPos} to ${

src/actions/setFilesToUpload.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import type {Selector, TestCafeSelector} from '../types/internal';
@@ -13,7 +12,7 @@ export const setFilesToUpload = (
   filePath: string | string[],
 ): Promise<void> => {
   const hasManyFiles = Array.isArray(filePath) && filePath.length > 0;
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log(
     `Populate file upload input with file${hasManyFiles ? 's' : ''} "${String(filePath)}"`,

src/actions/switchToIframe.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -14,7 +13,7 @@ export const switchToIframe = async (
   iframeSelector: Selector,
   {stabilizationInterval}: WithStabilizationInterval = {},
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(iframeSelector);
+  const locator = iframeSelector.getDescription();
 
   log(
     'Switch browsing context to the specified iframe',

src/actions/takeElementScreenshot.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import type {Selector, TestCafeSelector} from '../types/internal';
@@ -15,7 +14,7 @@ export const takeElementScreenshot = (
   pathToScreenshot?: string,
   options?: Options,
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log(
     'Take a screenshot of the element',

src/actions/typeText.ts

@@ -1,6 +1,5 @@
 import {LogEventType} from '../constants/internal';
 import {testController} from '../testController';
-import {getDescriptionFromSelector} from '../utils/locators';
 import {log} from '../utils/log';
 
 import {waitForInterfaceStabilization} from './waitFor';
@@ -17,7 +16,7 @@ export const typeText = async (
   text: string,
   {stabilizationInterval, ...options}: Options = {},
 ): Promise<void> => {
-  const locator = getDescriptionFromSelector(selector);
+  const locator = selector.getDescription();
 
   log(
     `Type "${text}" into an input element`,