feat: Add appTimeZone capability (#295)

README.md

@@ -54,7 +54,7 @@ appium:postrun | An object containing either `script` or `command` key. The valu
 appium:noReset | Whether to restart the app whose bundle identifier was passed to capabilities as `bundleId` value if it was already running on the session startup (`false`, the default value) or just pick it up without changing the app state (`true`). Note that neither of `arguments` or `environment` capabilities will take effect if the app did not restart.
 appium:appPath | The path to the application to automate, for example `/Applications/MyAppName.app`. This is an optional capability, but it requires `bundleId` to be present until mac2 driver v1.13.0. In earlier versions if `bundleId` is empty, `appPath` would be ignored. If the path is invalid or application is damaged/incomplete then an error will be thrown on session startup. This capability could be useful when you have multiple builds of the same application with the same bundleId on your machine (for example one production build in /Applications/ and several dev builds). If you provide bundleId only, the operating system could open any of these builds. By providing `appPath` you have a guarantee that the specified .app will be launched, rather than a random one.
 appium:appLocale | A dictionary with the following possible entries: `locale` (application locale name, for example `uk_UA`), `language` (application language name, for example `de`), `useMetricUnits` (whether to use metric units for the app, if `false` then imperial units are used), `measurementUnits` (the name of measurement units to use in the app, for example `Inches`). This capability only changes the locale for the app under test, it does not modify the system locale. You can achieve the same effect by providing custom values to reserved app command line arguments like `-AppleLanguages` or `-AppleLocale` using the `appium:arguments` capability. Example: use `appLocale = {locale: "de", language: "de_DE"}` to start the app in German language (if no German resources are defined in the destination app bundle then the app is started with the default locale, usually en_US).
-
+| `appium:appTimeZone` | Defines the custom time zone override for the application under test. You can use UTC, PST, EST, as well as place-based timezone names such as America/Los_Angeles. The application must be (re)launched for the capability to take effect. See the [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for more details. The same behavior could be achieved by providing a custom value to the [TZ](https://developer.apple.com/forums/thread/86951#263395) environment variable via the `appium:environment` capability | UTC |
 
 ## Element Attributes
 

WebDriverAgentMac/WebDriverAgentLib/Commands/FBSessionCommands.m

@@ -103,7 +103,14 @@ + (NSArray *)routes
         [launchArguments addObjectsFromArray:[self appArgumentsForLocale:requirements[AM_APP_LOCALE_CAPABILITY]]];
       }
       app.launchArguments = [launchArguments copy];
-      app.launchEnvironment = (NSDictionary <NSString *, NSString *> *)requirements[AM_APP_ENVIRONMENT_CAPABILITY] ?: @{};
+      NSMutableDictionary<NSString *, NSString *> *launchEnv = [NSMutableDictionary new];
+      if (nil != requirements[AM_APP_ENVIRONMENT_CAPABILITY]) {
+        [launchEnv addEntriesFromDictionary:requirements[AM_APP_ENVIRONMENT_CAPABILITY]];
+      }
+      if (nil != requirements[AM_APP_TIME_ZONE_CAPABILITY]) {
+        launchEnv[@"TZ"] = requirements[AM_APP_TIME_ZONE_CAPABILITY];
+      }
+      app.launchEnvironment = [launchEnv copy];
       [app launch];
       if (app.state <= XCUIApplicationStateNotRunning) {
         NSString *message = [NSString stringWithFormat:@"Failed to launch '%@' application", appPath ?: bundleID];

WebDriverAgentMac/WebDriverAgentLib/Utilities/AMSessionCapabilities.h

@@ -18,12 +18,21 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/** Bundle identifier of the application under test */
 extern NSString* const AM_BUNDLE_ID_CAPABILITY;
+/** Command line arguments for the application under test */
 extern NSString* const AM_APP_ARGUMENTS_CAPABILITY;
+/** Environment variables mapping for the application under test */
 extern NSString* const AM_APP_ENVIRONMENT_CAPABILITY;
+/** Whether to skip application under test termination when the test session is deleted */
 extern NSString* const AM_SKIP_APP_KILL_CAPABILITY;
+/** Whether to avoid resetting the state of the application under test on test startup */
 extern NSString* const AM_NO_RESET_CAPABILITY;
+/** Full path the the application under test bundle on the local FS */
 extern NSString* const AM_APP_PATH_CAPABILITY;
+/** Custom time zone name for the application under test */
+extern NSString* const AM_APP_TIME_ZONE_CAPABILITY;
+/** Custom locale properties for the application under test */
 extern NSString* const AM_APP_LOCALE_CAPABILITY;
 
 NS_ASSUME_NONNULL_END

WebDriverAgentMac/WebDriverAgentLib/Utilities/AMSessionCapabilities.m

@@ -22,4 +22,5 @@
 NSString* const AM_SKIP_APP_KILL_CAPABILITY = @"skipAppKill";
 NSString* const AM_NO_RESET_CAPABILITY = @"noReset";
 NSString* const AM_APP_PATH_CAPABILITY = @"appPath";
+NSString* const AM_APP_TIME_ZONE_CAPABILITY = @"appTimeZone";
 NSString* const AM_APP_LOCALE_CAPABILITY = @"appLocale";

lib/desired-caps.js

@@ -44,6 +44,9 @@ const desiredCapConstraints = {
   appLocale: {
     isObject: true
   },
+  appTimeZone: {
+    isString: true
+  },
 };
 
 export { desiredCapConstraints };