DataInteraction.java

/*
 * Copyright (C) 2014 The Android Open Source Project
 *
 * 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 androidx.test.espresso;

import static androidx.test.espresso.DataInteraction.DisplayDataMatcher.displayDataMatcher;
import static androidx.test.espresso.Espresso.onView;
import static androidx.test.espresso.matcher.ViewMatchers.isAssignableFrom;
import static androidx.test.espresso.matcher.ViewMatchers.isDescendantOfA;
import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.base.Preconditions.checkState;
import static org.hamcrest.Matchers.allOf;

import android.support.annotation.CheckResult;
import android.support.annotation.NonNull;
import android.support.annotation.VisibleForTesting;
import android.view.View;
import android.view.ViewParent;
import android.widget.Adapter;
import android.widget.AdapterView;
import androidx.test.espresso.action.AdapterDataLoaderAction;
import androidx.test.espresso.action.AdapterViewProtocol;
import androidx.test.espresso.action.AdapterViewProtocol.AdaptedData;
import androidx.test.espresso.action.AdapterViewProtocols;
import androidx.test.espresso.matcher.RootMatchers;
import androidx.test.espresso.remote.ConstructorInvocation;
import androidx.test.espresso.remote.annotation.RemoteMsgConstructor;
import androidx.test.espresso.remote.annotation.RemoteMsgField;
import androidx.test.espresso.util.EspressoOptional;
import com.google.common.base.Function;
import javax.annotation.CheckReturnValue;
import org.hamcrest.Description;
import org.hamcrest.Matcher;
import org.hamcrest.TypeSafeMatcher;

/**
 * An interface to interact with data displayed in AdapterViews.
 *
 * <p>This interface builds on top of {@link ViewInteraction} and should be the preferred way to
 * interact with elements displayed inside AdapterViews.
 *
 * <p>This is necessary because an AdapterView may not load all the data held by its Adapter into
 * the view hierarchy until a user interaction makes it necessary. Also it is more fluent / less
 * brittle to match upon the data object being rendered into the display then the rendering itself.
 *
 * <p>By default, a DataInteraction takes place against any AdapterView found within the current
 * screen, if you have multiple AdapterView objects displayed, you will need to narrow the selection
 * by using the inAdapterView method.
 *
 * <p>The check and perform method operate on the top level child of the adapter view, if you need
 * to operate on a subview (eg: a Button within the list) use the onChildView method before calling
 * perform or check.
 */
public class DataInteraction {

  private final Matcher<? extends Object> dataMatcher;
  private Matcher<View> adapterMatcher = isAssignableFrom(AdapterView.class);
  private EspressoOptional<Matcher<View>> childViewMatcher = EspressoOptional.absent();
  private EspressoOptional<Integer> atPosition = EspressoOptional.absent();
  private AdapterViewProtocol adapterViewProtocol = AdapterViewProtocols.standardProtocol();
  private Matcher<Root> rootMatcher = RootMatchers.DEFAULT;

  DataInteraction(Matcher<? extends Object> dataMatcher) {
    this.dataMatcher = checkNotNull(dataMatcher);
  }

  /**
   * Causes perform and check methods to take place on a specific child view of the view returned by
   * Adapter.getView()
   */
  @CheckResult
  @CheckReturnValue
  public DataInteraction onChildView(Matcher<View> childMatcher) {
    this.childViewMatcher = EspressoOptional.of(checkNotNull(childMatcher));
    return this;
  }

  /** Causes this data interaction to work within the Root specified by the given root matcher. */
  @CheckResult
  @CheckReturnValue
  public DataInteraction inRoot(Matcher<Root> rootMatcher) {
    this.rootMatcher = checkNotNull(rootMatcher);
    return this;
  }

  /**
   * Selects a particular adapter view to operate on, by default we operate on any adapter view on
   * the screen.
   */
  @CheckResult
  @CheckReturnValue
  public DataInteraction inAdapterView(Matcher<View> adapterMatcher) {
    this.adapterMatcher = checkNotNull(adapterMatcher);
    return this;
  }

  /** Selects the view which matches the nth position on the adapter based on the data matcher. */
  @CheckResult
  @CheckReturnValue
  public DataInteraction atPosition(Integer atPosition) {
    this.atPosition = EspressoOptional.of(checkNotNull(atPosition));
    return this;
  }

  /**
   * Use a different AdapterViewProtocol if the Adapter implementation does not satisfy the
   * AdapterView contract like (@code ExpandableListView)
   */
  @CheckResult
  @CheckReturnValue
  public DataInteraction usingAdapterViewProtocol(AdapterViewProtocol adapterViewProtocol) {
    this.adapterViewProtocol = checkNotNull(adapterViewProtocol);
    return this;
  }

  /**
   * Performs an action on the view after we force the data to be loaded.
   *
   * @return an {@link ViewInteraction} for more assertions or actions.
   */
  public ViewInteraction perform(ViewAction... actions) {
    return onView(makeTargetMatcher()).inRoot(rootMatcher).perform(actions);
  }

  /**
   * Performs an assertion on the state of the view after we force the data to be loaded.
   *
   * @return an {@link ViewInteraction} for more assertions or actions.
   */
  public ViewInteraction check(ViewAssertion assertion) {
    return onView(makeTargetMatcher()).inRoot(rootMatcher).check(assertion);
  }

  @SuppressWarnings("unchecked")
  private Matcher<View> makeTargetMatcher() {
    Matcher<View> targetView =
        displayDataMatcher(
            adapterMatcher, dataMatcher, rootMatcher, atPosition, adapterViewProtocol);
    if (childViewMatcher.isPresent()) {
      targetView = allOf(childViewMatcher.get(), isDescendantOfA(targetView));
    }
    return targetView;
  }

  /**
   * Internal matcher that is required for {@link Espresso#onData(Matcher)}.
   *
   * <p>This matcher is only visible to support proto serialization. Do not use this matcher in any
   * Espresso test code!
   */
  public static final class DisplayDataMatcher extends TypeSafeMatcher<View> {
    private static final String TAG = "DisplayDataMatcher";

    @RemoteMsgField(order = 0)
    private final Matcher<View> adapterMatcher;

    @RemoteMsgField(order = 1)
    private final Matcher<? extends Object> dataMatcher;

    @SuppressWarnings("unused") // Used reflectively
    @RemoteMsgField(order = 2)
    private final Class<? extends AdapterViewProtocol> adapterViewProtocolClass;

    @RemoteMsgField(order = 3)
    private final AdapterDataLoaderAction adapterDataLoaderAction;

    private final AdapterViewProtocol adapterViewProtocol;

    @RemoteMsgConstructor
    DisplayDataMatcher(
        @NonNull Matcher<View> adapterMatcher,
        @NonNull Matcher<? extends Object> dataMatcher,
        @NonNull Class<? extends AdapterViewProtocol> adapterViewProtocolClass,
        @NonNull AdapterDataLoaderAction adapterDataLoaderAction)
        throws IllegalAccessException, InstantiationException {
      this(
          adapterMatcher,
          dataMatcher,
          // TODO(b/33008615): MPE does not support root matchers yet, fallback to default for now.
          RootMatchers.DEFAULT,
          adapterViewProtocolClass.cast(
              new ConstructorInvocation(adapterViewProtocolClass, null).invokeConstructor()),
          adapterDataLoaderAction);
    }

    private DisplayDataMatcher(
        @NonNull final Matcher<View> adapterMatcher,
        @NonNull Matcher<? extends Object> dataMatcher,
        @NonNull final Matcher<Root> rootMatcher,
        @NonNull AdapterViewProtocol adapterViewProtocol,
        @NonNull AdapterDataLoaderAction adapterDataLoaderAction) {
      this(
          adapterMatcher,
          dataMatcher,
          adapterViewProtocol,
          adapterDataLoaderAction,
          new Function<AdapterDataLoaderAction, ViewInteraction>() {
            @Override
            public ViewInteraction apply(AdapterDataLoaderAction adapterDataLoaderAction) {
              return onView(adapterMatcher).inRoot(rootMatcher).perform(adapterDataLoaderAction);
            }
          });
    }

    @VisibleForTesting
    DisplayDataMatcher(
        @NonNull Matcher<View> adapterMatcher,
        @NonNull Matcher<? extends Object> dataMatcher,
        @NonNull AdapterViewProtocol adapterViewProtocol,
        @NonNull AdapterDataLoaderAction adapterDataLoaderAction,
        @NonNull Function<AdapterDataLoaderAction, ViewInteraction> loadDataFunction) {
      this.adapterMatcher = checkNotNull(adapterMatcher);
      this.dataMatcher = checkNotNull(dataMatcher);
      this.adapterViewProtocol = checkNotNull(adapterViewProtocol);
      this.adapterViewProtocolClass = adapterViewProtocol.getClass();
      this.adapterDataLoaderAction = checkNotNull(adapterDataLoaderAction);
      checkNotNull(loadDataFunction).apply(adapterDataLoaderAction);
    }

    /**
     * Returns an instance of {@link DisplayDataMatcher}.
     *
     * <p>Note: This is an internal method, do not call from test code!
     *
     * @param adapterMatcher matcher that matches an {@link AdapterView}
     * @param dataMatcher the data matcher for matching a {@link View} by it's adapter data
     * @param adapterViewProtocol the {@link AdapterViewProtocol} used for this data interaction
     */
    public static DisplayDataMatcher displayDataMatcher(
        @NonNull Matcher<View> adapterMatcher,
        @NonNull Matcher<? extends Object> dataMatcher,
        @NonNull Matcher<Root> rootMatcher,
        EspressoOptional<Integer> atPosition,
        @NonNull AdapterViewProtocol adapterViewProtocol) {
      return new DisplayDataMatcher(
          adapterMatcher,
          dataMatcher,
          rootMatcher,
          adapterViewProtocol,
          new AdapterDataLoaderAction(dataMatcher, atPosition, adapterViewProtocol));
    }

    @Override
    public void describeTo(Description description) {
      description.appendText(" displaying data matching: ");
      dataMatcher.describeTo(description);
      description.appendText(" within adapter view matching: ");
      adapterMatcher.describeTo(description);
    }

    @SuppressWarnings("unchecked")
    @Override
    public boolean matchesSafely(View view) {
      checkState(adapterViewProtocol != null, "adapterViewProtocol cannot be null!");
      ViewParent parent = view.getParent();
      while (parent != null && !(parent instanceof AdapterView)) {
        parent = parent.getParent();
      }
      if (parent != null && adapterMatcher.matches(parent)) {
        EspressoOptional<AdaptedData> data =
            adapterViewProtocol.getDataRenderedByView(
                (AdapterView<? extends Adapter>) parent, view);
        if (data.isPresent()) {
          return data.get()
              .opaqueToken
              .equals(adapterDataLoaderAction.getAdaptedData().opaqueToken);
        }
      }
      return false;
    }
  }
}