Add an optional format argument to getDeviceTime and update the documentation (#939)

* Update device time getters

* Update the docstring

* Tune conditions

Author: Mykola Mokhnach

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

@@ -18,11 +18,31 @@
 
 import static io.appium.java_client.MobileCommand.GET_DEVICE_TIME;
 
+import com.google.common.collect.ImmutableMap;
+
 import org.openqa.selenium.remote.Response;
 
 public interface HasDeviceTime extends ExecutesMethod {
-    /*
-        Gets device date and time for both iOS(Supports only real device) and Android devices
+
+    /**
+     * Gets device date and time for both iOS(host time is returned for simulators) and Android devices.
+     *
+     * @param format The set of format specifiers. Read
+     *               https://momentjs.com/docs/ to get the full list of supported
+     *               datetime format specifiers. The default format is
+     *               `YYYY-MM-DDTHH:mm:ssZ`, which complies to ISO-8601
+     * @return Device time string
+     */
+    default String getDeviceTime(String format) {
+        Response response = execute(GET_DEVICE_TIME, ImmutableMap.of("format", format));
+        return response.getValue().toString();
+    }
+
+    /**
+     * Gets device date and time for both iOS(host time is returned for simulators) and Android devices.
+     * The default format since Appium 1.8.2 is `YYYY-MM-DDTHH:mm:ssZ`, which complies to ISO-8601.
+     *
+     * @return Device time string
      */
     default String getDeviceTime() {
         Response response = execute(GET_DEVICE_TIME);

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

@@ -118,7 +118,7 @@ public class AndroidDriverTest extends BaseAndroidTest {
 
     @Test public void getDeviceTimeTest() {
         String time = driver.getDeviceTime();
-        assertTrue(time.length() == 28);
+        assertFalse(time.isEmpty());
     }
 
     @Test public void isAppInstalledTest() {

src/test/java/io/appium/java_client/ios/IOSDriverTest.java

@@ -30,11 +30,10 @@
 
 public class IOSDriverTest extends AppIOSTest {
 
-    //TODO There is no ability to check this function usibg simulators.
-    // When CI will have been set up then this test will be returned
+    @Test
     public void getDeviceTimeTest() {
         String time = driver.getDeviceTime();
-        assertTrue(time.length() == 28);
+        assertFalse(time.isEmpty());
     }
 
     @Test public void resetTest() {