promod 2.5.4 → 3.0.1

package/docs/config.md

@@ -0,0 +1,176 @@
+# Browser config
+
+Define browser settings once and translate them to engine-specific configuration for Playwright or Selenium WebDriver. No auto-launching — you still call `chromium.launch()` / `new Builder().build()` yourself.
+
+- [PromodBrowserConfig](#promodbrowserconfig)
+- [toPwConfig](#topwconfig)
+- [toSwdConfig](#toswdconfig)
+- [Full example](#full-example)
+
+---
+
+## PromodBrowserConfig
+
+A unified configuration object accepted by both translation functions.
+
+```ts
+const { toPwConfig, toSwdConfig } = require('promod');
+
+const config = {
+  browserName: 'chrome',
+  headless: true,
+  args: ['--disable-gpu'],
+  viewport: { width: 1280, height: 720 },
+};
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `browserName` | `'chrome' \| 'firefox' \| 'webkit' \| 'edge'` | Target browser (required) |
+| `headless` | `boolean` | Run without a visible window |
+| `args` | `string[]` | Extra browser arguments |
+| `executablePath` | `string` | Path to browser binary |
+| `proxy` | `{ server, bypass?, username?, password? }` | Proxy settings |
+| `viewport` | `{ width, height }` | Browser viewport size |
+| `userAgent` | `string` | Custom user-agent string |
+| `isMobile` | `boolean` | Emulate a mobile device |
+| `deviceScaleFactor` | `number` | Device pixel ratio |
+| `locale` | `string` | Browser locale (e.g. `'en-US'`) |
+| `timezoneId` | `string` | Timezone (e.g. `'America/New_York'`) |
+| `permissions` | `string[]` | Granted permissions (e.g. `['geolocation']`) |
+| `geolocation` | `{ latitude, longitude, accuracy? }` | Geolocation override |
+| `colorScheme` | `'light' \| 'dark' \| 'no-preference'` | Preferred color scheme |
+| `ignoreHTTPSErrors` | `boolean` | Accept insecure certificates |
+
+Only set properties appear in the output — no undefined keys are added.
+
+---
+
+## toPwConfig
+
+Translates a `PromodBrowserConfig` into Playwright launch and context options.
+
+```js
+const { toPwConfig } = require('promod');
+
+const { browserType, launchOptions, contextOptions } = toPwConfig({
+  browserName: 'chrome',
+  headless: true,
+  viewport: { width: 1280, height: 720 },
+  locale: 'en-US',
+});
+```
+
+Returns:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `browserType` | `'chromium' \| 'firefox' \| 'webkit'` | Playwright browser type to launch |
+| `launchOptions` | `object` | Passed to `chromium.launch(launchOptions)` |
+| `contextOptions` | `object` | Passed to `browser.newContext()` or `setClient({ baseConfig })` |
+
+Browser name mapping:
+
+| `browserName` | `browserType` | Extra |
+| --- | --- | --- |
+| `'chrome'` | `'chromium'` | — |
+| `'edge'` | `'chromium'` | `launchOptions.channel = 'msedge'` |
+| `'firefox'` | `'firefox'` | — |
+| `'webkit'` | `'webkit'` | — |
+
+Properties routed to `launchOptions`: `headless`, `args`, `executablePath`, `proxy`.
+
+Properties routed to `contextOptions`: `viewport`, `userAgent`, `isMobile`, `deviceScaleFactor`, `locale`, `timezoneId`, `permissions`, `geolocation`, `colorScheme`, `ignoreHTTPSErrors`.
+
+---
+
+## toSwdConfig
+
+Translates a `PromodBrowserConfig` into Selenium WebDriver capabilities.
+
+```js
+const { toSwdConfig } = require('promod');
+
+const { browserName, capabilities } = toSwdConfig({
+  browserName: 'chrome',
+  headless: true,
+  viewport: { width: 1280, height: 720 },
+});
+```
+
+Returns:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `browserName` | `string` | Selenium browser name (`'chrome'`, `'MicrosoftEdge'`, `'firefox'`) |
+| `capabilities` | `object` | Capabilities object for `new Builder().withCapabilities()` |
+
+Browser name mapping:
+
+| `browserName` | Selenium `browserName` | Capabilities key |
+| --- | --- | --- |
+| `'chrome'` | `'chrome'` | `goog:chromeOptions` |
+| `'edge'` | `'MicrosoftEdge'` | `ms:edgeOptions` |
+| `'firefox'` | `'firefox'` | `moz:firefoxOptions` |
+| `'webkit'` | — | throws an error |
+
+Property mapping — Chrome / Edge:
+
+| Property | Mapping |
+| --- | --- |
+| `headless` | `args: ['--headless=new']` |
+| `args` | merged into `args` |
+| `executablePath` | `binary` |
+| `proxy` | `--proxy-server=<server>` arg |
+| `viewport` | `--window-size=W,H` arg |
+| `userAgent` | `--user-agent=...` arg + `mobileEmulation.userAgent` |
+| `isMobile` | `mobileEmulation.deviceMetrics.mobile` |
+| `deviceScaleFactor` | `mobileEmulation.deviceMetrics.pixelRatio` |
+| `locale` | `--lang=...` arg |
+| `ignoreHTTPSErrors` | top-level `acceptInsecureCerts: true` |
+| `timezoneId, permissions, geolocation, colorScheme` | not mapped (require CDP at runtime) |
+
+Property mapping — Firefox:
+
+| Property | Mapping |
+| --- | --- |
+| `headless` | `args: ['-headless']` |
+| `args` | merged into `args` |
+| `executablePath` | `binary` |
+| `userAgent` | `prefs['general.useragent.override']` |
+| `locale` | `prefs['intl.accept_languages']` |
+| `ignoreHTTPSErrors` | top-level `acceptInsecureCerts: true` |
+| `proxy, viewport, isMobile, deviceScaleFactor` | not mapped (set at runtime) |
+| `timezoneId, permissions, geolocation, colorScheme` | not mapped |
+
+---
+
+## Full example
+
+```js
+const { chromium, firefox, webkit } = require('playwright');
+const { Builder } = require('selenium-webdriver');
+const { playwrightWD, seleniumWD, toPwConfig, toSwdConfig } = require('promod');
+
+const config = {
+  browserName: 'chrome',
+  headless: true,
+  viewport: { width: 1280, height: 720 },
+  locale: 'en-US',
+};
+
+// Playwright
+async function setupPlaywright() {
+  const pw = { chromium, firefox, webkit };
+  const { browserType, launchOptions, contextOptions } = toPwConfig(config);
+  const driver = await pw[browserType].launch(launchOptions);
+  playwrightWD.browser.setClient({ driver, baseConfig: contextOptions });
+}
+
+// Selenium WebDriver
+async function setupSelenium() {
+  const { browserName, capabilities } = toSwdConfig(config);
+  const driver = await new Builder().forBrowser(browserName).withCapabilities(capabilities).build();
+  seleniumWD.browser.setClient({ driver });
+}
+```

package/docs/element.md

@@ -1,230 +1,303 @@
 # Element
-Element has "lazy" interface (as it was in protractor)
 
-- [searchStragegy](#searchstragegy)
-- [sendKeys](#sendkeys)
+Element has a "lazy" interface (as it was in protractor). The element is not resolved until an action is performed on it.
+
+All examples work identically with both `playwrightWD` and `seleniumWD`.
+
+- [Selector strategies](#selector-strategies)
+- [Child elements](#child-elements)
 - [click](#click)
-- [doubleClick](#doubleClick)
+- [doubleClick](#doubleclick)
+- [sendKeys](#sendkeys)
+- [clear](#clear)
+- [clearViaBackspace](#clearViabackspace)
+- [pressEnter](#pressenter)
 - [hover](#hover)
+- [hoverByElementCoordinate](#hoverbyelementcoordinate)
+- [clickByElementCoordinate](#clickbyelementcoordinate)
+- [getElementCoordinates](#getelementcoordinates)
 - [focus](#focus)
+- [getText](#gettext)
 - [getTagName](#gettagname)
-- [getCssValue](#getcssvalue)
 - [getAttribute](#getattribute)
-- [getText](#gettext)
+- [getCssValue](#getcssvalue)
 - [getRect](#getrect)
+- [isDisplayed](#isdisplayed)
+- [isPresent](#ispresent)
 - [isEnabled](#isenabled)
 - [isSelected](#isselected)
-- [isPresent](#ispresent)
-- [isDisplayed](#isdisplayed)
 - [submit](#submit)
-- [clear](#clear)
-- [takeScreenshot](#takescreenshot)
+- [selectOption](#selectoption)
 - [scrollIntoView](#scrollintoview)
+- [takeScreenshot](#takescreenshot)
+- [getEngineElement](#getengineelement)
+- [locator](#locator)
 
+---
+
+## Selector strategies
 
-## searchStragegy
 ```js
-	const elementByCss = $('.class #id div a[href*="link"]') // css selector
-	const elementByXpath = $('xpath=.//div[@data-test="id"]/span') // xpath selector
-	const elementByJS = $(() => document.querySelector("div > span")) // js selector
+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.querySelector('div > span'));
+const byCustom = $({ query: 'button', text: 'Submit' });
+const byCustomRegex = $({ query: 'button', rg: 'Sub.*' });
 ```
 
-## sendKeys
-```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someInput = $('input')
+## Child elements
+
+Elements can create child `$` and `$$` from themselves, scoping the search to the parent element.
 
-	;(async () => {
-		await someInput.sendKeys('some value')
-	})
+```js
+const form = $('form');
+const input = form.$('input');           // single child element
+const buttons = form.$$('button');       // child elements collection
 ```
 
 ## click
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const button = $('button');
 
-	;(async () => {
-		await someButton.click()
-	})
+await button.click();                                  // regular click
+await button.click({ withScroll: true });              // scroll into view first
+await button.click({ allowForceIfIntercepted: true }); // retry via coordinates if intercepted
+await button.click({ force: true });                   // force click via coordinates
+await button.click({ button: 'right' });               // right click
 ```
 
+| Option | Type | Description |
+| --- | --- | --- |
+| `withScroll` | `boolean` | Scroll element into view before clicking |
+| `allowForceIfIntercepted` | `boolean` | Retry via coordinates if click is intercepted |
+| `force` | `boolean` | Click via coordinates directly |
+| `button` | `'left' \| 'right' \| 'middle'` | Mouse button |
+| `clickCount` | `number` | Number of clicks |
+| `delay` | `number` | Delay between mousedown and mouseup |
+| `modifiers` | `Array<'Alt'\|'Control'\|'Meta'\|'Shift'>` | Modifier keys |
+| `position` | `{ x: number; y: number }` | Click position relative to element |
+| `timeout` | `number` | Timeout in ms |
+
 ## doubleClick
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const button = $('button');
 
-	;(async () => {
-		await someButton.doubleClick()
-	})
+await button.doubleClick();
+await button.doubleClick({ withScroll: true });
 ```
 
-## hover
+Accepts the same options as `click` (except `clickCount`).
+
+## sendKeys
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const input = $('input');
 
-	;(async () => {
-		await someButton.hover()
-	})
+await input.sendKeys('hello world');
+await input.sendKeys(42);
+await input.sendKeys('hello', true); // use fill mode (Playwright: clears first then fills)
 ```
 
-## focus
+## clear
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const input = $('input');
+await input.clear();
+```
 
-	;(async () => {
-		await someButton.focus()
-	})
+## clearViaBackspace
+
+Clears input by pressing backspace repeatedly.
+
+```js
+const input = $('input');
+await input.sendKeys('hello');
+await input.clearViaBackspace(5, true); // 5 backspaces, focus first
 ```
 
-## getTagName
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `repeat` | `number` | Number of backspace presses (default 1) |
+| `focus` | `boolean` | Focus/click element first |
+
+## pressEnter
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const input = $('input');
+await input.sendKeys('search query');
+await input.pressEnter();       // focus first (default)
+await input.pressEnter(false);  // without focusing
+```
 
-	;(async () => {
-		const tagName = await someButton.getTagName() // button
-	})
+## hover
+
+```js
+const button = $('button');
+
+await button.hover();
+await button.hover({ force: true });
 ```
 
-## getCssValue
+## hoverByElementCoordinate
+
+Moves the mouse to a specific position relative to the element.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const el = $('div');
+await el.hoverByElementCoordinate('center');
+await el.hoverByElementCoordinate('right-top');
+```
+
+Positions: `'center'`, `'center-top'`, `'center-bottom'`, `'center-right'`, `'center-left'`, `'right-top'`, `'right-bottom'`, `'left-top'`, `'left-bottom'`
+
+## clickByElementCoordinate
 
-	;(async () => {
-		const buttonColor = await someButton.getCssValue('color') // some color
-	})
+Clicks at a specific position relative to the element.
+
+```js
+const el = $('div');
+await el.clickByElementCoordinate('center');
+await el.clickByElementCoordinate('left-top');
 ```
 
-## getAttribute
+## getElementCoordinates
+
+Returns the x/y coordinates of a specific position on the element.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const { x, y } = await $('div').getElementCoordinates('center');
+```
 
-	;(async () => {
-		const buttonAttribute = await someButton.getAttribute('data-id') // value of data-id attribute
-	})
+## focus
+
+```js
+const input = $('input');
+await input.focus();
 ```
 
 ## getText
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const text = await $('h1').getText();
+```
+
+## getTagName
 
-	;(async () => {
-		const buttonText = await someButton.getText() // button Text
-	})
+```js
+const tag = await $('h1').getTagName(); // 'h1'
 ```
 
-## getRect
+## getAttribute
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const href = await $('a').getAttribute('href');
+const dataId = await $('div').getAttribute('data-id');
+```
+
+## getCssValue
 
-	;(async () => {
-		const buttonRect = await someButton.getRect() // {x: number, y: number, width: number, height: number}
-	})
+Returns the computed CSS property value.
+
+```js
+const color = await $('button').getCssValue('color');
+const fontSize = await $('h1').getCssValue('font-size');
 ```
 
-## isEnabled
+## getRect
+
+Returns the element bounding box.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const { x, y, width, height } = await $('div').getRect();
+```
 
-	;(async () => {
-		const buttonAvailableToClick = await someButton.isEnabled() // true|false
-	})()
+## isDisplayed
+
+```js
+const visible = await $('button').isDisplayed(); // true | false
 ```
 
 ## isPresent
-```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
 
-	;(async () => {
-		const buttonExistsInDOM = await someButton.isPresent() // true|false
-	})()
-```
+Checks if the element exists in the DOM.
 
-## isDisplayed
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const exists = await $('button').isPresent(); // true | false
+```
 
-	;(async () => {
-		const buttonIsVisible = await someButton.isDisplayed() // true|false
-	})()
+## isEnabled
+
+```js
+const enabled = await $('button').isEnabled(); // true | false
 ```
 
 ## isSelected
-```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
 
-	;(async () => {
-		const buttonIsSelected = await someButton.isSelected() // true|false
-	})()
+```js
+const selected = await $('input[type="checkbox"]').isSelected(); // true | false
 ```
 
 ## submit
+
+```js
+await $('form').submit();
+```
+
+## selectOption
+
+Works with `<select>` elements.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someButton = $('button')
+const select = $('select');
+
+// By visible text
+await select.selectOption('Option text');
+
+// By value attribute
+await select.selectOption({ value: 'opt1' });
+
+// By label attribute
+await select.selectOption({ label: 'Option Label' });
 
-	;(async () => {
-		await someButton.submit()
-	})()
+// By index
+await select.selectOption({ index: 2 });
 ```
 
-## clear
+## scrollIntoView
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someInput = $('input')
+const el = $('div');
 
-	;(async () => {
-		await someInput.clear()
-	})()
+await el.scrollIntoView();          // default scroll
+await el.scrollIntoView('start');   // scroll to top of viewport
+await el.scrollIntoView('end');     // scroll to bottom of viewport
+await el.scrollIntoView('center');  // scroll to center of viewport
+await el.scrollIntoView('nearest'); // scroll to nearest edge
 ```
 
 ## takeScreenshot
-```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someForm = $('form')
 
-	;(async () => {
-		await someForm.takeScreenshot()
-	})()
+```js
+const screenshot = await $('form').takeScreenshot();
 ```
 
-## scrollIntoView
+## getEngineElement
+
+Returns the underlying native engine element (Playwright `Locator` / Selenium `WebElement`).
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {$} = seleniumWD
-	const someForm = $('form')
+const nativeElement = await $('button').getEngineElement();
+```
+
+## locator
 
-	;(async () => {
-		await someForm.scrollIntoView() // default scroll into view
-		await someForm.scrollIntoView('end') // move element to the bottom of the view port
-		await someForm.scrollIntoView('start') // move element to the top of the view port
-	})()
-```
+Returns the selector information used to find this element.
+
+```js
+const info = $('button').locator(); // { value: 'button' }
+```