Add docs for addLocatorStrategy (webdriverio#4960)

* add docs for addLocatorStrategy * PR feedback

Author: christian-bromann

docs/Selectors.md

@@ -424,3 +424,23 @@ browser.react$$('MyComponent') // returns the WebdriverIO Elements for the array
 ```
 
 **Note:** If you have multiple instances of `MyComponent` and you use `react$$` to select these fragment components, you will be returned an one-dimensional array of all the nodes. In other words, if you have 3 `<MyComponent />` instances, you will be returned an array with six WebdriverIO elements.
+
+## Custom Selector Strategies
+
+If your app requires a specific way to fetch elements you can define yourself a custom selector strategy that you can use with `custom$` and `custom$$`. For that register your strategy once in the beginning of the test:
+
+```js
+browser.addLocatorStrategy('myCustomStrategy', (selector) => {
+ return document.querySelectorAll(selector)
+})
+```
+
+The use it by calling:
+
+```js
+browser.url('https://webdriver.io')
+const pluginWrapper = browser.custom$$('myStrat', '.pluginWrapper')
+console.log(pluginWrapper.length) // 4
+```
+
+**Note:** this only works in an web environment in which the [`execute`](/docs/api/browser/execute.html) command can be run.

packages/wdio-reporter/README.md

@@ -20,7 +20,7 @@ Then you need to extend your reporter with the main `@wdio/reporter` class:
 ```js
 import Reporter from '@wdio/reporter'
 
-export default MyCustomeReporter extends Reporter {
+export default MyCustomReporter extends Reporter {
  constructor () {
  super()
  // your custom logic if necessary

packages/wdio-runner/src/reporter.js

@@ -149,12 +149,12 @@ export default class BaseReporter {
  * check if reporter was passed in from a file, e.g.
  *
  * ```js
- * const MyCustomeReporter = require('/some/path/MyCustomeReporter.js')
+ * const MyCustomReporter = require('/some/path/MyCustomReporter.js')
  * export.config = {
  * //...
  * reporters: [
- * MyCustomeReporter, // or
- * [MyCustomeReporter, { custom: 'option' }]
+ * MyCustomReporter, // or
+ * [MyCustomReporter, { custom: 'option' }]
  * ]
  * //...
  * }

packages/wdio-sync/webdriverio-core.d.ts

@@ -592,6 +592,14 @@ declare namespace WebdriverIO {
  func: (origCommand: Function, ...args: any[]) => any,
  attachToElement?: boolean
  ): void;
+
+ /**
+ * create custom selector
+ */
+ addLocatorStrategy(
+ name: string,
+ func: (elementFetchingMethod: (selector: string) => any) => void
+ ): void
 
  /**
  * The `$$` command is a short way to call the [`findElements`](/docs/api/webdriver.html#findelements) command in order

packages/webdriverio/webdriverio-core-v5.d.ts

@@ -592,6 +592,14 @@ declare namespace WebdriverIO {
  func: (origCommand: Function, ...args: any[]) => any,
  attachToElement?: boolean
  ): void;
+
+ /**
+ * create custom selector
+ */
+ addLocatorStrategy(
+ name: string,
+ func: (elementFetchingMethod: (selector: string) => any) => void
+ ): void
 
  /**
  * The `$$` command is a short way to call the [`findElements`](/docs/api/webdriver.html#findelements) command in order

packages/webdriverio/webdriverio-core.d.ts

@@ -592,6 +592,14 @@ declare namespace WebdriverIO {
  func: (origCommand: Function, ...args: any[]) => any,
  attachToElement?: boolean
  ): void;
+
+ /**
+ * create custom selector
+ */
+ addLocatorStrategy(
+ name: string,
+ func: (elementFetchingMethod: (selector: string) => any) => void
+ ): void
 
  /**
  * The `$$` command is a short way to call the [`findElements`](/docs/api/webdriver.html#findelements) command in order

scripts/templates/webdriverio.tpl.d.ts

@@ -248,6 +248,14 @@ declare namespace WebdriverIO {
  func: (origCommand: Function, ...args: any[]) => any,
  attachToElement?: boolean
  ): void;
+
+ /**
+ * create custom selector
+ */
+ addLocatorStrategy(
+ name: string,
+ func: (elementFetchingMethod: (selector: string) => any) => void
+ ): void
  // ... browser commands ...
  }
 

tests/typings/sync/sync.ts

@@ -92,6 +92,9 @@ browser.touchAction(touchAction)
 // dragAndDrop
 ele.dragAndDrop(ele, 0)
 
+// addLocatorStrategy
+browser.addLocatorStrategy('myStrat', () => {})
+
 // selenium-standalone-service
 const config: WebdriverIO.Config = {
  skipSeleniumInstall: true

tests/typings/webdriverio/async.ts

@@ -121,6 +121,9 @@ async function bar() {
 
  // dragAndDrop
  await ele.dragAndDrop(ele, 0)
+
+ // addLocatorStrategy
+ browser.addLocatorStrategy('myStrat', () => {})
 }
 
 // selenium-standalone-service