1 /* 2 * Copyright (C) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef ACCESSIBILITY_UI_TEST_ABILITY_H 17 #define ACCESSIBILITY_UI_TEST_ABILITY_H 18 19 #include <map> 20 #include <memory> 21 #include "accessibility_gesture_inject_path.h" 22 #include "accessibility_window_info.h" 23 #include "accessible_ability_listener.h" 24 25 namespace OHOS { 26 namespace Accessibility { 27 class AccessibilityUITestAbility { 28 public: 29 /** 30 * @brief Destruct 31 */ 32 virtual ~AccessibilityUITestAbility() = default; 33 34 /** 35 * @brief Gets an instance of AccessibilityUITestAbility. 36 * @return Return an instance of AccessibilityUITestAbility. 37 */ 38 static std::shared_ptr<AccessibilityUITestAbility> GetInstance(); 39 40 /** 41 * @brief Register ability listener. 42 * @param listener The listener to add. 43 * @return Return RET_OK if registers listener successfully, otherwise refer to the RetError for the failure. 44 */ 45 virtual RetError RegisterAbilityListener(const std::shared_ptr<AccessibleAbilityListener> &listener) = 0; 46 47 /** 48 * @brief Connect to AAMS. For UI test. 49 * @return Return RET_OK if the command of connection is sent successfully, 50 * otherwise refer to the RetError for the failure. 51 */ 52 virtual RetError Connect() = 0; 53 54 /** 55 * @brief disconnect to AAMS. For UI test. 56 * @return Return RET_OK if the command of disconnect is sent successfully, 57 * otherwise refer to the RetError for the failure. 58 */ 59 virtual RetError Disconnect() = 0; 60 61 /** 62 * @brief Obtains elementInfo of focus. 63 * @param focusType The type of focus. It contains FOCUS_TYPE_INPUT and FOCUS_TYPE_ACCESSIBILITY. 64 * @param elementInfo The accessibilityElementInfo of focus. 65 * @return Return RET_OK if obtains elementInfo successfully, otherwise refer to the RetError for the failure. 66 */ 67 virtual RetError GetFocus(const int32_t focusType, AccessibilityElementInfo &elementInfo) = 0; 68 69 /** 70 * @brief Obtains elementInfo of focus. 71 * @param sourceInfo The source info to get focus. 72 * @param focusType The type of focus. It contains FOCUS_TYPE_INPUT and FOCUS_TYPE_ACCESSIBILITY. 73 * @param elementInfo The accessibilityElementInfo of focus. 74 * @return Return RET_OK if obtains elementInfo successfully, otherwise refer to the RetError for the failure. 75 */ 76 virtual RetError GetFocusByElementInfo(const AccessibilityElementInfo &sourceInfo, const int32_t focusType, 77 AccessibilityElementInfo &elementInfo) = 0; 78 79 /** 80 * @brief Sends simulate gestures to the screen. 81 * @param gesturePath The gesture which need to send. 82 * @return Return RET_OK if the gesture sends successfully, otherwise refer to the RetError for the failure. 83 */ 84 virtual RetError InjectGesture(const std::shared_ptr<AccessibilityGestureInjectPath> &gesturePath) = 0; 85 86 /** 87 * @brief Obtains elementInfo of the accessible root node. 88 * @param elementInfo The elementInfo of the accessible root node. 89 * @return Return RET_OK if obtains elementInfo successfully, otherwise refer to the RetError for the failure. 90 */ 91 virtual RetError GetRoot(AccessibilityElementInfo &elementInfo) = 0; 92 93 /** 94 * @brief Obtains elementInfo of the accessible root node. 95 * @param windowInfo The source window info to get root. 96 * @param elementInfo The elementInfo of the accessible root node. 97 * @return Return RET_OK if obtains elementInfo successfully, otherwise refer to the RetError for the failure. 98 */ 99 virtual RetError GetRootByWindow(const AccessibilityWindowInfo &windowInfo, 100 AccessibilityElementInfo &elementInfo) = 0; 101 102 /** 103 * @brief Obtains elementInfos of the accessible root node in batchs. 104 * @param elementInfos ElementInfos of the accessible root node and its recursive subnodes. 105 * @return Return RET_OK if obtains elementInfos successfully, otherwise refer to the RetError for the failure. 106 */ 107 virtual RetError GetRootBatch(std::vector<AccessibilityElementInfo>& elementInfos) = 0; 108 109 /** 110 * @brief Obtains elementInfos of the accessible root node in batchs. 111 * @param windowInfo The source window info to get root. 112 * @param elementInfos ElementInfos of the accessible root node and its recursive subnodes. 113 * @param isFilter Indicates whether to filter nodes. 114 * @param needCut Indicates whether to remove invisible nodes. 115 * @return Return RET_OK if obtains elementInfos successfully, otherwise refer to the RetError for the failure. 116 */ 117 virtual RetError GetRootByWindowBatch(const AccessibilityWindowInfo &windowInfo, 118 std::vector<AccessibilityElementInfo>& elementInfos, bool isFilter = false, bool needCut = false) = 0; 119 120 /** 121 * @brief Get the window information related with the event 122 * @param windowId The window id. 123 * @param windowInfo The window information. 124 * @return Return RET_OK if obtains windowInfo successfully, otherwise refer to the RetError for the failure. 125 */ 126 virtual RetError GetWindow(const int32_t windowId, AccessibilityWindowInfo &windowInfo) = 0; 127 128 /** 129 * @brief Obtains the list of interactive windows on the device, in the layers they are visible to users. 130 * @param windows The information of windows. 131 * @return Return RET_OK if obtains windowInfo successfully, otherwise refer to the RetError for the failure. 132 */ 133 virtual RetError GetWindows(std::vector<AccessibilityWindowInfo> &windows) = 0; 134 135 /** 136 * @brief Obtains the list of interactive windows on the device, in the layers they are visible to users. 137 * @param displayId the id of display 138 * @param windows The information of windows. 139 * @return Return RET_OK if obtains windowInfo successfully, otherwise refer to the RetError for the failure. 140 */ 141 virtual RetError GetWindows(const uint64_t displayId, std::vector<AccessibilityWindowInfo> &windows) = 0; 142 143 /** 144 * @brief Gets the next focused node in the specified direction of the currently focused node. 145 * @param elementInfo The source info to get next info. 146 * @param direction Indicates the direction to obtain the next focused node. Refer to FocusMoveDirection 147 * @param nextElementInfo The info of next element. 148 * @return Return RET_OK if gets next elementInfo successfully, otherwise refer to the RetError for the failure. 149 */ 150 virtual RetError GetNext(const AccessibilityElementInfo &elementInfo, const FocusMoveDirection direction, 151 AccessibilityElementInfo &nextElementInfo) = 0; 152 153 /** 154 * @brief Get the child node information by child index. 155 * @param index The index of the child. 156 * @param parent The parent info to get child. 157 * @param child The element info of child. 158 * @return Return RET_OK if gets child elementInfo successfully, otherwise refer to the RetError for the failure. 159 */ 160 virtual RetError GetChildElementInfo(const int32_t index, const AccessibilityElementInfo &parent, 161 AccessibilityElementInfo &child) = 0; 162 163 /** 164 * @brief Get the children node information 165 * @param parent The parent info to get children. 166 * @param children The element info of children. 167 * @return Return RET_OK if gets children elementInfo successfully, otherwise refer to the RetError for the failure. 168 */ 169 virtual RetError GetChildren(const AccessibilityElementInfo &parent, 170 std::vector<AccessibilityElementInfo> &children) = 0; 171 172 /** 173 * @brief Searches for node information based on the specified content. 174 * @param elementInfo The source info. 175 * @param text specified content 176 * @param elementInfos The element infos of specified content. 177 * @return Return RET_OK if gets elementInfos successfully, otherwise refer to the RetError for the failure. 178 */ 179 virtual RetError GetByContent(const AccessibilityElementInfo &elementInfo, const std::string &text, 180 std::vector<AccessibilityElementInfo> &elementInfos) = 0; 181 182 /** 183 * @brief Get the node information related with the event 184 * @param eventInfo The source info to get source. 185 * @param elementInfo The element info of source. 186 * @return Return RET_OK if gets elementInfos successfully, otherwise refer to the RetError for the failure. 187 */ 188 virtual RetError GetSource(const AccessibilityEventInfo &eventInfo, AccessibilityElementInfo &elementInfo) = 0; 189 190 /** 191 * @brief Get Parent node information 192 * @param child The child element info to get parent. 193 * @param parent The parent element info. 194 * @return Return RET_OK if gets info successfully, otherwise refer to the RetError for the failure. 195 */ 196 virtual RetError GetParentElementInfo(const AccessibilityElementInfo &child, AccessibilityElementInfo &parent) = 0; 197 198 /** 199 * @brief Executes a specified action. 200 * @param elementInfo The source info to execute action. 201 * @param action: the action type 202 * @param actionArguments: The parameter for action type. such as: 203 * action: ACCESSIBILITY_ACTION_NEXT_HTML_ITEM, 204 * actionArguments(ACTION_ARGU_HTML_ELEMENT,HtmlItemType) 205 * action: ACCESSIBILITY_ACTION_PREVIOUS_HTML_ITEM, 206 * actionArguments(ACTION_ARGU_HTML_ELEMENT,HtmlItemType) 207 * action: ACCESSIBILITY_ACTION_NEXT_TEXT, 208 * actionArguments(ACTION_ARGU_MOVE_UNIT,MOVE_UNIT_XXX) 209 * action: ACCESSIBILITY_ACTION_PREVIOUS_TEXT, 210 * actionArguments(ACTION_ARGU_MOVE_UNIT,MOVE_UNIT_XXX) 211 * action: ACCESSIBILITY_ACTION_SET_SELECTION, 212 * actionArguments({ACTION_ARGU_SELECT_TEXT_START,"1"(start location)}, 213 * {ACTION_ARGU_SELECT_TEXT_END,"10"(end location)}) 214 * action: ACCESSIBILITY_ACTION_SET_TEXT, 215 * actionArguments(ACTION_ARGU_SET_TEXT,"the text of setted") 216 * @return Return RET_OK if performs action successfully, otherwise refer to the RetError for the failure. 217 */ 218 virtual RetError ExecuteAction(const AccessibilityElementInfo &elementInfo, const ActionType action, 219 const std::map<std::string, std::string> &actionArguments) = 0; 220 221 /** 222 * @brief Set target bundle names. 223 * @param targetBundleNames The target bundle name 224 * @return Return RET_OK if sets target bundle names successfully, otherwise refer to the RetError for the failure. 225 */ 226 virtual RetError SetTargetBundleName(const std::vector<std::string> &targetBundleNames) = 0; 227 228 /** 229 * @brief Set cache mode. 230 * The mode is used for functions: GetRoot, GetRootByWindow, GetChildElementInfo, 231 * GetChildren, GetSource, GetParentElementInfo. 232 * @param cacheMode The cache mode. It includes: 233 * PREFETCH_PREDECESSORS: cache the parent node info also. 234 * PREFETCH_SIBLINGS: cache the sister/brothers node info also. 235 * PREFETCH_CHILDREN: cache the child node info also. 236 * otherwise: no cache. 237 * @return Return RET_OK if sets cache mode successfully, otherwise refer to the RetError for the failure. 238 */ 239 virtual RetError SetCacheMode(const int32_t cacheMode) = 0; 240 241 /** 242 * @brief Find the node information by accessibility ID. 243 * @param accessibilityWindowId The window id that the component belongs to. 244 * @param elementId: The unique id of the component ID. 245 * @param mode PREFETCH_PREDECESSORS: Need to make the parent node info also. 246 * PREFETCH_SIBLINGS: Need to make the sister/brothers node info also. 247 * PREFETCH_CHILDREN: Need to make the child node info also. 248 * otherwise: Make the node information by elementId only. 249 * @param info[out] The components information matched conditions searched. 250 * @return Return RET_OK if search element info successfully, otherwise refer to the RetError for the failure. 251 */ 252 virtual RetError SearchElementInfoByAccessibilityId(const int32_t windowId, const int64_t elementId, 253 const uint32_t mode, AccessibilityElementInfo &info, bool isFilter = false) = 0; 254 }; 255 } // namespace Accessibility 256 } // namespace OHOS 257 #endif // ACCESSIBILITY_UI_TEST_ABILITY_H