add docs for execute driver script command
ADD
commands-yml/commands/session/execute-driver.yml
+---
+name: Execute Driver Script
+short_description: Run a WebdriverIO script against the current session, allowing execution of many commands in one Appium request.
+
+description:
+ |
+ One downside of Appium's client-server architecture is that each command must travel across a network with potentially high latency. This is especially the case in situations where the Appium session takes place on a service provider's host machine rather than locally.
+
+ This command enables the batching of many commands together, to be executed in one go on the Appium server. The way this is accomplished is on the model of `executeScript`: the client will send in a string representing code to be executed. The Appium server will execute that code in the context of the current session, and return any values specified by the script.
+
+ There are three parameters accepted by this command (which may be collected by each client in its own way):
+ * `script`: the string consisting of the script itself
+ * `timeout`: a number representing the number of milliseconds to wait before killing the process running the driver script. Default is equivalent to 1 hour.
+ * `type`: a string representing the script language/API. Currently only one type, `webdriverio`, is supported (and it is the default).
+
+ Not just any code can run in this context. The code must be written in Javascript, and it will have access to a context with three objects
+ * `driver`: a [WebdriverIO](https://webdriver.io/) driver object. It may be assumed this driver has already connected with the Appium server and is ready to run commands. The version of WebdriverIO used is the one installed according to the specification in `appium-base-driver`'s `package.json` file.
+ * `console`: a custom `console` object, with methods `log`, `warn`, and `error`, so that logging may take place.
+ * `Promise`: a Promise library ([Bluebird](http://bluebirdjs.com/docs/getting-started.html)), to make asynchronous work easier.
+
+ The code will be placed inside an `async` function, as below, so you are free to use `await`:
+
+ ```js
+ (async function (driver, console, Promise) {
+ // --> your script here <--
+ })()
+ ```
+
+ Any errors will result in an error response to the call to this command. Any return values will be wrapped up and sent back to your client in the following form:
+
+ ```js
+ {result: <return value>, logs: {log: [], warn: [], error: []}}
+ ```
+
+ Using this response object you can gather the return value as well as the output of any log statements you made.
+
+ The advantage of this approach of using WebdriverIO code is that you have access to a full programming language and Appium API, and can use any language or API features you need, including loops, conditionals, and explicit waits. The WebdriverIO API cannot be enumerated here, so visit the [WebdriverIO documentation](https://webdriver.io/docs/api.html) for more info.
+
+example_usage:
+ java:
+ |
+ // TODO fill out once client code is written
+
+ python:
+ |
+ # TODO fill out once client code is written
+ javascript_wd:
+ |
+ const script = `
+ const el = await driver.$('~foo');
+ await el.click();
+ `;
+ driver.executeDriver(script, {timeout: 200});
+ javascript_wdio:
+ |
+ // TODO fill out once client code is written
+ ruby:
+ |
+ # TODO fill out once client code is written
+ ruby_core:
+ |
+ # TODO fill out once client code is written
+ php:
+ |
+ // TODO PHP sample
+ csharp:
+ |
+ // TODO C# sample
+
+client_docs:
+ java: ""
+ python: ""
+ javascript_wdio: ""
+ javascript_wd: ""
+ ruby: ""
+ ruby_core: ""
+ php: "" # TODO PHP documentation link
+ csharp: "" # TODO Dotnet documentation link
+
+# Driver support by platform
+driver_support:
+ ios:
+ xcuitest: true
+ uiautomation: true
+ android:
+ uiautomator2: true
+ espresso: true
+ uiautomator: true
+ mac:
+ mac: true
+ windows:
+ windows: true
+client_support:
+ java: false
+ python: false
+ ruby: false
+ php: false
+ csharp: false
+ javascript_wd: false
+ javascript_wdio: false
+
+
+# Information about the HTTP endpoints
+endpoint:
+ url: /wd/hub/session/:session_id/appium/execute_driver
+ method: POST
+ url_parameters:
+ - name: session_id
+ description: ID of the session to route the command to
+ json_parameters:
+ - name: script
+ type: string
+ description: The webdriverio script to execute
+ - name: type
+ type: string
+ description: The name of the script type. Currently only 'webdriverio' is supported
+ - name: timeout
+ type: number
+ description: The number of ms Appium should wait for the script to finish before killing it due to timeout
+ response:
+ - type: any
+ description: >-
+ The script result. It will have two fields: `result` and `logs`. Result will be the return value of the script. Logs will contain the content of anything logged from the `console` object by the script.
+
+# Links to specifications. Should link to at least one specification
+specifications:
+ w3c: false
+ jsonwp: false

MODIFY
docs/en/commands/mobile-command.md
docs/en/commands/mobile-command.md
@@ -104,7 +104,7 @@ List of available commands:
### Android
| Command | Description | Argument | Argument Example |
| ------- | ----------- | -------- | ---------------- |
-| mobile:shell | Execute [ADB shell](https://developer.android.com/studio/command-line/adb#shellcommands) commands (requires [server flag](/docs/en/writing-running-appium/server-args.md#server-flags) `--relaxed-security` to be set) | ADB shell string | `am start -n com.example.demo/com.example.test.MainActivity` |
+| mobile:shell | Execute [ADB shell](https://developer.android.com/studio/command-line/adb#shellcommands) commands (requires [insecure feature](/docs/en/writing-running-appium/security.md) `adb_shell` to be enabled) | ADB shell string | `am start -n com.example.demo/com.example.test.MainActivity` |
| mobile:startLogsBroadcast | Starts Android logcat broadcast websocket on the same host and port where Appium is running at `/ws/session/:sessionId:/appium/device/logcat` endpoint | <none> | <none> |
| mobile:stopLogsBroadcast | Stops the logcat broadcasting websocket server started by `mobile:startLogsBroadcast` | <none> | <none> |
| mobile:performEditorAction | Performs the given editor action on the focused input field. The following action names are supported: `normal, unspecified, none, go, search, send, next, done, previous`. | `{action}` | `{action: "previous"}`|

ADD
docs/en/commands/session/execute-driver.md
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+# Execute Driver Script
+
+Run a WebdriverIO script against the current session, allowing execution of many commands in one Appium request.
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+## Example Usage
+
+```java
+// Java
+// TODO fill out once client code is written
+
+```
+
+```python
+# Python
+# TODO fill out once client code is written
+
+```
+
+```javascript
+// Javascript
+// webdriver.io example
+// TODO fill out once client code is written
+
+// wd example
+const script = `
+ const el = await driver.$('~foo');
+ await el.click();
+`;
+driver.executeDriver(script, {timeout: 200});
+
+```
+
+```ruby
+# Ruby
+# ruby_lib example
+# TODO fill out once client code is written
+
+# ruby_lib_core example
+# TODO fill out once client code is written
+
+```
+
+```php
+# PHP
+// TODO PHP sample
+
+```
+
+```csharp
+// C#
+// TODO C# sample
+
+```
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+## Description
+
+One downside of Appium's client-server architecture is that each command must travel across a network with potentially high latency. This is especially the case in situations where the Appium session takes place on a service provider's host machine rather than locally.
+
+This command enables the batching of many commands together, to be executed in one go on the Appium server. The way this is accomplished is on the model of `executeScript`: the client will send in a string representing code to be executed. The Appium server will execute that code in the context of the current session, and return any values specified by the script.
+
+There are three parameters accepted by this command (which may be collected by each client in its own way):
+ * `script`: the string consisting of the script itself
+ * `timeout`: a number representing the number of milliseconds to wait before killing the process running the driver script. Default is equivalent to 1 hour.
+ * `type`: a string representing the script language/API. Currently only one type, `webdriverio`, is supported (and it is the default).
+
+Not just any code can run in this context. The code must be written in Javascript, and it will have access to a context with three objects
+ * `driver`: a [WebdriverIO](https://webdriver.io/) driver object. It may be assumed this driver has already connected with the Appium server and is ready to run commands. The version of WebdriverIO used is the one installed according to the specification in `appium-base-driver`'s `package.json` file.
+ * `console`: a custom `console` object, with methods `log`, `warn`, and `error`, so that logging may take place.
+ * `Promise`: a Promise library ([Bluebird](http://bluebirdjs.com/docs/getting-started.html)), to make asynchronous work easier.
+
+The code will be placed inside an `async` function, as below, so you are free to use `await`:
+
+```js
+(async function (driver, console, Promise) {
+ // --> your script here <--
+})()
+```
+
+Any errors will result in an error response to the call to this command. Any return values will be wrapped up and sent back to your client in the following form:
+
+```js
+{result: <return value>, logs: {log: [], warn: [], error: []}}
+```
+
+Using this response object you can gather the return value as well as the output of any log statements you made.
+
+The advantage of this approach of using WebdriverIO code is that you have access to a full programming language and Appium API, and can use any language or API features you need, including loops, conditionals, and explicit waits. The WebdriverIO API cannot be enumerated here, so visit the [WebdriverIO documentation](https://webdriver.io/docs/api.html) for more info.
+
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+## Support
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+### Appium Server
+
+|Platform|Driver|Platform Versions|Appium Version|Driver Version|
+|--------|----------------|------|--------------|--------------|
+| iOS | [XCUITest](/docs/en/drivers/ios-xcuitest.md) | 9.3+ | 1.6.0+ | All |
+| | [UIAutomation](/docs/en/drivers/ios-uiautomation.md) | 8.0 to 9.3 | All | All |
+| Android | [UiAutomator2](/docs/en/drivers/android-uiautomator2.md) | ?+ | 1.6.0+ | All |
+| | [Espresso](/docs/en/drivers/android-espresso.md) | ?+ | 1.9.0+ | All |
+| | [UiAutomator](/docs/en/drivers/android-uiautomator.md) | 4.2+ | All | All |
+| Mac | [Mac](/docs/en/drivers/mac.md) | ?+ | 1.6.4+ | All |
+| Windows | [Windows](/docs/en/drivers/windows.md) | 10+ | 1.6.0+ | All |
+
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+### Appium Clients
+
+|Language|Support|Documentation|
+|--------|-------|-------------|
+|[Java](https://github.com/appium/java-client/releases/latest)| None | |
+|[Python](https://github.com/appium/python-client/releases/latest)| None | |
+|[Javascript (WebdriverIO)](http://webdriver.io/index.html)| None | |
+|[Javascript (WD)](https://github.com/admc/wd/releases/latest)| None | |
+|[Ruby](https://github.com/appium/ruby_lib/releases/latest)| None | |
+|[PHP](https://github.com/appium/php-client/releases/latest)| None | |
+|[C#](https://github.com/appium/appium-dotnet-driver/releases/latest)| None | |
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+## HTTP API Specifications
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+### Endpoint
+
+`POST /wd/hub/session/:session_id/appium/execute_driver`
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+### URL Parameters
+
+|name|description|
+|----|-----------|
+|session_id|ID of the session to route the command to|
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+### JSON Parameters
+
+|name|type|description|
+|----|----|-----------|
+| script | `string` | The webdriverio script to execute |
+| type | `string` | The name of the script type. Currently only 'webdriverio' is supported |
+| timeout | `number` | The number of ms Appium should wait for the script to finish before killing it due to timeout |
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+### Response
+
+The script result. It will have two fields: `result` and `logs`. Result will be the return value of the script. Logs will contain the content of anything logged from the `console` object by the script. (`any`)
+
+[//]: # (DO NOT EDIT THIS FILE! This is an auto-generated file. Editing for this document happens in /commands-yml/commands/session/execute-driver.yml)
+## See Also
+

add docs for execute driver script command