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