Android设备

AndroidDevice 代表一个已连接的设备，可以是真实硬件或模拟器。可以通过 android.devices() 获取设备。

方法​

关闭​

与设备断开连接。

用法

await androidDevice.close();

返回

• Promise<void>#

拖拽​

将selector定义的小部件拖动到dest点。

用法

await androidDevice.drag(selector, dest);
await androidDevice.drag(selector, dest, options);

参数

• selector [AndroidSelector]#

  要拖动的选择器。

• dest Object#

  • x number

  • y number

  拖动到的目标点。

• options Object (可选)

  • speed number (可选)#

    可选的拖动速度，单位为像素每秒。

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法修改。

返回

• Promise<void>#

fill​

在指定的selector输入框中填入text。

用法

await androidDevice.fill(selector, text);
await androidDevice.fill(selector, text, options);

参数

• selector [AndroidSelector]#

  要填充的选择器。

• text string#

  要在输入框中填充的文本。

• options Object (可选)

  • timeout number (可选)#

    最大等待时间(毫秒)，默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法修改。

返回

• Promise<void>#

快速滑动​

将selector定义的小部件沿指定的direction方向快速滑动。

用法

await androidDevice.fling(selector, direction);
await androidDevice.fling(selector, direction, options);

参数

• selector [AndroidSelector]#

  要滑动的选择器。

• direction "down" | "up" | "left" | "right"#

  滑动方向。

• options Object (可选)

  • speed number (可选参数)#

    可选参数，表示投掷速度（单位：像素/秒）。

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法进行修改。

返回

• Promise<void>#

信息​

返回由selector定义的小部件信息。

用法

await androidDevice.info(selector);

参数

• selector [AndroidSelector]#

  要返回相关信息的Android选择器。

返回

• Promise<[AndroidElementInfo]>#

installApk​

在设备上安装一个apk文件。

用法

await androidDevice.installApk(file);
await androidDevice.installApk(file, options);

参数

• file string | Buffer#

  可以是apk文件的路径，或者是apk文件内容。

• options Object (可选)

  • args Array<string> (可选)#

    传递给shell:cmd package install调用的可选参数。默认为-r -t -S。

返回

• Promise<void>#

launchBrowser​

在设备上启动Chrome浏览器，并返回其持久化上下文。

用法

await androidDevice.launchBrowser();
await androidDevice.launchBrowser(options);

参数

• options Object (optional)

  • acceptDownloads boolean (可选)#

    是否自动下载所有附件。默认为true，表示接受所有下载。

  • args Array<string> (可选) 添加于: v1.29#

    警告

    使用自定义浏览器参数存在风险，因为其中某些参数可能会破坏Playwright的功能。

    传递给浏览器实例的额外参数。Chromium标志的列表可以在这里找到。

  • baseURL string (可选)#

    在使用page.goto()、page.route()、page.waitForURL()、page.waitForRequest()或page.waitForResponse()时，会通过URL()构造函数考虑基础URL来构建相应的URL。默认情况下未设置。示例：

    • baseURL: http://localhost:3000 and navigating to /bar.html results in http://localhost:3000/bar.html
    • baseURL: http://localhost:3000/foo/ and navigating to ./bar.html results in http://localhost:3000/foo/bar.html
    • baseURL: http://localhost:3000/foo (without trailing slash) and navigating to ./bar.html results in http://localhost:3000/bar.html

  • bypassCSP boolean (可选)#

    切换绕过页面的内容安全策略。默认为 false。

  • colorScheme null | "light" | "dark" | "no-preference" (可选)#

    模拟prefers-colors-scheme媒体特性，支持的值有'light'和'dark'。更多详情请参阅page.emulateMedia()。传入null会将模拟重置为系统默认值。默认为'light'。

  • contrast null | "no-preference" | "more" (可选)#

    模拟'prefers-contrast'媒体特性，支持的值为'no-preference'、'more'。详情请参阅page.emulateMedia()。传入null会将模拟重置为系统默认值。默认为'no-preference'。

  • deviceScaleFactor number (可选)#

    指定设备缩放比例(可视为dpr)。默认为1。了解更多关于使用设备缩放比例模拟设备的信息。

  • extraHTTPHeaders Object<string, string> (可选)#

    包含随每个请求发送的额外HTTP头信息的对象。默认为无。

  • forcedColors null | "active" | "none" (可选)#

    模拟'forced-colors'媒体特性，支持的值为'active'、'none'。详情请参阅page.emulateMedia()。传入null会将模拟重置为系统默认值。默认为'none'。

  • geolocation Object (可选)#

    • latitude number

      纬度值，范围在-90到90之间。

    • longitude number

      经度值，范围在-180到180之间。

    • accuracy number (可选)

      非负精度值。默认为 0。

  • hasTouch boolean (可选)#

    指定视口是否支持触摸事件。默认为false。了解更多关于mobile emulation的信息。

  • httpCredentials Object (可选)#

    • username string

    • password string

    • origin string (可选)

      限制在特定来源(scheme://host:port)上发送HTTP凭据。

    • send "unauthorized" | "always" (可选)

      此选项仅适用于从对应APIRequestContext发送的请求，不会影响从浏览器发送的请求。'always' - 每个API请求都会附带包含基本认证凭据的Authorization头部。'unauthorized - 仅当收到带有WWW-Authenticate头部的401(未授权)响应时才发送凭据。默认为'unauthorized'。

    HTTP认证的凭据。如果未指定来源，则在收到未经授权的响应时，用户名和密码将被发送到任何服务器。

  • ignoreHTTPSErrors boolean (可选)#

    发送网络请求时是否忽略HTTPS错误。默认为false。

  • isMobile boolean (可选)#

    是否考虑meta viewport标签并启用触摸事件。isMobile是设备属性的一部分，因此实际上不需要手动设置。默认为false且在Firefox中不受支持。了解更多关于mobile emulation的信息。

  • javaScriptEnabled boolean (可选)#

    是否在上下文中启用JavaScript。默认为true。了解更多关于禁用JavaScript的信息。

  • locale string (可选)#

    指定用户区域设置，例如 en-GB, de-DE 等。区域设置会影响 navigator.language 值、Accept-Language 请求头值以及数字和日期格式规则。默认为系统默认区域设置。在我们的模拟指南中了解更多关于模拟的信息。

  • logger Logger (可选)#

    用于Playwright日志记录的日志接收器。

  • offline boolean (可选)#

    是否模拟网络离线状态。默认为false。了解更多关于网络模拟的信息。

  • permissions Array<string> (可选)#

    授予此上下文中所有页面的权限列表。更多详情请参阅browserContext.grantPermissions()。默认为无。

  • pkg string (可选)#

    可选的包名称，用于启动替代默认的Android版Chrome浏览器。

  • proxy Object (可选) 添加于: v1.29#

    • server string

      用于所有请求的代理服务器。支持HTTP和SOCKS代理，例如http://myproxy.com:3128或socks5://myproxy.com:3128。短格式myproxy.com:3128将被视为HTTP代理。

    • bypass string (可选)

      可选的逗号分隔域名以绕过代理，例如 ".com, chromium.org, .domain.com"。

    • username string (可选)

      如果HTTP代理需要认证时使用的可选用户名。

    • password string (可选)

      如果HTTP代理需要认证时可选的密码。

    网络代理设置。

  • recordHar Object (可选)#

    • omitContent boolean (可选)

      可选设置，用于控制是否从HAR中省略请求内容。默认为false。已弃用，请改用content策略。

    • content "omit" | "embed" | "attach" (可选)

      用于控制资源内容管理的可选设置。如果指定为omit，则内容不会被持久化保存。如果指定为attach，资源将作为单独文件或ZIP存档中的条目进行持久化。如果指定为embed，则根据HAR规范将内容内联存储在HAR文件中。对于.zip输出文件默认为attach，其他所有文件扩展名默认为embed。

    • path string

      要写入HAR文件在文件系统上的路径。如果文件名以.zip结尾，默认会使用content: 'attach'。

    • mode "full" | "minimal" (可选)

      当设置为minimal时，仅记录HAR路由所必需的信息。这会省略大小、时间、页面、cookies、安全和其他类型的HAR信息，这些信息在从HAR回放时不会被使用。默认为full。

    • urlFilter string | RegExp (可选)

      用于过滤存储在HAR中的请求的全局模式或正则表达式模式。当通过上下文选项提供了baseURL且传入的URL是路径时，将通过new URL()构造函数进行合并。默认为无。

    为所有页面启用HAR记录，将结果保存到recordHar.path文件中。如果未指定，则不会记录HAR。请确保等待browserContext.close()以保存HAR。

  • recordVideo Object (可选)#

    • dir string

      存放视频的目录路径。

    • size Object (可选)

      • width number

        视频帧宽度。

      • height number

        视频帧高度。

      录制视频的可选尺寸。如果未指定，尺寸将等于viewport按比例缩小以适应800x800。如果未显式配置viewport，视频尺寸默认为800x450。如有必要，每个页面的实际图像将按比例缩小以适应指定尺寸。

    启用所有页面的视频录制，视频将保存到recordVideo.dir目录。如果未指定则不会录制视频。请确保等待browserContext.close()以保存视频。

  • reducedMotion null | "reduce" | "no-preference" (可选)#

    模拟'prefers-reduced-motion'媒体特性，支持的值为'reduce'、'no-preference'。详情请参阅page.emulateMedia()。传入null会将模拟重置为系统默认值。默认为'no-preference'。

  • screen Object (可选)#

    • width number

      页面宽度，单位为像素。

    • height number

      页面高度，单位为像素。

    通过window.screen模拟网页内一致的窗口屏幕尺寸。仅在viewport设置时使用。

  • serviceWorkers "allow" | "block" (可选)#

    是否允许网站注册Service workers。默认为'allow'。

    • 'allow': 可以注册Service Workers。
    • 'block': Playwright 将阻止所有 Service Workers 的注册。

  • strictSelectors boolean (可选)#

    如果设置为true，将为此上下文启用严格选择器模式。在严格选择器模式下，所有针对选择器的操作如果匹配到多个DOM元素时都会抛出异常。此选项不会影响任何Locator API（Locator始终是严格的）。默认为false。有关严格模式的更多信息，请参阅Locator。

  • timezoneId string (可选)#

    更改上下文的时区。支持的时区ID列表请参见ICU's metaZones.txt。默认为系统时区。

  • userAgent string (可选)#

    在此上下文中使用的特定用户代理。

  • videoSize Object (可选)#

    Deprecated

    请改用recordVideo。

    • width number

      视频帧宽度。

    • height number

      视频帧高度。

  • videosPath string (可选)#

    已弃用

    请改用 recordVideo。

  • viewport null | Object (可选)#

    • width number

      页面宽度，单位为像素。

    • height number

      页面高度，单位为像素。

    为每个页面模拟一致的视口。默认视口尺寸为1280x720。使用null可禁用一致的视口模拟。了解更多关于视口模拟的信息。

    note

    null值表示不使用默认预设，使视口大小取决于操作系统定义的主机窗口尺寸。这会导致测试执行变得非确定性。

返回

• Promise<BrowserContext>#

长按​

对由selector定义的小部件执行长按操作。

用法

await androidDevice.longTap(selector);
await androidDevice.longTap(selector, options);

参数

• selector [AndroidSelector]#

  需要点击的选择器。

• options Object (可选)

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法修改。

返回

• Promise<void>#

model​

设备型号。

用法

androidDevice.model();

返回

• string#

打开​

在设备的shell中启动一个进程，并返回一个套接字用于与启动的进程通信。

用法

await androidDevice.open(command);

参数

• command string#

  要执行的Shell命令。

返回

• Promise<AndroidSocket>#

pinchClose​

在关闭方向上捏合由selector定义的小部件。

用法

await androidDevice.pinchClose(selector, percent);
await androidDevice.pinchClose(selector, percent, options);

参数

• selector [AndroidSelector]#

  用于捏合关闭的选择器。

• percent number#

  捏合大小占部件尺寸的百分比。

• options Object (可选)

  • speed number (可选)#

    可选的捏合速度，单位为像素每秒。

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法进行修改。

返回

• Promise<void>#

pinchOpen​

在指定方向上捏合由selector定义的小部件。

用法

await androidDevice.pinchOpen(selector, percent);
await androidDevice.pinchOpen(selector, percent, options);

参数

• selector [AndroidSelector]#

  用于放大操作的安卓选择器。

• percent number#

  捏合大小占部件尺寸的百分比。

• options Object (可选)

  • speed number (可选)#

    可选的捏合速度，单位为每秒像素数。

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法进行修改。

返回

• Promise<void>#

按下​

在由selector定义的小部件中按下特定的key键。

用法

await androidDevice.press(selector, key);
await androidDevice.press(selector, key, options);

参数

• selector [AndroidSelector]#

  用于按下按键的选择器。

• key [AndroidKey]#

  要按下的键。

• options Object (可选)

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法进行修改。

返回

• Promise<void>#

推送​

将文件复制到设备上。

用法

await androidDevice.push(file, path);
await androidDevice.push(file, path, options);

参数

• file string | Buffer#

  可以是文件路径，也可以是文件内容。

• path string#

  设备上文件的路径。

• options Object (可选)

  • mode number (可选)#

    可选的文件模式，默认为 644 (rw-r--r--)。

返回

• Promise<void>#

截图​

返回包含设备截图捕获的缓冲区。

用法

await androidDevice.screenshot();
await androidDevice.screenshot(options);

参数

• options Object (optional)

  • path string (可选)#

    保存图像的文件路径。如果path是相对路径，则相对于当前工作目录解析。如果没有提供路径，图像将不会保存到磁盘。

返回

• Promise<Buffer>#

滚动​

将selector定义的小部件按指定的direction方向滚动。

用法

await androidDevice.scroll(selector, direction, percent);
await androidDevice.scroll(selector, direction, percent, options);

参数

• selector [AndroidSelector]#

  要滚动的选择器。

• direction "down" | "up" | "left" | "right"#

  滚动方向。

• percent number#

  滚动距离占部件大小的百分比。

• options Object (可选)

  • speed number (可选)#

    可选的滚动速度，单位为像素每秒。

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法修改。

返回

• Promise<void>#

串行​

设备序列号。

用法

androidDevice.serial();

返回

• string#

setDefaultTimeout​

此设置将更改所有接受timeout选项的方法的默认最大时间。

用法

androidDevice.setDefaultTimeout(timeout);

参数

• timeout number#

  最大时间（毫秒）

shell​

在设备上执行shell命令并返回其输出。

用法

await androidDevice.shell(command);

参数

• command string#

  要执行的Shell命令。

返回

• Promise<Buffer>#

滑动​

在指定的direction方向上滑动由selector定义的小部件。

用法

await androidDevice.swipe(selector, direction, percent);
await androidDevice.swipe(selector, direction, percent, options);

参数

• selector [AndroidSelector]#

  要滑动的选择器。

• direction "down" | "up" | "left" | "right"#

  滑动方向。

• percent number#

  滑动距离占部件尺寸的百分比。

• options Object (可选)

  • speed number (可选)#

    可选的滑动速度，单位为像素每秒。

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法修改。

返回

• Promise<void>#

点击​

点击由selector定义的小部件。

用法

await androidDevice.tap(selector);
await androidDevice.tap(selector, options);

参数

• selector [AndroidSelector]#

  需要点击的选择器。

• options Object (可选)

  • duration number (可选)#

    可选的点击持续时间，单位为毫秒。

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法修改。

返回

• Promise<void>#

等待​

等待特定的selector出现或消失，具体取决于state。

用法

await androidDevice.wait(selector);
await androidDevice.wait(selector, options);

参数

• selector [AndroidSelector]#

  需要等待的选择器。

• options Object (可选)

  • state "gone" (可选)#

    可选状态。可以是以下之一：

    • default - 等待元素出现。
    • 'gone' - 等待元素不存在。

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法修改。

返回

• Promise<void>#

waitForEvent​

等待事件触发并将其值传递给谓词函数。当谓词返回真值时返回。

用法

await androidDevice.waitForEvent(event);
await androidDevice.waitForEvent(event, optionsOrPredicate);

参数

• event string#

  事件名称，通常与传入*.on(event)中的名称相同。

• optionsOrPredicate function | Object (可选)#

  • predicate function

    接收事件数据，当等待应解决时解析为真值。

  • timeout number (可选)

    等待的最长时间，以毫秒为单位。默认为30000（30秒）。传入0表示禁用超时。默认值可以通过使用androidDevice.setDefaultTimeout()来更改。

  可以是一个接收事件的谓词函数，也可以是一个选项对象。可选参数。

返回

• Promise<Object>#

webView​

该方法会等待直到匹配selector的AndroidWebView被打开并返回它。如果已经存在一个匹配selector的打开状态的AndroidWebView，则立即返回。

用法

await androidDevice.webView(selector);
await androidDevice.webView(selector, options);

参数

• selector Object#

  • pkg string (可选)

    可选的包标识符。

  • socketName string (可选)

    可选的webview套接字名称。

• options Object (optional)

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过androidDevice.setDefaultTimeout()方法修改。

返回

• Promise<AndroidWebView>#

web视图​

当前打开的WebViews。

用法

androidDevice.webViews();

返回

• Array<AndroidWebView>#

属性​

输入​

用法

androidDevice.input

类型

• AndroidInput

事件​

on('close')​

当设备连接关闭时触发。

用法

androidDevice.on('close', data => {});

事件数据

• AndroidDevice

on('webview')​

当检测到新的WebView实例时触发。

用法

androidDevice.on('webview', data => {});

事件数据

• AndroidWebView