1 /*
2  * Copyright (C) 2016 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 
17 package android.platform.helpers;
18 
19 import android.content.pm.PackageManager.NameNotFoundException;
20 import android.support.test.uiautomator.UiWatcher;
21 
22 import java.io.IOException;
23 
24 public interface IAppHelper extends ITestHelper {
25 
26     /**
27      * Setup expectation: On the launcher home screen.
28      *
29      * Launches the desired application.
30      */
open()31     abstract void open();
32 
33     /**
34      * Setup expectation: None
35      * <p>
36      * Presses back until the launcher package is visible, i.e. the home screen. This can be
37      * overriden for custom functionality, however consider and document the exit state if doing so.
38      */
exit()39     abstract void exit();
40 
41     /**
42      * Setup expectations: This application is on the initial launch screen.
43      * <p>
44      * Dismiss all visible relevant dialogs and block until this process is complete.
45      */
dismissInitialDialogs()46     abstract void dismissInitialDialogs();
47 
48     /**
49      * Setup expectations: None
50      * <p>
51      * Get the target application's component package.
52      * @return the package name for this helper's application.
53      */
getPackage()54     abstract String getPackage();
55 
56     /**
57      * Setup expectations: None.
58      * <p>
59      * Get the target application's launcher name.
60      * @return the name of this application's launcher.
61      */
getLauncherName()62     abstract String getLauncherName();
63 
64     /**
65      * Setup expectations: None
66      * <p>
67      * Get the target application's version String.
68      * @return the version code
69      * @throws NameNotFoundException if {@code getPackage} is not found
70      */
getVersion()71     abstract String getVersion() throws NameNotFoundException;
72 
73     /**
74      * Setup expectations: None
75      * @return true, if this app's package is the root (depth 0), and false otherwise
76      */
isAppInForeground()77     abstract boolean isAppInForeground();
78 
79     /**
80      * Setup expectations: None
81      *
82      * <p>Captures a screenshot and UI XML with the supplied name.
83      *
84      * @param name the screenshot prefix
85      * @throws IOException if there is a capture failure
86      * @throws TestHelperException if creating the screenshot directory fails.
87      */
captureScreenshot(String name)88     abstract boolean captureScreenshot(String name) throws IOException;
89 
90     /**
91      * Sends text events to the device through key codes.
92      * <p>
93      * Note: use this only when text accessibility is not supported.
94      * @param text the text to input as events
95      * @param delay the delay between each event
96      * @return true if successful, false otherwise
97      */
sendTextEvents(String text, long delay)98     abstract boolean sendTextEvents(String text, long delay);
99 
100     /**
101      * Setup expectations: None
102      *
103      * <p>Registers a UiWatcher.
104      *
105      * @param name the name of the UiWatcher to register
106      * @param watcher the UiWatcher to register
107      */
registerWatcher(String name, UiWatcher watcher)108     default void registerWatcher(String name, UiWatcher watcher) {
109         throw new UnsupportedOperationException("Not implemented yet.");
110     }
111 
112     /**
113      * Setup expectations: None
114      *
115      * <p>Registers a UiWatcher.
116      *
117      * @param name the name of the UiWatcher to register
118      * @param watcher the UiWatcher to register
119      */
registerWatcher(String name, androidx.test.uiautomator.UiWatcher watcher)120     default void registerWatcher(String name, androidx.test.uiautomator.UiWatcher watcher) {
121         throw new UnsupportedOperationException("Not implemented yet.");
122     }
123 
124     /**
125      * Setup expectations: None
126      * <p>
127      * Removes a previously registered UiWatcher.
128      * @param name the name of the UiWatcher to register
129      */
removeWatcher(String name)130     abstract void removeWatcher(String name);
131 }
132