Package io.appium.droiddriver.helpers

Helper classes for writing an Android UI test framework using DroidDriver.

See: Description

Class Summary

Class	Description
BaseDroidDriverTest<T extends android.app.Activity>	Base class for tests using DroidDriver that reports uncaught exceptions, for * example OOME, instead of crash.
D2ActivityInstrumentationTestCase2<T extends android.app.Activity>	Fixes bugs in ActivityInstrumentationTestCase2.
DroidDrivers	Static utility methods using a singleton DroidDriver instance.
DroidDriversInitializer	Calls DroidDrivers.setSingleton(io.appium.droiddriver.DroidDriver) once and only once.
PollingListeners	Static utility methods to create commonly used PollingListeners.
ScrollerHelper	Helper for Scroller.
SingleRun	Base class for an action that should run only once no matter how many times the method SingleRun.singleRun() is called upon an instance.

Package io.appium.droiddriver.helpers Description

Helper classes for writing an Android UI test framework using DroidDriver.

UI test framework design principles

A UI test framework should model the UI of the AUT in a hierarchical way to maximize code reuse. Common interactions should be abstracted as methods of page objects. Uncommon interactions may not be abstracted, but carried out using "driver" directly.

The organization of the entities (pages, components) does not need to strictly follow the AUT structure. The UI model can be greatly simplified to make it easy to use.

In general the framework should follow these principles:

• Layered abstraction: at the highest level, methods completely abstract the implementation detail. This kind of methods carry out a complex action, usually involving multiple steps. At a lower level, methods can expose some details, e.g. clickInstallButton(), which does a single action and returns a dialog instance it opens, and let the caller decide how to further interact with it. Lastly at the lowest level, you can always use "driver" to access any elements if no higher-level methods are available.
• Instance methods of a page object assume the page is currently shown.
• If a method opens another page, it should return that page on a best-effort basis. There could be exceptions where we let callers determine the type of the new page, but that should be considered hacks and be clearly documented.
• The page object constructors are public so that it's easy to hack as mentioned above, but don't abuse it -- typically callers should acquire page objects by calling methods of other page objects. The root is the home page of the AUT.
• Simple dialogs may not merit their own top-level classes, and can be nested as static subclasses.
• Define constants that use values generated from Android resources instead of using string literals. For example, call Context.getResources() to get the Resources instance, then call Resources.getResourceName(int) to get the string representation of a resource id, or call Resources.getString(int) to get the localized string of a string resource. This gives you compile-time check over incompatible changes.
• Avoid public constants. Typically clients of a page object are interested in what can be done on the page (the content or actions), not how to achieve that (which is an implementation detail). The constants used by the page object hence should be encapsulated (declared private). Another reason for this item is that the constants may not be real constants. Instead they are generated from resources and acquiring the values requires the Context, which is not available until setUp() is called. If those are referenced in static fields of a test class, they will be initialized at class loading time and result in a crash.
• There are cases that exposing public constants is arguably desired. For example, when the interaction is trivial (e.g. clicking a button that does not open a new page), and there are many similar elements on the page, thus adding distinct methods for them will bloat the page object class. In these cases you may define public constants, with a warning that "Don't use them in static fields of tests".

Common pitfalls

• UI elements are generally views. Users can get attributes and perform actions. Note that actions often update a UiElement, so users are advised not to store instances of UiElement for later use - the instances could become stale. In other words, UiElement represents a dynamic object, while Finder represents a static object. Don't declare fields of the type UiElement; use Finder instead.
• ActivityInstrumentationTestCase2.getActivity() calls InstrumentationTestCase.launchActivityWithIntent(java.lang.String, java.lang.Class<T>, android.content.Intent), which may hang in Instrumentation.waitForIdleSync(). You can call Context.startActivity(android.content.Intent) directly.
• startActivity does not wait until the new Activity is shown. This may cause problem when the old Activity on screen contains UiElements that match what are expected on the new Activity - interaction with the UiElements fails because the old Activity is closing. Sometimes it shows as a test passes when run alone but fails when run with other tests. The work-around is to add a delay after calling startActivity.
• Error "android.content.res.Resources$NotFoundException: Unable to find resource ID ..."?
  This may occur if you reference the AUT's resource in tests, and the two APKs are out of sync. Solution: build and install both AUT and tests together.
• "You said the test runs on older devices as well as API18 devices, but mine is broken on X (e.g. GingerBread)!"
  This may occur if your AUT has different implementations on older devices. In this case, your tests have to match the different execution paths of AUT, which requires insight into the implementation of the AUT. A tip for testing older devices: uiautomatorviewer does not work on ore-API16 devices (the "Device screenshot" button won't work), but you can use it with dumps from DroidDriver (use to-uiautomator.xsl to convert the format).
• "com.android.launcher has stopped unexpectedly" and logcat says OutOfMemoryError
  This is sometimes seen on GingerBread or other low-memory and slow devices. GC is not fast enough to reclaim memory on those devices. A work-around: call gc more aggressively and sleep to let gc run, e.g.

         
  public void setUp() throws Exception {
    super.setUp();
    if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.GINGERBREAD_MR1) {
      Runtime.getRuntime().gc();
      SystemClock.sleep(1000L);
    }
  }