airtest.core.ios.ios module

decorator_retry_session(func)[source]

When the operation fails due to session failure, try to re-acquire the session, retry at most 3 times.

当因为session失效而操作失败时,尝试重新获取session,最多重试3次。

decorator_pairing_dialog(func)[source]

When the device is not paired, trigger the trust dialogue and try again.

add_decorator_to_methods(decorator)[source]

This function takes a decorator as input and returns a decorator wrapper function. The decorator wrapper function takes a class as input and decorates all the methods of the class by applying the input decorator to each method.

Parameters:

decorator (-) – A decorator function that will be applied to the methods of the input class.

Returns:

A function that takes a class as input and decorates all the methods of the class by applying the input decorator to each method.

Return type:

  • decorator_wrapper

class TIDevice[source]

Bases: object

Below staticmethods are provided by Tidevice.

devices()[source]

Get all available devices connected by USB, return a list of UDIDs.

Returns:

A list of UDIDs. e.g. [‘539c5fffb18f2be0bf7f771d68f7c327fb68d2d9’]

Return type:

list

list_app(app_type='user')[source]

Returns a list of installed applications on the device.

Parameters:
  • udid (str) – The unique identifier of the device.

  • app_type (str, optional) – The type of applications to list. Defaults to “user”. Possible values are “user”, “system”, or “all”.

Returns:

A list of tuples containing the bundle ID, display name,

and version of the installed applications.

e.g. [(‘com.apple.mobilesafari’, ‘Safari’, ‘8.0’), …]

Return type:

list

list_wda()[source]

Get all WDA on device that meet certain naming rules.

Returns:

List of WDA bundleID.

device_info()[source]

Retrieves device information based on the provided UDID.

Parameters:

udid (str) – The unique device identifier.

Returns:

A dictionary containing selected device information. The keys include:
  • productVersion (str): The version of the product.

  • productType (str): The type of the product.

  • modelNumber (str): The model number of the device.

  • serialNumber (str): The serial number of the device.

  • phoneNumber (str): The phone number associated with the device.

  • timeZone (str): The time zone of the device.

  • uniqueDeviceID (str): The unique identifier of the device.

  • marketName (str): The market name of the device.

Return type:

dict

install_app(file_or_url)[source]
uninstall_app(bundle_id)[source]
start_app(bundle_id)[source]
stop_app(bundle_id)[source]
ps()[source]

Retrieves the process list of the specified device.

Parameters:

udid (str) – The unique device identifier.

Returns:

A list of dictionaries containing information about each process. Each dictionary contains the following keys:
  • pid (int): The process ID.

  • name (str): The name of the process.

  • bundle_id (str): The bundle identifier of the process.

  • display_name (str): The display name of the process.

e.g. [{‘pid’: 1, ‘name’: ‘MobileSafari’, ‘bundle_id’: ‘com.apple.mobilesafari’, ‘display_name’: ‘Safari’}, …]

Return type:

list

ps_wda()[source]

Get all running WDA on device that meet certain naming rules.

Returns:

List of running WDA bundleID.

xctest(wda_bundle_id)[source]
class IOS(addr='http://localhost:8100/', cap_method='MJPEG', mjpeg_port=None, udid=None, name=None, serialno=None, wda_bundle_id=None)[source]

Bases: Device

IOS client.

  • before this you have to run WebDriverAgent

  • xcodebuild -project path/to/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination "id=$(idevice_id -l)" test

  • iproxy $port 8100 $udid

property wda_bundle_id
property ip

Returns the IP address of the host connected to the iOS phone.

It is not the IP address of the iOS phone. If you want to get the IP address of the phone, you can access the interface get_ip_address. For example: when the device is connected via http://localhost:8100, return localhost. If it is a remote device http://192.168.xx.xx:8100, it returns the IP address of 192.168.xx.xx.

Returns:

IP.

property uuid
property using_ios_tagent

当前基础版本:appium/WebDriverAgent 4.1.4 基于上述版本,2022.3.30之后发布的iOS-Tagent版本,在/status接口中新增了一个Version参数,如果能检查到本参数,说明使用了新版本ios-Tagent 该版本基于Appium版的WDA做了一些改动,可以更快地进行点击和滑动,并优化了部分UI树的获取逻辑 但是所有的坐标都为竖屏坐标,需要airtest自行根据方向做转换 同时,大于4.1.4版本的appium/WebDriverAgent不再需要针对ipad进行特殊的横屏坐标处理了

Returns:

True if using ios-tagent, else False.

property is_pad

Determine whether it is an ipad(or 6P/7P/8P), if it is, in the case of horizontal screen + desktop, the coordinates need to be switched to vertical screen coordinates to click correctly (WDA bug).

判断是否是ipad(或 6P/7P/8P),如果是,在横屏+桌面的情况下,坐标需要切换成竖屏坐标才能正确点击(WDA的bug)

Returns:

True if it is an ipad, else False.

property device_info

Get the device info.

Notes

Might not work on all devices.

Returns:

Dict for device info, e.g. AttrDict({

’timeZone’: ‘GMT+0800’, ‘currentLocale’: ‘zh_CN’, ‘model’: ‘iPhone’, ‘uuid’: ‘90CD6AB7-11C7-4E52-B2D3-61FA31D791EC’, ‘userInterfaceIdiom’: 0, ‘userInterfaceStyle’: ‘light’, ‘name’: ‘iPhone’, ‘isSimulator’: False})

window_size()[source]
Returns:

Window size (width, height).

property orientation

Returns: Device orientation status in LANDSACPE POR.

get_orientation()[source]
property display_info
property touch_factor
get_render_resolution()[source]

Return render resolution after rotation.

Returns:

offset_x, offset_y, offset_width and offset_height of the display.

get_current_resolution()[source]
home()[source]
snapshot(filename=None, quality=10, max_size=None)[source]

Take snapshot.

Parameters:
  • filename – save screenshot to filename

  • quality – The image quality, integer in range [1, 99]

  • max_size – the maximum size of the picture, e.g 1200

Returns:

Screen snapshot’s cv2 object.

get_frame_from_stream()[source]
touch(pos, duration=0.01)[source]
Parameters:
  • pos – coordinates (x, y), can be float(percent) or int

  • duration (optional) – tap_hold duration

Returns: None(iOS may all use vertical screen coordinates, so coordinates will not be returned.)

Examples

>>> touch((100, 100))
>>> touch((0.5, 0.5), duration=1)
double_click(pos)[source]
swipe(fpos, tpos, duration=0, delay=None, *args, **kwargs)[source]
Parameters:
  • fpos – start point

  • tpos – end point

  • duration (float) – start coordinate press duration (seconds), default is None

  • delay (float) – start coordinate to end coordinate duration (seconds)

Returns:

None

Examples

>>> swipe((1050, 1900), (150, 1900))
>>> swipe((0.2, 0.5), (0.8, 0.5))
keyevent(keyname, **kwargs)[source]

Perform keyevent on the device.

Parameters:
  • keyname – home/volumeUp/volumeDown

  • **kwargs

press(keys)[source]

Some keys in [“home”, “volumeUp”, “volumeDown”] can be pressed.

text(text, enter=True)[source]

Input text on the device.

Parameters:
  • text – text to input

  • enter – True if you need to enter a newline at the end

Examples

>>> text("test")
>>> text("中文")
install_app(file_or_url, **kwargs)[source]

curl -X POST $JSON_HEADER -d “{“desiredCapabilities”:{“bundleId”:”com.apple.mobilesafari”, “app”:”[host_path]/magicapp.app”}}” $DEVICE_URL/session https://github.com/facebook/WebDriverAgent/wiki/Queries

Install app from the device.

Parameters:

file_or_url – file or url to install

Returns:

bundle ID

Raises:

LocalDeviceError – If the device is remote.

uninstall_app(bundle_id)[source]

Uninstall app from the device.

Notes

It seems always return True.

Parameters:

bundle_id – the app bundle id, e.g com.apple.mobilesafari

Raises:

LocalDeviceError – If the device is remote.

start_app(bundle_id, *args, **kwargs)[source]
Parameters:

bundle_id – the app bundle id, e.g com.apple.mobilesafari

Returns:

Process ID.

Examples

>>> start_app('com.apple.mobilesafari')
stop_app(bundle_id)[source]

Note: Both ways of killing the app may fail, nothing responds or just closes the app to the background instead of actually killing it and no error will be reported.

list_app(type='user')[source]

Returns a list of installed applications on the device.

Parameters:

type (str, optional) – The type of applications to list. Defaults to “user”. Possible values are “user”, “system”, or “all”.

Returns:

A list of tuples containing the bundle ID, display name,

and version of the installed applications.

e.g. [(‘com.apple.mobilesafari’, ‘Safari’, ‘8.0’), …]

Return type:

list

Raises:

LocalDeviceError – If the device is remote.

app_state(bundle_id)[source]

Get app state and ruturn.

Parameters:

bundle_id – Bundle ID of app.

Returns:

{

“value”: 4, “sessionId”: “0363BDC5-4335-47ED-A54E-F7CCB65C6A65”

}

Value 1(not running) 2(running in background) 3(running in foreground)? 4(running).

app_current()[source]

Get the app current.

Notes

Might not work on all devices.

Returns:

{“pid”: 1281,

”name”: “”, “bundleId”: “com.netease.cloudmusic”}

Return type:

Current app state dict, eg

get_clipboard(wda_bundle_id=None, *args, **kwargs)[source]

Get clipboard text.

Before calling the WDA interface, you need to ensure that WDA was foreground. If there are multiple WDA on your device, please specify the active WDA by parameter wda_bundle_id.

Parameters:

wda_bundle_id – The bundle id of the running WDA, if None, will use default WDA bundle id.

Returns:

Clipboard text.

Raises:

LocalDeviceError – If the device is remote and the wda_bundle_id parameter is not provided.

Notes

If you want to use this function, you have to set WDA foreground which would switch the current screen of the phone. Then we will try to switch back to the screen before.

set_clipboard(content, wda_bundle_id=None, *args, **kwargs)[source]

Set the clipboard content on the device.

Parameters:
  • content (str) – The content to be set on the clipboard.

  • wda_bundle_id (str, optional) – The bundle ID of the WDA app. Defaults to None.

Raises:

LocalDeviceError – If the device is remote and the wda_bundle_id parameter is not provided.

Returns:

None

paste(wda_bundle_id=None, *args, **kwargs)[source]

Paste the current clipboard content on the device.

Parameters:

wda_bundle_id (str, optional) – The bundle ID of the WDA app. Defaults to None.

Raises:

LocalDeviceError – If the device is remote and the wda_bundle_id parameter is not provided.

Returns:

None

get_ip_address()[source]

Get ip address from WDA.

Returns:

If no IP address has been found, otherwise return the IP address.

device_status()[source]

Show status return by WDA.

Returns:

Dicts of infos.

is_locked()[source]

Return True or False whether the device is locked or not.

Notes

Might not work on some devices.

Returns:

True or False.

unlock()[source]

Unlock the device, unlock screen, double press home.

Notes

Might not work on all devices.

lock()[source]

Lock the device, lock screen.

Notes

Might not work on all devices.

setup_forward(port)[source]

Setup port forwarding from device to host. :param port: device port

Returns:

host port, device port

Raises:

LocalDeviceError – If the device is remote.

ps()[source]

Get the process list of the device.

Returns:

Process list of the device.

alert_accept()[source]

Alert accept-Actually do click first alert button.

Notes

Might not work on all devices.

alert_dismiss()[source]

Alert dissmiss-Actually do click second alert button.

Notes

Might not work on all devices.

alert_wait(time_counter=2)[source]

If alert apper in time_counter second it will return True,else return False (default 20.0).

Notes

Might not work on all devices.

alert_buttons()[source]

Get alert buttons text.

Notes

Might not work on all devices.

Returns:

(“设置”, “好”)

Return type:

# example return

clear_app(package)
shell(*args, **kwargs)
to_json()
alert_exists()[source]

Get True for alert exists or False.

Notes

Might not work on all devices

Returns:

True or False

alert_click(buttons)[source]

When Arg type is list, click the first match, raise ValueError if no match.

e.g. [“设置”, “信任”, “安装”]

Notes

Might not work on all devices.

home_interface()[source]

Get True for the device status is on home interface.

Reason:

Some devices can Horizontal screen on the home interface.

Notes

Might not work on all devices.

Returns:

True or False

disconnect()[source]

Disconnected mjpeg and rotation_watcher.

start_recording(max_time=1800, output=None, fps=10, snapshot_sleep=0.001, orientation=0, max_size=None, *args, **kwargs)[source]

Start recording the device display.

Parameters:
  • max_time – maximum screen recording time, default is 1800

  • output – ouput file path

  • fps – frames per second will record

  • snapshot_sleep – sleep time for each snapshot.

  • orientation – 1: portrait, 2: landscape, 0: rotation, default is 0

  • max_size – max size of the video frame, e.g.800, default is None. Smaller sizes lead to lower system load.

Returns:

path of video file

Return type:

save_path

Examples

Record 30 seconds of video and export to the current directory test.mp4:

>>> from airtest.core.api import connect_device, sleep
>>> dev = connect_device("IOS:///")
>>> save_path = dev.start_recording(output="test.mp4")
>>> sleep(30)
>>> dev.stop_recording()
>>> print(save_path)
>>> # the screen is portrait
>>> portrait_mp4 = dev.start_recording(output="portrait.mp4", orientation=1)  # or orientation="portrait"
>>> sleep(30)
>>> dev.stop_recording()
>>> # the screen is landscape
>>> landscape_mp4 = dev.start_recording(output="landscape.mp4", orientation=2)  # or orientation="landscape"

You can specify max_size to limit the video’s maximum width/length. Smaller video sizes result in lower CPU load.

>>> dev.start_recording(output="test.mp4", max_size=800)
stop_recording()[source]

Stop recording the device display. Recoding file will be kept in the device.