promod 2.5.3 → 3.0.0

package/docs/client.md

@@ -1,212 +1,436 @@
 # Browser
 
-- [Key](#key)
-- [baseUrl](#baseUrl)
+The `browser` object provides methods for page navigation, tab/window management, script execution, cookies, iframes, keyboard actions, and more.
+
+All examples show both Playwright and Selenium WebDriver usage.
+
+- [Key / keyboard](#key--keyboard)
+- [baseUrl](#baseurl)
+- [get](#get)
 - [getCurrentUrl](#getcurrenturl)
-- [takeScreenshot](#takescreenshot)
+- [getTitle](#gettitle)
 - [refresh](#refresh)
-- [tabTitle](#tabtitle)
-- [getTabs](#gettabs)
-- [getCurrentTab](#getcurrenttab)
-- [close](#close)
-- [get](#get)
+- [back](#back)
+- [forward](#forward)
+- [takeScreenshot](#takescreenshot)
 - [setWindowSize](#setwindowsize)
+- [getWindomSize](#getwindomsize)
+- [maximize](#maximize)
 - [sleep](#sleep)
-- [manage](#manage)
 - [executeScript](#executescript)
-- [navigate](#navigate)
-- [switchTo](#switchto)
-- [quit](#quit)
-- [getTitle](#gettitle)
+- [getTabs](#gettabs)
+- [getTabsCount](#gettabscount)
+- [getCurrentTab](#getcurrenttab)
 - [switchToTab](#switchtotab)
 - [returnToInitialTab](#returntoinitialtab)
-- [actions](#actions)
+- [openNewTab](#opennewtab)
+- [makeActionAtEveryTab](#makeactionateverytab)
+- [close](#close)
+- [quit](#quit)
+- [quitAll](#quitall)
 - [runNewBrowser](#runnewbrowser)
 - [switchToBrowser](#switchtobrowser)
+- [switchToIframe](#switchtoiframe)
+- [switchToDefauldIframe](#switchtodefauldiframe)
+- [scrollByMouseWheel](#scrollbymousewheel)
+- [scrollElementByMouseWheel](#scrollelementbymousewheel)
+- [keyDownAndHold](#keydownandhold)
+- [keyUp](#keyup)
+- [keyDownAndUp](#keydownandup)
+- [keyboardPressEsc](#keyboardpressesc)
+- [keyboardPressEnter](#keyboardpressenter)
+- [setCookies](#setcookies)
+- [getCookies](#getcookies)
+- [getCookieByName](#getcookiebyname)
+- [deleteCookie](#deletecookie)
+- [deleteAllCookies](#deleteallcookies)
+- [getBrowserLogs](#getbrowserlogs)
+- [setBasicAuth](#setbasicauth)
+- [mockRequests](#mockrequests)
+- [wait](#wait)
+
+---
+
+## Key / keyboard
 
-## Key
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
-
-	browser.Key // getter - returns keyboard keys
+// Playwright
+const { playwrightWD } = require('promod');
+const { browser } = playwrightWD;
+browser.Key       // keyboard keys object
+browser.keyboard  // same as Key
+
+// Selenium
+const { seleniumWD } = require('promod');
+const { browser } = seleniumWD;
+browser.Key       // selenium Key object
 ```
 
 ## baseUrl
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+browser.baseUrl = 'https://your.app.com'; // setter
+const url = browser.baseUrl;              // getter
 
-	browser.baseUrl = 'https://your.app.com' // setter
-	const currnetBaseUrl = browser.baseUrl // getter - returns current base url
-	await browser.get('/test') // browser will open https://your.app.com/test
+await browser.get('/test'); // opens https://your.app.com/test
+```
+
+## get
+
+Opens a URL. If `baseUrl` is set and the argument is a relative path, the full URL is resolved.
+
+```js
+await browser.get('https://example.com');
+await browser.get('/relative/path'); // uses baseUrl
 ```
 
 ## getCurrentUrl
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+const url = await browser.getCurrentUrl();
+```
+
+## getTitle
 
-	const url = await browser.getCurrentUrl() // current browser line url
+```js
+const title = await browser.getTitle();
 ```
 
-## takeScreenshot
+## refresh
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.refresh();
+```
 
-	const screen = await browser.takeScreenshot()
+## back
+
+```js
+await browser.back();
 ```
 
-## refresh
+## forward
+
+```js
+await browser.forward();
+```
+
+## takeScreenshot
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+const screenshot = await browser.takeScreenshot();
+```
+
+## setWindowSize
 
-	await browser.refresh() // refresh page
+```js
+await browser.setWindowSize(1280, 720);
 ```
 
-## getTabs
+## getWindomSize
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+const { width, height } = await browser.getWindomSize();
+```
 
-	const tabs = await browser.getTabs() // current browser opened tabs
+## maximize
+
+```js
+await browser.maximize();
 ```
 
-## get
+## sleep
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.sleep(2500); // sleep 2.5 seconds
+```
+
+## executeScript
 
-	await browser.get('https://www.npmjs.com/package/promod') // open https://www.npmjs.com/package/promod
+Executes a script in the browser context. Arguments must be passed as an array.
+
+```js
+// No arguments
+const height = await browser.executeScript(() => document.body.offsetHeight);
+
+// With arguments
+const text = await browser.executeScript(
+  ([el]) => el.innerText,
+  [$('h1').getEngineElement()],
+);
 ```
 
-## setWindowSize
+## getTabs
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+const tabs = await browser.getTabs();
+```
+
+## getTabsCount
 
-	await browser.setWindowSize(200, 600) // set window size to width 200, height 600
+```js
+const count = await browser.getTabsCount();
 ```
 
-## sleep
+## getCurrentTab
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+const currentTab = await browser.getCurrentTab();
+```
 
-	await browser.sleep(2500) // sleep 2.5 seconds
+## switchToTab
+
+Switch to a tab by index, title, or URL.
+
+```js
+await browser.switchToTab({ index: 2 });
+await browser.switchToTab({ title: 'Some title' });
+await browser.switchToTab({ url: 'some-url-part', strictEquality: false });
+await browser.switchToTab({ index: 2, expectedQuantity: 3, timeout: 5000 });
 ```
 
-## executeScript
+| Option | Type | Description |
+| --- | --- | --- |
+| `index` | `number` | Tab index (0-based) |
+| `title` | `string` | Tab title to match |
+| `url` | `string` | URL to match |
+| `expectedQuantity` | `number` | Wait until this many tabs exist |
+| `timeout` | `number` | Max wait time in ms (default 5000) |
+| `strictEquality` | `boolean` | Exact match vs substring (default true) |
+
+## returnToInitialTab
+
+Closes all tabs except the initial one and switches back to it.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.switchToTab({ index: 2 });
+// ... do work ...
+await browser.returnToInitialTab();
+```
+
+## openNewTab
 
-	await browser.executeScript(() => document.querySelector('a').innerText) // returns result of the script
+```js
+await browser.openNewTab('https://example.com');
+await browser.openNewTab(); // opens blank tab
 ```
 
-## executeAsyncScript
+## makeActionAtEveryTab
+
+Runs an action in every open tab.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+const titles = [];
+await browser.makeActionAtEveryTab(async () => {
+  titles.push(await browser.getTitle());
+});
+```
+
+## close
+
+Closes the current tab/page.
 
-	await browser.executeAsyncScript((done) => {
-		setTimeout(() => {
-			done(document.querySelector('a').innerText)
-		}, 2500)
-	}) // returns result of the async script
+```js
+await browser.close();
 ```
 
 ## quit
+
+Closes the current browser context/session.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.quit();
+```
+
+## quitAll
 
-	await browser.quit() // close session
+Closes all contexts and the browser itself.
+
+```js
+await browser.quitAll();
 ```
 
-## actions
+## runNewBrowser
+
+Creates a new browser context (Playwright) or launches a new browser instance (Selenium).
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.runNewBrowser();
+await browser.runNewBrowser({
+  currentBrowserName: 'main',
+  newBrowserName: 'second',
+});
+```
 
-	const actionsObj = browser.actions() // returns selenium actions interface
+## switchToBrowser
+
+Switch between multiple browser contexts/instances.
+
+```js
+await browser.switchToBrowser({ index: 0 });
+await browser.switchToBrowser({ browserName: 'main' });
+await browser.switchToBrowser({ title: 'Page Title' });
 ```
 
-## switchTo
+## switchToIframe
+
+Switches the working context to an iframe.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+// By CSS selector
+await browser.switchToIframe('iframe.my-frame');
+
+// By element
+const frame = $('iframe.my-frame');
+await browser.switchToIframe(frame);
+
+// With options
+await browser.switchToIframe('iframe.my-frame', false, {
+  timeout: 30000,
+  message: 'Custom error message',
+});
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `selector` | `string \| PromodElementType` | Iframe selector or element |
+| `jumpToDefaultFirst` | `boolean` | Switch to top frame first (default false) |
+| `opts.timeout` | `number` | Max wait time (default 30000) |
+| `opts.message` | `string` | Custom error message |
+
+## switchToDefauldIframe
 
-	const switchToObj = browser.switchTo() // returns selenium switchTo interface
+Switches back to the top-level frame.
+
+```js
+await browser.switchToDefauldIframe();
 ```
 
-## navigate
+## scrollByMouseWheel
+
+Scrolls the page by moving the mouse and using the wheel.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.scrollByMouseWheel(x, y, deltaX, deltaY, duration);
+```
+
+## scrollElementByMouseWheel
+
+Scrolls inside an element by moving the mouse to it and using the wheel.
 
-	const navigateToObj = browser.navigate() // returns selenium navigate interface
+```js
+const container = $('.scrollable');
+await browser.scrollElementByMouseWheel(container, 0, 0, 0, 500, 100);
 ```
 
-## getCurrentTab
+## keyDownAndHold
+
+Presses and holds a key.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.keyDownAndHold(browser.Key.PageDown);
+await browser.keyDownAndHold('Shift', $('input'));
+```
+
+## keyUp
+
+Releases a held key.
 
-	const CurrentTabObj = await browser.getCurrentTab() // returns current browser tab item
+```js
+await browser.keyUp(browser.Key.PageDown);
 ```
 
-## getCurrentTab
+## keyDownAndUp
+
+Presses and immediately releases a key.
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.keyDownAndUp(browser.Key.Escape);
+```
 
-	await browser.close() // close current browser tab (if one close window)
+## keyboardPressEsc
+
+```js
+await browser.keyboardPressEsc();
 ```
 
-## getTitle
+## keyboardPressEnter
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.keyboardPressEnter();
+```
 
-	const browserWindowTabTitle = await browser.getTitle();
+## setCookies
+
+```js
+await browser.setCookies({ name: 'token', value: 'abc123' });
+await browser.setCookies([
+  { name: 'a', value: '1' },
+  { name: 'b', value: '2' },
+]);
 ```
 
-## switchToTab
+## getCookies
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+const cookies = await browser.getCookies();
+```
 
-	await browser.switchToTab({index: 2}); // will switch context to third browser tab (second tab in tabs array)
-	await browser.switchToTab({title: 'Some title'}); // will switch context to browser tab where tab title equals 'Some title'
+## getCookieByName
+
+```js
+const cookie = await browser.getCookieByName('token');
 ```
 
-## returnToInitialTab
+## deleteCookie
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+await browser.deleteCookie('token');
+```
 
-	await browser.switchToTab({index: 2}); // will switch context to third browser tab (second tab in tabs array)
-	await browser.returnToInitialTab(); // will switch first opened tab and close all other tabs
+## deleteAllCookies
+
+```js
+await browser.deleteAllCookies();
 ```
 
-## runNewBrowser
+## getBrowserLogs
+
+Returns console log entries from the page (Playwright only captures these natively).
+
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+const logs = await browser.getBrowserLogs();
+```
+
+## setBasicAuth
 
-	await browser.runNewBrowser(); // will runNewBrowser new browser
+Sets Basic authentication headers on all subsequent requests (Playwright).
+
+```js
+await browser.setBasicAuth({ username: 'user', password: 'pass' });
 ```
 
-## switchToBrowser
+## mockRequests
+
+Registers a request mock/intercept (Playwright).
 
 ```js
-	const {seleniumWD} = require('promod');
-	const {browser} = seleniumWD
+browser.mockRequests({
+  url: '**/api/data',
+  handler: (request) => ({
+    status: 200,
+    body: JSON.stringify({ mocked: true }),
+    headers: { 'Content-Type': 'application/json' },
+  }),
+});
+```
 
-	await browser.switchToBrowser({index: 0}); // will switch to browser (not tab) which was started first
-	await browser.switchToBrowser({title: 'Simple-Automation-Testing/promod: Library for browser manipulation'});
-	// will switch to browser (not tab) which has "Simple-Automation-Testing/promod: Library for browser manipulation" title
-```
+## wait
+
+Built-in wait utility (`sat-wait`). Waits until a condition is met.
+
+```js
+await browser.wait(
+  async () => (await browser.getTitle()) === 'Expected Title',
+  { timeout: 5000, message: 'Title did not match' },
+);
+```