@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 API 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 API 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 API 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.

Modules to Import

import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix} from '@ohos.UiTest';

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.

System capability: SystemCapability.Test.UiTest

Point⁹⁺

Provides the coordinates of a point.

System capability: SystemCapability.Test.UiTest

Rect⁹⁺

Provides bounds information of a component.

System capability: SystemCapability.Test.UiTest

WindowMode⁹⁺

System capability: SystemCapability.Test.UiTest

Enumerates the window modes.

DisplayRotation⁹⁺

System capability: SystemCapability.Test.UiTest

Describes the display rotation of the device.

WindowFilter⁹⁺

Provides the flag attributes of this window.

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 API capabilities 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.

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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

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

type⁹⁺

type(tp: string): On

Specifies the type attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let 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 status attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.clickable(true); // Use the static constructor ON to create an On object and specify the clickable status attribute of the target component.

longClickable⁹⁺

longClickable(b?: boolean): On

Specifies the long-clickable status attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.longClickable(true); // Use the static constructor ON to create an On object and specify the long-clickable status attribute of the target component.

scrollable⁹⁺

scrollable(b?: boolean): On

Specifies the scrollable status attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.scrollable(true); // Use the static constructor ON to create an On object and specify the scrollable status attribute of the target component.

enabled⁹⁺

enabled(b?: boolean): On

Specifies the enabled status attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.enabled(true); // Use the static constructor ON to create an On object and specify the enabled status attribute of the target component.

focused⁹⁺

focused(b?: boolean): On

Specifies the focused status attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.focused(true); // Use the static constructor ON to create an On object and specify the focused status attribute of the target component.

selected⁹⁺

selected(b?: boolean): On

Specifies the selected status attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.selected(true); // Use the static constructor ON to create an On object and specify the selected status attribute of the target component.

checked⁹⁺

checked(b?: boolean): On

Specifies the checked status attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.checked(true); // Use the static constructor ON to create an On object and specify the checked status attribute of the target component.

checkable⁹⁺

checkable(b?: boolean): On

Specifies the checkable status attribute of the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.checkable(true); // Use the static constructor ON to create an On object and specify the checkable status attribute of the target component.

isBefore⁹⁺

isBefore(on: On): On

Specifies the attributes of the component before which the target component is located.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.isBefore(ON.text('123')); // Use the static constructor ON to create an On object and specify the attributes of the component before which the target component is located.

isAfter⁹⁺

isAfter(on: On): On

Specifies the attributes of the component after which the target component is located.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let on = ON.isAfter(ON.text('123')); // Use the static constructor ON to create an On object and specify the attributes of the component after which the target component is located.

Component⁹⁺

In UiTest of API version 9, the Component class 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.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.click();
}

doubleClick⁹⁺

doubleClick(): Promise<void>

Double-clicks this component.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.doubleClick();
}

longClick⁹⁺

longClick(): Promise<void>

Long-clicks this component.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    await button.longClick();
}

getId⁹⁺

getId(): Promise<string>

Obtains the ID of this component.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let num = await button.getId();
}

getText⁹⁺

getText(): Promise<string>

Obtains the text information of this component.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let text = await button.getText();
}

getType⁹⁺

getType(): Promise<string>

Obtains the type of this component.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let type = await button.getType();
}

getBounds⁹⁺

getBounds(): Promise<Rect>

Obtains the bounds of this component.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let point = await button.getBoundsCenter();
}

isClickable⁹⁺

isClickable(): Promise<boolean>

Obtains the clickable status of this component.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let checkBox = 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let checkBox = 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let scrollBar = 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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>

Enters text into this component (available for text boxes).

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let text = 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.

System capability: SystemCapability.Test.UiTest

Error codes

Example

async function demo() {
    let driver = Driver.create();
    let text = 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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let scrollBar = 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let scrollBar = await driver.findComponent(ON.type('Scroll'));
    await scrollBar.scrollToBottom();
}

dragTo⁹⁺

dragTo(target: Component): Promise<void>

Drags this component to the target component.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = await driver.findComponent(ON.type('button'));
    let text = 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let image = 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let image = await driver.findComponent(ON.type('image'));
    await image.pinchIn(0.5);
    }

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 for 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.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
}

delayMs⁹⁺

delayMs(duration: number): Promise<void>

Delays this Driver object within the specified duration.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let buttonList = await driver.findComponents(ON.text('next page'));
}

findWindow⁹⁺

findWindow(filter: WindowFilter): Promise<UiWindow>

Searches for the window that matches the specified attributes.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = 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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let button = 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    await driver.assertComponentExist(ON.text('next page'));
}

pressBack⁹⁺

pressBack(): Promise<void>

Presses the Back button on this Driver object.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    await driver.screenCap('/local/tmp/1.png');
}

setDisplayRotation⁹⁺

setDisplayRotation(rotation: DisplayRotation): Promise<void>

Sets the display rotation of the device.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    await driver.setDisplayRotation(DisplayRotation.ROTATION_180);
}

getDisplayRotation⁹⁺

getDisplayRotation(): Promise<DisplayRotation>

Obtains the display rotation of the current device.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let rotation = await driver.getDisplayRotation();
}

setDisplayRotationEnabled⁹⁺

setDisplayRotationEnabled(enabled: boolean): Promise<void>

Enables or disables display rotation.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    await driver.setDisplayRotationEnabled(false);
}

getDisplaySize⁹⁺

getDisplaySize(): Promise<Point>

Obtains the display size of the current device.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

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

getDisplayDensity⁹⁺

getDisplayDensity(): Promise<Point>

Obtains the display density of the current device.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let density = await driver.getDisplayDensity();
}

wakeUpDisplay⁹⁺

wakeUpDisplay(): Promise<void>

Wakes up the device display.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    await driver.wakeUpDisplay();
}

pressHome⁹⁺

pressHome(): Promise<void>

Returns to the home screen.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    await driver.pressHome();
}

waitForIdle⁹⁺

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

Checks whether all components on the current page are idle.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let idled = await driver.waitForIdle(4000,5000);
}

fling⁹⁺

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

Simulates a fling operation on the screen.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let pointers = PointerMatrix.create(2,3);
    pointers.setPoint(0,0,{x:230,y:480});
    pointers.setPoint(0,1,{x:250,y:380});
    pointers.setPoint(0,2,{x:270,y:280});
    pointers.setPoint(1,0,{x:230,y:680});
    pointers.setPoint(1,1,{x:240,y:580});
    pointers.setPoint(1,2,{x:250,y:480});
    await driver.injectMultiPointerAction(pointers);
}

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.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

async function demo() {
    let 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.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let pointers = PointerMatrix.create(2,3);
    pointers.setPoint(0,0,{x:230,y:480});
    pointers.setPoint(0,1,{x:250,y:380});
    pointers.setPoint(0,2,{x:270,y:280});
    pointers.setPoint(1,0,{x:230,y:680});
    pointers.setPoint(1,1,{x:240,y:580});
    pointers.setPoint(1,2,{x:250,y:480});
}

UiWindow⁹⁺

The UiWindow class represents a window on the UI and provides APIs for obtaining window attributes, dragging a window, and adjusting the window size. All APIs provided in this class use a promise to return the result and must be invoked using await.

getBundleName⁹⁺

getBundleName(): Promise<string>

Obtains the bundle name of the application to which this window belongs.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let name = await window.getBundleName();
}

getBounds⁹⁺

getBounds(): Promise<Rect>

Obtains the bounds information of this window.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let rect = await window.getBounds();
}

getTitle⁹⁺

getTitle(): Promise<string>

Obtains the title of this window.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let rect = await window.getTitle();
}

getWindowMode⁹⁺

getWindowMode(): Promise<WindowMode>

Obtains the window mode of this window.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let mode = await window.getWindowMode();
}

isFocused⁹⁺

isFocused(): Promise<boolean>

Checks whether this window is in focused state.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let focused = await window.isFocused();
}

isActived⁹⁺

isActived(): Promise<boolean>

Checks whether this window is active.

System capability: SystemCapability.Test.UiTest

Return value

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    let focused = await window.isActived();
}

focus⁹⁺

focus(): Promise<void>

Moves the focus to this window.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.focus();
}

moveTo⁹⁺

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

Moves this window to the target point. This API is applicable to moveable windows.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.moveTo(100, 100);
}

resize⁹⁺

resize(wide: number, height: number, direction: ResizeDirection): Promise<void>

Resizes this window based on the specified width, height, and resize direction. This API is applicable to resizable windows.

System capability: SystemCapability.Test.UiTest

Parameters

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.resize(100, 100, ResizeDirection.LEFT);
}

split⁹⁺

split(): Promise<void>

Switches the window to split-screen mode. This API is applicable to windows that support screen splitting.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.split();
}

maximize⁹⁺

maximize(): Promise<void>

Maximizes this window. This API is applicable to windows that can be maximized.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.maximize();
}

minimize⁹⁺

minimize(): Promise<void>

Minimizes this window. This API is applicable to windows that can be minimized.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.minimize();
}

resume⁹⁺

resume(): Promise<void>

Restores this window to the previous window mode.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.resume();
}

close⁹⁺

close(): Promise<void>

Closes this window.

System capability: SystemCapability.Test.UiTest

Error codes

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

Example

async function demo() {
    let driver = Driver.create();
    let window = await driver.findWindow({actived: true});
    await window.close();
}

By^(deprecated)

The UiTest framework provides a wide range of UI component feature description APIs in the By class to filter and match components. The API capabilities provided by the By 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 By.isBefore^(deprecated) and By.isAfter^(deprecated) can be used to specify the features of adjacent components to assist positioning.
All APIs provided in the By class are synchronous. You are advised to use the static constructor BY to create a By object in chain mode.

This API is deprecated since API version 9. You are advised to use On⁹⁺ instead.

BY.text('123').type('button');

text^(deprecated)

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

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

This API is deprecated since API version 9. You are advised to use text⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.text('123'); // Use the static constructor BY to create a By object and specify the text attribute of the target component.

key^(deprecated)

key(key: string): By

Specifies the key attribute of the target component.

This API is deprecated since API version 9. You are advised to use id⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.key('123'); // Use the static constructor BY to create a By object and specify the key attribute of the target component.

id^(deprecated)

id(id: number): By

Specifies the ID attribute of the target component.

This API is deprecated since API version 9.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.id(123); // Use the static constructor BY to create a By object and specify the ID attribute of the target component.

type^(deprecated)

type(tp: string): By

Specifies the type attribute of the target component.

This API is deprecated since API version 9. You are advised to use type⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.type('button'); // Use the static constructor BY to create a By object and specify the type attribute of the target component.

clickable^(deprecated)

clickable(b?: boolean): By

Specifies the clickable status attribute of the target component.

This API is deprecated since API version 9. You are advised to use clickable⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.clickable(true); // Use the static constructor BY to create a By object and specify the clickable status attribute of the target component.

scrollable^(deprecated)

scrollable(b?: boolean): By

Specifies the scrollable status attribute of the target component.

This API is deprecated since API version 9. You are advised to use scrollable⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.scrollable(true); // Use the static constructor BY to create a By object and specify the scrollable status attribute of the target component.

enabled^(deprecated)

enabled(b?: boolean): By

Specifies the enabled status attribute of the target component.

This API is deprecated since API version 9. You are advised to use enabled⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.enabled(true); // Use the static constructor BY to create a By object and specify the enabled status attribute of the target component.

focused^(deprecated)

focused(b?: boolean): By

Specifies the focused status attribute of the target component.

This API is deprecated since API version 9. You are advised to use focused⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.focused(true); // Use the static constructor BY to create a By object and specify the focused status attribute of the target component.

selected^(deprecated)

selected(b?: boolean): By

Specifies the selected status of the target component.

This API is deprecated since API version 9. You are advised to use selected⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.selected(true); // Use the static constructor BY to create a By object and specify the selected status attribute of the target component.

isBefore^(deprecated)

isBefore(by: By): By

Specifies the attributes of the component before which the target component is located.

This API is deprecated since API version 9. You are advised to use isBefore⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.isBefore(BY.text('123')); // Use the static constructor BY to create a By object and specify the attributes of the component before which the target component is located.

isAfter^(deprecated)

isAfter(by: By): By

Specifies the attributes of the component after which the target component is located.

This API is deprecated since API version 9. You are advised to use isAfter⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

let by = BY.isAfter(BY.text('123')); // Use the static constructor BY to create a By object and specify the attributes of the component after which the target component is located.

UiComponent^(deprecated)

In UiTest, the UiComponent class 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.

This API is deprecated since API version 9. You are advised to use Component⁹⁺ instead.

click^(deprecated)

click(): Promise<void>

Clicks this component.

This API is deprecated since API version 9. You are advised to use click⁹⁺.

System capability: SystemCapability.Test.UiTest

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.click();
}

doubleClick^(deprecated)

doubleClick(): Promise<void>

Double-clicks this component.

This API is deprecated since API version 9. You are advised to use doubleClick⁹⁺.

System capability: SystemCapability.Test.UiTest

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.doubleClick();
}

longClick^(deprecated)

longClick(): Promise<void>

Long-clicks this component.

This API is deprecated since API version 9. You are advised to use longClick⁹⁺.

System capability: SystemCapability.Test.UiTest

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    await button.longClick();
}

getId^(deprecated)

getId(): Promise<number>

Obtains the ID of this component.

This API is deprecated since API version 9.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let num = await button.getId();
}

getKey^(deprecated)

getKey(): Promise<string>

Obtains the key of this component.

This API is deprecated since API version 9. You are advised to use getId⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let str_key = await button.getKey();
}

getText^(deprecated)

getText(): Promise<string>

Obtains the text information of this component.

This API is deprecated since API version 9. You are advised to use getText⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let text = await button.getText();
}

getType^(deprecated)

getType(): Promise<string>

Obtains the type of this component.

This API is deprecated since API version 9. You are advised to use getType⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    let type = await button.getType();
}

isClickable^(deprecated)

isClickable(): Promise<boolean>

Obtains the clickable status of this component.

This API is deprecated since API version 9. You are advised to use isClickable⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    if(await button.isClickable()) {
        console.info('This button can be Clicked');
    } else {
        console.info('This button can not be Clicked');
    }
}

isScrollable^(deprecated)

isScrollable(): Promise<boolean>

Obtains the scrollable status of this component.

This API is deprecated since API version 9. You are advised to use isScrollable⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let scrollBar = await driver.findComponent(BY.scrollable(true));
    if(await scrollBar.isScrollable()) {
        console.info('This scrollBar can be operated');
    } else {
        console.info('This scrollBar can not be operated');
    }
}

isEnabled^(deprecated)

isEnabled(): Promise<boolean>

Obtains the enabled status of this component.

This API is deprecated since API version 9. You are advised to use isEnabled⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    if(await button.isEnabled()) {
        console.info('This button can be operated');
    } else {
        console.info('This button can not be operated');
    }
}

isFocused^(deprecated)

isFocused(): Promise<boolean>

Obtains the focused status of this component.

This API is deprecated since API version 9. You are advised to use isFocused⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    if(await button.isFocused()) {
        console.info('This button is focused');
    } else {
        console.info('This button is not focused');
	}
}

isSelected^(deprecated)

isSelected(): Promise<boolean>

Obtains the selected status of this component.

This API is deprecated since API version 9. You are advised to use isSelected⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.type('button'));
    if(await button.isSelected()) {
        console.info('This button is selected');
    } else {
        console.info('This button is not selected');
    }
}

inputText^(deprecated)

inputText(text: string): Promise<void>

Enters text into this component (available for text boxes).

This API is deprecated since API version 9. You are advised to use inputText⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let driver = UiDriver.create();
    let text = await driver.findComponent(BY.text('hello world'));
    await text.inputText('123');
}

scrollSearch^(deprecated)

scrollSearch(by: By): Promise<UiComponent>

Scrolls on this component to search for the target component (applicable to components that support scrolling, such as <List>).

This API is deprecated since API version 9. You are advised to use scrollSearch⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

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

UiDriver^(deprecated)

The UiDriver 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 for UiDriver.create(), use a promise to return the result and must be invoked using await.

This API is deprecated since API version 9. You are advised to use Driver⁹⁺ instead.

create^(deprecated)

static create(): UiDriver

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

This API is deprecated since API version 9. You are advised to use create⁹⁺.

System capability: SystemCapability.Test.UiTest

Return value

Example

async function demo() {
    let driver = UiDriver.create();
}

delayMs^(deprecated)

delayMs(duration: number): Promise<void>

Delays this UiDriver object within the specified duration.

This API is deprecated since API version 9. You are advised to use delayMs⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.delayMs(1000);
}

findComponent^(deprecated)

findComponent(by: By): Promise<UiComponent>

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

This API is deprecated since API version 9. You are advised to use findComponent⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let button = await driver.findComponent(BY.text('next page'));
}

findComponents^(deprecated)

findComponents(by: By): Promise<Array<UiComponent>>

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

This API is deprecated since API version 9. You are advised to use findComponents⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    let buttonList = await driver.findComponents(BY.text('next page'));
}

assertComponentExist^(deprecated)

assertComponentExist(by: By): Promise<void>

Asserts that a component that matches the given attributes exists on the current page. If the component does not exist, the API throws a JS exception, causing the current test case to fail.

This API is deprecated since API version 9. You are advised to use assertComponentExist⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.assertComponentExist(BY.text('next page'));
}

pressBack^(deprecated)

pressBack(): Promise<void>

Presses the Back button on this UiDriver object.

This API is deprecated since API version 9. You are advised to use pressBack⁹⁺.

System capability: SystemCapability.Test.UiTest

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.pressBack();
}

triggerKey^(deprecated)

triggerKey(keyCode: number): Promise<void>

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

This API is deprecated since API version 9. You are advised to use triggerKey⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.triggerKey(123);
}

click^(deprecated)

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

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

This API is deprecated since API version 9. You are advised to use click⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.click(100,100);
}

doubleClick^(deprecated)

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

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

This API is deprecated since API version 9. You are advised to use doubleClick⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.doubleClick(100,100);
}

longClick^(deprecated)

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

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

This API is deprecated since API version 9. You are advised to use longClick⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.longClick(100,100);
}

swipe^(deprecated)

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

Swipes on this UiDriver object from the start point to the end point based on the given coordinates.

This API is deprecated since API version 9. You are advised to use swipe⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.swipe(100,100,200,200);
}

screenCap^(deprecated)

screenCap(savePath: string): Promise<boolean>

Captures the current screen of this UiDriver object and saves it as a PNG image to the given save path.

This API is deprecated since API version 9. You are advised to use screenCap⁹⁺.

System capability: SystemCapability.Test.UiTest

Parameters

Return value

Example

async function demo() {
    let driver = UiDriver.create();
    await driver.screenCap('/local/tmp/1.png');
}