feat: Add appTimeZone capability (#2379)

Author: mykola-mokhnach

docs/reference/capabilities.md

@@ -37,6 +37,7 @@ about capabilities, refer to the [Appium documentation](https://appium.io/docs/e
 | `appium:calendarFormat` | Calendar format to set for iOS Simulator, for example `gregorian` or `persian`. Can only be set in conjunction with `appium:locale`. |
 | `appium:appPushTimeout` | The timeout for application upload in milliseconds. Works for real devices only. The default value is `30000`ms |
 | `appium:appInstallStrategy` | Select application installation strategy for real devices. The following strategies are supported:<br>`serial` (default) - pushes app files to the device in a sequential order; this is the least performant strategy, although the most reliable<br>`parallel` - pushes app files simultaneously; this is usually the the most performant strategy, but sometimes could not be very stable<br>`ios-deploy` - tells the driver to use a third-party tool [ios-deploy](https://www.npmjs.com/package/ios-deploy) to install the app; obviously the tool must be installed separately first and must be present in PATH before it could be used. |
+| `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:processArguments` capability | UTC |
 
 ### WebDriverAgent
 

lib/desired-caps.js

@@ -369,7 +369,10 @@ const desiredCapConstraints = /** @type {const} */ ({
   },
   appLaunchStateTimeoutSec: {
     isNumber: true,
-  }
+  },
+  appTimeZone: {
+    isString: true,
+  },
 });
 
 export {desiredCapConstraints, PLATFORM_NAME_IOS, PLATFORM_NAME_TVOS};

lib/driver.js

@@ -1343,8 +1343,13 @@ export class XCUITestDriver extends BaseDriver {
       }
     }
 
+    if (util.hasValue(this.opts.appTimeZone)) {
+      // https://developer.apple.com/forums/thread/86951?answerId=263395022#263395022
+      env.TZ = this.opts.appTimeZone;
+    }
+
     /** @type {import('appium-webdriveragent').WDACapabilities} */
-    const wdaCaps = /** @type {any} */ ({
+    const wdaCaps = {
       bundleId: this.opts.autoLaunch === false ? undefined : bundleId,
       arguments: args,
       environment: env,
@@ -1366,7 +1371,7 @@ export class XCUITestDriver extends BaseDriver {
       forceSimulatorSoftwareKeyboardPresence:
         this.opts.forceSimulatorSoftwareKeyboardPresence ??
         (this.opts.connectHardwareKeyboard === true ? false : true),
-    });
+    };
     if (this.opts.autoAcceptAlerts) {
       wdaCaps.defaultAlertAction = 'accept';
     } else if (this.opts.autoDismissAlerts) {