1 /*
2  * Copyright (C) 2013 The Android Open Source Project
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 package com.android.uiautomator.core;
17 
18 /**
19  * Allows you to set key parameters for running uiautomator tests. The new
20  * settings take effect immediately and can be changed any time during a test run.
21  *
22  * To modify parameters using Configurator, first obtain an instance by calling
23  * {@link #getInstance()}. As a best practice, make sure you always save
24  * the original value of any parameter that you are modifying. After running your
25  * tests with the modified parameters, make sure to also restore
26  * the original parameter values, otherwise this will impact other tests cases.
27  * @since API Level 18
28  * @deprecated New tests should be written using UI Automator 2.0 which is available as part of the
29  * Android Testing Support Library.
30  */
31 @Deprecated
32 public final class Configurator {
33     private long mWaitForIdleTimeout = 10 * 1000;
34     private long mWaitForSelector = 10 * 1000;
35     private long mWaitForActionAcknowledgment = 3 * 1000;
36 
37     // The events for a scroll typically complete even before touchUp occurs.
38     // This short timeout to make sure we get the very last in cases where the above isn't true.
39     private long mScrollEventWaitTimeout = 200; // ms
40 
41     // Default is inject as fast as we can
42     private long mKeyInjectionDelay = 0; // ms
43 
44     // reference to self
45     private static Configurator sConfigurator;
46 
Configurator()47     private Configurator() {
48         /* hide constructor */
49     }
50 
51     /**
52      * Retrieves a singleton instance of Configurator.
53      *
54      * @return Configurator instance
55      * @since API Level 18
56      */
getInstance()57     public static Configurator getInstance() {
58         if (sConfigurator == null) {
59             sConfigurator = new Configurator();
60         }
61         return sConfigurator;
62     }
63 
64     /**
65      * Sets the timeout for waiting for the user interface to go into an idle
66      * state before starting a uiautomator action.
67      *
68      * By default, all core uiautomator objects except {@link UiDevice} will perform
69      * this wait before starting to search for the widget specified by the
70      * object's {@link UiSelector}. Once the idle state is detected or the
71      * timeout elapses (whichever occurs first), the object will start to wait
72      * for the selector to find a match.
73      * See {@link #setWaitForSelectorTimeout(long)}
74      *
75      * @param timeout Timeout value in milliseconds
76      * @return self
77      * @since API Level 18
78      */
setWaitForIdleTimeout(long timeout)79     public Configurator setWaitForIdleTimeout(long timeout) {
80         mWaitForIdleTimeout = timeout;
81         return this;
82     }
83 
84     /**
85      * Gets the current timeout used for waiting for the user interface to go
86      * into an idle state.
87      *
88      * By default, all core uiautomator objects except {@link UiDevice} will perform
89      * this wait before starting to search for the widget specified by the
90      * object's {@link UiSelector}. Once the idle state is detected or the
91      * timeout elapses (whichever occurs first), the object will start to wait
92      * for the selector to find a match.
93      * See {@link #setWaitForSelectorTimeout(long)}
94      *
95      * @return Current timeout value in milliseconds
96      * @since API Level 18
97      */
getWaitForIdleTimeout()98     public long getWaitForIdleTimeout() {
99         return mWaitForIdleTimeout;
100     }
101 
102     /**
103      * Sets the timeout for waiting for a widget to become visible in the user
104      * interface so that it can be matched by a selector.
105      *
106      * Because user interface content is dynamic, sometimes a widget may not
107      * be visible immediately and won't be detected by a selector. This timeout
108      * allows the uiautomator framework to wait for a match to be found, up until
109      * the timeout elapses.
110      *
111      * @param timeout Timeout value in milliseconds.
112      * @return self
113      * @since API Level 18
114      */
setWaitForSelectorTimeout(long timeout)115     public Configurator setWaitForSelectorTimeout(long timeout) {
116         mWaitForSelector = timeout;
117         return this;
118     }
119 
120     /**
121      * Gets the current timeout for waiting for a widget to become visible in
122      * the user interface so that it can be matched by a selector.
123      *
124      * Because user interface content is dynamic, sometimes a widget may not
125      * be visible immediately and won't be detected by a selector. This timeout
126      * allows the uiautomator framework to wait for a match to be found, up until
127      * the timeout elapses.
128      *
129      * @return Current timeout value in milliseconds
130      * @since API Level 18
131      */
getWaitForSelectorTimeout()132     public long getWaitForSelectorTimeout() {
133         return mWaitForSelector;
134     }
135 
136     /**
137      * Sets the timeout for waiting for an acknowledgement of an
138      * uiautomtor scroll swipe action.
139      *
140      * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>,
141      * corresponding to the scroll action, that lets the framework determine if
142      * the scroll action was successful. Generally, this timeout should not be modified.
143      * See {@link UiScrollable}
144      *
145      * @param timeout Timeout value in milliseconds
146      * @return self
147      * @since API Level 18
148      */
setScrollAcknowledgmentTimeout(long timeout)149     public Configurator setScrollAcknowledgmentTimeout(long timeout) {
150         mScrollEventWaitTimeout = timeout;
151         return this;
152     }
153 
154     /**
155      * Gets the timeout for waiting for an acknowledgement of an
156      * uiautomtor scroll swipe action.
157      *
158      * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>,
159      * corresponding to the scroll action, that lets the framework determine if
160      * the scroll action was successful. Generally, this timeout should not be modified.
161      * See {@link UiScrollable}
162      *
163      * @return current timeout in milliseconds
164      * @since API Level 18
165      */
getScrollAcknowledgmentTimeout()166     public long getScrollAcknowledgmentTimeout() {
167         return mScrollEventWaitTimeout;
168     }
169 
170     /**
171      * Sets the timeout for waiting for an acknowledgment of generic uiautomator
172      * actions, such as clicks, text setting, and menu presses.
173      *
174      * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>,
175      * corresponding to an action, that lets the framework determine if the
176      * action was successful. Generally, this timeout should not be modified.
177      * See {@link UiObject}
178      *
179      * @param timeout Timeout value in milliseconds
180      * @return self
181      * @since API Level 18
182      */
setActionAcknowledgmentTimeout(long timeout)183     public Configurator setActionAcknowledgmentTimeout(long timeout) {
184         mWaitForActionAcknowledgment = timeout;
185         return this;
186     }
187 
188     /**
189      * Gets the current timeout for waiting for an acknowledgment of generic
190      * uiautomator actions, such as clicks, text setting, and menu presses.
191      *
192      * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>,
193      * corresponding to an action, that lets the framework determine if the
194      * action was successful. Generally, this timeout should not be modified.
195      * See {@link UiObject}
196      *
197      * @return current timeout in milliseconds
198      * @since API Level 18
199      */
getActionAcknowledgmentTimeout()200     public long getActionAcknowledgmentTimeout() {
201         return mWaitForActionAcknowledgment;
202     }
203 
204     /**
205      * Sets a delay between key presses when injecting text input.
206      * See {@link UiObject#setText(String)}
207      *
208      * @param delay Delay value in milliseconds
209      * @return self
210      * @since API Level 18
211      */
setKeyInjectionDelay(long delay)212     public Configurator setKeyInjectionDelay(long delay) {
213         mKeyInjectionDelay = delay;
214         return this;
215     }
216 
217     /**
218      * Gets the current delay between key presses when injecting text input.
219      * See {@link UiObject#setText(String)}
220      *
221      * @return current delay in milliseconds
222      * @since API Level 18
223      */
getKeyInjectionDelay()224     public long getKeyInjectionDelay() {
225         return mKeyInjectionDelay;
226     }
227 }
228