Configurator.java revision 18b892c723e812a7e111f102d2b0c0782b116bb6 
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 */
16package 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 */
29public 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
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
221    public long getKeyInjectionDelay() {
222        return mKeyInjectionDelay;
223    }
224}
225