Merge branch 'master' of https://github.com/mykola-mokhnach/java-client into ws

# Conflicts:
#	src/main/java/io/appium/java_client/android/AndroidDriver.java

Author: Mykola Mokhnach

README.md

@@ -21,6 +21,13 @@ This is the Java language binding for writing Appium Tests, conforms to [Mobile
 
 *6.0.0 (under construction yet)*
 
+- **[BUG FIX]** **[BREAKING CHANGE]** Refactor of the `io.appium.java_client.AppiumFluentWait`. It uses `java.time.Duration` for time settings instead of `org.openqa.selenium.support.ui.Duration` and `java.util.concurrent.TimeUnit` [#863](https://github.com/appium/java-client/pull/863)
+- **[BREAKING CHANGE]** `io.appium.java_client.pagefactory.TimeOutDuration` became deprecated. It is going to be removed. Use `java.time.Duration` instead. FIX [#742](https://github.com/appium/java-client/issues/742)  [#863](https://github.com/appium/java-client/pull/863).
+- **[BREAKING CHANGE]** `io.appium.java_client.pagefactory.WithTimeOut#unit` became deprecated. It is going to be removed. Use `io.appium.java_client.pagefactory.WithTimeOut#chronoUnit` instead. FIX [#742](https://github.com/appium/java-client/issues/742)  [#863](https://github.com/appium/java-client/pull/863).
+- **[BREAKING CHANGE]** constructors of `io.appium.java_client.pagefactory.AppiumElementLocatorFactory`, `io.appium.java_client.pagefactory.AppiumFieldDecorator` and `io.appium.java_client.pagefactory.AppiumElementLocator` which use `io.appium.java_client.pagefactory.TimeOutDuration` as a parameter became deprecated. Use new constructors which use `java.time.Duration`.
+- **[DEPENDENCY UPDATES]**
+  - `org.seleniumhq.selenium:selenium-java` was updated to 3.11.0
+
 *6.0.0-BETA4*
 - **[ENHANCEMENT]** Added handler for isDispalyed in W3C mode. [#833](https://github.com/appium/java-client/pull/833)
 - **[ENHANCEMENT]** Added handlers for sending SMS, making GSM Call, setting GSM signal, voice, power capacity and power AC. [#834](https://github.com/appium/java-client/pull/834)

build.gradle

@@ -50,7 +50,7 @@ compileJava {
     ]
 }
 
-ext.seleniumVersion = '3.9.1'
+ext.seleniumVersion = '3.11.0'
 
 dependencies {
     compile ("org.seleniumhq.selenium:selenium-java:${seleniumVersion}") {

docs/environment.md

@@ -0,0 +1,17 @@
+# Appium Environment Troubleshooting
+
+Quite often there are questions about why Appium throws an error about missing environment variable, for example `ANDROID_HOME`, or about missing binaries, like `idevice_id`, `carthage` or `java`. This article explains what might be a cause of such problem and how to resolve it.
+
+## Prerequisites
+
+In order to understand this topic you should know concept of environment variables, how it works in your operating system and how you can change the system environment if needed. In particular, it is important to know the meaning of `PATH` environment variable. Read https://en.wikipedia.org/wiki/Environment_variable and https://en.wikipedia.org/wiki/PATH_(variable) for more details.
+
+## How To Verify What Is Missing
+
+Appium itself is a NodeJS application and uses the same environment as its host `node` process. If you experience an error related to local environment setup then verify the actual process environment first. In Mac OS, for example, it is possible to do this via `ps eww <PID>` command, where `PID` is the process identifier of the running Appium's host Node process. In Windows the [ProcessExplorer](technet.microsoft.com/en-us/sysinternals/bb896653.aspx) utility can be used for such purpose. Then make sure the corresponding variable is there and it is set to a proper value, or, in case there is an error finding some binary, make sure the parent folder of this binary is present in `PATH` list, the binary itself on the local file system and can be executed manually.
+
+## How To Fix Missing Environment Variables
+
+Usually, if one starts Appium from the command line, then it inherits all the environment variables from the parent process (`bash`/`cmd`, etc.). This means that if you start Appium manually or with a script then make sure its parent process has all the necessary environemnt variables set to proper values. Also, it is possible to set variables on [per-process](https://stackoverflow.com/questions/10856129/setting-an-environment-variable-before-a-command-in-bash-not-working-for-second) basis. This might be handy if Appium is set up to start automatically with the operating system, because on early stages of system initialization it might be that the "usual" environment is not present yet.
+
+In case the Appium process is started programatically, for example with java client's `AppiumDriverLocalService` helper class, then it might be necessary to setup the environment [in the client code](https://github.com/appium/java-client/pull/753), because prior to version 6.0 the client does not inherit it from the the parent process by default.

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

@@ -16,18 +16,19 @@
 
 package io.appium.java_client;
 
+import static java.time.Duration.ofMillis;
+
 import com.google.common.base.Throwables;
 
 import org.openqa.selenium.TimeoutException;
 import org.openqa.selenium.WebDriverException;
 import org.openqa.selenium.support.ui.Clock;
-import org.openqa.selenium.support.ui.Duration;
 import org.openqa.selenium.support.ui.FluentWait;
 import org.openqa.selenium.support.ui.Sleeper;
 
 import java.lang.reflect.Field;
+import java.time.Duration;
 import java.util.List;
-import java.util.concurrent.TimeUnit;
 import java.util.function.Function;
 import java.util.function.Supplier;
 
@@ -167,7 +168,7 @@ protected T getInput() {
     /**
      * Sets the strategy for polling. The default strategy is null,
      * which means, that polling interval is always a constant value and is
-     * set by {@link #pollingEvery(long, TimeUnit)} method. Otherwise the value set by that
+     * set by {@link #pollingEvery(Duration)} method. Otherwise the value set by that
      * method might be just a helper to calculate the actual interval.
      * Although, by setting an alternative polling strategy you may flexibly control
      * the duration of this interval for each polling round.
@@ -228,7 +229,7 @@ public AppiumFluentWait<T> withPollingStrategy(Function<IterationInfo, Duration>
     @Override
     public <V> V until(Function<? super T, V> isTrue) {
         final long start = getClock().now();
-        final long end = getClock().laterBy(getTimeout().in(TimeUnit.MILLISECONDS));
+        final long end = getClock().laterBy(getTimeout().toMillis());
         long iterationNumber = 1;
         Throwable lastException;
         while (true) {
@@ -254,15 +255,15 @@ public <V> V until(Function<? super T, V> isTrue) {
                 String timeoutMessage = String.format(
                         "Expected condition failed: %s (tried for %d second(s) with %s interval)",
                         message == null ? "waiting for " + isTrue : message,
-                        getTimeout().in(TimeUnit.SECONDS), getInterval());
+                        getTimeout().getSeconds(), getInterval());
                 throw timeoutException(timeoutMessage, lastException);
             }
 
             try {
                 Duration interval = getInterval();
                 if (pollingStrategy != null) {
                     final IterationInfo info = new IterationInfo(iterationNumber,
-                            new Duration(getClock().now() - start, TimeUnit.MILLISECONDS), getTimeout(),
+                            ofMillis(getClock().now() - start), getTimeout(),
                             interval);
                     interval = pollingStrategy.apply(info);
                 }

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

@@ -58,6 +58,11 @@ public class MobileCommand {
     protected static final String REMOVE_APP;
     //endregion
 
+    //region Clipboard
+    public static final String GET_CLIPBOARD;
+    public static final String SET_CLIPBOARD;
+    //endregion
+
     protected static final String GET_PERFORMANCE_DATA;
     protected static final String GET_SUPPORTED_PERFORMANCE_DATA_TYPES;
 
@@ -127,6 +132,11 @@ public class MobileCommand {
         INSTALL_APP = "installApp";
         //endregion
 
+        //region Clipboard
+        SET_CLIPBOARD = "setClipboard";
+        GET_CLIPBOARD = "getClipboard";
+        //endregion
+
         GET_PERFORMANCE_DATA = "getPerformanceData";
         GET_SUPPORTED_PERFORMANCE_DATA_TYPES = "getSuppportedPerformanceDataTypes";
 
@@ -205,6 +215,11 @@ public class MobileCommand {
         commandRepository.put(QUERY_APP_STATE, postC("/session/:sessionId/appium/device/app_state"));
         //endregion
 
+        //region Clipboard
+        commandRepository.put(GET_CLIPBOARD, postC("/session/:sessionId/appium/device/get_clipboard"));
+        commandRepository.put(SET_CLIPBOARD, postC("/session/:sessionId/appium/device/set_clipboard"));
+        //endregion
+
         //iOS
         commandRepository.put(SHAKE, postC("/session/:sessionId/appium/device/shake"));
         commandRepository.put(TOUCH_ID, postC("/session/:sessionId/appium/simulator/touch_id"));

src/main/java/io/appium/java_client/android/AndroidDriver.java

@@ -53,7 +53,7 @@ public class AndroidDriver<T extends WebElement>
         FindsByAndroidUIAutomator<T>, LocksDevice, HasAndroidSettings, HasDeviceDetails,
         HasSupportedPerformanceDataType, AuthenticatesByFinger,
         CanRecordScreen, SupportsSpecialEmulatorCommands,
-        SupportsNetworkStateManagement, ListensToLogcatMessages {
+        SupportsNetworkStateManagement, ListensToLogcatMessages, HasAndroidClipboard {
 
     private static final String ANDROID_PLATFORM = MobilePlatform.ANDROID;
 

src/main/java/io/appium/java_client/android/HasAndroidClipboard.java

@@ -0,0 +1,58 @@
+/*
+ * 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 static com.google.common.base.Preconditions.checkNotNull;
+import static io.appium.java_client.MobileCommand.SET_CLIPBOARD;
+import static io.appium.java_client.MobileCommand.prepareArguments;
+
+import io.appium.java_client.CommandExecutionHelper;
+import io.appium.java_client.clipboard.ClipboardContentType;
+import io.appium.java_client.clipboard.HasClipboard;
+
+import java.nio.charset.StandardCharsets;
+import java.util.AbstractMap;
+import java.util.Base64;
+
+public interface HasAndroidClipboard extends HasClipboard {
+    /**
+     * Set the content of device's clipboard.
+     *
+     * @param label clipboard data label.
+     * @param contentType one of supported content types.
+     * @param base64Content base64-encoded content to be set.
+     */
+    default void setClipboard(String label, ClipboardContentType contentType, byte[] base64Content) {
+        String[] parameters = new String[]{"content", "contentType", "label"};
+        Object[] values = new Object[]{new String(checkNotNull(base64Content), StandardCharsets.UTF_8),
+                contentType.name().toLowerCase(), checkNotNull(label)};
+        CommandExecutionHelper.execute(this, new AbstractMap.SimpleEntry<>(SET_CLIPBOARD,
+                prepareArguments(parameters, values)));
+    }
+
+    /**
+     * Set the clipboard text.
+     *
+     * @param label clipboard data label.
+     * @param text The actual text to be set.
+     */
+    default void setClipboardText(String label, String text) {
+        setClipboard(label, ClipboardContentType.PLAINTEXT, Base64
+                .getEncoder()
+                .encode(text.getBytes(StandardCharsets.UTF_8)));
+    }
+}

src/main/java/io/appium/java_client/clipboard/ClipboardContentType.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.clipboard;
+
+public enum ClipboardContentType {
+    PLAINTEXT, IMAGE, URL
+}

src/main/java/io/appium/java_client/clipboard/HasClipboard.java

@@ -0,0 +1,79 @@
+/*
+ * 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.clipboard;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import static io.appium.java_client.MobileCommand.GET_CLIPBOARD;
+import static io.appium.java_client.MobileCommand.SET_CLIPBOARD;
+import static io.appium.java_client.MobileCommand.prepareArguments;
+
+import io.appium.java_client.CommandExecutionHelper;
+import io.appium.java_client.ExecutesMethod;
+
+import java.nio.charset.StandardCharsets;
+import java.util.AbstractMap;
+import java.util.Base64;
+
+public interface HasClipboard extends ExecutesMethod {
+    /**
+     * Set the content of device's clipboard.
+     *
+     * @param contentType one of supported content types.
+     * @param base64Content base64-encoded content to be set.
+     */
+    default void setClipboard(ClipboardContentType contentType, byte[] base64Content) {
+        String[] parameters = new String[]{"content", "contentType"};
+        Object[] values = new Object[]{new String(checkNotNull(base64Content), StandardCharsets.UTF_8),
+                contentType.name().toLowerCase()};
+        CommandExecutionHelper.execute(this, new AbstractMap.SimpleEntry<>(SET_CLIPBOARD,
+                prepareArguments(parameters, values)));
+    }
+
+    /**
+     * Get the content of the clipboard.
+     *
+     * @param contentType one of supported content types.
+     * @return the actual content of the clipboard as base64-encoded string or an empty string if the clipboard is empty
+     */
+    default String getClipboard(ClipboardContentType contentType) {
+        return CommandExecutionHelper.execute(this, new AbstractMap.SimpleEntry<>(GET_CLIPBOARD,
+                prepareArguments("contentType", contentType.name().toLowerCase())));
+    }
+
+    /**
+     * Set the clipboard text.
+     *
+     * @param text The actual text to be set.
+     */
+    default void setClipboardText(String text) {
+        setClipboard(ClipboardContentType.PLAINTEXT, Base64
+                .getEncoder()
+                .encode(text.getBytes(StandardCharsets.UTF_8)));
+    }
+
+    /**
+     * Get the clipboard text.
+     *
+     * @return Either the text, which is stored in the clipboard or an empty string if the clipboard is empty
+     */
+    default String getClipboardText() {
+        byte[] base64decodedBytes = Base64
+                .getDecoder()
+                .decode(getClipboard(ClipboardContentType.PLAINTEXT));
+        return new String(base64decodedBytes, StandardCharsets.UTF_8);
+    }
+}

src/main/java/io/appium/java_client/events/DefaultAspect.java

@@ -83,6 +83,8 @@ class DefaultAspect {
         + ".rotate(..))";
     private static final String EXECUTION_CONTEXT = "execution(* org.openqa.selenium.ContextAware."
         + "context(..))";
+    private static final String EXECUTION_SWITCH_TO_WINDOW = "execution(* org.openqa.selenium.WebDriver.TargetLocator"
+            + ".window(..))";
     private static final String AROUND = "execution(* org.openqa.selenium.WebDriver.*(..)) || "
         + "execution(* org.openqa.selenium.WebElement.*(..)) || "
         + "execution(* org.openqa.selenium.WebDriver.Navigation.*(..)) || "
@@ -463,6 +465,24 @@ public void afterMaximization(JoinPoint joinPoint) throws Throwable {
         }
     }
 
+    @Before(EXECUTION_SWITCH_TO_WINDOW)
+    public void beforeSwitchToWindow(JoinPoint joinPoint) throws Throwable {
+        try {
+            listener.beforeSwitchToWindow(castArgument(joinPoint, 0), driver);
+        } catch (Throwable t) {
+            throw getRootCause(t);
+        }
+    }
+
+    @After(EXECUTION_SWITCH_TO_WINDOW)
+    public void afterSwitchToWindow(JoinPoint joinPoint) throws Throwable {
+        try {
+            listener.afterSwitchToWindow(castArgument(joinPoint, 0), driver);
+        } catch (Throwable t) {
+            throw getRootCause(t);
+        }
+    }
+
     @Before(EXECUTION_ROTATE)
     public void beforeRotation(JoinPoint joinPoint) throws Throwable {
         try {

src/main/java/io/appium/java_client/events/DefaultListener.java

@@ -209,6 +209,16 @@ public void afterWindowIsMoved(WebDriver driver, WebDriver.Window window, Point
         ((WindowEventListener) dispatcher).afterWindowIsMaximized(driver, window);
     }
 
+    @Override
+    public void beforeSwitchToWindow(String windowName, WebDriver driver) {
+        ((WebDriverEventListener) dispatcher).beforeSwitchToWindow(windowName, driver);
+    }
+
+    @Override
+    public void afterSwitchToWindow(String windowName, WebDriver driver) {
+        ((WebDriverEventListener) dispatcher).afterSwitchToWindow(windowName, driver);
+    }
+
     @Override public void beforeSwitchingToContext(WebDriver driver, String context) {
         ((ContextEventListener) dispatcher).beforeSwitchingToContext(driver, context);
     }

src/main/java/io/appium/java_client/events/api/general/WindowEventListener.java

@@ -78,4 +78,20 @@ void afterWindowIsMoved(WebDriver driver, WebDriver.Window window,
      * @param window is the window which has been maximized
      */
     void afterWindowIsMaximized(WebDriver driver, WebDriver.Window window);
+
+    /**
+     * This action will be performed each time before
+     * {@link org.openqa.selenium.WebDriver.TargetLocator#window(java.lang.String)}.
+     *
+     * @param driver WebDriver
+     */
+    void beforeSwitchToWindow(String windowName, WebDriver driver);
+
+    /**
+     * This action will be performed each time after
+     * {@link org.openqa.selenium.WebDriver.TargetLocator#window(java.lang.String)}.
+     *
+     * @param driver WebDriver
+     */
+    void afterSwitchToWindow(String windowName, WebDriver driver);
 }