@ohos.UiTest

The UiTest module provides APIs that you can use to simulate UI actions during testing, such as clicks, double-clicks, long-clicks, and swipes.

This module provides the following functions:

• On⁹⁺: provides UI component feature description APIs for component filtering and matching.
• Component⁹⁺: represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection.
• Driver⁹⁺: works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot.
• UiWindow⁹⁺: works as the entry class and provides APIs for obtaining window attributes, dragging windows, and adjusting window sizes.
• By^(deprecated): provides UI component feature description APIs for component filtering and matching. This class is deprecated since API version 9. You are advised to use On⁹⁺ instead.
• UiComponent^(deprecated): represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. This class is deprecated since API version 9. You are advised to use Component⁹⁺ instead.
• UiDriver^(deprecated): works as the entry class and provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. This class is deprecated since API version 9. You are advised to use Driver⁹⁺ instead.

NOTE

• The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• The APIs of this module can be used only in arkxtest.
• The APIs of this module do not support concurrent calls.
• The APIs of this module can be used on mobile phones, tablets, 2-in-1 devices, and smart wearable devices.

Modules to Import

import { UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton, UIElementInfo, UIEventObserver } from '@kit.TestKit';

MatchPattern

Enumerates the match patterns supported for component attributes.

System capability: SystemCapability.Test.UiTest

ResizeDirection⁹⁺

Enumerates the directions in which a window can be resized.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Point⁹⁺

Provides the coordinates of a point.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Rect⁹⁺

Provides bounds information of a component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

WindowMode⁹⁺

Enumerates the window modes.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

DisplayRotation⁹⁺

Describes the display rotation of the device.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

WindowFilter⁹⁺

Provides the flag attributes of this window.

System capability: SystemCapability.Test.UiTest

UiDirection¹⁰⁺

Describes the direction of a UI operation such as fling.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

MouseButton¹⁰⁺

Describes the injected simulated mouse button.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

UIElementInfo¹⁰⁺

Provides information about the UI event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

TouchPadSwipeOptions¹⁸⁺

Describes information about the touchpad swipe gesture option.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

On⁹⁺

Since API version 9, the UiTest framework provides a wide range of UI component feature description APIs in the On class to filter and match components.
The APIs provided by the On class exhibit the following features:
1. Allow one or more attributes as the match conditions. For example, you can specify both the text and id attributes to find the target component.
2. Provide multiple match patterns for component attributes.
3. Support absolute positioning and relative positioning for components. APIs such as ON.isBefore and ON.isAfter can be used to specify the features of adjacent components to assist positioning.
All APIs provided in the On class are synchronous. You are advised to use the static constructor ON to create an On object in chain mode.

import { ON } from '@kit.TestKit';

ON.text('123').type('Button');

text⁹⁺

text(txt: string, pattern?: MatchPattern): On

Specifies the text attribute of the target component. Multiple match patterns are supported.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.text('123'); // Use the static constructor ON to create an On object and specify the text attribute of the target component.

id⁹⁺

id(id: string): On

Specifies the ID attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';

let on:On = ON.id('123'); // Use the static constructor ON to create an On object and specify the id attribute of the target component.

id¹⁸⁺

id(id: string, pattern?: MatchPattern): On

Specifies the ID attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { MatchPattern, On, ON } from '@kit.TestKit';
let on:On = ON.id('id', MatchPattern.REG_EXP_ICASE) // Use case-insensitive regular expression to match the ID attribute value of the component.

type⁹⁺

type(tp: string): On

Specifies the type attribute of the target component.

NOTE

You can define the type of the component. In addition, you can use DevEco Testing to query the type information of the component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.type('Button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component.

type¹⁸⁺

type(tp: string, pattern?: MatchPattern): On

Specifies the type attribute of the target component.

NOTE

You can define the type of the component. In addition, you can use DevEco Testing to query the type information of the component.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.type('Button'); // Use the static constructor ON to create an On object and specify the type attribute of the target component.

clickable⁹⁺

clickable(b?: boolean): On

Specifies the clickable attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.clickable(true); // Use the static constructor ON to create an On object and specify the clickable attribute of the target component.

longClickable⁹⁺

longClickable(b?: boolean): On

Specifies the long-clickable attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.longClickable(true); // Use the static constructor ON to create an On object and specify the longClickable attribute of the target component.

scrollable⁹⁺

scrollable(b?: boolean): On

Specifies the scrollable attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.scrollable(true); // Use the static constructor ON to create an On object and specify the scrollable attribute of the target component.

enabled⁹⁺

enabled(b?: boolean): On

Specifies the enabled attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.enabled(true); // Use the static constructor ON to create an On object and specify the enabled attribute of the target component.

focused⁹⁺

focused(b?: boolean): On

Specifies the focused attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.focused(true); // Use the static constructor ON to create an On object and specify the focused attribute of the target component.

selected⁹⁺

selected(b?: boolean): On

Specifies the selected attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.selected(true); // Use the static constructor ON to create an On object and specify the selected attribute of the target component.

checked⁹⁺

checked(b?: boolean): On

Specifies the checked attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.checked(true); // Use the static constructor ON to create an On object and specify the checked attribute of the target component.

checkable⁹⁺

checkable(b?: boolean): On

Specifies the checkable attribute of the target component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.checkable(true); // Use the static constructor ON to create an On object and specify the checkable attribute of the target component.

isBefore⁹⁺

isBefore(on: On): On

Specifies that the target component is located before the given attribute component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';

// Use the static constructor ON to create an On object and specify that the target component is located before the given attribute component.
let on:On = ON.type('Button').isBefore(ON.text('123')); // Search for the first <Button> component located before the component whose text is 123.

isAfter⁹⁺

isAfter(on: On): On

Specifies that the target component is located after the given attribute component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';

// Use the static constructor ON to create an On object and specify that the target component is located after the given attribute component.
let on:On = ON.type('Text').isAfter(ON.text('123'))  // Search for the first <Text> component located after the component whose text is 123.

within¹⁰⁺

within(on: On): On

Specifies that the target component is located within the given attribute component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
// Use the static constructor ON to create an On object and specify that the target component is located within the given attribute component.
let on:On = ON.text('java').within(ON.type('Scroll'));  // Search for the child component whose text is java within the <Scroller> component.

inWindow¹⁰⁺

inWindow(bundleName: string): On;

Specifies that the target component is located within the given application window.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.inWindow('com.uitestScene.acts'); // Use the static constructor ON to create an On object and specify that the target component is located within the given application window.

description¹¹⁺

description(val: string, pattern?: MatchPattern): On

Specifies the description of the target component. Multiple match patterns are supported.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { On, ON } from '@kit.TestKit';
let on:On = ON.description('123'); // Use the static constructor ON to create an On object and specify the description attribute of the target component.

hint¹⁸⁺

hint(val: string, pattern?: MatchPattern): On

Obtains the component object of the specified hint text and returns the On object.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

 import { MatchPattern, On, ON } from '@kit.TestKit';
 
 let on:On = ON.hint('welcome', MatchPattern.EQUALS); // Use the static constructor ON to create an On object with the hint text attribute of the target component specified.

Component⁹⁺

Represents a component on the UI and provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection. All APIs provided in this class use a promise to return the result and must be invoked using await.

click⁹⁺

click(): Promise<void>

Clicks this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Driver, ON, Component } from '@kit.TestKit';
async function demo() {
  let driver:Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  await button.click();
}

doubleClick⁹⁺

doubleClick(): Promise<void>

Double-clicks this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import {Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  await button.doubleClick();
}

longClick⁹⁺

longClick(): Promise<void>

Long-clicks this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  await button.longClick();
}

getId⁹⁺

getId(): Promise<string>

Obtains the ID of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let id = await button.getId();
}

getText⁹⁺

getText(): Promise<string>

Obtains the text information of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let text = await button.getText();
}

getType⁹⁺

getType(): Promise<string>

Obtains the type of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let type = await button.getType();
}

getBounds⁹⁺

getBounds(): Promise<Rect>

Obtains the bounds of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let rect = await button.getBounds();
}

getBoundsCenter⁹⁺

getBoundsCenter(): Promise<Point>

Obtains the information about the center of the bounding box around this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let point = await button.getBoundsCenter();
}

isClickable⁹⁺

isClickable(): Promise<boolean>

Obtains the clickable status of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  if(await button.isClickable()) {
    console.info('This button can be Clicked');
  } else {
    console.info('This button can not be Clicked');
  }
}

isLongClickable⁹⁺

isLongClickable(): Promise<boolean>

Obtains the long-clickable status of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  if(await button.isLongClickable()) {
    console.info('This button can longClick');
  } else {
    console.info('This button can not longClick');
  }
}

isChecked⁹⁺

isChecked(): Promise<boolean>

Obtains the checked status of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let checkBox: Component = await driver.findComponent(ON.type('Checkbox'));
  if(await checkBox.isChecked()) {
    console.info('This checkBox is checked');
  } else {
    console.info('This checkBox is not checked');
  }
}

isCheckable⁹⁺

isCheckable(): Promise<boolean>

Obtains the checkable status of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let checkBox: Component = await driver.findComponent(ON.type('Checkbox'));
  if(await checkBox.isCheckable()) {
    console.info('This checkBox is checkable');
  } else {
    console.info('This checkBox is not checkable');
  }
}

isScrollable⁹⁺

isScrollable(): Promise<boolean>

Obtains the scrollable status of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = await driver.findComponent(ON.scrollable(true));
  if(await scrollBar.isScrollable()) {
    console.info('This scrollBar can be operated');
  } else {
    console.info('This scrollBar can not be operated');
  }
}

isEnabled⁹⁺

isEnabled(): Promise<boolean>

Obtains the enabled status of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  if(await button.isEnabled()) {
    console.info('This button can be operated');
  } else {
    console.info('This button can not be operated');
  }
}

isFocused⁹⁺

isFocused(): Promise<boolean>

Obtains the focused status of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  if(await button.isFocused()) {
    console.info('This button is focused');
  } else {
    console.info('This button is not focused');
  }
}

isSelected⁹⁺

isSelected(): Promise<boolean>

Obtains the selected status of this component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  if(await button.isSelected()) {
    console.info('This button is selected');
  } else {
    console.info('This button is not selected');
  }
}

inputText⁹⁺

inputText(text: string): Promise<void>

Inputs text to a component after the original text in the component is cleared. This API is applicable to text box components.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let text: Component = await driver.findComponent(ON.text('hello world'));
  await text.inputText('123');
}

clearText⁹⁺

clearText(): Promise<void>

Clears text in this component. This API is applicable to text boxes.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Error codes For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let text: Component = await driver.findComponent(ON.text('hello world'));
  await text.clearText();
}

scrollSearch⁹⁺

scrollSearch(on: On): Promise<Component>

Scrolls on this component to search for the target component. This API is applicable to components that support scrolling and uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = await driver.findComponent(ON.type('Scroll'));
  let button = await scrollBar.scrollSearch(ON.text('next page'));
}

scrollSearch¹⁸⁺

scrollSearch(on: On, vertical?: boolean, offset?: number): Promise<Component>

Scrolls on this component to search for the target component. This API is applicable to components that support scrolling and uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the following error codes, see Universal Error Codes and Uitest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = await driver.findComponent(ON.type('Scroll'));
  let button = await scrollBar.scrollSearch(ON.text('next page'));
}

scrollToTop⁹⁺

scrollToTop(speed?: number): Promise<void>

Scrolls to the top of this component. This API is applicable to components that support scrolling.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = await driver.findComponent(ON.type('Scroll'));
  await scrollBar.scrollToTop();
}

scrollToBottom⁹⁺

scrollToBottom(speed?: number): Promise<void>

Scrolls to the bottom of this component. This API is applicable to components that support scrolling.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let scrollBar: Component = await driver.findComponent(ON.type('Scroll'));
  await scrollBar.scrollToBottom();
}

dragTo⁹⁺

dragTo(target: Component): Promise<void>

Drags this component to the target component.

NOTE

This API takes effect only on phones, tablets, and 2-in-1 devices.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let text: Component = await driver.findComponent(ON.text('hello world'));
  await button.dragTo(text);
}

pinchOut⁹⁺

pinchOut(scale: number): Promise<void>

Pinches a component to scale it up to the specified ratio.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let image: Component = await driver.findComponent(ON.type('Image'));
  await image.pinchOut(1.5);
}

pinchIn⁹⁺

pinchIn(scale: number): Promise<void>

Pinches a component to scale it down to the specified ratio.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let image: Component = await driver.findComponent(ON.type('Image'));
  await image.pinchIn(0.5);
}

getDescription¹¹⁺

getDescription(): Promise<string>

Obtains the description of this component. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('Button'));
  let description = await button.getDescription();
}

getHint¹⁸⁺

getHint(): Promise<string>

Obtains the hint text of a component object. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.type('TextInput'));
  let hints = await button.getHint();
}

Driver⁹⁺

The Driver class is the main entry to the UiTest framework. It provides APIs for features such as component matching/search, key injection, coordinate clicking/sliding, and screenshot. All APIs provided by this class, except Driver.create(), use a promise to return the result and must be invoked using await.

create⁹⁺

static create(): Driver

Creates a Driver object and returns the object created. This API is a static API.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
}

delayMs⁹⁺

delayMs(duration: number): Promise<void>

Delays this Driver object within the specified duration.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.delayMs(1000);
}

findComponent⁹⁺

findComponent(on: On): Promise<Component>

Searches this Driver object for the target component that matches the given attributes.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.findComponent(ON.text('next page'));
}

findComponents⁹⁺

findComponents(on: On): Promise<Array<Component>>

Searches this Driver object for all components that match the given attributes.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let buttonList: Array<Component> = await driver.findComponents(ON.text('next page'));
}

findWindow⁹⁺

findWindow(filter: WindowFilter): Promise<UiWindow>

Searches for the window that matches the specified attributes.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver, UiWindow } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let window: UiWindow = await driver.findWindow({actived: true});
}

waitForComponent⁹⁺

waitForComponent(on: On, time: number): Promise<Component>

Searches this Driver object for the target component that matches the given attributes within the specified duration.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let button: Component = await driver.waitForComponent(ON.text('next page'),500);
}

assertComponentExist⁹⁺

assertComponentExist(on: On): Promise<void>

Asserts that a component that matches the given attributes exists on the current page.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.assertComponentExist(ON.text('next page'));
}

pressBack⁹⁺

pressBack(): Promise<void>

Presses the Back button on this Driver object.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.pressBack();
}

triggerKey⁹⁺

triggerKey(keyCode: number): Promise<void>

Triggers the key of this Driver object that matches the given key code.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.triggerKey(123);
}

triggerCombineKeys⁹⁺

triggerCombineKeys(key0: number, key1: number, key2?: number): Promise<void>

Triggers a key combination based on the specified key values. For example, if the value of Key is (2072, 2019), the Driver object finds and clicks the key combination that matches the value, for example, Ctrl+C.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.triggerCombineKeys(2072, 2047, 2035);
}

click⁹⁺

click(x: number, y: number): Promise<void>

Clicks a specific point of this Driver object based on the given coordinates.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.click(100,100);
}

doubleClick⁹⁺

doubleClick(x: number, y: number): Promise<void>

Double-clicks a specific point of this Driver object based on the given coordinates.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.doubleClick(100,100);
}

longClick⁹⁺

longClick(x: number, y: number): Promise<void>

Long-clicks a specific point of this Driver object based on the given coordinates.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.longClick(100,100);
}

swipe⁹⁺

swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise<void>

Swipes on this Driver object from the given start point to the given end point.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.swipe(100,100,200,200,600);
}

drag⁹⁺

drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise<void>

Drags this Driver object from the given start point to the given end point.

NOTE

This API takes effect only on phones, tablets, and 2-in-1 devices.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.drag(100,100,200,200,600);
}

screenCap⁹⁺

screenCap(savePath: string): Promise<boolean>

Captures the current screen of this Driver object and saves it as a PNG image to the given save path. This API can be used in scenarios where screenshots are supported.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.screenCap('/data/storage/el2/base/cache/1.png');
}

setDisplayRotation⁹⁺

setDisplayRotation(rotation: DisplayRotation): Promise<void>

Sets the display rotation of the current scene. It applies to rotatable scenarios.

NOTE

This API takes effect only on phones, tablets, and 2-in-1 devices.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver, DisplayRotation } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.setDisplayRotation(DisplayRotation.ROTATION_180);
}

getDisplayRotation⁹⁺

getDisplayRotation(): Promise<DisplayRotation>

Obtains the display rotation of the current device.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { DisplayRotation, Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let rotation: DisplayRotation = await driver.getDisplayRotation();
}

setDisplayRotationEnabled⁹⁺

setDisplayRotationEnabled(enabled: boolean): Promise<void>

Enables or disables display rotation.

NOTE

This API takes effect only on phones, tablets, and 2-in-1 devices.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.setDisplayRotationEnabled(false);
}

getDisplaySize⁹⁺

getDisplaySize(): Promise<Point>

Obtains the display size of the current device.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Driver, } from '@kit.TestKit';

async function demo() {
  let driver: Driver = Driver.create();
  let size = await driver.getDisplaySize();
}

getDisplayDensity⁹⁺

getDisplayDensity(): Promise<Point>

Obtains the display density of the current device.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let density = await driver.getDisplayDensity();
}

wakeUpDisplay⁹⁺

wakeUpDisplay(): Promise<void>

Wakes up the device display.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.wakeUpDisplay();
}

pressHome⁹⁺

pressHome(): Promise<void>

Returns to the home screen.

NOTE

This API takes effect only on phones, tablets, and 2-in-1 devices.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.pressHome();
}

waitForIdle⁹⁺

waitForIdle(idleTime: number, timeout: number): Promise<boolean>

Checks whether all components on the current page are idle.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let idled:boolean = await driver.waitForIdle(4000,5000);
}

fling⁹⁺

fling(from: Point, to: Point, stepLen: number, speed: number): Promise<void>

Simulates a fling operation on the screen.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.fling({x: 500, y: 480},{x: 450, y: 480},5,600);
}

injectMultiPointerAction⁹⁺

injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise<boolean>

Injects a multi-touch operation to the device.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver, PointerMatrix } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let pointers: PointerMatrix = PointerMatrix.create(2,5);
  pointers.setPoint(0,0,{x:250,y:480});
  pointers.setPoint(0,1,{x:250,y:440});
  pointers.setPoint(0,2,{x:250,y:400});
  pointers.setPoint(0,3,{x:250,y:360});
  pointers.setPoint(0,4,{x:250,y:320});
  pointers.setPoint(1,0,{x:250,y:480});
  pointers.setPoint(1,1,{x:250,y:440});
  pointers.setPoint(1,2,{x:250,y:400});
  pointers.setPoint(1,3,{x:250,y:360});
  pointers.setPoint(1,4,{x:250,y:320});
  await driver.injectMultiPointerAction(pointers);
}

fling¹⁰⁺

fling(direction: UiDirection, speed: number): Promise<void>;

Simulates a fling operation on the screen, in the specified direction and speed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver, UiDirection } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.fling(UiDirection.DOWN, 10000);
}

screenCapture¹⁰⁺

screenCapture(savePath: string, rect?: Rect): Promise<boolean>;

Captures the specified area of the current screen and saves the captured screenshot as a PNG image to the specified path. This API can be used in scenarios where screenshots are supported.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.screenCapture('/data/storage/el2/base/cache/1.png', {left: 0, top: 0, right: 100, bottom: 100});
}

mouseClick¹⁰⁺

mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise<void>;

Injects a mouse click at the specified coordinates, with the optional key or key combination. For example, if the value of key1 is 2072, the Ctrl button is pressed with the mouse click.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver,MouseButton } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072);
}

mouseScroll¹⁰⁺

mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): Promise<void>;

Injects a mouse scroll action at the specified coordinates, with the optional key or key combination. For example, if the value of key1 is 2072, the Ctrl button is pressed with mouse scrolling.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseScroll({x:360, y:640}, true, 30, 2072)
}

mouseMoveTo¹⁰⁺

mouseMoveTo(p: Point): Promise<void>;

Moves the cursor to the end point.

System capability: SystemCapability.Test.UiTest

Atomic service API: This API can be used in atomic services since API version 11.

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseMoveTo({x:100, y:100})
}

createUIEventObserver¹⁰⁺

createUIEventObserver(): UIEventObserver;

Creates a UI event listener.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

For details about the error codes, see UiTest Error Codes.

Example

import { Driver, UIEventObserver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let observer: UIEventObserver = await driver.createUIEventObserver()
}

mouseScroll¹¹⁺

mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number, speed?: number): Promise<void>

Injects a mouse scroll action at the specified coordinates. You can specify the key or key combination to work with the action, as well as the scroll speed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseScroll({x:360, y:640}, true, 30, 2072,20)
}

mouseDoubleClick¹¹⁺

mouseDoubleClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise<void>

Injects a double-click action at the specified coordinates, with the optional key or key combination. For example, if the value of key is 2072, the Ctrl button is pressed with the double-click.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver,MouseButton } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseDoubleClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072);
}

mouseLongClick¹¹⁺

mouseLongClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise<void>

Injects a long-click action of the mouse device at the specified coordinates, with the optional key or key combination. For example, if the value of Key is 2072, the Ctrl button is long-clicked with the mouse device.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver,MouseButton } from '@kit.TestKit';
async function demo() {
  let driver:Driver = Driver.create();
  await driver.mouseLongClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072);
}

mouseMoveWithTrack¹¹⁺

mouseMoveWithTrack(from: Point, to: Point, speed?: number): Promise<void>

Moves the mouse pointer from the start point to the end point.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseMoveWithTrack({x:100, y:100},{x:200, y:200},600);
}

mouseDrag¹¹⁺

mouseDrag(from: Point, to: Point, speed?: number): Promise<void>

Drags the mouse pointer from the start point to the end point.

NOTE

This API takes effect only on phones, tablets, and 2-in-1 devices.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.mouseDrag({x:100, y:100},{x:200, y:200},600);
}

inputText¹¹⁺

inputText(p: Point, text: string): Promise<void>

Inputs text at a specified coordinate without clearing the original text in the component.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { Component, Driver, ON } from '@kit.TestKit';
async function demo() {
  let driver:Driver = Driver.create();
  let text: Component = await driver.findComponent(ON.type('TextInput'));
  let point = await text.getBoundsCenter();
  await driver.inputText(point, '123');
}

touchPadMultiFingerSwipe¹⁸⁺

touchPadMultiFingerSwipe(fingers: number, direction: UiDirection, options?: TouchPadSwipeOptions): Promise<void>

Simulates a multi-finger swipe gesture on the touchpad. This API uses a promise to return the result.

NOTE

This API takes effect only on 2-in-1 devices.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the following error codes, see Universal Error Codes and Uitest Error Codes.

Example

import { Driver, UiDirection } from '@kit.TestKit';
async function demo() {
  let driver:Driver = Driver.create();
  await driver.touchPadMultiFingerSwipe(3, UiDirection.UP);
}

penClick¹⁸⁺

penClick(point: Point): Promise<void>

Simulates a pen click. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the following error codes, see Universal Error Codes and Uitest Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.penClick({x: 100, y: 100});
}

penLongClick¹⁸⁺

penLongClick(point: Point, pressure?: number): Promise<void>

Simulates a pen long-click. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the following error codes, see Universal Error Codes and Uitest Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.penLongClick({x: 100, y: 100}, 0.5);
}

penDoubleClick¹⁸⁺

penDoubleClick(point: Point): Promise<void>

Simulates a pen double-click. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the following error codes, see Universal Error Codes and Uitest Error Codes.

Example

import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.penDoubleClick({x: 100, y: 100});
}

penSwipe¹⁸⁺

penSwipe(startPoint: Point, endPoint: Point, speed?: number, pressure?: number): Promise<void>

Simulates a pen swipe. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the following error codes, see Universal Error Codes and Uitest Error Codes.

Example

 import { Driver } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  await driver.penSwipe({x: 100, y: 100}, {x: 100, y: 500}, 600, 0.5);
}

injectPenPointerAction¹⁸⁺

injectPenPointerAction(pointers: PointerMatrix, speed?: number, pressure?: number): Promise<void>

Simulates a continuous multi-point pen injection. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the following error codes, see Universal Error Codes and Uitest Error Codes.

Example

import { Driver, PointerMatrix } from '@kit.TestKit';
async function demo() {
  let driver: Driver = Driver.create();
  let pointer = PointerMatrix.create(1,8);
  for (let step = 0; step < 8; step++) {
    pointer.setPoint(0, step, {x: 500, y: 1100 - 100 *step});
  }
  await driver.injectPenPointerAction(pointer, 600, 0.5);
}

PointerMatrix⁹⁺

Implements a PointerMatrix object that stores coordinates and behaviors of each action of each finger in a multi-touch operation.

create⁹⁺

static create(fingers: number, steps: number): PointerMatrix

Creates a PointerMatrix object and returns the object created. This API is a static API.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { PointerMatrix } from '@kit.TestKit';
async function demo() {
  let pointerMatrix: PointerMatrix = PointerMatrix.create(2,3);
}

setPoint⁹⁺

setPoint(finger: number, step: number, point: Point): void

Sets the coordinates for the action corresponding to the specified finger and step in the PointerMatrix object.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

Example

import { PointerMatrix } from '@kit.TestKit';
async function demo() {
  let pointers: PointerMatrix = PointerMatrix.create(2,5);
  pointers.setPoint(0,0,{x:250,y:480});
  pointers.setPoint(0,1,{x:250,y:440});
  pointers.setPoint(0,2,{x:250,y:400});
  pointers.setPoint(0,3,{x:250,y:360});
  pointers.setPoint(0,4,{x:250,y:320});
  pointers.setPoint(1,0,{x:250,y:480});
  pointers.setPoint(1,1,{x:250,y:440});
  pointers.setPoint(1,2,{x:250,y:400});
  pointers.setPoint(1,3,{x:250,y:360});
  pointers.setPoint(1,4,{x:250,y:320});
}