1/* 2 * Copyright (C) 2013 DroidDriver committers 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package com.google.android.droiddriver; 18 19import com.google.android.droiddriver.exceptions.ElementNotFoundException; 20import com.google.android.droiddriver.exceptions.TimeoutException; 21import com.google.android.droiddriver.finders.Finder; 22 23public interface DroidDriver { 24 /** 25 * Returns whether a matching element exists without polling. Use this if the 26 * UI is not in the progress of updating. 27 */ 28 boolean has(Finder finder); 29 30 /** 31 * Returns whether a matching element appears within {@code timeoutMillis}. 32 * Use this only if you have no way to determine the content of current page. 33 * There are very few occasions using this is justified. For instance, you are 34 * looking for UiElements in a scrollable view, whose content varies based on 35 * the scroll position. Refrain from using this method in these cases: 36 * <ul> 37 * <li>You know one of a set of UiElements will show, but are not sure which 38 * one. Use this instead: 39 * 40 * <pre> 41 * UiElement el = driver.on(By.anyOf(finder1, finder2, ...)); 42 * // UI is stable now, find which one is returned 43 * if (finder1.matches(el)) ... 44 * </pre> 45 * 46 * </li> 47 * <li>You know the UiElement will appear, and want to optimize the speed by 48 * using a smaller timeout than the default timeout. It's not worth it -- on 49 * and checkExists return as soon as the finder is found. If it is not found, 50 * that's a test failure and should be rare.</li> 51 * </ul> 52 */ 53 boolean has(Finder finder, long timeoutMillis); 54 55 /** 56 * Returns the first {@link UiElement} found using the given finder. This 57 * method will poll until a match is found, or the default timeout is reached. 58 * 59 * @param finder The matching mechanism 60 * @return The first matching element 61 * @throws TimeoutException If no matching elements are found within the 62 * allowed time 63 */ 64 UiElement on(Finder finder); 65 66 /** 67 * Returns the first {@link UiElement} found using the given finder without 68 * polling. This method is useful in {@link Poller.PollingListener#onPolling}. 69 * In other situations polling is desired, and {@link #on} is more 70 * appropriate. 71 * 72 * @param finder The matching mechanism 73 * @return The first matching element 74 * @throws ElementNotFoundException If no matching elements are found 75 */ 76 UiElement find(Finder finder); 77 78 /** 79 * Polls until a {@link UiElement} is found using the given finder, or the 80 * default timeout is reached. 81 * 82 * @param finder The matching mechanism 83 * @throws TimeoutException If matching element does not appear within the 84 * default timeout 85 */ 86 void checkExists(Finder finder); 87 88 /** 89 * Polls until the {@link UiElement} found using the given finder is gone, or 90 * the default timeout is reached. 91 * 92 * @param finder The matching mechanism 93 * @throws TimeoutException If matching element is not gone within the default 94 * timeout 95 */ 96 void checkGone(Finder finder); 97 98 /** 99 * Returns the {@link Poller}. 100 */ 101 Poller getPoller(); 102 103 /** 104 * Sets the {@link Poller}. 105 */ 106 void setPoller(Poller poller); 107 108 /** 109 * Dumps the UiElement tree to a file to help debug. The tree is based on the 110 * last used root UiElement if it exists. Screenshot is always current. If 111 * they do not match, the UiElement tree must be stale, indicating that you 112 * should use a fresh UiElement instead of an old instance. 113 * 114 * @param path the path of file to save the tree 115 * @return whether the dumping succeeded 116 */ 117 boolean dumpUiElementTree(String path); 118} 119