1/* 2 * Copyright (c) 2021-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 16import { AsyncCallback } from '../basic'; 17import UIAbility from '../@ohos.app.ability.UIAbility'; 18import AbilityStage from '../@ohos.app.ability.AbilityStage'; 19import { AbilityMonitor } from './AbilityMonitor'; 20import { AbilityStageMonitor } from './AbilityStageMonitor'; 21import Context from './Context'; 22import Want from "../@ohos.app.ability.Want"; 23import { ShellCmdResult } from './shellCmdResult'; 24 25/** 26 * A global test utility interface used for adding AbilityMonitor objects and control lifecycle states of abilities. 27 * @interface 28 * @syscap SystemCapability.Ability.AbilityRuntime.Core 29 * @since 9 30 */ 31export interface AbilityDelegator { 32 /** 33 * Add an AbilityMonitor object for monitoring the lifecycle state changes of the specified ability in this process. 34 * @param { AbilityMonitor } monitor - AbilityMonitor object 35 * @param { AsyncCallback<void> } callback - The callback of addAbilityMonitor. 36 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 37 * @throws { BusinessError } 16000100 - AddAbilityMonitor failed. 38 * @syscap SystemCapability.Ability.AbilityRuntime.Core 39 * @since 9 40 */ 41 addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<void>): void; 42 43 /** 44 * Add an AbilityMonitor object for monitoring the lifecycle state changes of the specified ability in this process. 45 * @param { AbilityMonitor } monitor - AbilityMonitor object 46 * @returns { Promise<void> } The promise returned by the function. 47 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 48 * @throws { BusinessError } 16000100 - AddAbilityMonitor failed. 49 * @syscap SystemCapability.Ability.AbilityRuntime.Core 50 * @since 9 51 */ 52 addAbilityMonitor(monitor: AbilityMonitor): Promise<void>; 53 54 /** 55 * Add an AbilityStageMonitor object for monitoring the lifecycle state changes of the specified abilityStage in this process. 56 * @param { AbilityStageMonitor } monitor - AbilityStageMonitor object. 57 * @param { AsyncCallback<void> } callback - The callback of addAbilityStageMonitor. 58 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 59 * @throws { BusinessError } 16000100 - AddAbilityStageMonitor failed. 60 * @syscap SystemCapability.Ability.AbilityRuntime.Core 61 * @since 9 62 */ 63 addAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback<void>): void; 64 65 /** 66 * Add an AbilityStageMonitor object for monitoring the lifecycle state changes of the specified abilityStage in this process. 67 * @param { AbilityStageMonitor } monitor - AbilityStageMonitor object. 68 * @returns { Promise<void> } The promise returned by the function. 69 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 70 * @throws { BusinessError } 16000100 - AddAbilityStageMonitor failed. 71 * @syscap SystemCapability.Ability.AbilityRuntime.Core 72 * @since 9 73 */ 74 addAbilityStageMonitor(monitor: AbilityStageMonitor): Promise<void>; 75 76 /** 77 * Remove a specified AbilityMonitor object from the application memory. 78 * @param { AbilityMonitor } monitor - AbilityMonitor object. 79 * @param { AsyncCallback<void> } callback - The callback of removeAbilityMonitor. 80 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 81 * @throws { BusinessError } 16000100 - RemoveAbilityMonitor failed. 82 * @syscap SystemCapability.Ability.AbilityRuntime.Core 83 * @since 9 84 */ 85 removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<void>): void; 86 87 /** 88 * Remove a specified AbilityMonitor object from the application memory. 89 * @param { AbilityMonitor } monitor - AbilityMonitor object. 90 * @returns { Promise<void> } The promise returned by the function. 91 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 92 * @throws { BusinessError } 16000100 - RemoveAbilityMonitor failed. 93 * @syscap SystemCapability.Ability.AbilityRuntime.Core 94 * @since 9 95 */ 96 removeAbilityMonitor(monitor: AbilityMonitor): Promise<void>; 97 98 /** 99 * Remove a specified AbilityStageMonitor object from the application memory. 100 * @param { AbilityStageMonitor } monitor - AbilityStageMonitor object. 101 * @param { AsyncCallback<void> } callback - The callback of removeAbilityStageMonitor. 102 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 103 * @throws { BusinessError } 16000100 - RemoveAbilityStageMonitor failed. 104 * @syscap SystemCapability.Ability.AbilityRuntime.Core 105 * @since 9 106 */ 107 removeAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback<void>): void; 108 109 /** 110 * Remove a specified AbilityStageMonitor object from the application memory. 111 * @param { AbilityStageMonitor } monitor - AbilityStageMonitor object. 112 * @returns { Promise<void> } The promise returned by the function. 113 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 114 * @throws { BusinessError } 16000100 - RemoveAbilityStageMonitor failed. 115 * @syscap SystemCapability.Ability.AbilityRuntime.Core 116 * @since 9 117 */ 118 removeAbilityStageMonitor(monitor: AbilityStageMonitor): Promise<void>; 119 120 /** 121 * Wait for and returns the Ability object that matches the conditions set in the given AbilityMonitor. 122 * @param { AbilityMonitor } monitor - AbilityMonitor object. 123 * @param { AsyncCallback<UIAbility> } callback - The callback is used to return the Ability object. 124 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 125 * @throws { BusinessError } 16000100 - WaitAbilityMonitor failed. 126 * @syscap SystemCapability.Ability.AbilityRuntime.Core 127 * @since 9 128 */ 129 waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<UIAbility>): void; 130 131 /** 132 * Wait for and returns the Ability object that matches the conditions set in the given AbilityMonitor. 133 * @param { AbilityMonitor } monitor - AbilityMonitor object. 134 * @param { number } timeout - Maximum wait time, in milliseconds. 135 * @param { AsyncCallback<UIAbility> } callback - The callback is used to return the Ability object. 136 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 137 * @throws { BusinessError } 16000100 - WaitAbilityMonitor failed. 138 * @syscap SystemCapability.Ability.AbilityRuntime.Core 139 * @since 9 140 */ 141 waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback<UIAbility>): void; 142 143 /** 144 * Wait for and returns the Ability object that matches the conditions set in the given AbilityMonitor. 145 * @param { AbilityMonitor } monitor - AbilityMonitor object. 146 * @param { number } timeout - Maximum wait time, in milliseconds. 147 * @returns { Promise<UIAbility> } Returns the Ability object. 148 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 149 * @throws { BusinessError } 16000100 - WaitAbilityMonitor failed. 150 * @syscap SystemCapability.Ability.AbilityRuntime.Core 151 * @since 9 152 */ 153 waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise<UIAbility>; 154 155 /** 156 * Wait for and returns the AbilityStage object that matches the conditions set in the given AbilityStageMonitor. 157 * @param { AbilityStageMonitor } monitor - AbilityStageMonitor object. 158 * @param { AsyncCallback<AbilityStage> } callback - The callback is used to return the AbilityStage object. 159 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 160 * @throws { BusinessError } 16000100 - WaitAbilityStageMonitor failed. 161 * @syscap SystemCapability.Ability.AbilityRuntime.Core 162 * @since 9 163 */ 164 waitAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback<AbilityStage>): void; 165 166 /** 167 * Wait for and returns the AbilityStage object that matches the conditions set in the given AbilityStageMonitor. 168 * @param { AbilityStageMonitor } monitor - AbilityStageMonitor object. 169 * @param { number } timeout - Maximum wait time, in milliseconds. 170 * @param { AsyncCallback<AbilityStage> } callback - The callback is used to return the AbilityStage object. 171 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 172 * @throws { BusinessError } 16000100 - WaitAbilityStageMonitor failed. 173 * @syscap SystemCapability.Ability.AbilityRuntime.Core 174 * @since 9 175 */ 176 waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout: number, callback: AsyncCallback<AbilityStage>): void; 177 178 /** 179 * Wait for and returns the AbilityStage object that matches the conditions set in the given AbilityStageMonitor. 180 * @param { AbilityStageMonitor } monitor - AbilityStageMonitor object. 181 * @param { number } timeout - Maximum wait time, in milliseconds. 182 * @returns { Promise<AbilityStage> } Returns the AbilityStage object. 183 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 184 * @throws { BusinessError } 16000100 - WaitAbilityStageMonitor failed. 185 * @syscap SystemCapability.Ability.AbilityRuntime.Core 186 * @since 9 187 */ 188 waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout?: number): Promise<AbilityStage>; 189 190 /** 191 * Obtain the application context. 192 * @returns { Context } Returns the app Context. 193 * @syscap SystemCapability.Ability.AbilityRuntime.Core 194 * @since 9 195 */ 196 getAppContext(): Context; 197 198 /** 199 * Obtain the lifecycle state of a specified ability. 200 * @param { UIAbility } ability - The Ability object. 201 * @returns { number } Returns the state of the Ability object. 202 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 203 * @syscap SystemCapability.Ability.AbilityRuntime.Core 204 * @since 9 205 */ 206 getAbilityState(ability: UIAbility): number; 207 208 /** 209 * Obtain the ability that is currently being displayed in this process. 210 * @param { AsyncCallback<UIAbility> } callback - The callback is used to return the Ability object. 211 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 212 * @throws { BusinessError } 16000100 - GetCurrentTopAbility failed. 213 * @syscap SystemCapability.Ability.AbilityRuntime.Core 214 * @since 9 215 */ 216 getCurrentTopAbility(callback: AsyncCallback<UIAbility>): void; 217 218 /** 219 * Obtain the ability that is currently being displayed in this process. 220 * @returns { Promise<UIAbility> } Returns the Ability object. 221 * @throws { BusinessError } 16000100 - GetCurrentTopAbility failed. 222 * @syscap SystemCapability.Ability.AbilityRuntime.Core 223 * @since 9 224 */ 225 getCurrentTopAbility(): Promise<UIAbility> 226 227 /** 228 * Start a new ability. 229 * @param { Want } want - Indicates the ability to start 230 * @param { AsyncCallback<void> } callback - The callback of startAbility. 231 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 232 * @throws { BusinessError } 16000001 - The specified ability does not exist. 233 * @throws { BusinessError } 16000002 - Incorrect ability type. 234 * @throws { BusinessError } 16000004 - Can not start invisible component. 235 * @throws { BusinessError } 16000005 - The specified process does not have the permission. 236 * @throws { BusinessError } 16000006 - Cross-user operations are not allowed. 237 * @throws { BusinessError } 16000008 - The crowdtesting application expires. 238 * @throws { BusinessError } 16000009 - An ability cannot be started or stopped in Wukong mode. 239 * @throws { BusinessError } 16000010 - The call with the continuation flag is forbidden. 240 * @throws { BusinessError } 16000011 - The context does not exist. 241 * @throws { BusinessError } 16000050 - Internal error. 242 * @throws { BusinessError } 16000053 - The ability is not on the top of the UI. 243 * @throws { BusinessError } 16000055 - Installation-free timed out. 244 * @throws { BusinessError } 16200001 - The caller has been released. 245 * @syscap SystemCapability.Ability.AbilityRuntime.Core 246 * @since 9 247 */ 248 startAbility(want: Want, callback: AsyncCallback<void>): void; 249 250 /** 251 * Start a new ability. 252 * @param { Want } want - Indicates the ability to start 253 * @returns { Promise<void> } The promise returned by the function. 254 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 255 * @throws { BusinessError } 16000001 - The specified ability does not exist. 256 * @throws { BusinessError } 16000002 - Incorrect ability type. 257 * @throws { BusinessError } 16000004 - Can not start invisible component. 258 * @throws { BusinessError } 16000005 - The specified process does not have the permission. 259 * @throws { BusinessError } 16000006 - Cross-user operations are not allowed. 260 * @throws { BusinessError } 16000008 - The crowdtesting application expires. 261 * @throws { BusinessError } 16000009 - An ability cannot be started or stopped in Wukong mode. 262 * @throws { BusinessError } 16000010 - The call with the continuation flag is forbidden. 263 * @throws { BusinessError } 16000011 - The context does not exist. 264 * @throws { BusinessError } 16000050 - Internal error. 265 * @throws { BusinessError } 16000053 - The ability is not on the top of the UI. 266 * @throws { BusinessError } 16000055 - Installation-free timed out. 267 * @throws { BusinessError } 16200001 - The caller has been released. 268 * @syscap SystemCapability.Ability.AbilityRuntime.Core 269 * @since 9 270 */ 271 startAbility(want: Want): Promise<void>; 272 273 /** 274 * Invoke the Ability.onForeground() callback of a specified ability without changing its lifecycle state. 275 * @param { UIAbility } ability - The ability object. 276 * @param { AsyncCallback<void> } callback - The callback of doAbilityForeground. 277 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 278 * @throws { BusinessError } 16000100 - DoAbilityForeground failed. 279 * @syscap SystemCapability.Ability.AbilityRuntime.Core 280 * @since 9 281 */ 282 doAbilityForeground(ability: UIAbility, callback: AsyncCallback<void>): void; 283 284 /** 285 * Invoke the Ability.onForeground() callback of a specified ability without changing its lifecycle state. 286 * @param { UIAbility } ability - The ability object. 287 * @returns { Promise<void> } The promise returned by the function. 288 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 289 * @throws { BusinessError } 16000100 - DoAbilityForeground failed. 290 * @syscap SystemCapability.Ability.AbilityRuntime.Core 291 * @since 9 292 */ 293 doAbilityForeground(ability: UIAbility): Promise<void>; 294 295 /** 296 * Invoke the Ability.onBackground() callback of a specified ability without changing its lifecycle state. 297 * @param { UIAbility } ability - The ability object. 298 * @param { AsyncCallback<void> } callback - The callback of doAbilityBackground. 299 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 300 * @throws { BusinessError } 16000100 - DoAbilityBackground failed. 301 * @syscap SystemCapability.Ability.AbilityRuntime.Core 302 * @since 9 303 */ 304 doAbilityBackground(ability: UIAbility, callback: AsyncCallback<void>): void; 305 306 /** 307 * Invoke the Ability.onBackground() callback of a specified ability without changing its lifecycle state. 308 * @param { UIAbility } ability - The ability object. 309 * @returns { Promise<void> } The promise returned by the function. 310 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 311 * @throws { BusinessError } 16000100 - DoAbilityBackground failed. 312 * @syscap SystemCapability.Ability.AbilityRuntime.Core 313 * @since 9 314 */ 315 doAbilityBackground(ability: UIAbility): Promise<void>; 316 317 /** 318 * Prints log information to the unit testing console. 319 * The total length of the log information to be printed cannot exceed 1000 characters. 320 * @param msg Log information 321 * @param { AsyncCallback<void> } callback - The callback of print. 322 * @syscap SystemCapability.Ability.AbilityRuntime.Core 323 * @since 8 324 */ 325 print(msg: string, callback: AsyncCallback<void>): void; 326 327 /** 328 * Prints log information to the unit testing console. 329 * The total length of the log information to be printed cannot exceed 1000 characters. 330 * @param msg Log information 331 * @returns { Promise<void> } The promise returned by the function. 332 * @syscap SystemCapability.Ability.AbilityRuntime.Core 333 * @since 8 334 */ 335 print(msg: string): Promise<void>; 336 337 /** 338 * Prints log information to the unit testing console. 339 * The total length of the log information to be printed cannot exceed 1000 characters. 340 * @param { string } msg - Log information. 341 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 342 * @syscap SystemCapability.Ability.AbilityRuntime.Core 343 * @since 9 344 */ 345 printSync(msg: string): void; 346 347 /** 348 * Execute the given command in the aa tools side. 349 * @param cmd Shell command 350 * @param { AsyncCallback<void> } callback - The callback of executeShellCommand. 351 * @syscap SystemCapability.Ability.AbilityRuntime.Core 352 * @since 8 353 */ 354 executeShellCommand(cmd: string, callback: AsyncCallback<ShellCmdResult>): void; 355 356 /** 357 * Execute the given command in the aa tools side. 358 * @param cmd Shell command 359 * @param timeoutSecs Timeout, in seconds 360 * @param { AsyncCallback<void> } callback - The callback of executeShellCommand. 361 * @syscap SystemCapability.Ability.AbilityRuntime.Core 362 * @since 8 363 */ 364 executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback<ShellCmdResult>): void; 365 366 /** 367 * Execute the given command in the aa tools side. 368 * @param cmd Shell command 369 * @param timeoutSecs Timeout, in seconds 370 * @returns ShellCmdResult object 371 * @syscap SystemCapability.Ability.AbilityRuntime.Core 372 * @since 8 373 */ 374 executeShellCommand(cmd: string, timeoutSecs?: number): Promise<ShellCmdResult>; 375 376 /** 377 * Finish the test and print log information to the unit testing console. 378 * The total length of the log information to be printed cannot exceed 1000 characters. 379 * @param { string } msg - Log information. 380 * @param { number } code - Result code. 381 * @param { AsyncCallback<void> } callback - The callback of finishTest. 382 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 383 * @throws { BusinessError } 16000100 - FinishTest failed. 384 * @syscap SystemCapability.Ability.AbilityRuntime.Core 385 * @since 9 386 */ 387 finishTest(msg: string, code: number, callback: AsyncCallback<void>): void; 388 389 /** 390 * Finish the test and print log information to the unit testing console. 391 * The total length of the log information to be printed cannot exceed 1000 characters. 392 * @param { string } msg - Log information. 393 * @param { number } code - Result code. 394 * @returns { Promise<void> } The promise returned by the function. 395 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 396 * @throws { BusinessError } 16000100 - FinishTest failed. 397 * @syscap SystemCapability.Ability.AbilityRuntime.Core 398 * @since 9 399 */ 400 finishTest(msg: string, code: number): Promise<void>; 401} 402 403export default AbilityDelegator; 404