add localeScript capability to set script in locale

lib/android-helpers.js

@@ -150,17 +150,30 @@ helpers.ensureNetworkSpeed = function (adb, networkSpeed) {
   return adb.NETWORK_SPEED.FULL;
 };
 
-helpers.ensureDeviceLocale = async function (adb, language, country) {
+/**
+ * Set and ensure the locale name of the device under test.
+ *
+ * @param {Object} adb - The adb module instance.
+ * @param {string} language - Language. The language field is case insensitive, but Locale always canonicalizes to lower case.
+ *                            format: [a-zA-Z]{2,8}. e.g. en, ja : https://developer.android.com/reference/java/util/Locale.html
+ * @param {string} country - Country. The country (region) field is case insensitive, but Locale always canonicalizes to upper case.
+ *                            format: [a-zA-Z]{2} | [0-9]{3}. e.g. US, JP : https://developer.android.com/reference/java/util/Locale.html
+ * @param {?string} script - Script. The script field is case insensitive but Locale always canonicalizes to title case.
+ *                            format: [a-zA-Z]{4}. e.g. Hans in zh-Hans-CN : https://developer.android.com/reference/java/util/Locale.html
+ * @throws {Error} If it failed to set locale properly
+ */
+helpers.ensureDeviceLocale = async function (adb, language, country, script = null) {
   if (!_.isString(language) && !_.isString(country)) {
     logger.warn(`setDeviceLanguageCountry requires language or country.`);
     logger.warn(`Got language: '${language}' and country: '${country}'`);
     return;
   }
 
-  await adb.setDeviceLanguageCountry(language, country);
+  await adb.setDeviceLanguageCountry(language, country, script);
 
-  if (!await adb.ensureCurrentLocale(language, country)) {
-    throw new Error(`Failed to set language: ${language} and country: ${country}`);
+  if (!await adb.ensureCurrentLocale(language, country, script)) {
+    const message = script ? `language: ${language}, country: ${country} and script: ${script}` : `language: ${language} and country: ${country}`;
+    throw new Error(`Failed to set ${message}`);
   }
 };
 
@@ -612,7 +625,7 @@ helpers.initDevice = async function (adb, opts) {
     await helpers.setMockLocationApp(adb, SETTINGS_HELPER_PKG_ID);
   }
 
-  await helpers.ensureDeviceLocale(adb, opts.language, opts.locale);
+  await helpers.ensureDeviceLocale(adb, opts.language, opts.locale, opts.localeScript);
   await adb.startLogcat();
   if (opts.unicodeKeyboard) {
     return await helpers.initUnicodeKeyboard(adb);

lib/desired-caps.js

@@ -174,7 +174,10 @@ let commonCapConstraints = {
   },
   pageLoadStrategy: {
     isString: true
-  }
+  },
+  localeScript: {
+    isString: true
+  },
 };
 
 let uiautomatorCapConstraints = {

package.json

@@ -42,7 +42,7 @@
     "appium-support": "^2.24.1",
     "asyncbox": "^2.0.4",
     "bluebird": "^3.4.7",
-    "io.appium.settings": "^2.8.0",
+    "io.appium.settings": "^2.10.0",
     "jimp": "^0.5.3",
     "lodash": "^4.17.4",
     "moment": "^2.22.2",

test/functional/android-helper-e2e-specs.js

@@ -52,6 +52,16 @@ describe('android-helpers e2e', function () {
         await adb.getDeviceLocale().should.eventually.equal('fr-FR');
       }
     });
+    it('should set device language and country with script', async function () {
+      await helpers.ensureDeviceLocale(adb, 'zh', 'CN', 'Hans');
+
+      if (await adb.getApiLevel() < 23) {
+        await adb.getDeviceLanguage().should.eventually.equal('fr');
+        await adb.getDeviceCountry().should.eventually.equal('FR');
+      } else {
+        await adb.getDeviceLocale().should.eventually.equal('fr-Hans-CN');
+      }
+    });
   });
   describe('pushSettingsApp', function () {
     const settingsPkg = 'io.appium.settings';

test/unit/android-helper-specs.js

@@ -115,20 +115,32 @@ describe('Android Helpers', function () {
   });
   describe('ensureDeviceLocale', withMocks({adb}, (mocks) => {
     it('should call setDeviceLanguageCountry', async function () {
-      mocks.adb.expects('setDeviceLanguageCountry').withExactArgs('en', 'US').once();
-      mocks.adb.expects('ensureCurrentLocale').withExactArgs('en', 'US').once().returns(true);
+      mocks.adb.expects('setDeviceLanguageCountry').withExactArgs('en', 'US', null).once();
+      mocks.adb.expects('ensureCurrentLocale').withExactArgs('en', 'US', null).once().returns(true);
       await helpers.ensureDeviceLocale(adb, 'en', 'US');
       mocks.adb.verify();
     });
+    it('should call setDeviceLanguageCountry without script', async function () {
+      mocks.adb.expects('setDeviceLanguageCountry').withExactArgs('en', 'US', null).once();
+      mocks.adb.expects('ensureCurrentLocale').withExactArgs('en', 'US', null).once().returns(true);
+      await helpers.ensureDeviceLocale(adb, 'en', 'US', undefined);
+      mocks.adb.verify();
+    });
+    it('should call setDeviceLanguageCountry with script', async function () {
+      mocks.adb.expects('setDeviceLanguageCountry').withExactArgs('zh', 'CN', 'Hans').once();
+      mocks.adb.expects('ensureCurrentLocale').withExactArgs('zh', 'CN', 'Hans').once().returns(true);
+      await helpers.ensureDeviceLocale(adb, 'zh', 'CN', 'Hans');
+      mocks.adb.verify();
+    });
     it('should never call setDeviceLanguageCountry', async function () {
       mocks.adb.expects('setDeviceLanguageCountry').never();
       mocks.adb.expects('getApiLevel').never();
       await helpers.ensureDeviceLocale(adb);
       mocks.adb.verify();
     });
     it('should call setDeviceLanguageCountry with throw', async function () {
-      mocks.adb.expects('setDeviceLanguageCountry').withExactArgs('fr', 'FR').once();
-      mocks.adb.expects('ensureCurrentLocale').withExactArgs('fr', 'FR').once().returns(false);
+      mocks.adb.expects('setDeviceLanguageCountry').withExactArgs('fr', 'FR', null).once();
+      mocks.adb.expects('ensureCurrentLocale').withExactArgs('fr', 'FR', null).once().returns(false);
       await helpers.ensureDeviceLocale(adb, 'fr', 'FR').should.eventually.be.rejectedWith(Error, `Failed to set language: fr and country: FR`);
       mocks.adb.verify();
     });
@@ -620,11 +632,11 @@ describe('Android Helpers', function () {
   }));
   describe('initDevice', withMocks({helpers, adb}, (mocks) => {
     it('should init device', async function () {
-      const opts = {language: "en", locale: "us"};
+      const opts = {language: "en", locale: "us", localeScript: 'Script'};
       mocks.adb.expects('waitForDevice').once();
       mocks.adb.expects('startLogcat').once();
       mocks.helpers.expects('pushSettingsApp').once();
-      mocks.helpers.expects('ensureDeviceLocale').withExactArgs(adb, opts.language, opts.locale).once();
+      mocks.helpers.expects('ensureDeviceLocale').withExactArgs(adb, opts.language, opts.locale, opts.localeScript).once();
       mocks.helpers.expects('setMockLocationApp').withExactArgs(adb, 'io.appium.settings').once();
       await helpers.initDevice(adb, opts);
       mocks.helpers.verify();