codeceptjs 4.2.0-beta.4 → 4.2.1-beta.1

package/docs/helpers/Obscura.md

@@ -11,16 +11,12 @@ title: Obscura
 
 **Extends CDPBrowser**
 
-Obscura drives [Obscura][1], a minimal headless
-browser exposed over the Chrome DevTools Protocol. From v0.2.0, default release builds ship a
-real rendering engine (layout, paint, screenshots); `-no-render` variants and v0.1.x builds keep
-the original single-V8-isolate, nothing-rendered mode. This helper does not hardcode which mode a
-given binary is in — `CDPBrowser._probeCapabilities` detects `layout`/`screenshot` per binary at
-runtime, so the same helper works against either.
+Obscura drives [Obscura][1], a lightweight headless
+browser controlled over the Chrome DevTools Protocol. Default builds from v0.2.0 render pages
+(layout, screenshots); `-no-render` builds and v0.1.x run JavaScript and the DOM only. The helper
+detects which build it runs against, so the same config works for both.
 
-This helper is a thin `CDPBrowser` subclass: it changes nothing about how locating or acting on
-elements works, it only pins the config presets Obscura requires and manages the `obscura serve`
-process lifecycle, the same way Playwright manages its own browser process.
+The helper starts and stops `obscura serve` for you, the same way Playwright manages its browser.
 
 > Obscura support is experimental in CodeceptJS 4.2. Pin the browser version in CI and keep a
 > Playwright/WebDriver job for browser-compatibility coverage.
@@ -40,8 +36,8 @@ process lifecycle, the same way Playwright manages its own browser process.
 *   **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
     the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
     spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
-    the config, or a free port picked automatically), waits for it to answer, connects, and kills
-    it in `_finishTest`.
+    the config, or a free port picked automatically), waits for it to answer, connects, and stops
+    it when tests finish.
 *   **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
     answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
     before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -78,15 +74,13 @@ default.
 
 These are set automatically and only need overriding for unusual setups:
 
-| option          | value       | why                                                                                                                                                                                                                                          |
-| --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `input`         | `synthetic` | coordinate-click navigation is unreliable over CDP on Obscura even on rendering builds (no `frameNavigated` event, stale `page.url()`); `click` always takes the `forceClick` path — on Obscura, `click` and `forceClick` are the same thing |
-| `xpathPolyfill` | `auto`      | probed per binary/page: Obscura's native `document.evaluate` still doesn't support attribute selection or `not()`, so the polyfill is used until that lands                                                                                  |
+| option          | value       | why                                                                                        |
+| --------------- | ----------- | ------------------------------------------------------------------------------------------ |
+| `input`         | `synthetic` | clicks that navigate are unreliable in Obscura, so `click` behaves like `forceClick`       |
+| `xpathPolyfill` | `auto`      | Obscura's XPath lacks attribute selection and `not()`, so the polyfill is used when needed |
 
-`capabilities.layout`/`capabilities.screenshot`/`capabilities.xpath` are intentionally left
-unset here — `CDPBrowser._probeCapabilities` detects them at runtime from the actual binary
-(`'real'`/`true` on v0.2.0+ default builds, `'none'`/`false` on `-no-render` builds and v0.1.x).
-Set them explicitly in your own config to skip probing or to force a mode.
+`capabilities` are detected at runtime from the Obscura build. Set them in your config to skip
+detection or to force a mode.
 
 ## Limitations
 
@@ -104,23 +98,26 @@ Set them explicitly in your own config to skip probing or to force a mode.
 
 ## Configuration
 
-This helper should be configured in codecept.conf.js. It accepts everything `CDPBrowser`
-accepts (see its config table), plus:
+This helper should be configured in codecept.conf.js
 
-Type: [object][7]
+Type: [object][4]
 
 ### Properties
 
-*   `endpoint` **[string][5]?** explicit CDP endpoint. Setting this switches the helper to ATTACH
-    mode: it only connects, and never spawns or kills a process, no matter what else is configured.
-    Leave it unset for SELF-MANAGED mode (see below).
-*   `binaryPath` **[string][5]?** path to the `obscura` executable, used in SELF-MANAGED mode
-    (`endpoint` unset). Checked before `OBSCURA_PATH` and `PATH`.
-*   `port` **[number][4]?** port `obscura serve` listens on, in SELF-MANAGED mode. When unset, a
-    free port is picked automatically, which is what makes `run-workers` collision-free — every
-    worker gets its own instance on its own port with zero config.
-*   `serverStartTimeout` **[number][4]?** milliseconds to wait for a spawned `obscura serve`
-    to answer `/json/version` before `_connect` gives up.
+*   `endpoint` **[string][3]?** connect to a running Obscura instead of starting one (ATTACH mode).
+*   `binaryPath` **[string][3]?** path to the `obscura` executable. Checked before `OBSCURA_PATH` and `PATH`.
+*   `port` **[number][8]?** port for `obscura serve`. A free port is picked when unset, so parallel workers never collide.
+*   `serverStartTimeout` **[number][8]?** how long to wait for `obscura serve` to start, in milliseconds.
+*   `url` **[string][3]?** base url of website to be tested.
+*   `headers` **[object][4]?** headers sent when connecting to the endpoint, e.g. for authenticated remote browsers.
+*   `input` **[string][3]?** how actions are dispatched: `cdp` (real mouse and keyboard events) or `synthetic` (DOM events). `auto` picks `cdp` when the browser renders layout.
+*   `xpathPolyfill` **([string][3] | [boolean][17])?** inject an XPath polyfill for browsers with incomplete XPath support. `auto` detects when it is needed.
+*   `capabilities` **[object][4]?** browser capabilities (`layout`, `xpath`, `screenshot`, `innerText`) to use instead of detecting them at runtime.
+*   `waitForTimeout` **[number][8]?** default timeout for wait* actions, in seconds.
+*   `waitForAction` **[number][8]?** fixed delay after each action, in milliseconds. When unset, actions wait only for the navigation they trigger.
+*   `pollInterval` **[number][8]?** interval between checks while waiting, in milliseconds.
+*   `getPageTimeout` **[number][8]?** maximum time to wait for a page to load, in seconds.
+*   `waitForNavigation` **[string][3]?** when a navigation is considered finished: `load`, `domcontentloaded`, or `networkidle`.
 
 
 
@@ -157,80 +154,1808 @@ Type: [object][7]
 
 *   `config` **ObscuraConfig**&#x20;
 
-### _connect
+### amOnPage
+
+Opens a web page in a browser. Requires relative or absolute url.
+If url starts with `/`, opens a web page of a site defined in `url` config parameter.
+
+```js
+I.amOnPage('/'); // opens main page of website
+I.amOnPage('https://github.com'); // opens github
+I.amOnPage('/login'); // opens a login page
+```
+
+#### Parameters
+
+*   `url` **[string][3]** url path or global url.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### appendField
+
+Appends text to a input field or textarea.
+Field is located by name, label, CSS or XPath
+
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+I.appendField('#myTextField', 'appended');
+// typing secret
+I.appendField('password', secret('123456'));
+// within a context
+I.appendField('name', 'John', '.form-container');
+```
+
+#### Parameters
+
+*   `field` **([string][3] | [object][4])** located by label|name|CSS|XPath|strict locator
+*   `value` **[string][3]** text value to append.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### attachFile
+
+Attaches a file to element located by label, name, CSS or XPath
+Path to file is relative current codecept directory (where codecept.conf.ts or codecept.conf.js is located).
+File will be uploaded to remote system (if tests are running remotely).
+
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+I.attachFile('Avatar', 'data/avatar.jpg');
+I.attachFile('form input[name=avatar]', 'data/avatar.jpg');
+// within a context
+I.attachFile('Avatar', 'data/avatar.jpg', '.form-container');
+```
+
+If the locator points to a non-file-input element (e.g., a dropzone area),
+the file will be dropped onto that element using drag-and-drop events.
+
+```js
+I.attachFile('#dropzone', 'data/avatar.jpg');
+```
+
+#### Parameters
+
+*   `field` &#x20;
+*   `pathToFile` **[string][3]** local file path relative to codecept.conf.ts or codecept.conf.js config file.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+*   `locator` **([string][3] | [object][4])** field located by label|name|CSS|XPath|strict locator.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### blur
+
+Remove focus from a text input, button, etc.
+Calls [blur][5] on the element.
+
+Examples:
+
+```js
+I.blur('.text-area')
+```
+
+```js
+//element `#product-tile` is focused
+I.see('#add-to-cart-btn');
+I.blur('#product-tile')
+I.dontSee('#add-to-cart-btn');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** field located by label|name|CSS|XPath|strict locator.
+*   `options` **any?** Playwright only: [Additional options][6] for available options object as 2nd argument.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### checkOption
+
+Selects a checkbox or radio button.
+Element is located by label or name or CSS or XPath.
+
+The second parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+I.checkOption('#agree');
+I.checkOption('I Agree to Terms and Conditions');
+I.checkOption('agree', '//form');
+```
+
+#### Parameters
+
+*   `field` **([string][3] | [object][4])** checkbox located by label | name | CSS | XPath | strict locator.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### clearClipboard
+
+Clears the system clipboard.
+
+```js
+I.clearClipboard();
+I.seeClipboardEquals('');
+```
+
+Returns **void** automatically synchronized promise through #recorder
+
+### clearCookie
+
+Clears a cookie by name,
+if none provided clears all cookies.
+
+```js
+I.clearCookie();
+I.clearCookie('test');
+```
+
+#### Parameters
+
+*   `name` &#x20;
+*   `cookie` **[string][3]?** (optional, `null` by default) cookie name 
+
+### clearField
+
+Clears a `<textarea>` or text `<input>` element's value.
+
+The second parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+I.clearField('Email');
+I.clearField('user[email]');
+I.clearField('#email');
+// within a context
+I.clearField('Email', '.form-container');
+```
+
+#### Parameters
+
+*   `field` &#x20;
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+*   `editable` **([string][3] | [object][4])** field located by label|name|CSS|XPath|strict locator.
+
+Returns **void** automatically synchronized promise through #recorder.
+
+### click
+
+Perform a click on a link or a button, given by a locator.
+If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+For images, the "alt" attribute and inner text of any parent links are searched.
+
+If no locator is provided, defaults to clicking the body element (`'//body'`).
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+// click body element (default)
+I.click();
+// simple link
+I.click('Logout');
+// button of form
+I.click('Submit');
+// CSS button
+I.click('#form input[type=submit]');
+// XPath
+I.click('//form/*[@type=submit]');
+// link in context
+I.click('Logout', '#nav');
+// using strict locator
+I.click({css: 'nav a.login'});
+// using ARIA role locator
+I.click({role: 'button', name: 'Submit'});
+```
+
+> ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators][7].
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator. 
+*   `context` **([string][3]? | [object][4] | null)** (optional, `null` by default) element to search in CSS|XPath|Strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### clickXY
+
+Clicks at page coordinates, or at coordinates relative to an element.
+Requires a browser that renders layout.
+
+```js
+I.clickXY(100, 200); // page coordinates
+I.clickXY('#area', 50, 30); // relative to #area
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4] | [number][8])** element to click relative to, or the X page coordinate.
+*   `x` **[number][8]?** X coordinate relative to the element, or the Y page coordinate if `locator` is a number.
+*   `y` **[number][8]?** Y coordinate relative to the element.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSee
+
+Opposite to `see`. Checks that a text is not present on a page.
+Use context parameter to narrow down the search.
+
+```js
+I.dontSee('Login'); // assume we are already logged in.
+I.dontSee('Login', '.nav'); // no login inside .nav element
+```
+
+#### Parameters
+
+*   `text` **[string][3]** which is not present.
+*   `context` **([string][3] | [object][4])?** (optional) element located by CSS|XPath|strict locator in which to perfrom search. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeCheckboxIsChecked
+
+Verifies that the specified checkbox is not checked.
+
+```js
+I.dontSeeCheckboxIsChecked('#agree'); // located by ID
+I.dontSeeCheckboxIsChecked('I agree to terms'); // located by label
+I.dontSeeCheckboxIsChecked('agree'); // located by name
+```
+
+#### Parameters
+
+*   `locator` &#x20;
+*   `field` **([string][3] | [object][4])** located by label|name|CSS|XPath|strict locator.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeCookie
+
+Checks that cookie with given name does not exist.
+
+```js
+I.dontSeeCookie('auth'); // no auth cookie
+```
+
+#### Parameters
+
+*   `name` **[string][3]** cookie name.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeCurrentPathEquals
+
+Checks that current URL path does NOT match the expected path.
+Query strings and URL fragments are ignored.
+
+```js
+I.dontSeeCurrentPathEquals('/form'); // fails for '/form', '/form?user=1', '/form#section'
+I.dontSeeCurrentPathEquals('/'); // fails for '/', '/?user=ok', '/#top'
+```
+
+#### Parameters
+
+*   `path` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeCurrentUrlEquals
+
+Checks that current url is not equal to provided one.
+If a relative url provided, a configured url will be prepended to it.
+
+```js
+I.dontSeeCurrentUrlEquals('/login'); // relative url are ok
+I.dontSeeCurrentUrlEquals('http://mysite.com/login'); // absolute urls are also ok
+```
+
+#### Parameters
+
+*   `url` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeElement
+
+Opposite to `seeElement`. Checks that element is not visible (or in DOM)
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+I.dontSeeElement('.modal'); // modal is not shown
+I.dontSeeElement('.modal', '#container');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** located by CSS|XPath|Strict locator.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeElementInDOM
+
+Opposite to `seeElementInDOM`. Checks that element is not on page.
+
+```js
+I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or not
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** located by CSS|XPath|Strict locator.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeInCurrentUrl
+
+Checks that current url does not contain a provided fragment.
+
+#### Parameters
+
+*   `url` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeInField
+
+Checks that value of input field or textarea doesn't equal to given value
+Opposite to `seeInField`.
+
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+I.dontSeeInField('email', 'user@user.com'); // field by name
+I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
+// within a context
+I.dontSeeInField('Name', 'old_value', '.form-container');
+```
+
+#### Parameters
+
+*   `field` **([string][3] | [object][4])** located by label|name|CSS|XPath|strict locator.
+*   `value` **([string][3] | [object][4])** value to check.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeInSource
+
+Checks that the current page does not contains the given string in its raw source code.
+
+```js
+I.dontSeeInSource('<!--'); // no comments in source
+```
+
+#### Parameters
+
+*   `text` &#x20;
+*   `value` **[string][3]** to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeInTitle
+
+Checks that title does not contain text.
+
+```js
+I.dontSeeInTitle('Error');
+```
+
+#### Parameters
+
+*   `text` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### dontSeeTraffic
+
+Verifies that a certain request is not part of network traffic.
+
+Examples:
+
+```js
+I.dontSeeTraffic({ name: 'Unexpected API Call', url: 'https://api.example.com' });
+I.dontSeeTraffic({ name: 'Unexpected API Call of "user" endpoint', url: /api.example.com.*user/ });
+```
+
+#### Parameters
+
+*   `opts` **[Object][4]** options when checking the traffic network.
+
+    *   `opts.name` **[string][3]** A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+    *   `opts.url` **([string][3] | [RegExp][9])** Expected URL of request in network traffic. Can be a string or a regular expression.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### doubleClick
+
+Performs a double-click on an element matched by link|button|label|CSS or XPath.
+Context can be specified as second parameter to narrow search.
+
+```js
+I.doubleClick('Edit');
+I.doubleClick('Edit', '.actions');
+I.doubleClick({css: 'button.accept'});
+I.doubleClick('.btn.edit');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element to search in CSS|XPath|Strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### executeAsyncScript
+
+Executes async script on page.
+Provided function should execute a passed callback (as first argument) to signal it is finished.
+
+Example: In Vue.js to make components completely rendered we are waiting for [nextTick][10].
+
+```js
+I.executeAsyncScript(function(done) {
+  Vue.nextTick(done); // waiting for next tick
+});
+```
+
+By passing value to `done()` function you can return values.
+Additional arguments can be passed as well, while `done` function is always last parameter in arguments list.
+
+```js
+let val = await I.executeAsyncScript(function(url, done) {
+  // in browser context
+  $.ajax(url, { success: (data) => done(data); }
+}, 'http://ajax.callback.url/');
+```
+
+#### Parameters
+
+*   `fn` **([string][3] | [function][11])** function to be executed in browser context.
+*   `args` **...any** to be passed to function.
+
+Returns **[Promise][12]<any>** script return value
+
+### executeScript
+
+Executes sync script on a page.
+Pass arguments to function as additional parameters.
+Will return execution result to a test.
+In this case you should use async function and await to receive results.
+
+Example with jQuery DatePicker:
+
+```js
+// change date of jQuery DatePicker
+I.executeScript(function() {
+  // now we are inside browser context
+  $('date').datetimepicker('setDate', new Date());
+});
+```
+
+Can return values. Don't forget to use `await` to get them.
+
+```js
+let date = await I.executeScript(function(el) {
+  // only basic types can be returned
+  return $(el).datetimepicker('getDate').toString();
+}, '#date'); // passing jquery selector
+```
+
+#### Parameters
+
+*   `fn` **([string][3] | [function][11])** function to be executed in browser context.
+*   `args` **...any** to be passed to function.
+
+Returns **[Promise][12]<any>** script return value
+
+### fillField
+
+Fills a text field or textarea, after clearing its value, with the given string.
+Field is located by name, label, CSS, or XPath.
+
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+// by label
+I.fillField('Email', 'hello@world.com');
+// by name
+I.fillField('password', secret('123456'));
+// by CSS
+I.fillField('form#login input[name=username]', 'John');
+// or by strict locator
+I.fillField({css: 'form#login input[name=username]'}, 'John');
+// by ARIA role locator
+I.fillField({role: 'textbox', name: 'Email'}, 'hello@world.com');
+// within a context
+I.fillField('Name', 'John', '#section2');
+```
+
+> ℹ️ ARIA role locators (`{role, name}`) match fields by their accessible name and survive markup refactors. See [Locators][7].
+
+#### Parameters
+
+*   `field` **([string][3] | [object][4])** located by label|name|CSS|XPath|strict locator.
+*   `value` **([string][3] | [object][4])** text value to fill.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### flushNetworkTraffics
+
+Resets all recorded network requests.
+
+```js
+I.flushNetworkTraffics();
+```
+
+### focus
+
+Calls [focus][5] on the matching element.
+
+Examples:
+
+```js
+I.dontSee('#add-to-cart-btn');
+I.focus('#product-tile')
+I.see('#add-to-cart-bnt');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** field located by label|name|CSS|XPath|strict locator.
+*   `options` **any?** Playwright only: [Additional options][13] for available options object as 2nd argument.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### forceClick
+
+Perform an emulated click on a link or a button, given by a locator.
+Unlike normal click instead of sending native event, emulates a click with JavaScript.
+This works on hidden, animated or inactive elements as well.
+
+If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+For images, the "alt" attribute and inner text of any parent links are searched.
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+// simple link
+I.forceClick('Logout');
+// button of form
+I.forceClick('Submit');
+// CSS button
+I.forceClick('#form input[type=submit]');
+// XPath
+I.forceClick('//form/*[@type=submit]');
+// link in context
+I.forceClick('Logout', '#nav');
+// using strict locator
+I.forceClick({css: 'nav a.login'});
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element to search in CSS|XPath|Strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### grabAttributeFrom
+
+Retrieves an attribute from an element located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async with `await`** operator.
+If more than one element is found - attribute of first element is returned.
+
+```js
+let hint = await I.grabAttributeFrom('#tooltip', 'title');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `attr` **[string][3]** attribute name.
+
+Returns **[Promise][12]<[string][3]>** attribute value
+
+### grabAttributeFromAll
+
+Retrieves an array of attributes from elements located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async with `await`** operator.
+
+```js
+let hints = await I.grabAttributeFromAll('.tooltip', 'title');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `attr` **[string][3]** attribute name.
+
+Returns **[Promise][12]<[Array][14]<[string][3]>>** attribute value
+
+### grabCookie
+
+Gets a cookie object by name.
+If none provided gets all cookies.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let cookie = await I.grabCookie('auth');
+assert(cookie.value, '123456');
+```
+
+#### Parameters
+
+*   `name` **[string][3]?** cookie name. 
+
+Returns **any** attribute value
+
+### grabCookies
+
+Retrieves all cookies visible to the current page.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let cookies = await I.grabCookies();
+```
+
+Returns **[Promise][12]<[Array][14]<CodeceptJS.Cookie>>** array of cookie objects.
+
+### grabCssPropertyFrom
+
+Grab CSS property for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+If more than one element is found - value of first element is returned.
+
+```js
+const value = await I.grabCssPropertyFrom('h3', 'font-weight');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `cssProperty` **[string][3]** CSS property name.
+
+Returns **[Promise][12]<[string][3]>** CSS value
+
+### grabCssPropertyFromAll
+
+Grab array of CSS properties for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const values = await I.grabCssPropertyFromAll('h3', 'font-weight');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `cssProperty` **[string][3]** CSS property name.
+
+Returns **[Promise][12]<[Array][14]<[string][3]>>** CSS value
+
+### grabCurrentUrl
+
+Get current URL from browser.
+Resumes test execution, so should be used inside an async function.
+
+```js
+let url = await I.grabCurrentUrl();
+console.log(`Current URL is [${url}]`);
+```
+
+Returns **[Promise][12]<[string][3]>** current URL
+
+### grabFromClipboard
+
+Grabs the text content of the system clipboard and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+I.click('Copy to clipboard');
+let url = await I.grabFromClipboard();
+```
+
+Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+in Chromium-based browsers, where read access is granted automatically.
+
+Returns **[Promise][12]<[string][3]>** the system clipboard contents.
+
+### grabHTMLFrom
+
+Retrieves the innerHTML from an element located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+If more than one element is found - HTML of first element is returned.
+
+```js
+let postHTML = await I.grabHTMLFrom('#post');
+```
+
+#### Parameters
+
+*   `locator` &#x20;
+*   `element` **([string][3] | [object][4])** located by CSS|XPath|strict locator.
+
+Returns **[Promise][12]<[string][3]>** HTML code for an element
+
+### grabHTMLFromAll
+
+Retrieves all the innerHTML from elements located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let postHTMLs = await I.grabHTMLFromAll('.post');
+```
+
+#### Parameters
+
+*   `locator` &#x20;
+*   `element` **([string][3] | [object][4])** located by CSS|XPath|strict locator.
+
+Returns **[Promise][12]<[Array][14]<[string][3]>>** HTML code for an element
+
+### grabNumberOfElements
+
+Grab number of elements by locator.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let numOfElements = await I.grabNumberOfElements('p');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** located by CSS|XPath|strict locator.
+
+Returns **[Promise][12]<[number][8]>** number of matched elements.
+
+### grabNumberOfVisibleElements
+
+Grab number of visible elements by locator.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let numOfElements = await I.grabNumberOfVisibleElements('p');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** located by CSS|XPath|strict locator.
+
+Returns **[Promise][12]<[number][8]>** number of visible elements
+
+### grabPageScrollPosition
+
+Retrieves a page scroll position and returns it to test.
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+let { x, y } = await I.grabPageScrollPosition();
+```
+
+Returns **[Promise][12]<PageScrollPosition>** scroll position
+
+### grabRecordedNetworkTraffics
+
+Grab the recording network traffics
+
+```js
+const traffics = await I.grabRecordedNetworkTraffics();
+expect(traffics[0].url).to.equal('https://reqres.in/api/comments/1');
+expect(traffics[0].response.status).to.equal(200);
+expect(traffics[0].response.body).to.contain({ name: 'this was mocked' });
+```
+
+Returns **[Array][14]** recorded network traffics
+
+### grabSource
+
+Retrieves page source and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let pageSource = await I.grabSource();
+```
+
+Returns **[Promise][12]<[string][3]>** source code
+
+### grabTextFrom
+
+Retrieves a text from an element located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async with `await`** operator.
+
+```js
+let pin = await I.grabTextFrom('#pin');
+```
+
+If multiple elements found returns first element.
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][12]<[string][3]>** attribute value
+
+### grabTextFromAll
+
+Retrieves all texts from an element located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async with `await`** operator.
+
+```js
+let pins = await I.grabTextFromAll('#pin li');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][12]<[Array][14]<[string][3]>>** attribute value
+
+### grabTitle
+
+Retrieves a page title and returns it to test.
+Resumes test execution, so **should be used inside async with `await`** operator.
+
+```js
+let title = await I.grabTitle();
+```
+
+Returns **[Promise][12]<[string][3]>** title
+
+### grabValueFrom
+
+Retrieves a value from a form element located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+If more than one element is found - value of first element is returned.
+
+```js
+let email = await I.grabValueFrom('input[name=email]');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** field located by label|name|CSS|XPath|strict locator.
+
+Returns **[Promise][12]<[string][3]>** attribute value
+
+### grabValueFromAll
+
+Retrieves an array of value from a form located by CSS or XPath and returns it to test.
+Resumes test execution, so **should be used inside async function with `await`** operator.
+
+```js
+let inputs = await I.grabValueFromAll('//form/input');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** field located by label|name|CSS|XPath|strict locator.
+
+Returns **[Promise][12]<[Array][14]<[string][3]>>** attribute value
+
+### grabWebElement
+
+Grab WebElement for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElement = await I.grabWebElement('#button');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][12]<any>** WebElement of being used Web helper
+
+### grabWebElements
+
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][12]<any>** WebElement of being used Web helper
+
+### pressKey
+
+Presses a key or a key combination on the focused element.
+
+```js
+I.pressKey('Enter');
+I.pressKey(['Control', 'a']);
+```
+
+#### Parameters
+
+*   `key` **([string][3] | [Array][14]<[string][3]>)** a key or an array of keys to combine (modifiers first).
+
+Returns **void** automatically synchronized promise through #recorder
+
+### refreshPage
+
+Reload the current page.
+
+```js
+I.refreshPage();
+```
+
+Returns **void** automatically synchronized promise through #recorder
+
+### resizeWindow
+
+Resize the current window to provided width and height.
+First parameter can be set to `maximize`.
+
+#### Parameters
+
+*   `width` **[number][8]** width in pixels or `maximize`.
+*   `height` **[number][8]** height in pixels.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### rightClick
+
+Performs right click on a clickable element matched by semantic locator, CSS or XPath.
+
+```js
+// right click element with id el
+I.rightClick('#el');
+// right click link or button with text "Click me"
+I.rightClick('Click me');
+// right click button with text "Click me" inside .context
+I.rightClick('Click me', '.context');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** clickable element located by CSS|XPath|strict locator.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS|XPath|strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### saveElementScreenshot
+
+Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+Filename is relative to output folder.
+
+```js
+I.saveElementScreenshot(`#submit`,'debug.png');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `fileName` **[string][3]** file name to save.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### saveScreenshot
+
+Saves a screenshot to the output folder (set in codecept.conf.ts or codecept.conf.js).
+Filename is relative to the output folder.
+
+```js
+I.saveScreenshot('debug.png');
+```
+
+#### Parameters
+
+*   `fileName` **[string][3]** file name to save.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### scrollPageToBottom
+
+Scroll page to the bottom.
+
+```js
+I.scrollPageToBottom();
+```
+
+Returns **void** automatically synchronized promise through #recorder
+
+### scrollPageToTop
+
+Scroll page to the top.
+
+```js
+I.scrollPageToTop();
+```
+
+Returns **void** automatically synchronized promise through #recorder
+
+### scrollTo
+
+Scrolls to element matched by locator.
+Extra shift can be set with offsetX and offsetY options.
+
+```js
+I.scrollTo('footer');
+I.scrollTo('#submit', 5, 5);
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** located by CSS|XPath|strict locator.
+*   `offsetX` **[number][8]** (optional, `0` by default) X-axis offset. 
+*   `offsetY` **[number][8]** (optional, `0` by default) Y-axis offset. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### see
+
+Checks that a page contains a visible text.
+Use context parameter to narrow down the search.
+
+```js
+I.see('Welcome'); // text welcome on a page
+I.see('Welcome', '.content'); // text inside .content div
+I.see('Register', {css: 'form.register'}); // use strict locator
+```
+
+#### Parameters
+
+*   `text` **[string][3]** expected on page.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeAttributesOnElements
+
+Checks that all elements with given locator have given attributes.
+
+```js
+I.seeAttributesOnElements('//form', { method: "post"});
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** located by CSS|XPath|strict locator.
+*   `attributes` **[object][4]** attributes and their values to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeCheckboxIsChecked
+
+Verifies that the specified checkbox is checked.
+
+```js
+I.seeCheckboxIsChecked('Agree');
+I.seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
+I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
+```
+
+#### Parameters
+
+*   `locator` &#x20;
+*   `field` **([string][3] | [object][4])** located by label|name|CSS|XPath|strict locator.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeClipboardEquals
+
+Checks that the system clipboard is equal to the given text.
+
+```js
+I.click('Copy to clipboard');
+I.seeClipboardEquals('https://codecept.io');
+```
+
+Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+in Chromium-based browsers, where read access is granted automatically.
+
+#### Parameters
+
+*   `text` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeCookie
+
+Checks that cookie with given name exists.
+
+```js
+I.seeCookie('Auth');
+```
+
+#### Parameters
+
+*   `name` **[string][3]** cookie name.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeCssPropertiesOnElements
+
+Checks that all elements with given locator have given CSS properties.
+
+```js
+I.seeCssPropertiesOnElements('h3', { 'font-weight': "bold"});
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** located by CSS|XPath|strict locator.
+*   `cssProperties` **[object][4]** object with CSS properties and their values to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeCurrentPathEquals
+
+Checks that current URL path matches the expected path.
+Query strings and URL fragments are ignored.
+
+```js
+I.seeCurrentPathEquals('/info'); // passes for '/info', '/info?user=1', '/info#section'
+I.seeCurrentPathEquals('/'); // passes for '/', '/?user=ok', '/#top'
+```
+
+#### Parameters
+
+*   `path` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeCurrentUrlEquals
+
+Checks that current url is equal to provided one.
+If a relative url provided, a configured url will be prepended to it.
+So both examples will work:
+
+```js
+I.seeCurrentUrlEquals('/register');
+I.seeCurrentUrlEquals('http://my.site.com/register');
+```
+
+#### Parameters
+
+*   `url` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeElement
+
+Checks that a given Element is visible
+Element is located by CSS or XPath.
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+I.seeElement('#modal');
+I.seeElement('#modal', '#container');
+// using ARIA role locator
+I.seeElement({role: 'dialog'});
+```
+
+> ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators][7].
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** located by CSS|XPath|strict locator.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeElementInDOM
+
+Checks that a given Element is present in the DOM
+Element is located by CSS or XPath.
+
+```js
+I.seeElementInDOM('#modal');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeInClipboard
+
+Checks that the system clipboard contains the given text.
+
+```js
+I.click('Copy to clipboard');
+I.seeInClipboard('https://codecept.io');
+```
+
+Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+in Chromium-based browsers, where read access is granted automatically.
+
+#### Parameters
+
+*   `text` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeInCurrentUrl
+
+Checks that current url contains a provided fragment.
+
+```js
+I.seeInCurrentUrl('/register'); // we are on registration page
+```
+
+#### Parameters
 
-In ATTACH mode, connects exactly as `CDPBrowser._connect` would. In SELF-MANAGED mode,
-resolves and spawns `obscura serve` (or courtesy-attaches to an already-running one on
-:9222) exactly once via `_resolveSelfManaged`, then connects.
+*   `url` **[string][3]** a fragment to check
 
-A spawn failure (e.g. a bad binary) is delivered asynchronously by Node as an `error`
-event; it is recorded on `this.serverError` and surfaced as a rejection from `_waitForServer`
-instead of crashing the process as an uncaught exception.
+Returns **void** automatically synchronized promise through #recorder
+
+### seeInField
+
+Checks that the given input field or textarea equals to given value.
+For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.
+
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+I.seeInField('Username', 'davert');
+I.seeInField({css: 'form textarea'},'Type your comment here');
+I.seeInField('form input[type=hidden]','hidden_value');
+I.seeInField('#searchform input','Search');
+// within a context
+I.seeInField('Name', 'John', '.form-container');
+```
+
+#### Parameters
+
+*   `field` **([string][3] | [object][4])** located by label|name|CSS|XPath|strict locator.
+*   `value` **([string][3] | [object][4])** value to check.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeInSource
+
+Checks that the current page contains the given string in its raw source code.
+
+```js
+I.seeInSource('<h1>Green eggs &amp; ham</h1>');
+```
+
+#### Parameters
+
+*   `text` **[string][3]** value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeInTitle
+
+Checks that title contains text.
+
+```js
+I.seeInTitle('Home Page');
+```
+
+#### Parameters
+
+*   `text` **[string][3]** text value to check.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeNumberOfVisibleElements
+
+Asserts that an element is visible a given number of times.
+Element is located by CSS or XPath.
+
+```js
+I.seeNumberOfVisibleElements('.buttons', 3);
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `num` **[number][8]** number of elements.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### seeTraffic
+
+Verifies that a certain request is part of network traffic.
+
+```js
+// checking the request url contains certain query strings
+I.amOnPage('https://openai.com/blog/chatgpt');
+I.startRecordingTraffic();
+await I.seeTraffic({
+    name: 'sentry event',
+    url: 'https://images.openai.com/blob/cf717bdb-0c8c-428a-b82b-3c3add87a600',
+    parameters: {
+    width: '1919',
+    height: '1138',
+    },
+  });
+```
+
+```js
+// checking the request url contains certain post data
+I.amOnPage('https://openai.com/blog/chatgpt');
+I.startRecordingTraffic();
+await I.seeTraffic({
+    name: 'event',
+    url: 'https://cloudflareinsights.com/cdn-cgi/rum',
+    requestPostData: {
+    st: 2,
+    },
+  });
+```
+
+#### Parameters
+
+*   `opts` **[Object][4]** options when checking the traffic network.
+
+    *   `opts.name` **[string][3]** A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+    *   `opts.url` **[string][3]** Expected URL of request in network traffic
+    *   `opts.parameters` **[Object][4]?** Expected parameters of that request in network traffic
+    *   `opts.requestPostData` **[Object][4]?** Expected that request contains post data in network traffic
+    *   `opts.timeout` **[number][8]?** Timeout to wait for request in seconds. Default is 10 seconds.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### selectOption
+
+Selects an option in a drop-down select.
+Field is searched by label | name | CSS | XPath.
+Option is selected by visible text or by value.
+
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+I.selectOption('Choose Plan', 'Monthly'); // select by label
+I.selectOption('subscription', 'Monthly'); // match option by text
+I.selectOption('subscription', '0'); // or by value
+I.selectOption('//form/select[@name=account]','Premium');
+I.selectOption('form select[name=account]', 'Premium');
+I.selectOption({css: 'form select[name=account]'}, 'Premium');
+// within a context
+I.selectOption('age', '21-60', '#section2');
+```
+
+Provide an array for the second argument to select multiple options.
+
+```js
+I.selectOption('Which OS do you use?', ['Android', 'iOS']);
+```
+
+#### Parameters
+
+*   `select` **([string][3] | [object][4])** field located by label|name|CSS|XPath|strict locator.
+*   `option` **([string][3] | [Array][14]<any>)** visible text or value of option.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### setCookie
+
+Sets cookie(s).
+
+Can be a single cookie object or an array of cookies:
+
+```js
+I.setCookie({name: 'auth', value: true});
+
+// as array
+I.setCookie([
+  {name: 'auth', value: true},
+  {name: 'agree', value: true}
+]);
+```
+
+#### Parameters
+
+*   `cookie` **(Cookie | [Array][14]<Cookie>)** a cookie object or array of cookie objects.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### startRecordingTraffic
+
+Starts recording the network traffics.
+This also resets recorded network requests.
+
+```js
+I.startRecordingTraffic();
+```
+
+Returns **void** automatically synchronized promise through #recorder
+
+### startScreencast
+
+Starts recording a video of the page. Stop it with `stopScreencast`.
+Usually enabled through the `screencast` plugin rather than called directly.
+
+```js
+I.startScreencast();
+```
+
+#### Parameters
+
+*   `options` **[object][4]?** `{ maxWidth, maxHeight, quality, everyNthFrame }` 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### stopRecordingTraffic
+
+Stops recording of network traffic. Recorded traffic is not flashed.
+
+```js
+I.stopRecordingTraffic();
+```
+
+### stopScreencast
+
+Stops the recording started by `startScreencast` and returns it as an animated PNG.
+
+```js
+const video = await I.stopScreencast();
+```
+
+#### Parameters
+
+*   `options` **[object][4]?** `{ lastFrameDelayMs }`: how long the last frame is shown, in milliseconds (1000 by default). 
+
+Returns **[Promise][12]<([Buffer][15] | null)>** APNG data, or `null` if no frames were recorded.
+
+### type
+
+Types out the given text into an active field.
+To slow down typing use a second parameter, to set interval between key presses.
+*Note:* Should be used when [`fillField`][16] is not an option.
+
+```js
+// passing in a string
+I.type('Type this out.');
+
+// typing values with a 100ms interval
+I.type('4141555311111111', 100);
+
+// passing in an array
+I.type(['T', 'E', 'X', 'T']);
+
+// passing a secret
+I.type(secret('123456'));
+```
+
+#### Parameters
+
+*   `keys` &#x20;
+*   `delay` **[number][8]?** (optional) delay in ms between key presses 
+*   `key` **([string][3] | [Array][14]<[string][3]>)** or array of keys to type.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### uncheckOption
+
+Unselects a checkbox or radio button.
+Element is located by label or name or CSS or XPath.
+
+The second parameter is an optional context (CSS or XPath locator) to narrow the search.
+
+```js
+I.uncheckOption('#agree');
+I.uncheckOption('I Agree to Terms and Conditions');
+I.uncheckOption('agree', '//form');
+```
+
+#### Parameters
+
+*   `field` **([string][3] | [object][4])** checkbox located by label | name | CSS | XPath | strict locator.
+*   `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### wait
+
+Pauses execution for a number of seconds.
+
+```js
+I.wait(2); // wait 2 secs
+```
+
+#### Parameters
+
+*   `sec` **[number][8]** number of second to wait.
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitCurrentPathEquals
+
+Waits for the current URL path to match the expected path.
+Query strings and URL fragments are ignored.
+
+```js
+I.waitCurrentPathEquals('/info', 5);
+```
+
+#### Parameters
+
+*   `path` **[string][3]** value to check.
+*   `sec` **[number][8]?** (optional, `waitForTimeout` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitForCookie
+
+Waits for the specified cookie in the cookies.
+
+```js
+I.waitForCookie("token");
+```
+
+#### Parameters
+
+*   `name` **[string][3]** expected cookie name.
+*   `sec` **[number][8]** (optional, `3` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitForDetached
+
+Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForDetached('#popup');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitForElement
+
+Waits for element to be present on page (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForElement('.btn.continue');
+I.waitForElement('.btn.continue', 5); // wait for 5 secs
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `sec` **[number][8]?** (optional, `1` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitForFunction
+
+Waits for a function to return true (waits for 1 sec by default).
+Running in browser context.
+
+```js
+I.waitForFunction(fn[, [args[, timeout]])
+```
+
+```js
+I.waitForFunction(() => window.requests == 0);
+I.waitForFunction(() => window.requests == 0, 5); // waits for 5 sec
+I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and wait for 5 sec
+```
+
+#### Parameters
+
+*   `fn` **([string][3] | [function][11])** to be executed in browser context.
+*   `argsOrSec` **([Array][14]<any> | [number][8])?** (optional, `1` by default) arguments for function or seconds. 
+*   `sec` **[number][8]?** (optional, `1` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitForInvisible
+
+Waits for an element to be removed or become invisible on a page (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForInvisible('#popup');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitForText
+
+Waits for a text to appear (by default waits for 1sec).
+Element can be located by CSS or XPath.
+Narrow down search results by providing context.
+
+```js
+I.waitForText('Thank you, form has been submitted');
+I.waitForText('Thank you, form has been submitted', 5, '#modal');
+```
+
+#### Parameters
+
+*   `text` **[string][3]** to wait for.
+*   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait 
+*   `context` **([string][3] | [object][4])?** (optional) element located by CSS|XPath|strict locator. 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitForVisible
+
+Waits for an element to become visible on a page (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForVisible('#popup');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitInUrl
+
+Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
+
+```js
+I.waitInUrl('/info', 2);
+```
+
+#### Parameters
+
+*   `urlPart` **[string][3]** value to check.
+*   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitToHide
+
+Waits for an element to hide (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitToHide('#popup');
+```
+
+#### Parameters
+
+*   `locator` **([string][3] | [object][4])** element located by CSS|XPath|strict locator.
+*   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### waitUrlEquals
+
+Waits for the entire URL to match the expected
+
+```js
+I.waitUrlEquals('/info', 2);
+I.waitUrlEquals('http://127.0.0.1:8000/info');
+```
+
+#### Parameters
+
+*   `urlPart` **[string][3]** value to check.
+*   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait 
+
+Returns **void** automatically synchronized promise through #recorder
+
+### _connect
+
+In SELF-MANAGED mode, resolves and spawns the browser server (or courtesy-attaches to an
+already-running one on :9222) exactly once via `_resolveSelfManaged`. Then resolves the CDP
+endpoint and opens the underlying `CDPConnection`, storing it on `this.cdp`.
 
 ### _findFreePort
 
-Picks a free TCP port on 127.0.0.1 by briefly listening on port 0 and reading back the OS-assigned
-port. Used as the SELF-LAUNCH default when `options.port` isn't explicitly set, so multiple
-`run-workers` workers never collide on the same port.
+Picks a free TCP port on 127.0.0.1 by briefly listening on port 0 and reading back the
+OS-assigned port. Used when `options.port` isn't explicitly set, so multiple `run-workers`
+workers never collide on the same port.
 
-Returns **[Promise][3]<[number][4]>** a free port.
+Returns **[Promise][12]<[number][8]>** a free port.
 
-### _finishTest
+### _manageServer
 
-Closes the CDP connection (via `CDPBrowser._finishTest`), then kills the `obscura serve`
-process spawned by `_connect`, if any (never runs in ATTACH or COURTESY-ATTACH mode, since
-`this.serverProcess` is only ever set in SELF-LAUNCH mode). Runs in a `finally` so the process
-is always reaped even if closing the CDP connection throws. Sends `SIGTERM` first and waits for
-the process to exit; a process that ignores `SIGTERM` is escalated to `SIGKILL` after 5s. The
-promise only resolves once the child has actually exited (confirmed via the `exit` event, not
-merely once `SIGKILL` was sent — the kernel needs a moment to reap it), with a final safety-net
-timeout so a stuck child can never keep the event loop alive even if that confirmation is
-somehow lost.
+Opts a subclass into managing its own browser server process. Called from a subclass
+constructor with the raw user config and a server descriptor:
+
+*   `name` — binary name looked up on `PATH`, also used in messages
+*   `envVar` — environment variable that may point at the binary
+*   `args(port)` — arguments the binary is spawned with to serve CDP on `port`
+*   `env` — extra environment variables for the spawned process
+*   `releases` — URL shown when no binary can be resolved
+
+An explicit `endpoint` in the user config always wins: the helper stays in ATTACH mode and
+never spawns or kills anything. Otherwise the helper becomes SELF-MANAGED and the default
+`endpoint` is cleared until `_resolveSelfManaged` sets the real one.
+
+#### Parameters
+
+*   `config` **[object][4]** the config object the helper was constructed with.
+*   `server` **[object][4]** the server descriptor described above.
 
 ### _probeUp
 
-Probes a `/json/version`-style URL with a short timeout, used for the COURTESY-ATTACH check.
+Probes a `/json/version`-style URL with a short timeout, used for the courtesy-attach check.
 
 #### Parameters
 
-*   `url` **[string][5]**&#x20;
+*   `url` **[string][3]**&#x20;
 
-Returns **[Promise][3]<[boolean][6]>** true if the URL answered.
+Returns **[Promise][12]<[boolean][17]>** true if the URL answered.
 
 ### _resolveBinary
 
-Resolves the `obscura` binary to spawn, in priority order: `options.binaryPath`, then the
-`OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The `PATH` lookup walks the
+Resolves the binary to spawn, in priority order: `options.binaryPath`, then the server
+descriptor's environment variable, then its name on `PATH`. The `PATH` lookup walks the
 directories itself instead of shelling out to `which`, which does not exist on Windows: on
-Windows every `PATHEXT` suffix is tried, so an `obscura.exe` on `PATH` is found too.
+Windows every `PATHEXT` suffix is tried, so a `.exe` on `PATH` is found too.
 
-Returns **([string][5] | null)** an absolute or relative path to the binary, or null if none resolved.
+Returns **([string][3] | null)** an absolute or relative path to the binary, or null if none resolved.
 
 ### _resolveSelfManaged
 
-Resolves how to reach Obscura when no explicit `endpoint` was configured, trying, in order:
-spawn a binary (`binaryPath` config, then `OBSCURA_PATH` env, then `obscura` on `PATH`),
-courtesy-attach to `http://127.0.0.1:9222` if something already answers there, or throw a
-loud, actionable error. Sets `this.options.endpoint` as a side effect.
+Resolves how to reach a SELF-MANAGED browser, trying, in order: spawn a binary
+(`binaryPath` config, then the descriptor's `envVar`, then its `name` on `PATH`) on
+`options.port` or a free port, courtesy-attach to `http://127.0.0.1:9222` if something already
+answers there (never killed by this helper), or throw a loud, actionable error. Sets
+`this.options.endpoint` as a side effect.
+
+A spawn failure (e.g. a bad binary) is delivered asynchronously by Node as an `error` event;
+it is recorded on `this.serverError` and surfaced as a rejection from `_waitForServer` instead
+of crashing the process as an uncaught exception.
 
 ### _waitForServer
 
-Polls `http://127.0.0.1:<port>/json/version` until `obscura serve` responds, `this.serverError`
-is set by the spawned process' `error` event, or `options.serverStartTimeout` elapses. The
-process typically comes up within tens of milliseconds — a 20ms retry interval (down from a
-previous 200ms) keeps the wasted tail after the server is actually ready small, since this cost
-is paid once per run and counts directly toward real-world startup latency.
+Polls `http://127.0.0.1:<port>/json/version` until the spawned server responds,
+`this.serverError` is set by the process' `error` event, or `options.serverStartTimeout`
+elapses. The process typically comes up within tens of milliseconds — a 20ms retry interval
+keeps the wasted tail after the server is actually ready small, since this cost is paid once
+per run and counts directly toward real-world startup latency.
 
 [1]: https://github.com/h4ckf0r0day/obscura
 
 [2]: https://github.com/h4ckf0r0day/obscura/releases
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[5]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
+
+[6]: https://playwright.dev/docs/api/class-locator#locator-blur
+
+[7]: /locators#aria-locators
+
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp
+
+[10]: https://vuejs.org/v2/api/#Vue-nextTick
+
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+[13]: https://playwright.dev/docs/api/class-locator#locator-focus
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[15]: https://nodejs.org/api/buffer.html
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[16]: #fillfield
 
-[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean