From ef4f5be44c24aa7ea38a4a249bf93909379a0cbc Mon Sep 17 00:00:00 2001 From: shadowusr <58862284+shadowusr@users.noreply.github.com> Date: Wed, 17 Jul 2024 02:13:48 +0300 Subject: [PATCH] docs: add en versions of browser commands (#17) * docs: add en versions of browser commands --- docs/quickstart/index.mdx | 2 - .../current/commands/browser/$$.mdx | 96 +++++++++ .../current/commands/browser/$.mdx | 119 +++++++++++ .../current/commands/browser/action.mdx | 165 +++++++++++++++ .../current/commands/browser/actions.mdx | 32 +++ .../current/commands/browser/addCommand.mdx | 69 +++++++ .../current/commands/browser/assertView.mdx | 190 ++++++++++++++++++ .../current/commands/browser/call.mdx | 59 ++++++ .../current/commands/browser/debug.mdx | 31 +++ .../commands/browser/deleteCookies.mdx | 69 +++++++ .../current/commands/browser/execute.mdx | 59 ++++++ .../current/commands/browser/executeAsync.mdx | 63 ++++++ .../commands/browser/executionContext.mdx | 42 ++++ .../current/commands/browser/getConfig.mdx | 27 +++ .../current/commands/browser/getCookies.mdx | 60 ++++++ .../current/commands/browser/getMeta.mdx | 65 ++++++ .../current/commands/browser/getPuppeteer.mdx | 51 +++++ .../commands/browser/getWindowSize.mdx | 29 +++ .../current/commands/browser/keys.mdx | 53 +++++ .../current/commands/browser/mock.mdx | 139 +++++++++++++ .../current/commands/browser/mockClearAll.mdx | 44 ++++ .../commands/browser/mockRestoreAll.mdx | 41 ++++ .../current/commands/browser/newWindow.mdx | 63 ++++++ .../current/commands/browser/openAndWait.mdx | 72 +++++++ .../commands/browser/overwriteCommand.mdx | 61 ++++++ .../current/commands/browser/pause.mdx | 49 +++++ .../current/commands/browser/reactDollar.mdx | 80 ++++++++ .../commands/browser/reactDollarDollar.mdx | 61 ++++++ .../commands/browser/reloadSession.mdx | 29 +++ .../current/commands/browser/savePDF.mdx | 63 ++++++ .../commands/browser/saveRecordingScreen.mdx | 52 +++++ .../commands/browser/saveScreenshot.mdx | 46 +++++ .../current/commands/browser/scroll.mdx | 44 ++++ .../current/commands/browser/setCookies.mdx | 97 +++++++++ .../current/commands/browser/setMeta.mdx | 57 ++++++ .../current/commands/browser/setTimeout.mdx | 49 +++++ .../commands/browser/setWindowSize.mdx | 32 +++ .../current/commands/browser/switchWindow.mdx | 45 +++++ .../current/commands/browser/throttle.mdx | 73 +++++++ .../current/commands/browser/touchAction.mdx | 90 +++++++++ .../current/commands/browser/uploadFile.mdx | 55 +++++ .../current/commands/browser/url.mdx | 63 ++++++ .../current/commands/browser/waitUntil.mdx | 61 ++++++ .../current/quickstart/index.mdx | 104 ++++++++++ 44 files changed, 2849 insertions(+), 2 deletions(-) create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/$$.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/$.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/action.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/actions.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/addCommand.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/assertView.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/call.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/debug.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/deleteCookies.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/execute.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/executeAsync.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/executionContext.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getConfig.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getCookies.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getMeta.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getPuppeteer.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getWindowSize.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/keys.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mock.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mockClearAll.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mockRestoreAll.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/newWindow.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/openAndWait.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/overwriteCommand.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/pause.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reactDollar.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reactDollarDollar.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reloadSession.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/savePDF.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/saveRecordingScreen.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/saveScreenshot.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/scroll.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setCookies.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setMeta.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setTimeout.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setWindowSize.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchWindow.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/throttle.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/touchAction.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/uploadFile.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/url.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/waitUntil.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/quickstart/index.mdx diff --git a/docs/quickstart/index.mdx b/docs/quickstart/index.mdx index 956127b..a00aa62 100644 --- a/docs/quickstart/index.mdx +++ b/docs/quickstart/index.mdx @@ -3,8 +3,6 @@ import TabItem from "@theme/TabItem"; # Быстрый старт -Прежде всего, убедитесь, что ваша система удовлетворяет нужным требованиям. - ## Установка {#install} Запустите установщик testplane с помощью `npm`. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/$$.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/$$.mdx new file mode 100644 index 0000000..2b71523 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/$$.mdx @@ -0,0 +1,96 @@ +--- +slug: _dollardollar +sidebar_label: $$ +--- + +import Admonition from "@theme/Admonition"; + +# $$ + +## Overview {#overview} + +Use the `$$` command instead of [findElements][find-elements] as a shorter command to get multiple elements on the page. + +The `$$` command returns an array with the desired elements, on each of which you can call action commands without passing the selector. However, if you do pass a selector, it will first find the corresponding element and then call the action for that element. + +You can chain `$` or `$$` together to traverse down the DOM tree. + + + Read more about how to select specific elements in the recipe "[How to use + selectors][how-to-use-selectors]". + + +## Usage {#usage} + +```javascript +await browser.$$(selector); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
selectorString or FunctionSelector or JS function to get multiple elements.
+ +## Examples {#examples} + +**index.html** + +```html + +``` + +**$.js** + +```javascript +it("should get text of a menu link", async ({ browser }) => { + const text = await browser.$$("#menu")[0]; + + console.log(await text.$$("li")[2].$("a").getText()); // outputs: "API" +}); + +it("should get text of a menu link - JS Function", async ({ browser }) => { + const text = await browser.$$(function () { + // Arrow function cannot be used here. + // This is Window – https://developer.mozilla.org/en-US/docs/Web/API/Window + // + // TypeScript users can do something like: + // return (this as Window).document.querySelectorAll('#menu') + return this.document.querySelectorAll("#menu"); // Element[] + })[0]; + + console.log(await text.$$("li")[2].$("a").getText()); // outputs: "API" +}); +``` + +## Related Commands {#related} + +- [browser.$](../_dollar) +- [element.$](../../element/_dollar) +- [element.$$](../../element/_dollardollar) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/$$), from which we drew some information while writing our version. + +[find-elements]: https://webdriver.io/docs/api/webdriver/#findelements +[how-to-use-selectors]: https://webdriver.io/docs/selectors diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/$.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/$.mdx new file mode 100644 index 0000000..fd66cf6 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/$.mdx @@ -0,0 +1,119 @@ +--- +slug: _dollar +sidebar_position: 1 +--- + +import Admonition from "@theme/Admonition"; + +# $ + +## Overview {#overview} + +Use the `$` command instead of [findElement][find-element] as a shorter command to get a single element on the page. + +The `$` command returns an object describing the element, on which you can call action commands without passing the selector. However, if you pass a selector, it will first find the corresponding element and then call the action for that element. You can also pass an object as the selector, where the object contains the property `element-6066-11e4-a52e-4f735466cecf` with the value of the element reference. The command will then convert the reference into an extended WebdriverIO element. + +You can chain `$` or `$$` together to traverse down the DOM tree. + + + Read more about how to select specific elements in the recipe "[How to use + selectors][how-to-use-selectors]". + + +## Usage {#usage} + +```javascript +await browser.$(selector); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
selectorString or Function or MatcherSelector or JS function to get a specific element.
+ +## Examples {#examples} + +**index.html** + +```html + +``` + +**$.js** + +```javascript +it("should get text of a menu link", async ({ browser }) => { + const text = await browser.$("#menu"); + + console.log(await text.$$("li")[2].$("a").getText()); // outputs: "API" +}); + +it("should get text of a menu link - JS Function", async ({ browser }) => { + const text = await browser.$(function () { + // Arrow function cannot be used here. + // This is Window – https://developer.mozilla.org/en-US/docs/Web/API/Window + // + // TypeScript users can do something like: + // return (this as Window).document.querySelector('#menu') + return this.document.querySelector("#menu"); // Element + }); + + console.log(await text.$$("li")[2].$("a").getText()); // outputs: "API" +}); + +it("should allow converting the protocol result of an element into a WebdriverIO element", async ({ + browser, +}) => { + const activeElement = await browser.getActiveElement(); + + console.log(await browser.$(activeElement).getTagName()); // outputs the active element +}); + +it("should use Androids DataMatcher or ViewMatcher selector", async ({ browser }) => { + const menuItem = await browser.$({ + name: "hasEntry", + args: ["title", "ViewTitle"], + class: "androidx.test.espresso.matcher.ViewMatchers", + }); + await menuItem.click(); + + const menuItem = await browser.$({ + name: "hasEntry", + args: ["title", "ViewTitle"], + }); + await menuItem.click(); +}); +``` + +## Related Commands {#related} + +- [browser.$$](../_dollardollar) +- [element.$](../../element/_dollar) +- [element.$$](../../element/_dollardollar) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/$), from which we drew some information while writing our version. + +[find-element]: https://webdriver.io/docs/api/webdriver/#findelement +[how-to-use-selectors]: https://webdriver.io/docs/selectors diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/action.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/action.mdx new file mode 100644 index 0000000..b30745d --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/action.mdx @@ -0,0 +1,165 @@ +import Admonition from "@theme/Admonition"; + +# action + +## Overview {#overview} + +Use the `action` command to perform input actions on one of the virtualizable devices in the web browser. + +Unlike high-level commands like [scrollIntoView][scrollIntoView] and [doubleClick][doubleClick], the Actions API provides more granular control of input devices. The following input sources are available: + +- text input for keyboard devices; +- control of mouse, pen, or touch device; +- scroll control for devices with a scroll wheel. + +Each chain of `action` commands must end with a `perform` command to execute the specified set of actions. This also releases all pressed keys, buttons, etc., on virtual input devices and triggers the necessary events. The release can be skipped by passing the argument `true` to the `perform` command. Example: + +```typescript +await browser.action(...).perform(true); +``` + + + Support for this command and specific actions may vary depending on the execution environment. + The development progress can be tracked on [wpt.fyi][web-platform-tests]. For mobile devices, + you can use specialized gesture commands with [Appium][appium] on [iOS][appium-ios] and + [Android][appium-android]. + + +## Keyboard Control {#keyboard_control} + +Used when specifying `key` as the argument for the `action` command. Example: + +```typescript +await browser.action("key"); +``` + +Returns a `KeyAction` object that supports the following actions: + +- `down(value: string)` — creates a key press action; +- `up(value: string)` — creates a key release action; +- `pause(ms: number)` — specifies that the input source does nothing for the specified amount of time. + +### Special Symbols {#special_symbols} + +To use special symbols (`Control`, `Page Up`, `Shift`, etc.), you can use the `Key` object from the [webdriverio][webdriverio-npm] package. It contains Unicode representations of all necessary special symbols. Example: + +```typescript +import { Key } from "webdriverio"; + +await browser.action("key").down(Key.Ctrl).perform(); +``` + +### Usage Examples {#keyboard_examples} + +```typescript +import { Key } from "webdriverio"; + +it("should emit key events using key action commands", async ({ browser }) => { + const elem = await browser.$("input"); + await elem.click(); // make the element active + + await browser.action("key").down("f").down("o").down("o").up("f").up("o").up("o").perform(); + + console.log(await elem.getValue()); // returns "foo" + + // copy value from input element + await browser.action("key").down(Key.Ctrl).down("c").pause(10).up(Key.Ctrl).up("c").perform(); +}); +``` + +Instead of a series of `down/up` events, it is better to use the `setValue` command. The example is purely for demonstrating the principles of the `action` command. + +## Pointer Control {#pointer_control} + +Used when specifying `pointer` as the argument for the `action` command, and you can also specify the pointer type. Example: + +```typescript +await browser.action("pointer", { + parameters: { pointerType: "mouse" }, // "mouse" is the default value, also available: "pen" or "touch" +}); +``` + +Returns a `PointerAction` object that supports the following actions: + +- `down(button: 'left' | 'middle' | 'right')` — creates an action to press a key; +- `down(params: PointerActionParams)` — creates an action to press a key with detailed parameters; +- `move(x: number, y: number)` — creates an action to move the pointer by `x` and `y` pixels relative to the viewport; +- `move(params: PointerActionMoveParams)` — creates an action to move the pointer by `x` and `y` pixels from the specified origin. The origin can be defined as the current pointer position, the viewport, or the center of a specific element; +- `up(button: 'left' | 'middle' | 'right')` — creates an action to release a key; +- `up(params: PointerActionUpParams)` — creates an action to release a key with detailed parameters; +- `cancel()` — creates an action that cancels the current pointer position; +- `pause(ms: number)` — specifies that the input source does nothing for the specified amount of time. + +Detailed information on the parameter types [PointerActionParams][pointer-action-params], [PointerActionMoveParams][pointer-action-move-params], and [PointerActionUpParams][pointer-action-up-params] can be found in the webdriverio source code. + +### Usage Examples {#pointer_examples} + +```typescript +it("drag and drop using pointer action command", async ({ browser }) => { + const origin = await browser.$("#source"); + const targetOrigin = await browser.$("#target"); + + await browser + .action("pointer") + .move({ duration: 0, origin, x: 0, y: 0 }) + .down({ button: 0 }) // left button + .pause(10) + .move({ duration: 0, origin: targetOrigin }) + .up({ button: 0 }) + .perform(); +}); +``` + +## Scroll Wheel Control {#scroll_wheel_control} + +Used when specifying `wheel` as the argument for the `action` command. Example: + +```typescript +await browser.action("wheel"); +``` + +Returns a `WheelAction` object that supports the following actions: + +- `scroll(params: ScrollParams)` — scrolls the page to the specified coordinates or origin; +- `pause(ms: number)` — specifies that the input source does nothing for the specified amount of time. + +Detailed information on the parameter type [ScrollParams][scroll-params] can be found in the webdriverio source code. + +### Usage Examples {#scroll_examples} + +```typescript +it("should scroll using wheel action commands", async ({ browser }) => { + console.log(await browser.execute(() => window.scrollY)); // returns 0 + + await browser + .action("wheel") + .scroll({ + deltaX: 0, + deltaY: 500, + duration: 200, + }) + .perform(); + + console.log(await browser.execute(() => window.scrollY)); // returns 500 +}); +``` + +## Related Commands {#related} + +- [actions](../actions) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/action), from which we drew some information while writing our version. + +[scrollIntoView]: ../../element/scrollIntoView +[doubleClick]: ../../element/doubleClick +[web-platform-tests]: https://wpt.fyi/results/webdriver/tests/perform_actions?label=experimental&label=master&aligned +[appium]: http://appium.io +[appium-ios]: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/#mobile-pinch +[appium-android]: https://github.com/appium/appium-uiautomator2-driver#mobile-gesture-commands +[webdriverio-npm]: https://www.npmjs.com/package/webdriverio +[pointer-action-params]: https://github.com/webdriverio/webdriverio/blob/8ca026c75bf7c27ef9d574f0ec48d8bc13658602/packages/webdriverio/src/utils/actions/pointer.ts#L20-L35 +[pointer-action-move-params]: https://github.com/webdriverio/webdriverio/blob/8ca026c75bf7c27ef9d574f0ec48d8bc13658602/packages/webdriverio/src/utils/actions/pointer.ts#L20-L42 +[pointer-action-up-params]: https://github.com/webdriverio/webdriverio/blob/8ca026c75bf7c27ef9d574f0ec48d8bc13658602/packages/webdriverio/src/utils/actions/pointer.ts#L13-L19 +[scroll-params]: https://github.com/webdriverio/webdriverio/blob/8ca026c75bf7c27ef9d574f0ec48d8bc13658602/packages/webdriverio/src/utils/actions/wheel.ts#L4-L29 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/actions.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/actions.mdx new file mode 100644 index 0000000..8a03adc --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/actions.mdx @@ -0,0 +1,32 @@ +# actions + +## Overview {#overview} + +Use the `actions` command to perform multiple input actions on one of the virtualizable devices in the web browser, for example, to simulate page zooming. More detailed information is provided in the description of the [action][action] command. + +## Usage {#usage} + +```typescript +await browser.actions([action1, action2, ...]); +``` + +## Usage Examples {#examples} + +```typescript +it("run multiple actions at once for a pinch zoom", async ({ browser }) => { + await browser.actions([ + browser.action("pointer").move(500, 500).down().move(250, 250).up(), + browser.action("pointer").move(500, 500).down().move(750, 750).up(), + ]); +}); +``` + +## Related Commands {#related} + +- [action](../action) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/actions), from which we drew some information while writing our version. + +[action]: ../action diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/addCommand.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/addCommand.mdx new file mode 100644 index 0000000..3e69e17 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/addCommand.mdx @@ -0,0 +1,69 @@ +import Admonition from "@theme/Admonition"; + +# addCommand + +## Overview {#overview} + +Use the `addCommand` command to add your own command to the browser or to an element. The command being added can be either synchronous or asynchronous. + + + Read more about how to add your custom commands in the recipe "[How to add custom + commands][how-to-add-custom-commands]". + + +## Usage {#usage} + +```javascript +await browser.addCommand(name, callback, elementScope); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + +
**Name****Type****Description**
nameStringCustom command name.
callbackFunctionCommand implementation function.
elementScopeBooleanIf the value is _true_, add the command to the element instead of the browser. Default: _false_.
+ +## Usage Examples {#examples} + +```javascript +// add the getUrlAndTitle command +await browser.addCommand("getUrlAndTitle", async function (customParam) { + return { + url: await this.getUrl(), // `this` here and below refers to the "browser" object + title: await this.getTitle(), + customParam: customParam, + }; +}); + +// use the new getUrlAndTitle command +it("should use my add command", async ({ browser }) => { + await browser.url("https://webdriver.io"); + + const result = await browser.getUrlAndTitle("foobar"); + + assert.strictEqual(result.url, "https://webdriver.io"); + assert.strictEqual( + result.title, + "WebdriverIO · Next-gen browser and mobile automation test framework for Node.js", + ); + assert.strictEqual(result.customParam, "foobar"); +}); +``` + +## Related Commands {#related} + +- [overwriteCommand](../overwriteCommand) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/addCommand), from which we drew some information while writing our version. + +[how-to-add-custom-commands]: https://webdriver.io/docs/customcommands/#adding-custom-commands diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/assertView.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/assertView.mdx new file mode 100644 index 0000000..b098130 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/assertView.mdx @@ -0,0 +1,190 @@ +import Admonition from "@theme/Admonition"; + +# assertView + +## Overview {#overview} + +Use the `assertView` command to take a screenshot for a specific test state and compare it with a reference. + + + This command is implemented within Testplane, it's not available in the [API + WebDriverIO][webdriverio-api]. + + +## Usage {#usage} + +```javascript +await browser.assertView(state, selector, options); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + +
**Name****Type****Description**
[state](#state)StringRequired parameter. The name of the test state. It must be unique within a single test.
[selector](#selector)String or String[]Required parameter. The DOM element selector to capture.
[options](#options)ObjectSettings for the _assertView_ command.
+ +### state + +Required parameter. Specifies the name of the test state. The name must be unique within a single test. + +### selector + +Required parameter. Specifies the selector of the DOM element to capture. + +### options + +Specifies the settings for the `assertView` command: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
**Option****Type****Description**
ignoreElementsArray or String + Elements (specified as selectors) that will be ignored when comparing screenshots. + Ignoring is implemented by painting the listed elements black. For a single element, + the parameter can be set as a string. +
toleranceNumber + Sensitivity to color differences. The value overrides + [browsers.tolerance][browsers-tolerance]. +
antialiasingToleranceNumber + Sensitivity to anti-aliasing. The value overrides + [browsers.antialiasingTolerance][browsers-antialiasing-tolerance]. +
allowViewportOverflowBoolean + By default, Testplane throws an error if the element is outside the viewport + boundaries. This parameter disables boundary checks, allowing screenshots of + elements that don't fully fit in the viewport. On the screenshot, only the parts of + the element that fit into the viewport will be visible. However, if _compositeImage_ + is set to _true_, the parts of the element that are below the viewport boundary will + also be visible in the screenshot. Similarly, if _captureElementFromTop_ is set to + _true_, the parts of the element that are above the viewport boundary will also be + captured in the screenshot. +
captureElementFromTopBoolean + Capture the screenshot of the element from the very top. If the element is outside + the viewport, it will be scrolled into view. +
compositeImageBoolean + If the element does not fit into the viewport, multiple screenshots of different + parts of the element will be taken sequentially, and then stitched together into one + to display the entire element. +
screenshotDelayNumber + Delay in milliseconds before taking a screenshot. Useful when there are elements + with animations on the page, or a scrollbar that does not disappear immediately and + appears in the resulting screenshot. +
selectorToScrollString + Selector to scroll. Useful when you need to take a screenshot of a modal window that + doesn’t fit on the screen. Otherwise, without specifying a selector, the scroll will + be applied to the _window_ object, scrolling the background while keeping the popup + window in place. +
disableAnimationBoolean + Disable animations and transitions when taking a screenshot. Default is `true` + starting from version `8.0.0`. +
ignoreDiffPixelCount`` `${number}%` `` or Number + The percentage of pixels to ignore during the diff. Useful to ignore very small + differences. Default is `0`. Available starting from version `8.2.0`. +
+ +## Usage Examples {#examples} + +**example-1.js** + +```javascript +it("should assert view", async ({ browser }) => { + await browser.url("some/url"); + await browser.assertView("plain", ".button"); + + await browser.click(".button"); + await browser.assertView("clicked", ".button"); +}); +``` + +**example-2.js** + +```javascript +it("should assert view with given options", async ({ browser }) => { + await browser.url("some/url"); + await browser.assertView("plain", ".form", { + ignoreElements: [".link"], + tolerance: 5, + antialiasingTolerance: 4, + allowViewportOverflow: true, + captureElementFromTop: true, + compositeImage: true, + screenshotDelay: 10, + selectorToScroll: ".modal", + }); +}); +``` + +## Related Commands {#related} + +- [element.assertView](../../element/assertView) +- [browser.saveRecordingScreen](../saveRecordingScreen) +- [browser.saveScreenshot](../saveScreenshot) +- [element.saveScreenshot](../../element/saveScreenshot) + +[webdriverio-api]: https://webdriver.io/docs/api +[browsers-tolerance]: ../../../config/browsers#tolerance +[browsers-antialiasing-tolerance]: ../../../config/browsers#antialiasing_tolerance diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/call.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/call.mdx new file mode 100644 index 0000000..40432fc --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/call.mdx @@ -0,0 +1,59 @@ +# call + +## Overview {#overview} + +Use the `call` command to perform any asynchronous action in tests. + +This command is treated as a synchronous function. It accepts a promise and halts its execution until the promise is resolved. + +## Usage {#usage} + +```javascript +await browser.call(callback); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
callbackFunctionThe function to call.
+ +## Usage Examples {#examples} + +```javascript +it("some testing here", async ({ browser }) => { + await browser.url("http://google.com"); + + // make an asynchronous call using a third-party library + // that supports promises, e.g., a call to a backend or DB + // to inject a fixture + await browser.call(() => { + return somePromiseLibrary.someMethod().then(() => { + // ... + }); + }); + + // example for an asynchronous call using a third-party library + // that does not support promises + const result = await browser.call(() => { + return new Promise((resolve, reject) => { + someOtherNodeLibrary.someMethod(param1, (err, res) => { + if (err) { + return reject(err); + } + resolve(res); + }); + }); + }); +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/call), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/debug.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/debug.mdx new file mode 100644 index 0000000..b0e87b3 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/debug.mdx @@ -0,0 +1,31 @@ +# debug + +## Overview {#overview} + +Use the `debug` command to pause the execution of a test in the browser. + +By pausing the test, you can switch to the browser, open _DevTools_, and inspect the web page in real-time. This can be useful for debugging the test. + +## Usage {#usage} + +```javascript +await browser.debug(); +``` + +## Usage Examples {#examples} + +```javascript +it("should demonstrate the debug command", async ({ browser }) => { + await browser.$("#input").setValue("FOO"); + + await browser.debug(); // switch to the browser and change the value of #input to "BAR" + + const value = await browser.$("#input").getValue(); + + console.log(value); // outputs: "BAR" +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/debug), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/deleteCookies.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/deleteCookies.mdx new file mode 100644 index 0000000..b65c24b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/deleteCookies.mdx @@ -0,0 +1,69 @@ +# deleteCookies + +## Overview {#overview} + +Use the `deleteCookies` command to delete all or specific cookies for the current page. + +To delete specific cookies, you need to specify the cookie name as a string or a list of cookie names as an array of strings. + +## Usage {#usage} + +```javascript +await browser.deleteCookies(names); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
namesString or String[]Optional parameter. The cookie name or list of cookie names to delete. If the parameter is missing, all cookies for the current page will be deleted.
+ +## Usage Examples {#examples} + +```javascript +it("should delete cookies", async ({ browser }) => { + await browser.setCookies([ + { name: "test", value: "123" }, + { name: "test2", value: "456" }, + { name: "test3", value: "789" }, + ]); + + let cookies = await browser.getCookies(); + console.log(cookies); + // outputs: + // [ + // { name: 'test', value: '123' }, + // { name: 'test2', value: '456' }, + // { name: 'test3', value: '789' } + // ] + + await browser.deleteCookies(["test3"]); + + cookies = await browser.getCookies(); + console.log(cookies); + // outputs: + // [ + // { name: 'test', value: '123' }, + // { name: 'test2', value: '456' } + // ] + + await browser.deleteCookies(); + cookies = await browser.getCookies(); + console.log(cookies); // outputs: [] +}); +``` + +## Related Commands {#related} + +- [getCookies](../getCookies) +- [setCookies](../setCookies) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/deleteCookies), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/execute.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/execute.mdx new file mode 100644 index 0000000..e9a7110 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/execute.mdx @@ -0,0 +1,59 @@ +# execute + +## Overview {#overview} + +Use `execute` to _synchronously_ execute the specified JavaScript code in the context of the currently selected frame. + +The command returns the result of the script execution to the client. + +The `script` argument defines the script to be executed as the body of a function. The value returned by this function will be returned to the client. The function will be invoked with the provided array of `args`, and access to the values can be obtained through the `arguments` object in the specified order. + +Arguments can be any JSON primitives, arrays, or JSON objects. JSON objects that define a reference to a _WebElement_ will be converted to the corresponding DOM element. Similarly, any _WebElements_ in the script result will be returned to the client as _WebElement JSON_ objects. + +## Usage {#usage} + +```javascript +await browser.execute(script, arguments); +``` + +## Command Parameters {#parameters} + + + + + + + + + + +
**Name****Type****Description**
scriptString or FunctionThe script to be executed.
argumentsAnyOptional parameter. Arguments for the script.
+ +## Usage Examples {#examples} + +```javascript +it("should inject javascript on the page", async ({ browser }) => { + const result = await browser.execute( + (a, b, c, d) => { + // here we are in the browser context: no access to console or client + return a + b + c + d; + }, + 1, + 2, + 3, + 4, + ); + + // here we are in the node.js context: access to console and client is available + console.log(result); // outputs: 10 +}); +``` + +## Related Commands {#related} + +- [executeAsync](../executeAsync) +- [setTimeout](../setTimeout) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/execute), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/executeAsync.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/executeAsync.mdx new file mode 100644 index 0000000..f4feab1 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/executeAsync.mdx @@ -0,0 +1,63 @@ +# executeAsync + +## Overview {#overview} + +Use the `executeAsync` command to _asynchronously_ execute the specified JavaScript code in the context of the currently selected frame. + +The last argument of the command must be a callback that will be called as soon as the script completes its execution. The command passes the script result to the callback as an input parameter. + +The `script` argument defines the script to be executed as the body of a function. The function will be invoked with the provided array of `args`, and access to the values can be obtained through the `arguments` object in the specified order. The last argument must always be a callback function, which will be called once the script has been executed. + +Arguments can be any JSON primitives, arrays, or JSON objects. JSON objects that define a reference to a _WebElement_ will be converted to the corresponding DOM element. Similarly, any _WebElements_ in the script result will be returned to the client as _WebElement JSON_ objects. + +## Usage {#usage} + +```javascript +await browser.executeAsync(script, arguments); +``` + +## Command Parameters {#parameters} + + + + + + + + + + +
**Name****Type****Description**
scriptString or FunctionThe script to be executed.
argumentsAnyArguments for the script. The last argument must be a callback function, which will be called once the script has been executed.
+ +## Usage Examples {#examples} + +```javascript +it("should execute async JavaScript on the page", async ({ browser }) => { + await browser.setTimeout({ script: 5000 }); + + const result = await browser.executeAsync( + function (a, b, c, d, done) { + // here we are in the browser context: no access to console or client + setTimeout(() => { + done(a + b + c + d); + }, 3000); + }, + 1, + 2, + 3, + 4, + ); + + // here we are in the node.js context: access to console and client is available + console.log(result); // outputs: 10 +}); +``` + +## Related Commands {#related} + +- [execute](../execute) +- [setTimeout](../setTimeout) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/executeAsync), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/executionContext.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/executionContext.mdx new file mode 100644 index 0000000..471af96 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/executionContext.mdx @@ -0,0 +1,42 @@ +import Admonition from "@theme/Admonition"; + +# executionContext + +## Overview {#overview} + +During the test run, testplane adds an `executionContext` property to `browser` to store the execution context. + +The `browser.executionContext` property holds the current test or hook \_Mocha object, supplemented with a browser identifier. + + + The execution context is added by testplane and is not available in the [API + WebDriverIO][webdriverio-api]. + + +## Usage Example {#examples} + +```javascript +it("should log execution context", async ({ browser }) => { + await browser.url("/foo/bar"); + + console.log("test", browser.executionContext); + // outputs: + // test: { + // "title": "should log execution context", + // "async": 0, + // "sync": true, + // "timedOut": false, + // "pending": false, + // "type": "test", + // "body": "...", + // "file": "/foo/bar/baz/qux.js", + // "parent": "#", + // "ctx": "#", + // "browserId": "chrome", + // "meta": {}, + // "timer": {} + // } +}); +``` + +[webdriverio-api]: https://webdriver.io/docs/api diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getConfig.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getConfig.mdx new file mode 100644 index 0000000..be96867 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getConfig.mdx @@ -0,0 +1,27 @@ +# getConfig + +## Overview {#overview} + +Use the `getConfig` command to get the browser [config][browser-config]. + +## Usage {#usage} + +```javascript +await browser.getConfig(); +``` + +## Usage Examples {#examples} + +```javascript +it("some test", async ({ browser }) => { + const browserConfig = await browser.getConfig(); + console.log(browserConfig.id); + // outputs: "chromeDesktop" – the name of the browser configuration specified in the config + + const { browserName } = browserConfig.desiredCapabilities; + console.log(browserName); + // outputs: "chrome" – the actual name of the browser +}); +``` + +[browser-config]: ../../../config/browsers#browser_main_settings diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getCookies.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getCookies.mdx new file mode 100644 index 0000000..c875668 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getCookies.mdx @@ -0,0 +1,60 @@ +# getCookies + +## Overview {#overview} + +Use the `getCookies` command to get all or specific cookies on the current page. + +To get specific cookies, you need to specify the cookie name as a string or a list of cookie names as an array of strings. + +## Usage {#usage} + +```javascript +await browser.getCookies(names); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
namesString or String[]Optional parameter. The name of the cookie or list of cookie names to get. If the parameter is missing, all cookies for the current page will be returned.
+ +## Usage Examples {#examples} + +```javascript +it("should return a cookie for me", async ({ browser }) => { + await browser.setCookies([ + { name: "test", value: "123" }, + { name: "test2", value: "456" }, + ]); + + const testCookie = await browser.getCookies(["test"]); + console.log(testCookie); + // outputs: + // [ + // { name: 'test', value: '123' } + // ] + + const allCookies = await browser.getCookies(); + console.log(allCookies); + // outputs: + // [ + // { name: 'test', value: '123' }, + // { name: 'test2', value: '456' } + // ] +}); +``` + +## Related Commands {#related} + +- [setCookies](../setCookies) +- [deleteCookies](../deleteCookies) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/getCookies), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getMeta.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getMeta.mdx new file mode 100644 index 0000000..5cd34cb --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getMeta.mdx @@ -0,0 +1,65 @@ +import Admonition from "@theme/Admonition"; + +# getMeta + +## Overview + +Use the `getMeta` command to retrieve metadata about the test. + +If a key is specified, the command returns the value for that specific key. +If the key is not specified, the command will return an object with all the metadata for the test. + +To set values in the metadata, use the [setMeta](../setMeta) command. + + + This command is implemented within testplane and is not available in the [API + WebDriverIO][webdriverio-api]. + + +## Usage {#usage} + +```javascript +await browser.getMeta(); +``` + +or + +```javascript +await browser.getMeta(key); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
keyStringOptional parameter. The key whose value needs to be retrieved from the test metadata.
+ +## Usage Examples {#examples} + +```javascript +it("should get meta info of test", async ({ browser }) => { + await browser.setMeta("foo", "bar"); + await browser.url("/foo/bar?baz=qux"); + + const val = await browser.getMeta("foo"); + console.log(val); // outputs: bar + + const url = await browser.getMeta("url"); + console.log(url); // outputs: /foo/bar?baz=qux + + const meta = await browser.getMeta(); + console.log(meta); // outputs: {foo: 'bar', url: '/foo/bar?baz=qux'} +}); +``` + +## Related Commands {#related} + +- [setMeta](../setMeta) + +[webdriverio-api]: https://webdriver.io/docs/api diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getPuppeteer.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getPuppeteer.mdx new file mode 100644 index 0000000..9159b42 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getPuppeteer.mdx @@ -0,0 +1,51 @@ +import Admonition from "@theme/Admonition"; + +# getPuppeteer + +## Overview {#overview} + +Use the `getPuppeteer` command to get an instance of the browser's [Puppeteer][puppeteer] in order to execute specialized commands with it. + +Please note that all [Puppeteer][puppeteer] commands are asynchronous by default, so to switch between synchronous and asynchronous execution, be sure to wrap [Puppeteer][puppeteer] calls in [browser.call][browser-call], as shown in the example below. + + +The _getPuppeteer_ command only works when using _Chrome DevTools Protocol (CDP)_. + +Read more in the section "[How to use Chrome DevTools Protocol in testplane][how-to-use-cdp]". + + + +## Usage {#usage} + +```javascript +await browser.getPuppeteer(); +``` + +## Usage Examples {#examples} + +```javascript +it("should allow me to use Puppeteer", async ({ browser }) => { + await browser.url("https://webdriver.io"); + + const puppeteerBrowser = await browser.getPuppeteer(); + + // switch to Puppeteer + const metrics = await browser.call(async () => { + const pages = await puppeteerBrowser.pages(); + + await pages[0].setGeolocation({ latitude: 59.95, longitude: 30.31667 }); + + return pages[0].metrics(); + }); + + console.log(metrics.LayoutCount); // outputs: 42 +}); +``` + +[how-to-use-cdp]: ../../../guides/how-to-use-cdp +[puppeteer]: https://pptr.dev/#?product=Puppeteer&version=v5.1.0&show=api-class-browser +[browser-call]: ../call + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/getPuppeteer), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getWindowSize.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getWindowSize.mdx new file mode 100644 index 0000000..7a31f66 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/getWindowSize.mdx @@ -0,0 +1,29 @@ +# getWindowSize + +## Overview {#overview} + +Use the `getWindowSize` command to get the size of the browser window. + +## Usage {#usage} + +```javascript +await browser.getWindowSize(); +``` + +## Usage Examples {#examples} + +```javascript +it("should return browser window size", async ({ browser }) => { + const windowSize = await browser.getWindowSize(); + + console.log(windowSize); // outputs: { width: 1280, height: 767 } +}); +``` + +## Related Commands {#related} + +- [setWindowSize](../setWindowSize) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/getWindowSize), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/keys.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/keys.mdx new file mode 100644 index 0000000..51c03fb --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/keys.mdx @@ -0,0 +1,53 @@ +# keys + +## Overview {#overview} + +Use the `keys` command to send a sequence of key presses to the active element. + +You can also use symbols like “Left Arrow” or “Right Arrow”. They will be automatically transformed to the corresponding unicode characters. You can see all supported characters [here][keyboard-actions]. + +Modifiers such as `Ctrl`, `Shift`, `Alt`, and `Meta` remain pressed until you release them by calling the function again. However, modifying clicks requires using the [performActions][perform-actions] method from the WebDriver Actions API. + +## Usage {#usage} + +```javascript +await browser.keys(value); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + + + + + +
**Name****Type****Description**
valueString or String[]The sequence of keys to type.
+ +## Usage Examples {#examples} + +```javascript +it("copies text out of active element", async ({ browser }) => { + // copy text from input element + await browser.$("#username").setValue("anonymous"); + + await browser.keys(["Meta", "a"]); + await browser.keys(["Meta", "c"]); +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/keys), from which we drew some information while writing our version. + +[keyboard-actions]: https://w3c.github.io/webdriver/#keyboard-actions +[perform-actions]: https://webdriver.io/docs/api/webdriver#performactions diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mock.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mock.mdx new file mode 100644 index 0000000..0c83283 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mock.mdx @@ -0,0 +1,139 @@ +import Admonition from "@theme/Admonition"; + +# mock + +## Overview {#overview} + +Use the `mock` command to mock the response to a request. + +You can enable mocking depending on the URL, headers, or status code. Calling the `mock` method returns a stub object that you can use to modify the response from the web resource. With the stub object, you can return a mock response or abort the request. + +There are 3 ways to modify the response: + +- return a custom JSON object (e.g., to mock an API response); +- replace the response with a local file (inject a modified JavaScript file); +- redirect to another URL and return the response from there. + + +The _mock_ command only works when using _Chrome DevTools Protocol (CDP)_. + +Read more in the section "[How to use Chrome DevTools Protocol in testplane][how-to-use-cdp]". + +Also, see the recipe "[How to intercept requests and responses][how-to-intercept-requests-and-responses]". + + + +## Usage {#usage} + +```javascript +await browser.mock(url, { method, headers, responseHeaders, postData, statusCode }); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + + + +
**Name****Type****Description**
urlStringThe URL of the request to mock.
methodString or FunctionThe HTTP method to filter the resource.
headersObject or FunctionThe request headers to filter the resource.
responseHeadersObject or FunctionThe response headers to filter the resource.
postDataString or FunctionThe request postData to filter the resource.
statusCodeNumber or FunctionThe status code to filter the resource.
+ +## Usage Examples {#examples} + +```javascript +it("should mock network resources", async ({ browser }) => { + // use a static string + const userListMock = await browser.mock("**" + "/users/list"); + + // we can also mock responses based on + // request or response headers, status code, or postData + const strictMock = await browser.mock("**", { + // mock all json responses + statusCode: 200, + headers: { "Content-Type": "application/json" }, + responseHeaders: { "Cache-Control": "no-cache" }, + postData: "foobar", + }); + + // comparator function + const apiV1Mock = await browser.mock("**" + "/api/v1", { + statusCode: statusCode => statusCode >= 200 && statusCode <= 203, + headers: headers => + headers["Authorization"] && headers["Authorization"].startsWith("Bearer "), + responseHeaders: headers => headers["Impersonation"], + postData: data => typeof data === "string" && data.includes("foo"), + }); +}); + +it("should modify API responses", async ({ browser }) => { + // filter by method + const todoMock = await browser.mock("**" + "/todos", { + method: "get", + }); + + // mock the response of the endpoint with predefined fixture + mock.respond([ + { + title: "Injected Todo", + order: null, + completed: false, + url: "http://todo-backend-express-knex.herokuapp.com/916", + }, + ]); + + // respond with a different status code or header + mock.respond( + [ + { + title: "Injected Todo", + order: null, + completed: false, + url: "http://todo-backend-express-knex.herokuapp.com/916", + }, + ], + { + statusCode: 404, + headers: { + "x-custom-header": "foobar", + }, + }, + ); +}); + +it("should modify text assets", async ({ browser }) => { + const scriptMock = await browser.mock("**" + "/script.min.js"); + scriptMock.respond("./tests/fixtures/script.js"); +}); + +it("should redirect web resources", async ({ browser }) => { + const headerMock = await browser.mock("**" + "/header.png"); + headerMock.respond("https://media.giphy.com/media/F9hQLAVhWnL56/giphy.gif"); + + const pageMock = await browser.mock("https://google.com/"); + pageMock.respond("https://webdriver.io"); + await browser.url("https://google.com"); + + console.log(await browser.getTitle()); + // outputs: "WebdriverIO · Next-gen browser and mobile automation test framework for Node.js" +}); +``` + +## Related Commands {#related} + +- [mockClearAll](../mockClearAll) +- [mockRestoreAll](../mockRestoreAll) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/mock), from which we drew some information while writing our version. + +[how-to-use-cdp]: ../../../guides/how-to-use-cdp +[how-to-intercept-requests-and-responses]: ../../../guides/how-to-intercept-requests-and-responses diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mockClearAll.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mockClearAll.mdx new file mode 100644 index 0000000..38d11d7 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mockClearAll.mdx @@ -0,0 +1,44 @@ +# mockClearAll + +## Overview {#overview} + +Use the `mockClearAll` command to reset all stored information in registered mocks. Mocks are registered using the [mock][mock] command. + +## Usage {#usage} + +```typescript +await browser.mockClearAll(); +``` + +## Usage Examples {#examples} + +```typescript +it("should clear all mocks", async ({ browser }) => { + const docMock = await browser.mock("**", { + headers: { "Content-Type": "text/html" }, + }); + const jsMock = await browser.mock("**", { + headers: { "Content-Type": "application/javascript" }, + }); + + await browser.url("http://guinea-pig.webdriver.io/"); + console.log(docMock.calls.length, jsMock.calls.length); // returns "1 4" + + await browser.url("http://guinea-pig.webdriver.io/"); + console.log(docMock.calls.length, jsMock.calls.length); // returns "2 4" (JavaScript comes from cache) + + await browser.mockClearAll(); + console.log(docMock.calls.length, jsMock.calls.length); // returns "0 0" +}); +``` + +## Related Commands {#related} + +- [mock][mock] +- [mockRestoreAll](../mockRestoreAll) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/mockClearAll), from which we drew some information while writing our version. + +[mock]: ../mock diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mockRestoreAll.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mockRestoreAll.mdx new file mode 100644 index 0000000..acbac54 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/mockRestoreAll.mdx @@ -0,0 +1,41 @@ +# mockRestoreAll + +## Overview {#overview} + +Use the `mockRestoreAll` command to restore the information and behavior in registered mocks to their original state. Mocks are registered using the [mock][mock] command. + +## Usage {#usage} + +```typescript +await browser.mockRestoreAll(); +``` + +## Usage Examples {#examples} + +```typescript +it("should restore all mocks", async ({ browser }) => { + const googleMock = await browser.mock("https://google.com/"); + googleMock.respond("https://webdriver.io"); + const wdioMock = await browser.mock("https://webdriver.io"); + wdioMock.respond("http://json.org"); + + await browser.url("https://google.com/"); + console.log(await browser.getTitle()); // JSON + + await browser.mockRestoreAll(); + + await browser.url("https://google.com/"); + console.log(await browser.getTitle()); // Google +}); +``` + +## Related Commands {#related} + +- [mock][mock] +- [mockClearAll](../mockClearAll) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/mockRestoreAll), from which we drew some information while writing our version. + +[mock]: ../mock diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/newWindow.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/newWindow.mdx new file mode 100644 index 0000000..e7ab3e8 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/newWindow.mdx @@ -0,0 +1,63 @@ +import Admonition from "@theme/Admonition"; + +# newWindow + +## Overview {#overview} + +Use the `newWindow` command to open a new window in the browser. + +This command is equivalent to the [window.open()][window-open] function. + +Note that this command will automatically switch you to the new window upon execution. + + + The _newWindow_ command does not work in mobile environments (!) + + +## Usage {#usage} + +```javascript +await browser.newWindow(url, { windowName, windowFeatures }); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + +
**Name****Type****Description**
urlStringThe URL of the website to open.
windowNameStringThe name of the new window.
windowFeaturesStringSettings for the new window, such as size, position, scrollbars, etc.
+ +## Usage Examples {#examples} + +```javascript +it("should open a new tab", async ({ browser }) => { + await browser.url("http://google.com"); + console.log(await browser.getTitle()); + // outputs: "Google" + + await browser.newWindow( + "https://webdriver.io", + "WebdriverIO window", + "width=420,height=230,resizable,scrollbars=yes,status=1", + ); + console.log(await browser.getTitle()); + // outputs: "WebdriverIO · Next-gen browser and mobile automation test framework for Node.js" + + await browser.closeWindow(); + console.log(await browser.getTitle()); + // outputs: "Google" +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/newWindow), from which we drew some information while writing our version. + +[window-open]: https://developer.mozilla.org/en-US/docs/Web/API/Window/open diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/openAndWait.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/openAndWait.mdx new file mode 100644 index 0000000..a99418a --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/openAndWait.mdx @@ -0,0 +1,72 @@ +# openAndWait + +## Overview {#overview} + +Use the `openAndWait` command to open a page and wait for it to load (based on a combination of specified factors). + +Functions for waiting for network idle and failing on network errors are only available when using browsers that support _Chrome DevTools Protocol (CDP)_. + +## Usage {#usage} + +```javascript +await browser.openAndWait("some/url", { + selector: [".some", ".selector"], + predicate: () => document.isReady, + ignoreNetworkErrorsPatterns: ["https://mc.yandex.ru", "https://avatars.mds.yandex.net/*"], + waitNetworkIdle: true, + waitNetworkIdleTimeout: 500, + failOnNetworkError: true, + timeout: 20000, +}); +``` + +## Command Parameters {#parameters} + + + + + + + + + + +
**Name****Type****Description**
urlStringThe page URL.
WaitOptsObjectPage waiting parameters. Optional, as are all its fields.
+ +### WaitOpts + + + + + + + + + + + + + + + + +
**Name****Type****Description**
selectorString\|String[]Selector(s) of element(s) that must exist on the loaded page.
predicate() => Promise<bool> \| boolPredicate that returns `true` if the page is loaded. Executed in the browser context: [waitUntil](https://webdriver.io/docs/api/element/waitUntil).
waitNetworkIdleBooleanIf `true`, waits for the completion of all network requests. Default is `true`. Only works in CDP browsers; ignored for others.
waitNetworkIdleTimeoutNumberTime (in milliseconds) after the completion of all network requests to consider the network idle. Default is 500.
failOnNetworkErrorBooleanWhether to throw an error on network errors. Default is `true`. Only works in CDP browsers; ignored for others.
shouldThrowError(match) => BooleanPredicate that should return `true` by [Match](https://webdriver.io/docs/api/mock#match) if the network error is considered critical for proper page loading. By default, returns `true` for images, styles, and fonts.
ignoreNetworkErrorsPatternsArray<String \| RegExp>Patterns of resource URLs for which load success checks are ignored. Takes precedence over `shouldThrowError`.
timeoutNumberPage load timeout. By default, the `pageLoadTimeout` value is used. An exception is thrown if selectors still do not exist or the predicate still resolves to `false` after the time has elapsed.
+ +## Usage Examples {#examples} + +```javascript +it("some test", async ({ browser }) => { + // With `waitNetworkIdle` also wait for loading images, fonts, styles, ignoring metric errors + await browser.openAndWait("some/url", { + selector: [".selector"], + predicate: () => document.isReady, + ignoreNetworkErrorsPatterns: ["https://mc.yandex.ru"], + waitNetworkIdle: true, + waitNetworkIdleTimeout: 500, + failOnNetworkError: true, + timeout: 20000, + }); + + await browser.assertView("plain", ".selector"); +}); +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/overwriteCommand.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/overwriteCommand.mdx new file mode 100644 index 0000000..4ee162f --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/overwriteCommand.mdx @@ -0,0 +1,61 @@ +import Admonition from "@theme/Admonition"; + +# overwriteCommand + +## Overview {#overview} + +Use the `overwriteCommand` command to override existing commands of the browser or an element. + + + Also see the recipe "[How to add custom commands][how-to-add-custom-commands]". + + +## Usage {#usage} + +```javascript +await browser.overwriteCommand(name, callback, elementScope); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + +
**Name****Type****Description**
nameStringThe name of the custom command.
callbackFunctionThe function implementation of the command.
elementScopeBooleanIf the value is _true_, add the command to the element instead of the browser. Default: _false_.
+ +## Usage Examples {#examples} + +```javascript +// log the pause duration in ms before the pause and then return the value +await browser.overwriteCommand("pause", function (origPauseFunction, ms) { + console.log(`Sleeping for ${ms}`); + + origPauseFunction(ms); + + return ms; +}); + +// use the overwritten pause command +it("should use my overwrite command", async ({ browser }) => { + await browser.url("https://webdriver.io"); + + await browser.pause(1000); // outputs: "Sleeping for 1000" +}); +``` + +## Related Commands {#related} + +- [addCommand](../addCommand) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/overwriteCommand), from which we drew some information while writing our version. + +[how-to-add-custom-commands]: https://webdriver.io/docs/customcommands/#adding-custom-commands diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/pause.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/pause.mdx new file mode 100644 index 0000000..1dcbc36 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/pause.mdx @@ -0,0 +1,49 @@ +import Admonition from "@theme/Admonition"; + +# pause + +## Overview {#overview} + +Use the `pause` command to halt the execution of the test for a specified period of time. + + + It is not recommended to use this command for waiting for an element to appear. To avoid false + test results, it's better to use commands like [waitForExist][wait-for-exist] or other + _waitFor*_ commands. + + +## Usage {#usage} + +```javascript +await browser.pause(milliseconds); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
millisecondsNumberTime in milliseconds.
+ +## Usage Examples {#examples} + +```javascript +it("should pause the execution", async ({ browser }) => { + const starttime = new Date().getTime(); + await browser.pause(3000); + const endtime = new Date().getTime(); + + console.log(endtime - starttime); // outputs: 3000 +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/pause), from which we drew some information while writing our version. + +[wait-for-exist]: ../../element/waitForExist diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reactDollar.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reactDollar.mdx new file mode 100644 index 0000000..d92be12 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reactDollar.mdx @@ -0,0 +1,80 @@ +import Admonition from "@theme/Admonition"; + +# react$ + +## Overview {#overview} + +Use the `react$` command to find React components on the page by their actual name, while filtering them by props and state. + + +The _react$_ command only works in applications that use _React v16.x._ + +Read more about React selectors in the recipe "[How to use selectors][how-to-use-selectors]". + + + +## Usage {#usage} + +```javascript +await browser.react$(reactComponentSelector, { props, state }); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + +
**Name****Type****Description**
reactComponentSelectorStringThe React component selector.
propsObjectReact properties the component should have.
stateAny or Any[]React state the component should be in.
+ +## Usage Examples {#examples} + +```javascript +it("should calculate 7 * 6", async ({ browser }) => { + await browser.url("https://ahfarmer.github.io/calculator/"); + + await browser + .react$("t", { + props: { name: "7" }, + }) + .click(); + + await browser + .react$("t", { + props: { name: "x" }, + }) + .click(); + + await browser + .react$("t", { + props: { name: "6" }, + }) + .click(); + + await browser + .react$("t", { + props: { name: "=" }, + }) + .click(); + + console.log(await browser.$(".component-display").getText()); // outputs: "42" +}); +``` + +## Related Commands {#related} + +- [browser.react$$](../reactDollarDollar) +- [element.react$](../../element/reactDollar) +- [element.react$$](../../element/reactDollarDollar) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/react$), from which we drew some information while writing our version. + +[how-to-use-selectors]: https://webdriver.io/docs/selectors diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reactDollarDollar.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reactDollarDollar.mdx new file mode 100644 index 0000000..a97b712 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reactDollarDollar.mdx @@ -0,0 +1,61 @@ +import Admonition from "@theme/Admonition"; + +# react$$ + +## Overview {#overview} + +Use the `react$$` command to find multiple React components on the page by their actual name, while filtering them by props and state. + + +The _react$_ command only works in applications that use _React v16.x._ + +Read more about React selectors in the recipe "[How to use selectors][how-to-use-selectors]". + + + +## Usage {#usage} + +```javascript +await browser.react$$(reactComponentSelector, { props, state }); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + +
**Name****Type****Description**
reactComponentSelectorStringThe React component selector.
propsObjectReact properties the component should have.
stateAny or Any[]React state the component should be in.
+ +## Usage Examples {#examples} + +```javascript +it("should calculate 7 * 6", async ({ browser }) => { + await browser.url("https://ahfarmer.github.io/calculator/"); + + const orangeButtons = await browser.react$$("t", { + props: { orange: true }, + }); + + console.log(await Promise.all(orangeButtons.map(btn => btn.getText()))); + // outputs: "[ '÷', 'x', '-', '+', '=' ]" +}); +``` + +## Related Commands {#related} + +- [browser.react$](../reactDollar) +- [element.react$](../../element/reactDollar) +- [element.react$$](../../element/reactDollarDollar) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/react$$), from which we drew some information while writing our version. + +[how-to-use-selectors]: https://webdriver.io/docs/selectors diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reloadSession.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reloadSession.mdx new file mode 100644 index 0000000..a089b60 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/reloadSession.mdx @@ -0,0 +1,29 @@ +# reloadSession + +## Overview {#overview} + +Use the `reloadSession` command to create a new Selenium session with the current capabilities. + +This command can be useful if you are testing an application with many states and need to clear the browser session between individual tests in a single file, to avoid creating hundreds of separate test files with WDIO. However, be cautious, as this command significantly impacts testing time since creating new Selenium sessions is time-consuming, especially when using cloud services. + +## Usage {#usage} + +```javascript +await browser.reloadSession(); +``` + +## Usage Examples {#examples} + +```javascript +it("should reload my session with current capabilities", async ({ browser }) => { + console.log(browser.sessionId); // outputs: e042b3f3cd5a479da4e171825e96e655 + + await browser.reloadSession(); + + console.log(browser.sessionId); // outputs: 9a0d9bf9d4864160aa982c50cf18a573 +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/reloadSession), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/savePDF.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/savePDF.mdx new file mode 100644 index 0000000..882452d --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/savePDF.mdx @@ -0,0 +1,63 @@ +# savePDF + +## Overview {#overview} + +Use the `savePDF` command to save the current browser context to a PDF file. + +## Usage {#usage} + +```javascript +await browser.savePDF(filepath, { + orientation, + scale, + background, + width, + height, + top, + bottom, + left, + right, + shrinkToFit, + pageRanges, +}); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + + + + + + + + + +
**Name****Type****Description**
filepathStringPath to the PDF file relative to the execution directory (the _.pdf_ extension is mandatory).
orientationStringOrientation of the PDF page.
scaleNumberScale of the PDF page.
backgroundBooleanInclude the background in the PDF.
widthNumberWidth of the PDF page.
heightNumberHeight of the PDF page.
topNumberTop margin of the PDF page.
bottomNumberBottom margin of the PDF page.
leftNumberLeft margin of the PDF page.
rightNumberRight margin of the PDF page.
shrinkToFitNumberShrink the page to fit the PDF page size.
pageRangesObject[]Range of pages to include in the PDF.
+ +## Usage Examples {#examples} + +```javascript +it("should save a PDF screenshot of the browser view", async ({ browser }) => { + await browser.savePDF("./some/path/screenshot.pdf"); +}); +``` + +## Related Commands {#related} + +- [saveRecordingScreen](../saveRecordingScreen) +- [saveScreenshot](../saveScreenshot) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/savePDF), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/saveRecordingScreen.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/saveRecordingScreen.mdx new file mode 100644 index 0000000..bd65754 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/saveRecordingScreen.mdx @@ -0,0 +1,52 @@ +import Admonition from "@theme/Admonition"; + +# saveRecordingScreen + +## Overview {#overview} + +Use the `saveRecordingScreen` command to save a video to a file that was started with the [startRecordingScreen][start-recording-screen] command. + + + The _saveRecordingScreen_ command is only supported for mobile sessions that use + [Appium][appium]. + + +## Usage {#usage} + +```javascript +await browser.saveRecordingScreen(filepath); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
filepathStringFull or relative path to the video file from the execution directory.
+ +## Usage Examples {#examples} + +```javascript +it("should save a video", async ({ browser }) => { + await browser.startRecordingScreen(); + await browser.$("~BUTTON").click(); + await browser.saveRecordingScreen("./some/path/video.mp4"); +}); +``` + +## Related Commands {#related} + +- [savePDF](../savePDF) +- [saveScreenshot](../saveScreenshot) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/saveRecordingScreen), from which we drew some information while writing our version. + +[start-recording-screen]: https://webdriver.io/docs/api/appium/#startrecordingscreen +[appium]: http://appium.io/docs/en/commands/device/recording-screen/start-recording-screen/ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/saveScreenshot.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/saveScreenshot.mdx new file mode 100644 index 0000000..144db5a --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/saveScreenshot.mdx @@ -0,0 +1,46 @@ +# saveScreenshot + +## Overview {#overview} + +Use the `saveScreenshot` command to save a screenshot of the current browser context to a PNG file. + +Keep in mind that some browser drivers capture screenshots of the entire document (e.g., the [Gecko driver][gecko] for Firefox), while others capture only the current viewport (e.g., [Chromedriver][chromedriver] for Chrome). + +## Usage {#usage} + +```javascript +await browser.saveScreenshot(filepath); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
filepathStringThe path to the screenshot relative to the execution directory (the _.png_ extension is mandatory).
+ +## Usage Examples {#examples} + +```javascript +it("should save a screenshot of the browser view", async ({ browser }) => { + await browser.saveScreenshot("./some/path/screenshot.png"); +}); +``` + +## Related Commands {#related} + +- [browser.savePDF](../savePDF) +- [browser.saveRecordingScreen](../saveRecordingScreen) +- [element.saveScreenshot](../../element/saveScreenshot) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/saveScreenshot), from which we drew some information while writing our version. + +[gecko]: https://github.com/mozilla/geckodriver +[chromedriver]: https://chromedriver.chromium.org/ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/scroll.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/scroll.mdx new file mode 100644 index 0000000..768ff11 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/scroll.mdx @@ -0,0 +1,44 @@ +# scroll + +## Overview {#overview} + +Use the `scroll` command to scroll the browser viewport. Note that the `x` and `y` coordinates refer to the current scrolling position of the viewport. + +## Usage {#usage} + +```typescript +await browser.scroll(x, y); +``` + +## Command Parameters {#parameters} + + + + + + + + + + +
**Name****Type****Description**
xNumberOptional parameter. The x-coordinate to scroll to. Default: _0_.
yNumberOptional parameter. The y-coordinate to scroll to. Default: _0_.
+ +## Usage Examples {#examples} + +```typescript +it("should demonstrate the scroll command", async ({ browser }) => { + await browser.url("https://webdriver.io"); + + console.log(await browser.execute(() => window.scrollY)); // returns 0 + await browser.scroll(0, 200); + console.log(await browser.execute(() => window.scrollY)); // returns 200 +}); +``` + +## Related Commands {#related} + +- [element.scrollIntoView](../../element/scrollIntoView) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/scroll), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setCookies.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setCookies.mdx new file mode 100644 index 0000000..07a0e01 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setCookies.mdx @@ -0,0 +1,97 @@ +# setCookies + +## Overview {#overview} + +Use the `setCookies` command to set cookies on the current page. + +Make sure you are on the page for which you want to set the cookies. You cannot set cookies for an arbitrary page without being on it. + +## Usage {#usage} + +```javascript +await browser.setCookies(cookies); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
cookiesWebDriver.Cookie or WebDriver.Cookie[]A cookie object or an array of cookie objects.
+ +### WebDriver.Cookie Object Parameters + + + + + + + + + + + + + + + + +
**Name****Type****Default****Description**
nameString_N/A_The name of the cookie.
valueString_N/A_The value of the cookie.
pathString"/"The path of the cookie.
domainString_see description_The domain the cookie is visible to. If omitted, defaults to the domain of the current document's URL in the browser context.
secureBooleanfalseThe secure flag of the cookie.
httpOnlyBooleanfalseThe HTTP-only flag of the cookie.
expiryNumber_not set_The expiry date of the cookie as the number of seconds since the Unix epoch.
sameSiteString"None"The SameSite attribute of the cookie. Valid values are _"Lax"_ or _"Strict"_.
+ +## Usage Examples {#examples} + +```javascript +it("should set a cookie for the page", async ({ browser }) => { + await browser.url("/"); + + // set a single cookie + await browser.setCookies({ + name: "test1", + value: "one", + // Optional parameters: + // cookie path, defaults to "/" + // path: '/foo', + // domain the cookie is visible to + // defaults to domain of the current document's URL in the browser context + // domain: '.example.com', + // secure cookie flag, defaults to false + // secure: true, + // HTTP-only cookie flag, defaults to false + // httpOnly: true, + // expiry date of the cookie in seconds since the Unix epoch + // expiry: 1551393875 + }); + + // set multiple cookies + await browser.setCookies([ + { name: "test2", value: "two" }, + { name: "test3", value: "three" }, + ]); + + const cookies = await browser.getCookies(); + + await console.log(cookies); + // outputs: + // [ + // { name: 'test1', value: 'one', domain: 'www.example.com' }, + // { name: 'test2', value: 'two', domain: 'www.example.com' }, + // { name: 'test3', value: 'three', domain: 'www.example.com' } + // ] +}); +``` + +## Related Commands {#related} + +- [getCookies](../getCookies) +- [deleteCookies](../deleteCookies) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/setCookies), from which we drew some information while writing our version. + +[same-site]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setMeta.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setMeta.mdx new file mode 100644 index 0000000..d6c7f91 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setMeta.mdx @@ -0,0 +1,57 @@ +import Admonition from "@theme/Admonition"; + +# setMeta + +## Overview + +Use the `setMeta` command to write a value under a specified key in the test's metadata. + +To read the metadata, use the [getMeta](../getMeta) command. + + + This command is implemented within testplane and is not available in the [API + WebDriverIO][webdriverio-api]. + + +## Usage {#usage} + +```javascript +await browser.setMeta(key, value); +``` + +## Command Parameters {#parameters} + + + + + + + + + + +
**Name****Type****Description**
keyStringThe key whose value needs to be written in the test's metadata.
valueStringThe value to be saved in the test's metadata.
+ +## Usage Examples {#examples} + +```javascript +it("should get meta info of test", async ({ browser }) => { + await browser.setMeta("foo", "bar"); + await browser.url("/foo/bar?baz=qux"); + + const val = await browser.getMeta("foo"); + console.log(val); // outputs: bar + + const url = await browser.getMeta("url"); + console.log(url); // outputs: /foo/bar?baz=qux + + const meta = await browser.getMeta(); + console.log(meta); // outputs: {foo: 'bar', url: '/foo/bar?baz=qux'} +}); +``` + +## Related Commands {#related} + +- [getMeta](../getMeta) + +[webdriverio-api]: https://webdriver.io/docs/api diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setTimeout.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setTimeout.mdx new file mode 100644 index 0000000..e7d08a0 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setTimeout.mdx @@ -0,0 +1,49 @@ +# setTimeout + +## Overview {#overview} + +Use the `setTimeout` command to set timeouts for element searches on the page, document load waits, and script executions through the [execute][execute] or [executeAsync][execute-async] commands. + +## Usage {#usage} + +```javascript +await browser.setTimeout({ implicit, pageLoad, script }); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + +
**Name****Type****Description**
implicitNumberTime in milliseconds for retrying element location when searching for an element.
pageLoadNumberTime to wait for the document to load, in milliseconds.
scriptNumberTimeout for scripts run using [execute][execute] or [executeAsync][execute-async], in milliseconds.
+ +## Usage Examples {#examples} + +```javascript +it("should change timeout duration for session with long code duration", async ({ browser }) => { + await browser.setTimeout({ + pageLoad: 10000, + script: 60000, + }); + + // execute code that takes a long time + await browser.executeAsync(done => { + console.log("Wake me up before you go!"); + setTimeout(done, 59000); + }); +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/setTimeout), from which we drew some information while writing our version. + +[execute]: ../execute +[execute-async]: ../executeAsync diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setWindowSize.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setWindowSize.mdx new file mode 100644 index 0000000..9144891 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setWindowSize.mdx @@ -0,0 +1,32 @@ +# setWindowSize + +## Overview {#overview} + +Use the `setWindowSize` command to change the outer size of the browser window to the specified width and height. + +## Usage {#usage} + +```javascript +await browser.setWindowSize(width, height); +``` + +## Command Parameters {#parameters} + + + + + + + + + + +
**Name****Type****Description**
widthNumberThe width of the browser window to set.
heightNumberThe height of the browser window to set.
+ +## Related Commands {#related} + +- [getWindowSize](../getWindowSize) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/setWindowSize), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchWindow.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchWindow.mdx new file mode 100644 index 0000000..4eb9a90 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchWindow.mdx @@ -0,0 +1,45 @@ +# switchWindow + +## Overview {#overview} + +Use the `switchWindow` command to focus on a specific tab or window. + +## Usage {#usage} + +```javascript +await browser.switchWindow(urlOrTitleToMatch); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
urlOrTitleToMatchString or RegExpA string or regular expression matching the page's title or URL.
+ +## Usage Examples {#examples} + +```javascript +it("should switch to another window", async ({ browser }) => { + // open URL + await browser.url("https://google.com"); + + // create a new window + await browser.newWindow("https://webdriver.io"); + + // switch back by matching the URL + await browser.switchWindow("google.com"); + + // switch again by matching the page title + await browser.switchWindow("Next-gen browser and mobile automation test framework for Node.js"); +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/switchWindow), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/throttle.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/throttle.mdx new file mode 100644 index 0000000..e512387 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/throttle.mdx @@ -0,0 +1,73 @@ +import Admonition from "@theme/Admonition"; + +# throttle + +## Overview {#overview} + +Use the `throttle` command to simulate different types of network connections for the user. + +This command allows you to model the behavior of a website or web application under various network bandwidth conditions. + +There are also many presets with ready-made network configuration settings. For example: + +- offline | online +- GPRS +- Regular2G | Good2G +- Regular3G | Good3G +- Regular4G +- DSL +- WiFi + + +The _throttle_ command only works when using the _Chrome DevTools Protocol (CDP)_. + +Read more in the section "[How to use Chrome DevTools Protocol in testplane][how-to-use-cdp]". + +Also, see the recipe "[How to manage network bandwidth][how-to-manage-network-bandwidth]". + + + +## Usage {#usage} + +```javascript +await browser.throttle({ offline, latency, downloadThroughput, uploadThroughput }); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + +
**Name****Type****Description**
offlineBooleanEnable emulation of a loss of connection.
latencyNumberMinimum latency from the sent request to received response headers, in milliseconds.
downloadThroughputNumberMaximum total download throughput (bytes/sec). _-1_ disables download throttling.
uploadThroughputNumberMaximum total upload throughput (bytes/sec). _-1_ disables upload throttling.
+ +## Usage Examples {#examples} + +```javascript +it("should throttle the network", async ({ browser }) => { + // use a preset + await browser.throttle("Regular 3G"); + + // configure the network settings manually + await browser.throttle({ + offline: false, + downloadThroughput: (200 * 1024) / 8, + uploadThroughput: (200 * 1024) / 8, + latency: 20, + }); +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/throttle), from which we drew some information while writing our version. + +[how-to-use-cdp]: ../../../guides/how-to-use-cdp +[how-to-manage-network-bandwidth]: ../../../guides/how-to-manage-network-bandwidth diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/touchAction.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/touchAction.mdx new file mode 100644 index 0000000..fe5850f --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/touchAction.mdx @@ -0,0 +1,90 @@ +import Admonition from "@theme/Admonition"; + +# touchAction + +## Overview {#overview} + +Use the `touchAction` command to perform gestures in mobile platform tests. + +The command allows chaining separate ad hoc actions, which will then be applied to the application element on the device. + +The main actions you can use are: + +- **press** — requires an element or coordinates (x, y), or both +- **longPress** — requires an element or coordinates (x, y), or both +- **tap** — requires an element or coordinates (x, y), or both +- **moveTo** — requires absolute coordinates (x, y) +- **wait** — requires time in milliseconds +- **release** — no parameters needed + + + Currently, the _touchAction_ command is only available for native apps and cannot be used to + interact with web apps. + + +## Usage {#usage} + +```javascript +await browser.touchAction(action); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
actionObjectThe action to perform.
+ +## Usage Examples {#examples} + +```javascript +it("should do a touch gesture", async ({ browser }) => { + const screen = await browser.$("//UITextbox"); + + // simple touch action on element + await browser.touchAction({ + action: "tap", + element: screen, + }); + + // simple touch action with x and y coordinates + // touch coordinates are 30px right and 20px down from the viewport + await browser.touchAction({ + action: "tap", + x: 30, + y: 20, + }); + + // simple touch action with x and y coordinates + // touch coordinates are 30px right and 20px down from the element center + await browser.touchAction({ + action: "tap", + x: 30, + y: 20, + element: screen, + }); + + // multi action on element + // drag&drop from point (200, 200) down by 100px on the screen + await browser.touchAction([ + { action: "press", x: 200, y: 200 }, + { action: "moveTo", x: 200, y: 300 }, + "release", + ]); +}); +``` + +## Related Commands {#related} + +- [element.touchAction](../../element/touchAction) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/touchAction), from which we drew some information while writing our version. + +[ad-hoc]: https://en.wikipedia.org/wiki/Ad_hoc diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/uploadFile.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/uploadFile.mdx new file mode 100644 index 0000000..ea77b00 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/uploadFile.mdx @@ -0,0 +1,55 @@ +import Admonition from "@theme/Admonition"; + +# uploadFile + +## Overview {#overview} + +Use the `uploadFile` command to upload a file to a _[Selenium Standalone][selenium-file]_ server or to the browser via its driver (e.g., [Chromedriver][chromedriver]). + + + The _uploadFile_ command is only supported when using [Selenium Grid][selenium-grid] or + [Chromedriver][chromedriver]. This is because it uses an unofficial protocol feature that is + currently implemented only in _Chrome_ and when running on [Selenium Grid][selenium-grid]. + + +## Usage {#usage} + +```javascript +await browser.uploadFile(localPath); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
localPathStringThe path to the local file.
+ +## Usage Examples {#examples} + +```javascript +const path = require("path"); + +it("should upload a file", async ({ browser }) => { + await browser.url("https://the-internet.herokuapp.com/upload"); + + const filePath = "/path/to/some/file.png"; + const remoteFilePath = await browser.uploadFile(filePath); + + await browser.$("#file-upload").setValue(remoteFilePath); + await browser.$("#file-submit").click(); +}); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/uploadFile), from which we drew some information while writing our version. + +[selenium-grid]: https://www.selenium.dev/documentation/grid/ +[selenium-file]: https://webdriver.io/docs/api/selenium/#file +[chromedriver]: https://chromedriver.chromium.org/ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/url.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/url.mdx new file mode 100644 index 0000000..7d07423 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/url.mdx @@ -0,0 +1,63 @@ +# url + +## Overview {#overview} + +Use the `url` command to navigate to the specified URL in the browser. + +If [baseUrl][base-url] is specified in the configuration, it will be added to the `url` parameter using the Node.js method [url.resolve()][url-resolve]. + +Calling `browser.url()` with the same URL as before will reload the page. + +## Usage {#usage} + +```javascript +await browser.url(url); +``` + +## Command Parameters {#parameters} + + + + + + + + + +
**Name****Type****Description**
urlStringThe URL to open.
+ +## Usage Examples {#examples} + +**url.js** + +```javascript +// navigate to URL +await browser.url("https://webdriver.io"); + +// get the URL +console.log(await browser.getUrl()); // outputs: "https://webdriver.io" +``` + +**baseUrlResolutions.js** + +```javascript +// Let baseUrl = http://example.com/site + +// Specifying a full URL results in https://webdriver.io +await browser.url("https://webdriver.io"); + +// Specifying a URL without a leading slash +// results in the URL relative to the baseUrl: http://example.com/site/relative +await browser.url("relative"); + +// Specifying a URL with a leading slash +// results in the URL relative to the root of baseUrl: http://example.com/rootRelative +await browser.url("/rootRelative"); +``` + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/url), from which we drew some information while writing our version. + +[base-url]: ../../../config/browsers#base_url +[url-resolve]: https://nodejs.org/api/url.html#urlresolvefrom-to diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/waitUntil.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/waitUntil.mdx new file mode 100644 index 0000000..77b2553 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/waitUntil.mdx @@ -0,0 +1,61 @@ +# waitUntil + +## Overview {#overview} + +Use the `waitUntil` command to wait for a specific condition to be met on the page in the browser. + +## Usage {#usage} + +```javascript +await browser.waitUntil(condition, { timeout, timeoutMsg, interval }); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + +
**Name****Type****Default****Description**
conditionFunction_N/A_The condition to wait for.
timeoutNumber5000Timeout in milliseconds.
timeoutMsgString_N/A_Error message to throw when the timeout is reached.
intervalNumber500Interval in milliseconds between condition checks.
+ +## Usage Examples {#examples} + +**example.html** + +```javascript +
I am some text
+ +``` + +**waitUntil.js** + +```javascript +it("should wait until text has changed", async ({ browser }) => { + await browser.waitUntil( + async () => (await browser.$("#someText").getText()) === "I am now different", + { + timeout: 5000, + timeoutMsg: "expected text to be different after 5s", + }, + ); +}); +``` + +## Related Commands {#related} + +- [element.waitUntil](../../element/waitUntil) + +## References + +We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/browser/waitUntil), from which we drew some information while writing our version. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/quickstart/index.mdx b/i18n/en/docusaurus-plugin-content-docs/current/quickstart/index.mdx new file mode 100644 index 0000000..15dc02d --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/quickstart/index.mdx @@ -0,0 +1,104 @@ +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Quick Start + +## Installation {#install} + +Run the testplane installer using `npm`. + +```bash +npm init testplane@latest YOUR_PROJECT_PATH +``` + +If you do not want to use the defaults when initializing the project and want to configure it using a wizard, specify the `-v` option. + +## Setup {#setup} + +After executing the command mentioned above, a `.testplane.conf.js` file with basic settings will be generated at the root of the project. Depending on which protocol you want to use, there are 2 configuration options (by default, the CDP protocol will be specified for the browser). + + + +```javascript +module.exports = { + sets: { + desktop: { + files: 'tests/desktop' + } + }, + + browsers: { + chrome: { + automationProtocol: 'devtools', + desiredCapabilities: { + browserName: 'chrome' + } + } + } + +}; + +```` + + + + +```javascript +module.exports = { + gridUrl: 'http://localhost:4444/wd/hub', + + sets: { + desktop: { + files: 'tests/desktop' + } + }, + + browsers: { + chrome: { + automationProtocol: 'webdriver', // default value + desiredCapabilities: { + browserName: 'chrome' + } + } + } +}; +```` + + + + + +## Creating a Test {#test_creation} + +Navigate to the `tests/example.testplane.js` file with a test. Here you can see a test example or write your own. For example, + +```javascript +describe("github", async function () { + it("should find testplane", async function ({ browser }) { + await browser.url("https://github.com/gemini-testing/testplane"); + const elem = await browser.$("#readme h1"); + + await expect(elem).toHaveText("Testplane"); + }); +}); +``` + +## Running a Test {#test_running} + +Now you can run the tests: + +```bash +npx testplane +``` + +or launch the GUI mode and run the test through the browser interface + +```bash +npx testplane gui +``` + +If you chose the `WebDriver protocol` during the config setup, you should have `selenium-standalone` running (in a separate tab) before running the tests: + +```bash +selenium-standalone start +```