docs: add en versions of element commands (#18)

gemini-testing · Jul 18, 2024 · a93f786 · a93f786
1 parent ef4f5be
commit a93f786
Show file tree

Hide file tree

Showing 47 changed files with 2,737 additions and 0 deletions.
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/element/$$.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/element/$$.mdx
@@ -0,0 +1,98 @@
+---
+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 within the scope of an element. This command is similar to the [browser.$$()](../../browser/_dollardollar) command but differs in that the search for elements will be among the children of the current element.
+
+<Admonition type="info">
+    Read more about how to select specific elements in the recipe "[How to use
+    selectors][how-to-use-selectors]".
+</Admonition>
+
+## Usage {#usage}
+
+```javascript
+await browser.$(selector).$$(subSelector);
+```
+
+## Command Parameters {#parameters}
+
+<table>
+<thead>
+<tr><td>**Name**</td><td>**Type**</td><td>**Description**</td></tr>
+</thead>
+<tbody>
+<tr><td>subSelector</td><td>String or Function or Matcher</td><td>Selector, JS function, or Matcher object to get multiple elements.</td></tr>
+
+</tbody>
+</table>
+
+## Usage Examples {#examples}
+
+**index.html**
+
+```html
+<ul id="menu">
+    <li>
+        <a href="/">Home</a>
+    </li>
+    <li>
+        <a href="/">Developer Guide</a>
+    </li>
+    <li>
+        <a href="/">API</a>
+    </li>
+    <li>
+        <a href="/">Contribute</a>
+    </li>
+</ul>
+```
+
+**$$.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.$("#menu");
+
+    console.log(
+        await text
+            .$$(function () {
+                // Arrow function cannot be used here.
+                // This is Element – https://developer.mozilla.org/en-US/docs/Web/API/Element
+                // in this specific example – this is HTMLUListElement
+                //
+                // TypeScript users can do something like:
+                // return (this as Element).querySelector('li')
+                return this.querySelectorAll("li"); // Element[]
+            })[2]
+            .$("a")
+            .getText(),
+    ); // outputs: "API"
+});
+```
+
+## Related Commands
+
+-   [element.$](../_dollar)
+-   [browser.$](../../browser/_dollar)
+-   [browser.$$](../../browser/_dollardollar)
+
+## References
+
+We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/element/$$), 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/element/$.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/element/$.mdx
@@ -0,0 +1,123 @@
+---
+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 do 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 then converts the reference into an extended WebdriverIO element. Note: Use these element objects only if you are certain they exist on the page. This can be verified, for example, using the [isExisting](../isExisting) command.
+
+You can chain `$` or `$$` together to navigate down the DOM tree. But note that chaining `$` and `$$` commands makes sense only when using multiple selector strategies. Otherwise, you will be making unnecessary requests that will slow down the test (e.g., `$('body').$('div')` creates two requests, whereas `$('body div')` does the same in one request).
+
+<Admonition type="info">
+    Read more about how to select specific elements in the recipe "[How to use
+    selectors][how-to-use-selectors]".
+</Admonition>
+
+## Usage {#usage}
+
+```javascript
+await browser.$(selector);
+```
+
+## Command Parameters {#parameters}
+
+<table>
+<thead>
+<tr><td>**Name**</td><td>**Type**</td><td>**Description**</td></tr>
+</thead>
+<tbody>
+<tr><td>selector</td><td>String or Function or Matcher</td><td>Selector, JS function, or Matcher object to get a specific element.</td></tr>
+
+</tbody>
+</table>
+
+## Usage Examples {#examples}
+
+**index.html**
+
+```html
+<ul id="menu">
+    <li>
+        <a href="/">Home</a>
+    </li>
+    <li>
+        <a href="/">Developer Guide</a>
+    </li>
+    <li>
+        <a href="/">API</a>
+    </li>
+    <li>
+        <a href="/">Contribute</a>
+    </li>
+</ul>
+```
+
+```javascript
+it("should get text of a menu link - JS Function", async ({ browser }) => {
+    const text = await browser.$("#menu");
+
+    console.log(
+        await text
+            .$$("li")[2]
+            .$(function () {
+                // Arrow function cannot be used here.
+                // This is Element – https://developer.mozilla.org/en-US/docs/Web/API/Element
+                // in this specific example – this is HTMLLIElement
+                //
+                // TypeScript users can do something like:
+                // return (this as Element).querySelector('a')
+                return this.querySelector("a"); // Element
+            })
+            .getText(),
+    ); // outputs: "API"
+});
+
+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 allow to convert 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 Android's 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}
+
+-   [element.$$](../_dollardollar)
+-   [browser.$](../../browser/_dollar)
+-   [browser.$$](../../browser/_dollardollar)
+
+## References
+
+We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/element/$), 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/element/addValue.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/element/addValue.mdx
@@ -0,0 +1,46 @@
+# addValue
+
+## Overview {#overview}
+
+Use the `addValue` command to add a value to an `<input>` or `<textarea>` element.
+
+## Usage {#usage}
+
+```javascript
+await browser.$(selector).addValue(value);
+```
+
+## Command Parameters {#parameters}
+
+<table>
+<thead>
+<tr><td>**Name**</td><td>**Type**</td><td>**Description**</td></tr>
+</thead>
+<tbody>
+<tr><td>value</td><td>String or Number</td><td>The value to add.</td></tr>
+
+</tbody>
+</table>
+
+## Usage Examples {#examples}
+
+```javascript
+it("should demonstrate the addValue command", async ({ browser }) => {
+    let input = await browser.$(".input");
+    await input.addValue("test");
+    await input.addValue(123);
+
+    value = await input.getValue();
+    assert.equal(value, "test123"); // true
+});
+```
+
+## Related Commands {#related}
+
+-   [element.clearValue](../clearValue)
+-   [element.setValue](../setValue)
+-   [browser.keys](../../browser/keys)
+
+## References
+
+We'd like to give credit to the original WebdriverIO docs [article](https://webdriver.io/docs/api/element/addValue), from which we drew some information while writing our version.