promod 2.5.3 → 3.0.0

package/docs/elements.md

@@ -1,116 +1,176 @@
 # Elements
 
-Elements has "lazy" interface (as it was in protractor)
+Elements has a "lazy" interface (as it was in protractor). The collection is not resolved until an action is performed on it.
 
-- [searchStragegy](#searchstragegy)
+All examples work identically with both `playwrightWD` and `seleniumWD`.
+
+- [Selector strategies](#selector-strategies)
 - [get](#get)
 - [first](#first)
 - [last](#last)
+- [count](#count)
+- [getFirstVisible](#getfirstvisible)
+- [getAllVisible](#getallvisible)
 - [each](#each)
 - [map](#map)
 - [some](#some)
 - [every](#every)
+- [find](#find)
+- [filter](#filter)
+- [getEngineElements](#getengineelements)
+
+---
 
-## searchStragegy
+## Selector strategies
 
 ```js
-const { seleniumWD } = require('promod');
-const { By, $$ } = seleniumWD;
-// css
-const elementsByCss = $$('.class #id div a[href*="link"]'); // css selector
-const elementsByXpath = $$('xpath=.//div[@data-test="id"]/span'); // xpath selector
-const elementsByJS = $$(() => document.querySelectorAll("div>span")); // js selector
-const elementWithByInterface = $$(By.className('class')); // By object interface
+const { playwrightWD } = require('promod');
+const { $$ } = playwrightWD;
+
+const byCss = $$('.class #id div a[href*="link"]');
+const byXpath = $$('xpath=.//div[@data-test="id"]/span');
+const byJS = $$(() => document.querySelectorAll('div > span'));
+const byCustom = $$({ query: 'button', text: 'Submit' });
 ```
 
 ## get
 
+Returns a single element from the collection by index. Negative indexes count from the end.
+
 ```js
-const { seleniumWD } = require('promod');
-const { $$ } = seleniumWD;
-const someInput = $$('input').get(3);
+const buttons = $$('button');
 
-(async () => {
-  await someInput.sendKeys('some value');
-})();
+const first = buttons.get(0);
+const third = buttons.get(2);
+const last = buttons.get(-1);
+
+await first.click();
 ```
 
 ## first
 
-```js
-const { seleniumWD } = require('promod');
-const { $$ } = seleniumWD;
-const someButton = $$('button').first();
+Shorthand for `get(0)`.
 
-(async () => {
-  await someButton.click();
-})();
+```js
+const button = $$('button').first();
+await button.click();
 ```
 
 ## last
 
+Shorthand for `get(-1)`.
+
 ```js
-const { seleniumWD } = require('promod');
-const { $$ } = seleniumWD;
-const someButton = $$('button').last();
+const button = $$('button').last();
+await button.click();
+```
+
+## count
 
-(async () => {
-  await someButton.click();
-})();
+Returns the number of elements matching the selector.
+
+```js
+const count = await $$('button').count();
+```
+
+## getFirstVisible
+
+Returns the first visible (displayed) element in the collection.
+
+```js
+const visibleButton = $$('button').getFirstVisible();
+await visibleButton.click();
+```
+
+## getAllVisible
+
+Returns a new elements collection containing only visible elements.
+
+```js
+const visibleButtons = $$('button').getAllVisible();
+const visibleCount = await visibleButtons.count();
 ```
 
 ## each
 
+Iterates over each element in the collection.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$$} = seleniumWD
-	const someButtons = $$('button');
-
-	;(async () => {
-		await someButtons.each((someButton) => {
-			await someButton.click()
-		})
-	})()
+const buttons = $$('button');
+
+await buttons.each(async (button, index) => {
+  await button.click();
+});
 ```
 
 ## map
 
+Maps each element to a value.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$$} = seleniumWD
-	const someButtons = $$('button');
-
-	;(async () => {
-		const allButtonTexts = await someButtons.map((button) => {
-			return await someButton.getText()
-		})
-	})()
+const buttons = $$('button');
+
+const texts = await buttons.map(async (button) => {
+  return await button.getText();
+});
 ```
 
 ## some
 
+Returns `true` if the callback returns `true` for at least one element.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$$} = seleniumWD
-	const someButtons = $$('button');
-
-	;(async () => {
-		const isSomeButtonVisible = await someButtons.some((button) => {
-			return await someButton.isDisplayed()
-		})
-	})()
+const buttons = $$('button');
+
+const isSomeVisible = await buttons.some(async (button) => {
+  return await button.isDisplayed();
+});
 ```
 
 ## every
 
+Returns `true` if the callback returns `true` for every element.
+
+```js
+const buttons = $$('button');
+
+const allVisible = await buttons.every(async (button) => {
+  return await button.isDisplayed();
+});
+```
+
+## find
+
+Finds the first element matching the callback condition.
+
+```js
+const buttons = $$('button');
+
+const submitBtn = await buttons.find(async (button) => {
+  return (await button.getText()) === 'Submit';
+});
+
+await submitBtn.click();
+```
+
+## filter
+
+Returns a new elements collection with elements matching the callback condition.
+
+```js
+const buttons = $$('button');
+
+const enabledButtons = buttons.filter(async (button) => {
+  return await button.isEnabled();
+});
+
+const count = await enabledButtons.count();
+```
+
+## getEngineElements
+
+Returns the underlying native engine elements (Playwright `Locator[]` / Selenium `WebElement[]`).
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$$} = seleniumWD
-	const someButtons = $$('button');
-
-	;(async () => {
-		const isEveryButtonVisible = await someButtons.every((button) => {
-			return await someButton.isDisplayed()
-		})
-	})()
+const nativeElements = await $$('button').getEngineElements();
 ```

package/docs/init.md

@@ -1,27 +1,81 @@
-# Set driver to engine wrapper
+# Engine setup
 
-[Promod](https://github.com/Simple-Automation-Testing/promod) is a library, it does not have own test runner, and own browser manipulation interface. <br> Currently promod has API alignment for [playwright](https://www.npmjs.com/package/playwright) <br> and [selenium-webdriver](https://www.npmjs.com/package/selenium-webdriver) so to run browser manipulation interface next functions could be created
+Promod does not ship its own test runner or browser driver. It wraps [Playwright](https://www.npmjs.com/package/playwright) and [Selenium WebDriver](https://www.npmjs.com/package/selenium-webdriver) with a unified API.
+
+- [Playwright setup](#playwright-setup)
+- [Selenium WebDriver setup](#selenium-webdriver-setup)
+- [Engine switcher](#engine-switcher)
+- [Browser config translation](./config.md) — define settings once, translate to engine-specific config
+
+## Playwright setup
+
+```js
+const { chromium } = require('playwright');
+const { playwrightWD } = require('promod');
+const { browser, $, $$ } = playwrightWD;
+
+async function setup() {
+  const launched = await chromium.launch({ headless: false });
+  browser.setClient({ driver: launched });
+}
+```
+
+`setClient` accepts:
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `driver` | `Browser` (Playwright) | Launched browser instance |
+| `lauchNewInstance` | `() => Promise<Browser>` | Factory to create new browser instances for `runNewBrowser()` |
+| `baseConfig` | `object` | Default context config (viewport, userAgent, isMobile) |
+
+## Selenium WebDriver setup
+
+```js
+const { Browser, Builder } = require('selenium-webdriver');
+require('chromedriver');
+const { seleniumWD } = require('promod');
+const { browser, $, $$ } = seleniumWD;
+
+async function setup() {
+  const driver = await new Builder().forBrowser(Browser.CHROME).build();
+  browser.setClient({
+    driver,
+    lauchNewInstance: () => new Builder().forBrowser(Browser.CHROME).build(),
+  });
+}
+```
+
+`setClient` accepts:
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `driver` | `ThenableWebDriver` | Selenium WebDriver instance |
+| `lauchNewInstance` | `() => Promise<ThenableWebDriver>` | Factory for `runNewBrowser()` |
+
+## Engine switcher
+
+A common pattern is to select the engine via an environment variable:
 
 ```js
 const { chromium } = require('playwright');
 const { Browser, Builder } = require('selenium-webdriver');
-const { ENGINE } = process.env;
+const { playwrightWD, seleniumWD } = require('promod');
+
+const { ENGINE } = process.env; // 'pw' or 'swd'
 
 async function getEngine() {
   if (ENGINE === 'pw') {
-    const lauchedChrome = await chromium.launch({ headless: false });
-    playwrightWD.browser.setClient({ driver: lauchedChrome });
-
-		return playwrightWD;
+    const launched = await chromium.launch({ headless: false });
+    playwrightWD.browser.setClient({ driver: launched });
+    return playwrightWD;
   } else {
     require('chromedriver');
-    const lauchedChrome = await new Builder().forBrowser(Browser.CHROME).build();
+    const driver = await new Builder().forBrowser(Browser.CHROME).build();
     seleniumWD.browser.setClient({
-      driver: lauchedChrome,
-      lauchNewInstance: async () => await new Builder().forBrowser(Browser.CHROME).build(),
+      driver,
+      lauchNewInstance: () => new Builder().forBrowser(Browser.CHROME).build(),
     });
-
-		return seleniumWD
+    return seleniumWD;
   }
 }
 

package/oxlintrc.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://raw.githubusercontent.com/nicolo-ribaudo/oxc/json-schema/npm/oxlint/configuration_schema.json",
+  "plugins": ["unicorn", "promise"],
+  "ignorePatterns": ["built", "playground.*"],
+  "rules": {
+    "no-console": "error",
+    "unicorn/no-null": "off",
+    "unicorn/explicit-length-check": "off",
+    "unicorn/prevent-abbreviations": "off",
+    "unicorn/prefer-node-protocol": "off",
+    "unicorn/import-style": "off",
+    "unicorn/no-this-assignment": "off",
+    "unicorn/no-array-for-each": "off",
+    "unicorn/no-array-reduce": "off",
+    "unicorn/filename-case": "off",
+    "unicorn/prefer-module": "off",
+    "unicorn/prefer-spread": "off",
+    "unicorn/consistent-destructuring": "off"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promod",
-  "version": "2.5.3",
+  "version": "3.0.0",
   "description": "Library for automation testing",
   "bin": "./bin/promod_cli",
   "main": "./built/cjs/index.js",
@@ -16,7 +16,7 @@
     "test:swd": "ENGINE=swd mocha $(find specs -name '*.spec.*') --require ts-node/register --timeout 500000",
     "test:units": "mocha $(find units -name '*.test.*') --require ts-node/register --timeout 500000",
     "test:debug": "mocha ./specs/async.child.methods.spec.ts --require ts-node/register --timeout 300000",
-    "lint": "eslint --ext .ts ./",
+    "lint": "oxlint -c oxlintrc.json --tsconfig tsconfig.json .",
     "tsc:cjs": "tsc -p tsconfig.json",
     "tsc:esm": "tsc -p tsconfig.esm.json",
     "tsc": "rm -rf ./built && npm run tsc:cjs && npm run tsc:esm"
@@ -35,11 +35,12 @@
   },
   "homepage": "https://github.com/Simple-Automation-Testing/promod#readme",
   "dependencies": {
-    "@types/selenium-webdriver": "^4.35.4",
+    "@types/selenium-webdriver": "^4.35.5",
+    "playwright-core": "^1.58.2",
     "sat-compare": "^0.1.0",
-    "sat-utils": "^3.0.2",
-    "sat-wait": "^0.1.0",
-    "playwright-core": "^1.56.1"
+    "sat-utils": "^3.2.0",
+    "sat-wait": "^0.1.6",
+    "selenium-webdriver": "^4.40.0"
   },
   "keywords": [
     "promod",
@@ -52,18 +53,14 @@
     "playwright mod"
   ],
   "devDependencies": {
-    "@types/mocha": "^10.0.8",
-    "@typescript-eslint/eslint-plugin": "^8.7.0",
-    "@typescript-eslint/parser": "^8.7.0",
+    "@types/mocha": "^10.0.10",
     "assertior": "^0.0.28",
-    "chromedriver": "^135.0.2",
-    "eslint": "^9.11.1",
-    "eslint-plugin-mocha": "^10.5.0",
-    "mocha": "^10.7.3",
-    "playwright": "^1.52.0",
-    "prettier": "^3.3.3",
-    "selenium-webdriver": "^4.31.0",
+    "chromedriver": "^144.0.1",
+    "mocha": "^11.7.5",
+    "oxlint": "^1.43.0",
+    "playwright": "^1.58.2",
+    "prettier": "^3.8.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.7.3"
+    "typescript": "^5.9.3"
   }
-}
+}

package/readme.md

@@ -1,19 +1,119 @@
+# promod
+
 <p align="center">
-  <h1 align="center"> PROMOD </h1>
-  <img style="width:100%;" src="./docs/promod.png"/>
+  <img src="./docs/promod.png" alt="promod" width="200"/>
 </p>
 
-<h2> API </h2>
-<p>
-  Browser and element APIs
-</p>
-<p><a href="/docs/element.md">Element</a></p>
-<p><a href="/docs/elements.md">Elements</a></p>
-<p><a href="/docs/client.md">Browser</a></p>
-<p><a href="/docs/init.md">Init driver</a></p>
+Browser automation library with a unified API over [Playwright](https://playwright.dev/) and [Selenium WebDriver](https://www.selenium.dev/documentation/webdriver/).
+
+Promod provides a **protractor-like** lazy element interface — elements are not resolved until an action is performed on them.
+
+## Installation
+
+```bash
+npm install promod
+```
+
+Promod requires a browser engine as a peer dependency:
+
+```bash
+# For Playwright
+npm install playwright
+
+# For Selenium WebDriver
+npm install selenium-webdriver chromedriver
+```
+
+## Quick start
+
+### Playwright
+
+```js
+const { chromium } = require('playwright');
+const { playwrightWD } = require('promod');
+const { browser, $, $$ } = playwrightWD;
+
+async function main() {
+  const launched = await chromium.launch({ headless: false });
+  browser.setClient({ driver: launched });
+
+  await browser.get('https://example.com');
+
+  const heading = $('h1');
+  console.log(await heading.getText());
+
+  await browser.quitAll();
+}
+
+main();
+```
+
+### Selenium WebDriver
+
+```js
+const { Browser, Builder } = require('selenium-webdriver');
+require('chromedriver');
+const { seleniumWD } = require('promod');
+const { browser, $, $$ } = seleniumWD;
+
+async function main() {
+  const driver = await new Builder().forBrowser(Browser.CHROME).build();
+  browser.setClient({
+    driver,
+    lauchNewInstance: () => new Builder().forBrowser(Browser.CHROME).build(),
+  });
+
+  await browser.get('https://example.com');
+
+  const heading = $('h1');
+  console.log(await heading.getText());
+
+  await browser.quit();
+}
+
+main();
+```
+
+## ESM / CommonJS
+
+Promod ships dual builds. Bundlers and Node `import` will use ESM; `require()` will use CommonJS.
+
+```js
+// ESM
+import { playwrightWD, seleniumWD } from 'promod';
+
+// CommonJS
+const { playwrightWD, seleniumWD } = require('promod');
+```
+
+## Selector strategies
+
+All examples work identically with both `playwrightWD` and `seleniumWD`.
+
+```js
+// CSS (default)
+const el = $('.my-class #id a[href*="link"]');
+
+// XPath
+const el = $('xpath=.//div[@data-test="id"]/span');
+
+// JavaScript function
+const el = $(() => document.querySelector('div > span'));
+
+// Custom selector (query + text filter)
+const el = $({ query: 'button', text: 'Submit' });
+const el = $({ query: 'button', rg: 'Sub.*' }); // regex filter
+```
+
+## API
+
+| Topic | Link |
+| --- | --- |
+| Engine setup | [docs/init.md](./docs/init.md) |
+| Browser (client) | [docs/client.md](./docs/client.md) |
+| Element (`$`) | [docs/element.md](./docs/element.md) |
+| Elements (`$$`) | [docs/elements.md](./docs/elements.md) |
 
-## Improvement plan
+## License
 
-- [x] Add playwright integration - done
-- [x] Add documentation - done
-- [ ] Add logger - in progress
+MIT

package/tsconfig.esm.json

@@ -1,12 +1,16 @@
 {
   "compilerOptions": {
-    "module": "NodeNext",
+    "module": "ESNext",
     "target": "ESNext",
+    "moduleResolution": "bundler",
     "sourceMap": true,
     "outDir": "built/esm",
     "declaration": true,
     "experimentalDecorators": true,
-    "allowJs": true
+    "allowJs": true,
+    "strict": true,
+    "strictPropertyInitialization": false,
+    "strictNullChecks": false
   },
   "include": [
     "lib"

package/tsconfig.json

@@ -6,7 +6,10 @@
 		"outDir": "built/cjs",
 		"declaration": true,
 		"experimentalDecorators": true,
-		"allowJs": true
+		"allowJs": true,
+		"strict": true,
+		"strictPropertyInitialization": false,
+		"strictNullChecks": false
 	},
 	"exclude": [
 		"node_modules",