From a91cc889b1fe8b440219f8dc4d38682e5381e06a Mon Sep 17 00:00:00 2001 From: DavertMik Date: Fri, 2 Oct 2026 00:37:12 +0300 Subject: [PATCH] updated docs generation --- Bunoshfile.js | 4 +- docs/helpers/Kitesurf.md | 1474 +++++++++++++---------------------- docs/helpers/Obscura.md | 1569 ++++++++++++++------------------------ lib/helper/CDPBrowser.js | 1508 +++--------------------------------- lib/helper/Kitesurf.js | 24 +- lib/helper/Obscura.js | 107 +-- runok.cjs | 4 +- 7 files changed, 1260 insertions(+), 3430 deletions(-) diff --git a/Bunoshfile.js b/Bunoshfile.js index 12a8d5682..e4e9f31fe 100644 --- a/Bunoshfile.js +++ b/Bunoshfile.js @@ -425,11 +425,13 @@ async function docsHelperMarkdown(name, { parent, exclude = [], excludeConfig = const documentation = await import('documentation') const buildOptions = { shallow: true, sortOrder: ['alpha'] } const doc = await documentation.build([`docs/build/${name}.js`], buildOptions) + doc.sort((a, b) => (b.kind === 'class') - (a.kind === 'class')) let members = doc[0].members.instance if (parent) { const parentDoc = await documentation.build([`docs/build/${parent}.js`], buildOptions) - for (const method of parentDoc[0].members.instance) { + const parentClass = parentDoc.find(c => c.kind === 'class') + for (const method of parentClass.members.instance) { if (exclude.some(f => method.name.match(f))) continue if (members.some(m => m.name === method.name)) continue members.push(method) diff --git a/docs/helpers/Kitesurf.md b/docs/helpers/Kitesurf.md index 2981d5465..29af91547 100644 --- a/docs/helpers/Kitesurf.md +++ b/docs/helpers/Kitesurf.md @@ -66,26 +66,25 @@ export CF_API_TOKEN="your-api-token" ## 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][5] +Type: [object][4] ### Properties * `url` **[string][3]?** base URL for tests * `accountId` **[string][3]?** Cloudflare account ID; defaults to CF_ACCOUNT_ID env var * `apiToken` **[string][3]?** Cloudflare API token; defaults to CF_API_TOKEN env var -* `keepAlive` **[number][7]?** session keep-alive time in milliseconds +* `keepAlive` **[number][8]?** session keep-alive time in milliseconds * `apiBase` **[string][3]?** Cloudflare API base URL -* `input` **[string][3]?** input method for user actions; defaults to 'cdp' for Kitesurf's real layout engine, but can be overridden -* `capabilities` **[object][5]?** pre-configured capabilities; Kitesurf uses { layout: 'real', screenshot: true } -* `xpathPolyfill` **([string][3] | [boolean][11])?** whether to inject the bundled XPath polyfill before installing the in-page client. `auto` probes the page and only injects when `document.evaluate` is unavailable or broken; `true`/`false` force the behavior. -* `waitForTimeout` **[number][7]?** default wait* timeout in seconds, used by helpers built on top of this class. -* `waitForAction` **[number][7]?** only takes effect when set explicitly: a literal fixed pacing sleep (in milliseconds) after click, type, or other interactions, mirroring other browser helpers. Left unset, actions settle in an event-aware way instead — near-instant when nothing navigates, waiting for the navigation to actually finish (not a guessed fixed delay) when one does. -* `pollInterval` **[number][7]?** interval in milliseconds between retries while polling for a condition (e.g. page ready state, `waitFor*`). Distinct from `waitForAction`. -* `getPageTimeout` **[number][7]?** maximum time in seconds to wait for a page to finish loading after navigation or reload; also used as the CDP command timeout (in ms, x1000). -* `waitForNavigation` **[string][3]?** when to consider a navigation finished: `load`, `domcontentloaded`, or `networkidle`. Mirrors the Puppeteer helper's option name. `networkidle` waits for the CDP `networkIdle` lifecycle event, which on a busy page can lag `load` by a second or more — only opt in if the extra wait is actually needed. +* `input` **[string][3]?** how actions are dispatched: `cdp` (real mouse and keyboard events) or `synthetic` (DOM events). +* `capabilities` **[object][4]?** browser capabilities; Kitesurf sets `{ layout: 'real', screenshot: true }`. +* `xpathPolyfill` **([string][3] | [boolean][17])?** inject an XPath polyfill for browsers with incomplete XPath support. `auto` detects when it is needed. +* `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`. @@ -97,7 +96,8 @@ Type: [object][5] ### amOnPage -Opens a web page in the current session. +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 @@ -105,90 +105,98 @@ I.amOnPage('https://github.com'); // opens github I.amOnPage('/login'); // opens a login page ``` -Navigates via `Page.navigate`, then waits (up to `options.getPageTimeout` seconds) for the page -to finish loading, preferring the push-based `Page.lifecycleEvent` signal (per -`options.waitForNavigation`) over polling `document.readyState`. Capabilities are (re-)probed -(a no-op after the first page, since they're cached for the helper's lifetime). - -The in-page client is deliberately *not* eagerly (re-)installed here — navigation discards any -previously injected script, but installing it is deferred to the first actual action after -this call, via `_runSelected`'s sentinel-and-retry. This keeps `amOnPage` itself down to the -navigate command plus the push-based wait: no `_evaluate` call is issued on this hot path, -which matters most right when the page's own JavaScript may still be busy (measured directly: -an `_evaluate` sent in that window can queue behind it for hundreds of ms to multiple seconds -on a JS-heavy real-world page, regardless of how small the evaluated expression is). - #### Parameters * `url` **[string][3]** url path or global url. -Returns **[Promise][4]** +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][5])** located by label|name|CSS|XPath|strict locator +* `field` **([string][3] | [object][4])** located by label|name|CSS|XPath|strict locator * `value` **[string][3]** text value to append. -* `context` **([string][3]? | [object][5])** (optional, `null` by default) element to search in CSS|XPath|Strict locator. +* `context` **([string][3]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. -Returns **[Promise][4]** +Returns **void** automatically synchronized promise through #recorder ### attachFile -Attaches a file to a file input field, or drops it onto a drag-and-drop dropzone element, -resolved by label|name|CSS|XPath|strict locator. `pathToFile` is resolved relative to -`codecept_dir` (matching Puppeteer/WebDriver). Since `CDPBrowser` never brings element handles -back to Node, the resolved element is marked with a throwaway `data-codecept-upload` attribute -in-page (respecting `context`/`within`/elementIndex exactly like every other action). A real -`` is then addressed by that attribute through the CDP `DOM` domain, which -`CDPBrowser` otherwise never uses, to call `DOM.setFileInputFiles`; any other element (a -drag-and-drop dropzone) instead gets a synthetic `dragenter`/`dragover`/`drop` sequence with a -`DataTransfer` built from the file's contents, entirely in-page. The marker is removed again in -a `finally`. +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('#file', '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` **([string][3] | [object][5])** located by label|name|CSS|XPath|strict locator. -* `pathToFile` **[string][3]** path to file, relative to `codecept_dir`. -* `context` **([string][3]? | [object][5])** (optional, `null` by default) element to search in CSS|XPath|Strict locator. +* `field` +* `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 **[Promise][4]** +Returns **void** automatically synchronized promise through #recorder ### blur -Removes focus from a given element. +Remove focus from a text input, button, etc. +Calls [blur][5] on the element. + +Examples: + +```js +I.blur('.text-area') +``` ```js -I.blur('#name'); +//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][5])** element located by CSS|XPath|strict locator. +* `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 **[Promise][4]** +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'); @@ -197,10 +205,10 @@ I.checkOption('agree', '//form'); #### Parameters -* `field` **([string][3] | [object][5])** checkbox located by label | name | CSS | XPath | strict locator. -* `context` **([string][3]? | [object][5])** (optional, `null` by default) element located by CSS | XPath | strict locator. +* `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 **[Promise][4]** +Returns **void** automatically synchronized promise through #recorder ### clearClipboard @@ -211,7 +219,7 @@ I.clearClipboard(); I.seeClipboardEquals(''); ``` -Returns **[Promise][4]** +Returns **void** automatically synchronized promise through #recorder ### clearCookie @@ -225,26 +233,30 @@ I.clearCookie('test'); #### Parameters -* `name` **([string][3] | null)** (optional, `null` by default) cookie name - -Returns **[Promise][4]** +* `name` +* `cookie` **[string][3]?** (optional, `null` by default) cookie name ### clearField Clears a `