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 * @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
32public 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
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
224    public long getKeyInjectionDelay() {
225        return mKeyInjectionDelay;
226    }
227}
228