Screen & system

Read the current screen's element tree, size and screenshot, open links, write the clipboard, and handle system alerts.

client.source#

The current screen's element tree. Useful when working out a locator, but slow — keep it out of tight loops.

typescript

client.source(format?: "xml" | "json", accessible?: boolean): string;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`format`	`"xml" \| "json"`	لا	`"xml"`	The output format.
`accessible`	`boolean`	لا	`false`	Pass true to keep only the accessibility-visible nodes, which makes the tree much smaller.

القيمة المُعادة

النوع	الوصف
`string`	The element tree as text.

مثال

javascript

var xml = client.source();
logd(xml.substring(0, 500));

انظر أيضًا setSnapshotMaxDepth

setSnapshotMaxDepth#

Set how deep the element tree is read (default 50). Deeper finds more deeply nested elements but is slower. Returns the previous depth so you can raise it temporarily and restore it afterwards.

typescript

setSnapshotMaxDepth(depth?: number): number | null;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`depth`	`number`	لا	`50`	The maximum depth.

القيمة المُعادة

النوع	الوصف
`number \| null`	The previous depth, or null when it could not be read.

ملاحظات

A depth of 0 means “root node only” in WDA, not “unlimited”. When restoring, skip values below 1.

مثال

javascript

var prev = setSnapshotMaxDepth(80);
var found = findElement('accessibilityId', 'deep_button');
if (prev >= 1) {
  setSnapshotMaxDepth(prev);
}

انظر أيضًا client.source

client.windowSize#

The screen size in points. The result is cached.

typescript

client.windowSize(): { width: number; height: number };

القيمة المُعادة

النوع	الوصف
`{ width, height }`	The screen width and height in points.

مثال

javascript

var size = client.windowSize();
client.click(size.width / 2, size.height - 80);

client.screenshot#

Take a screenshot and get the image data. Colour, image and text lookups do not need this — call findColor / findImage / ocr directly.

typescript

client.screenshot(format?: "base64" | "bytes"): string | number[];

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`format`	`"base64" \| "bytes"`	لا	`"base64"`	base64 returns the PNG as a base64 string; bytes returns a byte array.

القيمة المُعادة

النوع	الوصف
`string \| number[]`	The PNG image data.

الاستثناءات

الاستثناء	متى يحدث
`WDAError`	format is neither base64 nor bytes.

مثال

javascript

var png = client.screenshot();
savePicVideo(png, 'screen.png');

انظر أيضًا keepScreen、savePicVideo

client.openUrl#

Have the system open a URL or a custom scheme (such as an app deep link).

typescript

client.openUrl(targetUrl: string): object;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`targetUrl`	`string`	نعم	—	The address to open.

القيمة المُعادة

النوع	الوصف
`object`	The raw WDA response; rarely needed.

مثال

javascript

client.openUrl('https://example.com');

client.setClipboard#

Write to the device clipboard; non-ASCII text is supported. Read it back with client.getClipboard().

typescript

client.setClipboard(content: string, contentType?: string): object;
client.getClipboard(): string;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`content`	`string`	نعم	—	The text to write.
`contentType`	`string`	لا	`"plaintext"`	The content type.

القيمة المُعادة

النوع	الوصف
`object \| string`	setClipboard returns the raw WDA response; getClipboard returns the clipboard text.

الاستثناءات

الاستثناء	متى يحدث
`WDAError`	content is not a string.

ملاحظات

iOS lets only the foreground app read the clipboard, so getClipboard brings WDA to the front through Siri, reads, and switches back — about 3 seconds in total.

مثال

javascript

client.setClipboard('要粘贴的文字 / text to paste');
var text = client.getClipboard();

انظر أيضًا client.sendKeys

client.alert#

Handle system alerts (permission prompts, confirmations): check for one, accept, dismiss, or list the buttons.

typescript

client.alert.exists(): boolean;
client.alert.accept(): object;
client.alert.dismiss(): object;
client.alert.buttons(): string[];

القيمة المُعادة

النوع	الوصف
`boolean \| object \| string[]`	exists is true when an alert is up; accept taps the last button (usually Allow or OK) and dismiss the first (usually Cancel or Don't Allow); buttons lists the button titles in order.

ملاحظات

To tap a specific button use client.alert.click('Button title'); client.alert.wait(seconds) waits for an alert to appear.

مثال

javascript

if (client.alert.exists()) {
  client.alert.accept();
}