diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..d03936b
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,43 @@
+name: CI
+
+on:
+ push:
+ branches: [master]
+ pull_request:
+ branches: [master]
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ test:
+ name: Run tests on Node.js ${{ matrix.node-version }}
+ runs-on: self-hosted-arc
+
+ strategy:
+ matrix:
+ node-version: [18, 20, 22, 24]
+ fail-fast: false
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Setup Node.js ${{ matrix.node-version }}
+ uses: actions/setup-node@v4
+ with:
+ node-version: ${{ matrix.node-version }}
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Run lint
+ run: npm run lint
+
+ - name: Check formatting
+ run: npm run check-formatting
+
+ - name: Run build
+ run: npm run build
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..d4ae904
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+node_modules
+build
+tmp
+.vscode
+.idea
diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 0000000..2bd5a0a
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+22
diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000..e1da2f3
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1,10 @@
+.idea
+build
+LICENSE
+package.json
+package-lock.json
+*.md
+.gitignore
+.nvmrc
+.prettierignore
+.github
diff --git a/.prettierrc.js b/.prettierrc.js
new file mode 100644
index 0000000..008a62f
--- /dev/null
+++ b/.prettierrc.js
@@ -0,0 +1,10 @@
+module.exports = {
+ printWidth: 120,
+ useTabs: false,
+ tabWidth: 4,
+ semi: true,
+ singleQuote: false,
+ trailingComma: "all",
+ bracketSpacing: true,
+ arrowParens: "avoid",
+};
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..d6f7db0
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 YANDEX LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
index e69de29..449717d 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,84 @@
+
+
+
+
+
+
+
+
+
+
+
+## Introduction
+[Testing-library](https://testing-library.com/) is a collection of tools for testing web application user interfaces, focused on creating reliable and maintainable tests by emphasizing user behavior. The main advantage of `testing-library` is its focus on interaction with interface elements. And in testplane, you can use the element search methods provided by the `testing-library` itself.
+
+## Installation
+
+1. Install the npm package `@testplane/testing-library`:
+```shell
+npm i -D @testplane/testing-library
+```
+
+2. Include it in the Testplane config in the `prepareBrowser` section:
+```js
+// .testplane.conf.js
+const { setupBrowser } = require("@testplane/testing-library");
+
+module.exports = {
+ prepareBrowser(browser) {
+ setupBrowser(browser);
+ },
+
+ // other Testplane settings...
+};
+```
+
+If you are using TypeScript and experiencing issues with testing-library types, you may add the following line to your tsconfig.json
+
+```json
+{
+ "compilerOptions": {
+ "types": [
+ "@testplane/testing-library"
+ ]
+ }
+}
+```
+
+## Usage
+
+After configuring, you will be able to use the search by selectors from `testing-library`, as described in the [official documentation](https://testing-library.com/docs/queries/about/). For example, searching for an element by its text:
+
+```js
+it("example", async ({ browser }) => {
+ await browser.url("https://github.com/");
+
+ const newRepoButton = await browser.getByText("New");
+
+ await newRepoButton.click();
+});
+
+
+```
+
+This feature will also be available in the context of found elements:
+
+```js
+it("example", async ({ browser }) => {
+ await browser.url("https://github.com/");
+
+ const sidebar = await browser.$(".dashboard-sidebar");
+ const newRepoButton = await sidebar.getByText("New");
+
+ await newRepoButton.click();
+});
+```
+
+Disclaimer:
+All testing-library selectors return a promise and cannot be chained (like `browser.getByText().click()` — this is not possible).
+Each testing-library selector must be awaited before performing any actions on it.
diff --git a/docs/images/logo-dark.svg b/docs/images/logo-dark.svg
new file mode 100644
index 0000000..759f636
--- /dev/null
+++ b/docs/images/logo-dark.svg
@@ -0,0 +1 @@
+;
+
+function isContainerWithExecute(
+ container: WebdriverIO.Element | WebdriverIO.Browser,
+): container is WebdriverIO.Browser {
+ return (container as { execute?: unknown }).execute !== null;
+}
+
+function findContainerWithExecute(container: WebdriverIO.Element): WebdriverIO.Browser {
+ let curContainer: WebdriverIO.Element | WebdriverIO.Browser = container.parent;
+ while (!isContainerWithExecute(curContainer)) {
+ curContainer = curContainer.parent;
+ }
+ return curContainer;
+}
+
+const findBrowser = (container: WebdriverIO.Element): WebdriverIO.Browser => {
+ let browser: WebdriverIO.Element | WebdriverIO.Browser = container;
+ while ((browser as WebdriverIO.Element).parent && browser.capabilities === undefined) {
+ browser = (browser as WebdriverIO.Element).parent;
+ }
+ return browser as WebdriverIO.Browser;
+};
+
+async function injectDOMTestingLibrary(container: WebdriverIO.Element) {
+ const browser = findContainerWithExecute(container);
+ const shouldInjectDTL = await browser.execute(function () {
+ return !window.TestingLibraryDom;
+ });
+
+ if (shouldInjectDTL) {
+ await browser.execute(function (library) {
+ if (navigator.userAgent.indexOf("Firefox") !== -1) {
+ try {
+ // Inject via inline-script
+ const script = window.document.createElement("script");
+ script.textContent = library;
+ window.document.head.append(script);
+ if (!window.TestingLibraryDom) {
+ // Inject via eval
+ window.eval(library);
+ }
+ } catch (error) {
+ throw new Error(
+ `The DOM Testing Library cannot be injected on certain domains, particularly "${window.location.host}", due to restrictions imposed by the Content-Security-Policy (CSP) header. ${error}`,
+ );
+ }
+ } else {
+ eval(library);
+ }
+ }, DOM_TESTING_LIBRARY_UMD);
+ }
+
+ await browser.execute(function (config: Partial) {
+ window.TestingLibraryDom.configure(config);
+ }, _config);
+}
+
+function serializeObject(object: ObjectQueryArg): SerializedObject {
+ return Object.entries(object)
+ .map<[string, SerializedArg]>(([key, value]: [string, QueryArg]) => [key, serializeArg(value)])
+ .reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {
+ serialized: "object",
+ });
+}
+
+function serializeArg(arg: QueryArg): SerializedArg {
+ if (arg instanceof RegExp) {
+ return { serialized: "RegExp", RegExp: arg.toString() };
+ }
+ if (typeof arg === "undefined") {
+ return { serialized: "Undefined", Undefined: true };
+ }
+ if (arg && typeof arg === "object") {
+ return serializeObject(arg);
+ }
+ return arg;
+}
+
+type SerializedQueryResult = { selector: string }[] | string | { selector: string } | null;
+
+async function executeQuery(query: QueryName, container: HTMLElement, ...args: SerializedArg[]) {
+ return new Promise((done: (result: SerializedQueryResult) => void) => {
+ function deserializeObject(object: SerializedObject) {
+ return Object.entries(object)
+ .map<[string, QueryArg]>(([key, value]) => [key, deserializeArg(value)])
+ .reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {});
+ }
+
+ function deserializeArg(arg: SerializedArg): QueryArg {
+ if (typeof arg === "object" && arg === null) {
+ return undefined;
+ }
+ if (typeof arg === "object" && (arg as { nodeType?: string }).nodeType !== undefined) {
+ return arg as QueryArg;
+ }
+ if (typeof arg === "object" && arg.serialized === "RegExp") {
+ return eval(arg.RegExp);
+ }
+ if (typeof arg === "object" && arg.serialized === "Undefined") {
+ return undefined;
+ }
+ if (typeof arg === "object") {
+ return deserializeObject(arg);
+ }
+ return arg;
+ }
+
+ const [matcher, options, waitForOptions] = args.map(deserializeArg);
+
+ void (async () => {
+ let result: ReturnType<(typeof window.TestingLibraryDom)[typeof query]> = null;
+ try {
+ // Override RegExp to fix 'matcher instanceof RegExp' check on Firefox
+ window.RegExp = RegExp;
+
+ result = await window.TestingLibraryDom[query](
+ container,
+ // @ts-expect-error Matcher can be any type from @testing-library/dom
+ matcher as Matcher,
+ options as MatcherOptions,
+ waitForOptions as WaitForOptions,
+ );
+ } catch (e: unknown) {
+ return done((e as Error).message);
+ }
+
+ if (!result) {
+ return done(null);
+ }
+
+ function makeSelectorResult(element: HTMLElement): { selector: string } {
+ const elementIdAttributeName = "data-testplane-element-id";
+ let elementId = element.getAttribute(elementIdAttributeName);
+
+ // if id doesn't already exist create one and add it to element
+ if (!elementId) {
+ elementId = (Math.abs(Math.random()) * 1000000000000).toFixed(0);
+ element.setAttribute(elementIdAttributeName, elementId);
+ }
+
+ return { selector: `[${elementIdAttributeName}="${elementId}"]` };
+ }
+
+ if (Array.isArray(result)) {
+ return done(result.map(makeSelectorResult));
+ }
+
+ return done(makeSelectorResult(result));
+ })();
+ });
+}
+
+function createQuery(container: WebdriverIO.Element & SelectorsBase, queryName: QueryName) {
+ return async (...args: QueryArg[]) => {
+ await injectDOMTestingLibrary(container);
+
+ const browser = findBrowser(container);
+ const result: SerializedQueryResult = await browser.execute(
+ executeQuery,
+ queryName,
+ container as unknown as HTMLElement,
+ ...args.map(serializeArg),
+ );
+
+ if (typeof result === "string") {
+ throw new Error(result);
+ }
+
+ if (!result) {
+ return null;
+ }
+
+ if (Array.isArray(result)) {
+ return Promise.all(result.map(({ selector }) => container.$(selector)));
+ }
+
+ return container.$(result.selector);
+ };
+}
+
+function within(element: WebdriverIO.Element & SelectorsBase) {
+ return (Object.keys(baseQueries) as QueryName[]).reduce(
+ (queries, queryName) => ({
+ ...queries,
+ [queryName]: createQuery(element, queryName),
+ }),
+ {},
+ ) as TestplaneQueries;
+}
+
+/*
+ eslint-disable
+ @typescript-eslint/no-explicit-any
+*/
+
+// Patches (via addCommand) the browser object with the DomTestingLibrary queries
+function setupBrowser(browser: Browser): TestplaneQueries {
+ const queries: { [key: string | number | symbol]: TestplaneQueries[QueryName] } = {};
+
+ Object.keys(baseQueries).forEach(key => {
+ const queryName = key as QueryName;
+
+ const query = async (...args: Parameters) => {
+ const body = await browser.$("body");
+ return within(body as WebdriverIO.Element & SelectorsBase)[queryName](...(args as any[]));
+ };
+
+ // add query to response queries
+ queries[queryName] = query as TestplaneQueries[QueryName];
+
+ // add query to BrowserObject and Elements
+ browser.addCommand(queryName, query as TestplaneQueries[QueryName]);
+ browser.addCommand(
+ queryName,
+ function (this: WebdriverIO.Element & SelectorsBase, ...args: any) {
+ return within(this)[queryName](...args);
+ },
+ true,
+ );
+
+ // add chainable query to BrowserObject and Elements
+ browser.addCommand(`${queryName}$`, query as TestplaneQueriesChainable[`${QueryName}$`]);
+ browser.addCommand(
+ `${queryName}$`,
+ function (this: WebdriverIO.Element & SelectorsBase, ...args) {
+ return within(this)[queryName](...args);
+ },
+ true,
+ );
+ });
+
+ return queries as unknown as TestplaneQueries;
+}
+
+/*
+ eslint-enable
+ @typescript-eslint/no-explicit-any
+*/
+
+function configure(config: Partial) {
+ _config = config;
+}
+
+export * from "./types.js";
+export { within, setupBrowser, configure };
diff --git a/src/types.ts b/src/types.ts
new file mode 100644
index 0000000..564a982
--- /dev/null
+++ b/src/types.ts
@@ -0,0 +1,88 @@
+import {
+ Config as BaseConfig,
+ BoundFunction as BoundFunctionBase,
+ queries,
+ waitForOptions,
+ SelectorMatcherOptions,
+ MatcherOptions,
+} from "@testing-library/dom";
+
+/*
+ eslint-disable
+ @typescript-eslint/no-explicit-any
+*/
+
+export type BaseWithExecute = {
+ execute(script: string | ((...args: any[]) => T), ...args: any[]): Promise;
+
+ execute(script: string | ((...args: any[]) => T), ...args: any[]): T;
+
+ executeAsync(script: string | ((...args: any[]) => void), ...args: any[]): any;
+};
+
+export type SelectorsBase = Pick;
+
+export type Queries = typeof queries;
+export type QueryName = keyof Queries;
+
+export type Config = Pick<
+ BaseConfig,
+ | "asyncUtilTimeout"
+ | "computedStyleSupportsPseudoElements"
+ | "defaultHidden"
+ | "testIdAttribute"
+ | "throwSuggestions"
+>;
+
+export type QueryReturnType =
+ T extends Promise
+ ? Element
+ : T extends HTMLElement
+ ? Element
+ : T extends Promise
+ ? ElementArray
+ : T extends HTMLElement[]
+ ? ElementArray
+ : T extends null
+ ? null
+ : never;
+
+export type BoundFunction = (
+ ...params: Parameters>
+) => Promise>>>;
+
+export type BoundFunctionSync = (
+ ...params: Parameters>
+) => QueryReturnType>>;
+
+export type TestplaneQueries = {
+ [P in keyof Queries]: BoundFunction;
+};
+
+export type TestplaneQueriesChainable = {
+ [P in keyof Queries as `${string & P}$`]: Container extends SelectorsBase
+ ? BoundFunctionSync, ReturnType, Queries[P]>
+ : undefined;
+};
+
+export type ObjectQueryArg = MatcherOptions | queries.ByRoleOptions | SelectorMatcherOptions | waitForOptions;
+
+export type QueryArg = ObjectQueryArg | RegExp | number | string | undefined;
+
+export type SerializedObject = {
+ serialized: "object";
+ [key: string]: SerializedArg;
+};
+export type SerializedRegExp = { serialized: "RegExp"; RegExp: string };
+export type SerializedUndefined = { serialized: "Undefined"; Undefined: true };
+
+export type SerializedArg = SerializedObject | SerializedRegExp | SerializedUndefined | number | string;
+
+declare global {
+ // eslint-disable-next-line @typescript-eslint/no-namespace
+ namespace WebdriverIO {
+ // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+ interface Element extends TestplaneQueries {}
+ interface Browser extends TestplaneQueries, TestplaneQueriesChainable {}
+ }
+}
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..19d77ef
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "es2019",
+ "module": "commonjs",
+ "strict": true,
+ "esModuleInterop": true,
+ "declaration": true,
+ "outDir": "./build",
+ "skipLibCheck": true,
+ "noEmit": false,
+ "types": ["testplane"]
+ },
+ "exclude": ["build"]
+}
+ 
+ 
+ 