IAbilityDelegator

```
public interface IAbilityDelegator
```
A global test utility interface used for adding IAbilityMonitor objects and control lifecycle states of abilities.
You can call addAbilityMonitor(java.lang.String) to add IAbilityMonitor objects to monitor the lifecycle states of specified abilities. You can also call method such as triggerClickEvent(ohos.aafwk.ability.Ability,ohos.agp.components.Component) to control the lifecycle states of abilities and dispatch input events.

从以下版本开始:

3

SystemCapability

SystemCapability.Aafwk#ABILITY

字段概要

字段
限定符和类型	字段	说明
`static int`	`ACTIVE`	Indicates that the ability is in the active state.
`static int`	`BACKGROUND`	Indicates that the ability is in the background state.
`static int`	`INACTIVE`	Indicates that the ability is in the inactive state.
`static int`	`INITIAL`	Indicates that the ability is in the initial state.
`static int`	`UNDEFINED`	Indicates that the lifecycle state of the ability is not defined.

方法概要

所有方法实例方法抽象方法
限定符和类型	方法	说明
`IAbilityMonitor`	`addAbilityMonitor(String abilityName)`	Creates an `IAbilityMonitor` object based on the specified ability name for monitoring the lifecycle state changes of the ability.
`void`	`clearAllMonitors()`	Clears all `IAbilityMonitor` objects saved in the memory.
`boolean`	`doAbilitySliceStart(Ability ability, AbilitySlice targetSlice)`	Starts a specified `AbilitySlice` on the specified `Ability` currently displayed on the UI.
`boolean`	`doAbilitySliceStop(Ability ability)`	Stops the active `AbilitySlice` on the specified `Ability` currently displayed on the UI.
`ShellCmdResult`	`executeShellCommand(String cmd, long timeoutSecs)`	Execute the given command in the aa tools side
`int`	`getAbilitySliceState(AbilitySlice targetSlice)`	Obtains the lifecycle state of a specified ability slice.
`int`	`getAbilityState(Ability ability)`	Obtains the lifecycle state of a specified ability.
`List<AbilitySlice>`	`getAllAbilitySlice(Ability ability)`	Obtains all ability slices of a specified ability.
`Context`	`getAppContext()`	Obtains the application context.
`AbilitySlice`	`getCurrentAbilitySlice(Ability ability)`	Obtains the top ability slice of a specified ability.
`Ability`	`getCurrentTopAbility()`	Obtains the ability that is currently being displayed.
`int`	`getMonitorsNum()`	Obtains the total number of `IAbilityMonitor` objects saved in the memory.
`int`	`getSliceStackSize(Ability ability)`	Obtains the size of the ability slice stack in a specified ability.
`String`	`getThreadName()`	Obtains the name of the current unit testing thread.
`void`	`invokeAbilityOnActive(Ability ability)`	Invokes the `Ability.onActive()` callback of a specified ability without changing its lifecycle state.
`void`	`invokeAbilityOnBackground(Ability ability)`	Invokes the `Ability.onBackground()` callback of a specified ability without changing its lifecycle state.
`void`	`invokeAbilityOnForeground(Ability ability)`	Invokes the `Ability.onForeground(ohos.aafwk.content.Intent)` callback of a specified ability without changing its lifecycle state.
`void`	`invokeAbilityOnInactive(Ability ability)`	Invokes the `Ability.onInactive()` callback of a specified ability without changing its lifecycle state.
`void`	`invokeAbilityOnPostActive(Ability ability)`	Invokes the `Ability.onPostActive()` callback of a specified ability without changing its lifecycle state.
`void`	`invokeAbilityOnPostStart(Ability ability)`	Invokes the `Ability.onPostStart(ohos.utils.PacMap)` callback of a specified ability without changing its lifecycle state.
`void`	`invokeAbilityOnStart(Ability ability)`	Invokes the `Ability.onStart(ohos.aafwk.content.Intent)` callback of a specified ability without changing its lifecycle state.
`void`	`invokeAbilityOnStop(Ability ability)`	Invokes the `Ability.onStop()` callback of a specified ability without changing its lifecycle state.
`boolean`	`isAbilityHasSlice(Ability ability)`	Checks whether a specified ability contains any ability slices.
`boolean`	`isSliceStackEmpty(Ability ability)`	Checks whether the ability slice stack in the specified ability is empty.
`void`	`print(String msg)`	Prints log information to the unit testing console.
`void`	`println(String msg)`	Prints log information to the unit testing console and automatically wraps lines.
`void`	`removeAbilityMonitor(IAbilityMonitor monitor)`	Removes a specified `IAbilityMonitor` object from the application memory.
`boolean`	`runOnUIThreadSync(Runnable task)`	Runs a specified task on the UI thread and blocks the thread until the task is complete.
`Optional<Ability>`	`startAbilitySync(Intent intent)`	Starts an ability based on the given `Intent` and waits for 2 seconds for the ability to start running before returning.
`Optional<Ability>`	`startAbilitySync(Intent intent, long timeout)`	Starts an ability based on the given `Intent` and waits for a specified time period for the ability to start running before returning.
`boolean`	`stopAbility(Ability ability)`	Destroys a specified ability.
`boolean`	`triggerClickEvent(Ability ability, Component component)`	Dispatches a click event to the specified `Component` object of the given ability and waits for it to be processed.
`boolean`	`triggerKeyEvent(Ability ability, KeyEvent keyEvent)`	Dispatches a key event to the given ability and waits for it to be processed.
`boolean`	`triggerTouchEvent(Ability ability, TouchEvent touchEvent)`	Dispatches a touch event to the given ability and waits for it to be processed.
`Optional<Ability>`	`waitAbilityMonitor(IAbilityMonitor monitor)`	Waits for and returns the `Ability` object that matches the conditions set in the given `IAbilityMonitor`.
`Optional<Ability>`	`waitAbilityMonitor(IAbilityMonitor monitor, long timeout)`	Waits for and returns the `Ability` object that matches the conditions set in the given `IAbilityMonitor` within the specified time period.

- 字段详细资料
  - ACTIVE
```
static final int ACTIVE
```
    Indicates that the ability is in the active state.
    
    从以下版本开始:
    
    3
    
    另请参阅:
    
    常量字段值
  - BACKGROUND
```
static final int BACKGROUND
```
    Indicates that the ability is in the background state.
    
    从以下版本开始:
    
    3
    
    另请参阅:
    
    常量字段值
  - INACTIVE
```
static final int INACTIVE
```
    Indicates that the ability is in the inactive state.
    
    从以下版本开始:
    
    3
    
    另请参阅:
    
    常量字段值
  - INITIAL
```
static final int INITIAL
```
    Indicates that the ability is in the initial state.
    
    从以下版本开始:
    
    3
    
    另请参阅:
    
    常量字段值
  - UNDEFINED
```
static final int UNDEFINED
```
    Indicates that the lifecycle state of the ability is not defined.
    
    从以下版本开始:
    
    3
    
    另请参阅:
    
    常量字段值
- 方法详细资料
  - waitAbilityMonitor
```
Optional<Ability> waitAbilityMonitor(IAbilityMonitor monitor)
```
    Waits for and returns the Ability object that matches the conditions set in the given IAbilityMonitor.
    If a matched ability is successfully obtained, the specified IAbilityMonitor object becomes invalid. Otherwise, you can continue to use it in waitAbilityMonitor(ohos.aafwk.ability.delegation.IAbilityMonitor) or waitAbilityMonitor(ohos.aafwk.ability.delegation.IAbilityMonitor,long) to obtain abilities.
    
    参数:
    
    monitor - Indicates the IAbilityMonitor object used for monitoring lifecycle state changes of an ability.
    
    返回:
    
    Returns an Optional object containing the Ability object if its lifecycle state has changed and it matches the given monitor; returns an empty Optional object otherwise.
    
    从以下版本开始:
    
    3
  - waitAbilityMonitor
```
Optional<Ability> waitAbilityMonitor(IAbilityMonitor monitor,
                                     long timeout)
```
    Waits for and returns the Ability object that matches the conditions set in the given IAbilityMonitor within the specified time period.
    If a matched ability is successfully obtained, the specified IAbilityMonitor object becomes invalid. Otherwise, you can continue to use it in waitAbilityMonitor(ohos.aafwk.ability.delegation.IAbilityMonitor) or waitAbilityMonitor(ohos.aafwk.ability.delegation.IAbilityMonitor,long) to obtain abilities.
    
    参数:
    
    monitor - Indicates the IAbilityMonitor object used for monitoring lifecycle state changes of an ability.
    
    timeout - Indicates the maximum amount of time to wait, in milliseconds. The value must be a positive integer.
    
    返回:
    
    Returns an Optional object containing the Ability object if its lifecycle state has changed and it matches the given monitor; returns an empty Optional object otherwise.
    
    从以下版本开始:
    
    3
  - startAbilitySync
```
Optional<Ability> startAbilitySync(Intent intent)
```
    Starts an ability based on the given Intent and waits for 2 seconds for the ability to start running before returning.
    If no ability is started within 2 seconds, an empty Optional object will be returned.
    
    参数:
    
    intent - Indicates the Intent for starting the ability.
    
    返回:
    
    Returns an Optional object containing the started Ability object if it is started successfully within 2 seconds; returns an empty Optional object otherwise.
    
    从以下版本开始:
    
    3
  - runOnUIThreadSync
```
boolean runOnUIThreadSync(Runnable task)
```
    Runs a specified task on the UI thread and blocks the thread until the task is complete.
    
    参数:
    
    task - Indicates the Runnable task to run.
    
    返回:
    
    Returns true if the task executed successfully on the UI thread; returns false otherwise.
    
    从以下版本开始:
    
    3
  - startAbilitySync
```
Optional<Ability> startAbilitySync(Intent intent,
                                   long timeout)
```
    Starts an ability based on the given Intent and waits for a specified time period for the ability to start running before returning.
    If no ability is started within the time specified by timeout, an empty Optional object will be returned.
    
    参数:
    
    intent - Indicates the Intent for starting the ability.
    
    timeout - Indicates the maximum amount of time to wait, in milliseconds. The value must be a positive integer.
    
    返回:
    
    Returns an Optional object containing the started Ability object if it is started successfully within the specified time; returns an empty Optional object otherwise.
    
    从以下版本开始:
    
    3
  - stopAbility
```
boolean stopAbility(Ability ability)
```
    Destroys a specified ability.
    
    参数:
    
    ability - Indicates the Ability object to destroy.
    
    返回:
    
    Returns true if the ability is successfully destroyed; returns false otherwise.
    
    从以下版本开始:
    
    3
  - triggerTouchEvent
```
boolean triggerTouchEvent(Ability ability,
                          TouchEvent touchEvent)
```
    Dispatches a touch event to the given ability and waits for it to be processed.
    This method is synchronous and cannot be run on the UI thread. Otherwise, the UI thread will be suspended.
    
    参数:
    
    ability - Indicates the Ability object.
    
    touchEvent - Indicates the touch event to dispatch.
    
    返回:
    
    Returns true if the touch event is successfully dispatched; returns false otherwise.
    
    从以下版本开始:
    
    3
  - triggerClickEvent
```
boolean triggerClickEvent(Ability ability,
                          Component component)
```
    Dispatches a click event to the specified Component object of the given ability and waits for it to be processed.
    This method is synchronous and cannot be run on the UI thread. Otherwise, the UI thread will be suspended.
    
    参数:
    
    ability - Indicates the Ability object.
    
    component - Indicates the component of the ability to click.
    
    返回:
    
    Returns true if the click event is successfully dispatched; returns false otherwise.
    
    从以下版本开始:
    
    3
  - triggerKeyEvent
```
boolean triggerKeyEvent(Ability ability,
                        KeyEvent keyEvent)
```
    Dispatches a key event to the given ability and waits for it to be processed.
    This method is synchronous and cannot be run on the UI thread. Otherwise, the UI thread will be suspended.
    
    参数:
    
    ability - Indicates the Ability object.
    
    keyEvent - Indicates the key event to dispatch.
    
    返回:
    
    Returns true if the key event is successfully dispatched; returns false otherwise.
    
    从以下版本开始:
    
    3
  - addAbilityMonitor
```
IAbilityMonitor addAbilityMonitor(String abilityName)
```
    Creates an IAbilityMonitor object based on the specified ability name for monitoring the lifecycle state changes of the ability.
    
    参数:
    
    abilityName - Indicates the name of the ability to monitor.
    
    返回:
    
    Returns the created IAbilityMonitor object.
    
    从以下版本开始:
    
    3
  - getMonitorsNum
```
int getMonitorsNum()
```
    Obtains the total number of IAbilityMonitor objects saved in the memory.
    
    返回:
    
    Returns the total number of IAbilityMonitor objects.
    
    从以下版本开始:
    
    3
  - clearAllMonitors
```
void clearAllMonitors()
```
    Clears all IAbilityMonitor objects saved in the memory.
    
    从以下版本开始:
    
    3
  - getAbilityState
```
int getAbilityState(Ability ability)
```
    Obtains the lifecycle state of a specified ability.
    
    参数:
    
    ability - Indicates the Ability object whose state is to be obtained.
    
    返回:
    
    Returns the state of the ability, which can be UNDEFINED and so on.
    
    从以下版本开始:
    
    3
  - removeAbilityMonitor
```
void removeAbilityMonitor(IAbilityMonitor monitor)
```
    Removes a specified IAbilityMonitor object from the application memory.
    
    参数:
    
    monitor - Indicates the IAbilityMonitor object to remove.
    
    从以下版本开始:
    
    3
  - print
```
void print(String msg)
```
    Prints log information to the unit testing console.
    The total length of the log information to be printed cannot exceed 1000 characters.
    
    参数:
    
    msg - Indicates the log information to print.
    
    从以下版本开始:
    
    3
  - println
```
void println(String msg)
```
    Prints log information to the unit testing console and automatically wraps lines.
    The total length of the log information to be printed, including the newline characters, cannot exceed 1000 characters.
    
    参数:
    
    msg - Indicates the log information to print.
    
    从以下版本开始:
    
    4
  - getCurrentTopAbility
```
Ability getCurrentTopAbility()
```
    Obtains the ability that is currently being displayed.
    
    返回:
    
    Returns the ability that is currently being displayed.
    
    从以下版本开始:
    
    3
  - doAbilitySliceStop
```
boolean doAbilitySliceStop(Ability ability)
```
    Stops the active AbilitySlice on the specified Ability currently displayed on the UI.
    Do not run this method in the UI thread. Otherwise, the UI thread will be suspended. If the specified ability has only one ability slice, this method is asynchronously executed and the ability is directly destroyed. If there are multiple ability slices in the specified ability, this method is synchronously executed. In this case, it stops the currently displayed ability slice and then activates the ability slice at the top of the AbilitySlice stack.
    
    参数:
    
    ability - Indicates the ability that hosts the ability slice to stop. This parameter cannot be null, and the ability must be in the ACTIVE state and contains at least one ability slice.
    
    返回:
    
    Returns true if the ability slice is successfully stopped; returns false otherwise.
    
    从以下版本开始:
    
    4
  - doAbilitySliceStart
```
boolean doAbilitySliceStart(Ability ability,
                            AbilitySlice targetSlice)
```
    Starts a specified AbilitySlice on the specified Ability currently displayed on the UI.
    Do not run this method in the UI thread. Otherwise, the UI thread will be suspended.
    
    参数:
    
    ability - Indicates the ability that hosts the ability slice to start. This parameter cannot be null, and the ability must be in the ACTIVE state and contains at least one ability slice.
    
    targetSlice - Indicates the target ability slice. This parameter cannot be null.
    
    返回:
    
    Returns true if the ability slice is successfully started; returns false otherwise.
    
    从以下版本开始:
    
    4
  - getAbilitySliceState
```
int getAbilitySliceState(AbilitySlice targetSlice)
```
    Obtains the lifecycle state of a specified ability slice.
    
    参数:
    
    targetSlice - Indicates the AbilitySlice object whose state is to be obtained.
    
    返回:
    
    Returns the state of the ability slice, which can be UNDEFINED and so on.
    
    从以下版本开始:
    
    3
  - getAllAbilitySlice
```
List<AbilitySlice> getAllAbilitySlice(Ability ability)
```
    Obtains all ability slices of a specified ability.
    
    参数:
    
    ability - Indicates the Ability object.
    
    返回:
    
    Returns the list of all ability slices of the specified ability.
    
    从以下版本开始:
    
    3
  - getCurrentAbilitySlice
```
AbilitySlice getCurrentAbilitySlice(Ability ability)
```
    Obtains the top ability slice of a specified ability.
    
    参数:
    
    ability - Indicates the Ability object.
    
    返回:
    
    Returns the top ability slice of the specified ability.
    
    从以下版本开始:
    
    3
  - getAppContext
```
Context getAppContext()
```
    Obtains the application context.
    
    返回:
    
    Returns the application context.
    
    从以下版本开始:
    
    4
  - getThreadName
```
String getThreadName()
```
    Obtains the name of the current unit testing thread.
    
    返回:
    
    Returns the thread name.
    
    从以下版本开始:
    
    4
  - isAbilityHasSlice
```
boolean isAbilityHasSlice(Ability ability)
```
    Checks whether a specified ability contains any ability slices.
    
    参数:
    
    ability - Indicates the Ability object to check.
    
    返回:
    
    Returns true if the ability contains ability slices; returns false otherwise.
    
    从以下版本开始:
    
    4
  - isSliceStackEmpty
```
boolean isSliceStackEmpty(Ability ability)
```
    Checks whether the ability slice stack in the specified ability is empty.
    The ability slice stack is considered empty if the ability to check contains only one or no ability slice.
    
    参数:
    
    ability - Indicates the Ability object to check.
    
    返回:
    
    Returns true if the ability slice stack is empty; returns false otherwise.
    
    从以下版本开始:
    
    4
  - getSliceStackSize
```
int getSliceStackSize(Ability ability)
```
    Obtains the size of the ability slice stack in a specified ability.
    
    参数:
    
    ability - Indicates the Ability object.
    
    返回:
    
    Returns the size of the ability slice stack.
    
    从以下版本开始:
    
    4
  - invokeAbilityOnStart
```
void invokeAbilityOnStart(Ability ability)
```
    Invokes the Ability.onStart(ohos.aafwk.content.Intent) callback of a specified ability without changing its lifecycle state.
    
    参数:
    
    ability - Indicates the Ability object.
    
    从以下版本开始:
    
    4
  - invokeAbilityOnPostStart
```
void invokeAbilityOnPostStart(Ability ability)
```
    Invokes the Ability.onPostStart(ohos.utils.PacMap) callback of a specified ability without changing its lifecycle state.
    
    参数:
    
    ability - Indicates the Ability object.
    
    从以下版本开始:
    
    4
  - invokeAbilityOnInactive
```
void invokeAbilityOnInactive(Ability ability)
```
    Invokes the Ability.onInactive() callback of a specified ability without changing its lifecycle state.
    
    参数:
    
    ability - Indicates the Ability object.
    
    从以下版本开始:
    
    4
  - invokeAbilityOnActive
```
void invokeAbilityOnActive(Ability ability)
```
    Invokes the Ability.onActive() callback of a specified ability without changing its lifecycle state.
    
    参数:
    
    ability - Indicates the Ability object.
    
    从以下版本开始:
    
    4
  - invokeAbilityOnPostActive
```
void invokeAbilityOnPostActive(Ability ability)
```
    Invokes the Ability.onPostActive() callback of a specified ability without changing its lifecycle state.
    
    参数:
    
    ability - Indicates the Ability object.
    
    从以下版本开始:
    
    4
  - invokeAbilityOnBackground
```
void invokeAbilityOnBackground(Ability ability)
```
    Invokes the Ability.onBackground() callback of a specified ability without changing its lifecycle state.
    
    参数:
    
    ability - Indicates the Ability object.
    
    从以下版本开始:
    
    4
  - invokeAbilityOnForeground
```
void invokeAbilityOnForeground(Ability ability)
```
    Invokes the Ability.onForeground(ohos.aafwk.content.Intent) callback of a specified ability without changing its lifecycle state.
    
    参数:
    
    ability - Indicates the Ability object.
    
    从以下版本开始:
    
    4
  - invokeAbilityOnStop
```
void invokeAbilityOnStop(Ability ability)
```
    Invokes the Ability.onStop() callback of a specified ability without changing its lifecycle state.
    
    参数:
    
    ability - Indicates the Ability object.
    
    从以下版本开始:
    
    4
  - executeShellCommand
```
ShellCmdResult executeShellCommand(String cmd,
                                   long timeoutSecs)
```
    Execute the given command in the aa tools side
    
    参数:
    
    cmd - Indicates the shell command to be executed.
    
    timeoutSecs - the timeout seconds
    
    返回:
    
    the command result.
    
    从以下版本开始:
    
    7

接口 IAbilityDelegator

字段概要

方法概要

字段详细资料

ACTIVE

BACKGROUND

INACTIVE

INITIAL

UNDEFINED

方法详细资料

waitAbilityMonitor

waitAbilityMonitor

startAbilitySync

runOnUIThreadSync

startAbilitySync

stopAbility

triggerTouchEvent

triggerClickEvent

triggerKeyEvent

addAbilityMonitor

getMonitorsNum

clearAllMonitors

getAbilityState

removeAbilityMonitor

print

println

getCurrentTopAbility

doAbilitySliceStop

doAbilitySliceStart

getAbilitySliceState

getAllAbilitySlice

getCurrentAbilitySlice

getAppContext

getThreadName

isAbilityHasSlice

isSliceStackEmpty

getSliceStackSize

invokeAbilityOnStart

invokeAbilityOnPostStart

invokeAbilityOnInactive

invokeAbilityOnActive

invokeAbilityOnPostActive

invokeAbilityOnBackground

invokeAbilityOnForeground

invokeAbilityOnStop

executeShellCommand