Uiautomator Unicode Input Helper

(Japanese Version is here.)

Uiautomator Unicode Input Helper enables you to input any Unicode (including non-ASCII) characters by using Android uiautomator.

Uiautomator has UiObject.setText(String) API to set text in an editable field. The API works well if the text consists of only the ASCII character, but can not input any non-ASCII characters, such as Japanese. This limitation has prevented developers of non-English applications from using uiautomator for testing.

Uiautomator Unicode Input Helper solves it by providing an IME, which converts encoded text using only ASCII characters into Unicode text. Modified UTF-7 (RFC 3501) is used for the encoding scheme.

Getting Started

Precaution

Utf7Ime, which is installed by the following instructions, prevents you from inputting any text via software keyboard. Do not use Utf7Ime as a human interface. It is intended for only test automation.

To avoid your confusion, change the default IME to your favorite one after using it:

1. Show home screen by tapping home key.
2. Launch Settings.
3. Open Language & input.
4. Tap Default belonging to KEYBOARD & INPUT METHODS category.
5. Select your favorite IME.

Prerequisites

Install Utf7Ime and change the default IME

• Import Utf7Ime/ directory into your Eclipse workspace. You can import by File -> Import... -> Existing Android Code Into Workspace.
• Build Utf7Ime project and install it on your Android-powered device (or emulator) for UI testing.
• Launch Settings App in the device.
• Open Language & input.
• Switch on the UTF7 IME for UI Testing checkbox belonging to KEYBOARD & INPUT METHODS category.
• Tap Default belonging to KEYBOARD & INPUT METHODS category.
• Change the default IME to Utf7Ime by selecting UTF7 IME for UI Testing.

Prepare your Uiautomator tests

Prepare (or create) your test that runs in the uiautomator framework. If you have not written a test for uiautomator yet, you can see detailed instruction here.

Copy the helper library to your Uiautomator project

Copy helper-library/src/* to <your uiaotomator project>/src/.
Note that a uiautomator project does not recognize any JAR libraries in libs directory.

Usage

Apply Utf7ImeHelper.e() to a string used for UiObject.setText(). Any Unicode (including non-ASCII) characters are accepted.

import jp.jun_nama.test.utf7ime.helper.Utf7ImeHelper;

....

// gets UiObject which refers to editable text
UiObject editText = ...; 
// inputs German umlaut characters
editText.setText(Utf7ImeHelper.e("Danke schön"));
// inputs Japanese characters
editText.setText(Utf7ImeHelper.e("ありがとう"));
....

Note that you can set a string to UiObject.setText() directly as long as the string consists of only the ASCII characters except &.

....    
UiObject editText = ...; 
// inputs ASCII text not containing '&'.
// Utf7ImeHelper.e() is not needed.
editText.setText("Thank you very much.");

// inputs ASCII text containing '&'.
// You must use Utf7ImeHelper.e().
editText.setText(Utf7ImeHelper.e("fish & chips"));
....

Sample

You can see a sample project which resides in UiAutomatorInputSample/ directory. This sample code simulates the following instructions:

• Press on the HOME button.
• Launch the "Google" app.
• Input Japanese sentences into Google search box.
  

How to run

• Change the Locale of your testing device to English (United States).
• Set ANDROID_HOME environment variable properly.
• Connect your testing device.
• Change directories to the root of the sample project.

• Build and run by typing the following commands (ant is required):

  ant clean build install
  adb shell uiautomator runtest UiAutomatorInputSample.jar \
      -c jp.jun_nama.test.utf7ime.sample.UiAutomatorInputTest

The sample code is tested under Nexus7 (2013) based on Android 4.4.

It is not run properly for Android emulators based on Android 4.3 or earlier because the class name of Google search box is different. Rewrite search criteria in the sample code so that it can be run under such a device or emulator.

Note that such restrictions are applied to only the sample code. Utf7Ime and the helper library are run properly under devices supporting uiautomator.

License

Copyright 2013 TOYAMA Sumio <jun.nama@gmail.com>
Licensed under the Apache License, Version 2.0.

This software contains jutf7-1.0.0 written by J.T. Beetstra, which is available under a MIT license.