Add executeDriverScript command

src/main/java/io/appium/java_client/AppiumDriver.java

@@ -65,7 +65,8 @@
  */
 @SuppressWarnings("unchecked")
 public class AppiumDriver<T extends WebElement>
- extends DefaultGenericMobileDriver<T> implements ComparesImages, FindsByImage<T>, FindsByCustom<T> {
+ extends DefaultGenericMobileDriver<T> implements ComparesImages, FindsByImage<T>, FindsByCustom<T>,
+ ExecutesDriverScript {
 
  private static final ErrorHandler errorHandler = new ErrorHandler(new ErrorCodesMobile(), true);
  // frequently used command parameters

src/main/java/io/appium/java_client/ExecutesDriverScript.java

@@ -0,0 +1,71 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client;
+
+import io.appium.java_client.driverscripts.ScriptOptions;
+import io.appium.java_client.driverscripts.ScriptValue;
+import org.openqa.selenium.remote.Response;
+
+import javax.annotation.Nullable;
+import java.util.HashMap;
+import java.util.Map;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import static io.appium.java_client.MobileCommand.EXECUTE_DRIVER_SCRIPT;
+
+public interface ExecutesDriverScript extends ExecutesMethod {
+
+ /**
+ * Run a set of scripts in scope of the current session.
+ * This allows multiple web driver commands to be executed within one request
+ * and may significantly speed up the automation script performance in
+ * distributed client-server environments with high latency.
+ * Read http://appium.io/docs/en/commands/session/execute-driver for more details.
+ *
+ * @since Appium 1.14
+ * @param script the web driver script to execute (it should
+ * be a valid webdriverio code snippet by default
+ * unless another option is provided)
+ * @param options additional scripting options
+ * @return The script result
+ * @throws org.openqa.selenium.WebDriverException if there was a failure while executing the script
+ */
+ default ScriptValue executeDriverScript(String script, @Nullable ScriptOptions options) {
+ Map<String, Object> data = new HashMap<>();
+ data.put("script", checkNotNull(script));
+ if (options != null) {
+ data.putAll(options.build());
+ }
+ Response response = execute(EXECUTE_DRIVER_SCRIPT, data);
+ //noinspection unchecked
+ Map<String, Object> value = (Map<String, Object>) response.getValue();
+ //noinspection unchecked
+ return new ScriptValue(value.get("result"), (Map<String, Object>) value.get("logs"));
+ }
+
+ /**
+ * Run a set of scripts in scope of the current session with default options.
+ *
+ * @since Appium 1.14
+ * @param script the web driver script to execute (it should
+ * be a valid webdriverio code snippet)
+ * @return The script result
+ */
+ default ScriptValue executeDriverScript(String script) {
+ return executeDriverScript(script, null);
+ }
+}

src/main/java/io/appium/java_client/MobileCommand.java

@@ -110,6 +110,7 @@ public class MobileCommand {
  protected static final String TOGGLE_AIRPLANE_MODE;
  protected static final String TOGGLE_DATA;
  protected static final String COMPARE_IMAGES;
+ protected static final String EXECUTE_DRIVER_SCRIPT;
 
  public static final Map<String, CommandInfo> commandRepository;
 
@@ -184,6 +185,7 @@ public class MobileCommand {
  TOGGLE_AIRPLANE_MODE = "toggleFlightMode";
  TOGGLE_DATA = "toggleData";
  COMPARE_IMAGES = "compareImages";
+ EXECUTE_DRIVER_SCRIPT = "executeDriverScript";
 
  commandRepository = new HashMap<>();
  commandRepository.put(RESET, postC("/session/:sessionId/appium/app/reset"));
@@ -268,6 +270,7 @@ public class MobileCommand {
  commandRepository.put(TOGGLE_AIRPLANE_MODE, postC("/session/:sessionId/appium/device/toggle_airplane_mode"));
  commandRepository.put(TOGGLE_DATA, postC("/session/:sessionId/appium/device/toggle_data"));
  commandRepository.put(COMPARE_IMAGES, postC("/session/:sessionId/appium/compare_images"));
+ commandRepository.put(EXECUTE_DRIVER_SCRIPT, postC("/session/:sessionId/appium/execute_driver"));
  }
 
  /**

src/main/java/io/appium/java_client/driverscripts/ScriptOptions.java

@@ -0,0 +1,66 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.driverscripts;
+
+import com.google.common.collect.ImmutableMap;
+
+import java.util.Map;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import static java.util.Optional.ofNullable;
+
+
+public class ScriptOptions {
+ private ScriptType scriptType;
+ private Long timeoutMs;
+
+ /**
+ * Sets the script type.
+ *
+ * @param type the actual script type
+ * @return self instance for chaining
+ */
+ public ScriptOptions withScriptType(ScriptType type) {
+ this.scriptType = checkNotNull(type);
+ return this;
+ }
+
+ /**
+ * Sets the script execution timeout.
+ * If this is not set then the maximum duration of the script
+ * is not limited (e. g. may block forever).
+ *
+ * @param timeoutMs the timeout in milliseconds
+ * @return self instance for chaining
+ */
+ public ScriptOptions withTimeout(long timeoutMs) {
+ this.timeoutMs = timeoutMs;
+ return this;
+ }
+
+ /**
+ * Builds a values map for further usage in HTTP requests to Appium.
+ *
+ * @return The map containing the provided options
+ */
+ public Map<String, Object> build() {
+ final ImmutableMap.Builder<String, Object> builder = ImmutableMap.builder();
+ ofNullable(scriptType).map(x -> builder.put("type", x.name().toLowerCase()));
+ ofNullable(timeoutMs).map(x -> builder.put("timeout", x));
+ return builder.build();
+ }
+}

src/main/java/io/appium/java_client/driverscripts/ScriptType.java

@@ -0,0 +1,21 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.driverscripts;
+
+public enum ScriptType {
+ WEBDRIVERIO
+}

src/main/java/io/appium/java_client/driverscripts/ScriptValue.java

@@ -0,0 +1,49 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.driverscripts;
+
+import java.util.Map;
+
+public class ScriptValue {
+ private final Object result;
+ private final Map<String, Object> logs;
+
+ public ScriptValue(Object result, Map<String, Object> logs) {
+ this.result = result;
+ this.logs = logs;
+ }
+
+ /**
+ * The result of ExecuteDriverScript call.
+ *
+ * @return The actual returned value depends on the script content
+ */
+ public Object getResult() {
+ return result;
+ }
+
+ /**
+ * Retrieves logs mapping from ExecuteDriverScript call.
+ *
+ * @return Mapping keys are log levels, for example `warn` or
+ * `error` and the values are lists of strings that were printed
+ * by the script into the corresponding logging level
+ */
+ public Map<String, Object> getLogs() {
+ return logs;
+ }
+}

src/test/java/io/appium/java_client/android/ExecuteDriverScriptTest.java

@@ -0,0 +1,51 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.android;
+
+import io.appium.java_client.driverscripts.ScriptOptions;
+import io.appium.java_client.driverscripts.ScriptType;
+import io.appium.java_client.driverscripts.ScriptValue;
+import org.junit.Test;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.core.Is.is;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertThat;
+
+public class ExecuteDriverScriptTest extends BaseAndroidTest {
+
+ @Test
+ public void verifyBasicScriptExecution() {
+ String script = String.join("\n", Arrays.asList(
+ "const status = await driver.status();",
+ "console.warn('warning message');",
+ "return status;")
+ );
+ ScriptValue value = driver.executeDriverScript(script, new ScriptOptions()
+ .withTimeout(5000)
+ .withScriptType(ScriptType.WEBDRIVERIO));
+ //noinspection unchecked
+ assertNotNull(((Map<String, Object>) value.getResult()).get("build"));
+ //noinspection unchecked
+ assertThat(((List<String>)value.getLogs().get("warn")).get(0),
+ is(equalTo("warning message")));
+ }
+}