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 17 package io.appium.droiddriver; 18 19 import io.appium.droiddriver.exceptions.ElementNotFoundException; 20 import io.appium.droiddriver.exceptions.TimeoutException; 21 import io.appium.droiddriver.finders.Finder; 22 23 /** 24 * The entry interface for using droiddriver. 25 */ 26 public interface DroidDriver { 27 /** 28 * Returns whether a matching element exists without polling. Use this if the 29 * UI is not in the progress of updating. 30 */ has(Finder finder)31 boolean has(Finder finder); 32 33 /** 34 * Returns whether a matching element appears within {@code timeoutMillis}. 35 * Use this only if you have no way to determine the content of current page. 36 * There are very few occasions using this is justified. For instance, you are 37 * looking for UiElements in a scrollable view, whose content varies based on 38 * the scroll position. Refrain from using this method in these cases: 39 * <ul> 40 * <li>You know one of a set of UiElements will show, but are not sure which 41 * one. Use this instead: 42 * 43 * <pre> 44 * UiElement el = driver.on(By.anyOf(finder1, finder2, ...)); 45 * // UI is stable now, find which one is returned 46 * if (finder1.matches(el)) ... 47 * </pre> 48 * 49 * </li> 50 * <li>You know the UiElement will appear, and want to optimize the speed by 51 * using a smaller timeout than the default timeout. It's not worth it -- on 52 * and checkExists return as soon as the finder is found. If it is not found, 53 * that's a test failure and should be rare.</li> 54 * </ul> 55 */ has(Finder finder, long timeoutMillis)56 boolean has(Finder finder, long timeoutMillis); 57 58 /** 59 * Returns the first {@link UiElement} found using the given finder. This 60 * method will poll until a match is found, or the default timeout is reached. 61 * 62 * @param finder The matching mechanism 63 * @return The first matching element 64 * @throws TimeoutException If no matching elements are found within the 65 * allowed time 66 */ on(Finder finder)67 UiElement on(Finder finder); 68 69 /** 70 * Returns the first {@link UiElement} found using the given finder without 71 * polling and without {@link #refreshUiElementTree}. This method is useful in 72 * {@link Poller.PollingListener#onPolling}. In other situations polling is 73 * desired, and {@link #on} is more appropriate. 74 * 75 * @param finder The matching mechanism 76 * @return The first matching element 77 * @throws ElementNotFoundException If no matching elements are found 78 */ find(Finder finder)79 UiElement find(Finder finder); 80 81 /** 82 * Refreshes the UiElement tree. All methods in this interface that take a 83 * Finder parameter call this method, unless noted otherwise. 84 */ refreshUiElementTree()85 void refreshUiElementTree(); 86 87 /** 88 * Polls until a {@link UiElement} is found using the given finder, or the 89 * default timeout is reached. This behaves the same as {@link #on} except 90 * that it does not return the {@link UiElement}. 91 * 92 * @param finder The matching mechanism 93 * @throws TimeoutException If matching element does not appear within the 94 * default timeout 95 */ checkExists(Finder finder)96 void checkExists(Finder finder); 97 98 /** 99 * Polls until the {@link UiElement} found using the given finder is gone, or 100 * the default timeout is reached. 101 * 102 * @param finder The matching mechanism 103 * @throws TimeoutException If matching element is not gone within the default 104 * timeout 105 */ checkGone(Finder finder)106 void checkGone(Finder finder); 107 108 /** 109 * Returns the {@link Poller}. 110 */ getPoller()111 Poller getPoller(); 112 113 /** 114 * Sets the {@link Poller}. 115 */ setPoller(Poller poller)116 void setPoller(Poller poller); 117 118 /** 119 * Returns a {@link UiDevice} for device-wide interaction. 120 */ getUiDevice()121 UiDevice getUiDevice(); 122 123 /** 124 * Dumps the UiElement tree to a file to help debug. The tree is based on the 125 * last used root UiElement if it exists, otherwise 126 * {@link #refreshUiElementTree} is called. 127 * <p> 128 * The dump may contain invisible UiElements that are not used in the finding 129 * algorithm. 130 * </p> 131 * 132 * @param path the path of file to save the tree 133 * @return whether the dumping succeeded 134 */ dumpUiElementTree(String path)135 boolean dumpUiElementTree(String path); 136 } 137