droiddriver/scroll/DynamicSentinelStrategy.java

/*
 * Copyright (C) 2013 DroidDriver committers
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.appium.droiddriver.scroll;

import android.util.Log;

import io.appium.droiddriver.DroidDriver;
import io.appium.droiddriver.UiElement;
import io.appium.droiddriver.exceptions.ElementNotFoundException;
import io.appium.droiddriver.finders.By;
import io.appium.droiddriver.finders.Finder;
import io.appium.droiddriver.scroll.Direction.DirectionConverter;
import io.appium.droiddriver.scroll.Direction.PhysicalDirection;
import io.appium.droiddriver.util.Logs;
import io.appium.droiddriver.util.Strings;

/**
 * Determines whether scrolling is possible by checking whether the sentinel
 * child is updated after scrolling. Use this when {@link UiElement#getChildren}
 * is not reliable. This can happen, for instance, when UiAutomationDriver is
 * used, which skips invisible children, or in the case of dynamic list, which
 * shows more items when scrolling beyond the end.
 */
public class DynamicSentinelStrategy extends SentinelStrategy {

  /**
   * Interface for determining whether sentinel is updated.
   */
  public static interface IsUpdatedStrategy {
    /**
     * Returns whether {@code newSentinel} is updated from {@code oldSentinel}.
     */
    boolean isSentinelUpdated(UiElement newSentinel, UiElement oldSentinel);

    /**
     * {@inheritDoc}
     *
     * <p>
     * It is recommended that this method return a description to help
     * debugging.
     */
    @Override
    String toString();
  }

  /**
   * Determines whether the sentinel is updated by checking a single unique
   * String attribute of a descendant element of the sentinel (or itself).
   */
  public static abstract class SingleStringUpdated implements IsUpdatedStrategy {
    private final Finder uniqueStringFinder;

    /**
     * @param uniqueStringFinder a Finder relative to the sentinel that finds
     *        its descendant or self which contains a unique String.
     */
    public SingleStringUpdated(Finder uniqueStringFinder) {
      this.uniqueStringFinder = uniqueStringFinder;
    }

    /**
     * @param uniqueStringElement the descendant or self that contains the
     *        unique String
     * @return the unique String
     */
    protected abstract String getUniqueString(UiElement uniqueStringElement);

    private String getUniqueStringFromSentinel(UiElement sentinel) {
      try {
        return getUniqueString(uniqueStringFinder.find(sentinel));
      } catch (ElementNotFoundException e) {
        return null;
      }
    }

    @Override
    public boolean isSentinelUpdated(UiElement newSentinel, UiElement oldSentinel) {
      // If the sentinel moved, scrolling has some effect. This is both an
      // optimization - getBounds is cheaper than find - and necessary in
      // certain cases, e.g. user is looking for a sibling of the unique string;
      // the scroll is close to the end therefore the unique string does not
      // change, but the target could be revealed.
      if (!newSentinel.getBounds().equals(oldSentinel.getBounds())) {
        return true;
      }

      String newString = getUniqueStringFromSentinel(newSentinel);
      // A legitimate case for newString being null is when newSentinel is
      // partially shown. We return true to allow further scrolling. But program
      // error could also cause this, e.g. a bad choice of Getter, which
      // results in unnecessary scroll actions that have no visual effect. This
      // log helps troubleshooting in the latter case.
      if (newString == null) {
        Logs.logfmt(Log.WARN, "Unique String is null: sentinel=%s, uniqueStringFinder=%s",
            newSentinel, uniqueStringFinder);
        return true;
      }
      if (newString.equals(getUniqueStringFromSentinel(oldSentinel))) {
        Logs.log(Log.INFO, "Unique String is not updated: " + newString);
        return false;
      }
      return true;
    }

    @Override
    public String toString() {
      return Strings.toStringHelper(this).addValue(uniqueStringFinder).toString();
    }
  }

  /**
   * Determines whether the sentinel is updated by checking the text of a
   * descendant element of the sentinel (or itself).
   */
  public static class TextUpdated extends SingleStringUpdated {
    public TextUpdated(Finder uniqueStringFinder) {
      super(uniqueStringFinder);
    }

    @Override
    protected String getUniqueString(UiElement uniqueStringElement) {
      return uniqueStringElement.getText();
    }
  }

  /**
   * Determines whether the sentinel is updated by checking the content
   * description of a descendant element of the sentinel (or itself).
   */
  public static class ContentDescriptionUpdated extends SingleStringUpdated {
    public ContentDescriptionUpdated(Finder uniqueStringFinder) {
      super(uniqueStringFinder);
    }

    @Override
    protected String getUniqueString(UiElement uniqueStringElement) {
      return uniqueStringElement.getContentDescription();
    }
  }

  /**
   * Determines whether the sentinel is updated by checking the resource-id of a
   * descendant element of the sentinel (often itself). This is useful when the
   * children of the container are heterogeneous -- they don't have a common
   * pattern to get a unique string.
   */
  public static class ResourceIdUpdated extends SingleStringUpdated {
    /**
     * Uses the resource-id of the sentinel itself.
     */
    public static final ResourceIdUpdated SELF = new ResourceIdUpdated(By.any());

    public ResourceIdUpdated(Finder uniqueStringFinder) {
      super(uniqueStringFinder);
    }

    @Override
    protected String getUniqueString(UiElement uniqueStringElement) {
      return uniqueStringElement.getResourceId();
    }
  }

  private final IsUpdatedStrategy isUpdatedStrategy;
  private UiElement lastSentinel;

  /**
   * Constructs with {@code Getter}s that decorate the given {@code Getter}s
   * with {@link UiElement#VISIBLE}, and the given {@code isUpdatedStrategy} and
   * {@code directionConverter}. Be careful with {@code Getter}s: the sentinel
   * after each scroll should be unique.
   */
  public DynamicSentinelStrategy(IsUpdatedStrategy isUpdatedStrategy, Getter backwardGetter,
      Getter forwardGetter, DirectionConverter directionConverter) {
    super(new MorePredicateGetter(backwardGetter, UiElement.VISIBLE), new MorePredicateGetter(
        forwardGetter, UiElement.VISIBLE), directionConverter);
    this.isUpdatedStrategy = isUpdatedStrategy;
  }

  /**
   * Defaults to the standard {@link DirectionConverter}.
   */
  public DynamicSentinelStrategy(IsUpdatedStrategy isUpdatedStrategy, Getter backwardGetter,
      Getter forwardGetter) {
    this(isUpdatedStrategy, backwardGetter, forwardGetter, DirectionConverter.STANDARD_CONVERTER);
  }

  /**
   * Defaults to LAST_CHILD_GETTER for forward scrolling, and the standard
   * {@link DirectionConverter}.
   */
  public DynamicSentinelStrategy(IsUpdatedStrategy isUpdatedStrategy, Getter backwardGetter) {
    this(isUpdatedStrategy, backwardGetter, LAST_CHILD_GETTER,
        DirectionConverter.STANDARD_CONVERTER);
  }

  @Override
  public boolean scroll(DroidDriver driver, Finder containerFinder, PhysicalDirection direction) {
    UiElement oldSentinel = getOldSentinel(driver, containerFinder, direction);
    doScroll(oldSentinel.getParent(), direction);
    UiElement newSentinel = getSentinel(driver, containerFinder, direction);
    lastSentinel = newSentinel;
    return isUpdatedStrategy.isSentinelUpdated(newSentinel, oldSentinel);
  }

  private UiElement getOldSentinel(DroidDriver driver, Finder containerFinder,
      PhysicalDirection direction) {
    return lastSentinel != null ? lastSentinel : getSentinel(driver, containerFinder, direction);
  }

  @Override
  public void beginScrolling(DroidDriver driver, Finder containerFinder, Finder itemFinder,
      PhysicalDirection direction) {
    lastSentinel = null;
  }

  @Override
  public void endScrolling(DroidDriver driver, Finder containerFinder, Finder itemFinder,
      PhysicalDirection direction) {
    // Prevent memory leak
    lastSentinel = null;
  }

  @Override
  public String toString() {
    return String.format("DynamicSentinelStrategy{%s, isUpdatedStrategy=%s}", super.toString(),
        isUpdatedStrategy);
  }
}