add DroidDriver#refreshUiElementTree

This makes the refreshing step explicit, and gives
users finer control.

Change-Id: Ia4b4e9476805a887096bf620d83a522d2892ee59

4 files changed, 22 insertions, 12 deletions

diff --git a/src/com/google/android/droiddriver/DroidDriver.java b/src/com/google/android/droiddriver/DroidDriver.java
index abf8fba..5421718 100644
--- a/src/com/google/android/droiddriver/DroidDriver.java
+++ b/src/com/google/android/droiddriver/DroidDriver.java
@@ -68,9 +68,9 @@ public interface DroidDriver {
 
   /**
    * Returns the first {@link UiElement} found using the given finder without
-   * polling. This method is useful in {@link Poller.PollingListener#onPolling}.
-   * In other situations polling is desired, and {@link #on} is more
-   * appropriate.
+   * polling and without {@link #refreshUiElementTree}. This method is useful in
+   * {@link Poller.PollingListener#onPolling}. In other situations polling is
+   * desired, and {@link #on} is more appropriate.
    *
    * @param finder The matching mechanism
    * @return The first matching element
@@ -79,6 +79,12 @@ public interface DroidDriver {
   UiElement find(Finder finder);
 
   /**
+   * Refreshes the UiElement tree. All methods in this interface that take a
+   * Finder parameter call this method, unless noted otherwise.
+   */
+  void refreshUiElementTree();
+
+  /**
    * Polls until a {@link UiElement} is found using the given finder, or the
    * default timeout is reached. This behaves the same as {@link #on} except
    * that it does not return the {@link UiElement}.
@@ -116,9 +122,8 @@ public interface DroidDriver {
 
   /**
    * Dumps the UiElement tree to a file to help debug. The tree is based on the
-   * last used root UiElement if it exists. Screenshot is always current. If
-   * they do not match, the UiElement tree must be stale, indicating that you
-   * should use a fresh UiElement instead of an old instance.
+   * last used root UiElement if it exists, otherwise
+   * {@link #refreshUiElementTree} is called.
    *
    * @param path the path of file to save the tree
    * @return whether the dumping succeeded
diff --git a/src/com/google/android/droiddriver/Poller.java b/src/com/google/android/droiddriver/Poller.java
index 24cce77..548f1ad 100644
--- a/src/com/google/android/droiddriver/Poller.java
+++ b/src/com/google/android/droiddriver/Poller.java
@@ -106,10 +106,13 @@ public interface Poller {
   ConditionChecker<Void> GONE = new ConditionChecker<Void>() {
     @Override
     public Void check(DroidDriver driver, Finder finder) throws UnsatisfiedConditionException {
-      if (driver.has(finder)) {
+      try {
+        // "find" does not call refreshUiElementTree, while "has" calls
+        driver.find(finder);
         throw new UnsatisfiedConditionException();
+      } catch (ElementNotFoundException enfe) {
+        return null;
       }
-      return null;
     }
 
     @Override
diff --git a/src/com/google/android/droiddriver/base/BaseDroidDriver.java b/src/com/google/android/droiddriver/base/BaseDroidDriver.java
index 2b9ff64..7ca237f 100644
--- a/src/com/google/android/droiddriver/base/BaseDroidDriver.java
+++ b/src/com/google/android/droiddriver/base/BaseDroidDriver.java
@@ -37,12 +37,13 @@ public abstract class BaseDroidDriver implements DroidDriver {
   @Override
   public UiElement find(Finder finder) {
     Logs.call(this, "find", finder);
-    return finder.find(refreshRootElement());
+    return finder.find(getRootElement());
   }
 
   @Override
   public boolean has(Finder finder) {
     try {
+      refreshUiElementTree();
       find(finder);
       return true;
     } catch (ElementNotFoundException enfe) {
@@ -94,15 +95,15 @@ public abstract class BaseDroidDriver implements DroidDriver {
 
   protected BaseUiElement getRootElement() {
     if (rootElement == null) {
-      refreshRootElement();
+      refreshUiElementTree();
     }
     return rootElement;
   }
 
-  private BaseUiElement refreshRootElement() {
+  @Override
+  public void refreshUiElementTree() {
     getContext().clearData();
     rootElement = getNewRootElement();
-    return rootElement;
   }
 
   @Override
diff --git a/src/com/google/android/droiddriver/base/DefaultPoller.java b/src/com/google/android/droiddriver/base/DefaultPoller.java
index 9c619b7..17cb4f0 100644
--- a/src/com/google/android/droiddriver/base/DefaultPoller.java
+++ b/src/com/google/android/droiddriver/base/DefaultPoller.java
@@ -67,6 +67,7 @@ public class DefaultPoller implements Poller {
     long end = SystemClock.uptimeMillis() + timeoutMillis;
     while (true) {
       try {
+        driver.refreshUiElementTree();
         return checker.check(driver, finder);
       } catch (UnsatisfiedConditionException e) {
         // fall through to poll