BrowserContext
浏览器上下文 (BrowserContexts) 提供了一种操作多个独立浏览器会话的方式。
如果一个页面打开另一个页面,例如通过 window.open
调用,则弹出的页面将属于父页面的浏览器上下文。
Playwright 允许使用 browser.newContext() 方法创建隔离的非持久性浏览器上下文。非持久性浏览器上下文不会将任何浏览数据写入磁盘。
// Create a new incognito browser context
const context = await browser.newContext();
// Create a new page inside context.
const page = await context.newPage();
await page.goto('https://example.com');
// Dispose context once it's no longer needed.
await context.close();
方法
addCookies
v1.9 之前添加将 cookie 添加到此浏览器上下文。此上下文中的所有页面都将安装这些 cookie。cookie 可以通过 browserContext.cookies() 获取。
用法
await browserContext.addCookies([cookieObject1, cookieObject2]);
参数
cookies
Array<Object>#-
name
string -
value
string -
url
string (可选)需要提供 url 或 domain/path。可选。
-
domain
string (可选)要使 cookie 也适用于所有子域,请在 domain 前加上点,例如:".example.com"。需要提供 url 或 domain/path。可选。
-
path
string (可选)需要提供 url 或 domain/path。可选。
-
expires
number (可选)Unix 时间(秒)。可选。
-
httpOnly
boolean (可选)可选。
-
secure
boolean (可选)可选。
-
sameSite
"Strict" | "Lax" | "None" (可选)可选。
-
partitionKey
string (可选)对于分区的第三方 cookie (又称 CHIPS),分区键。可选。
-
返回
addInitScript
v1.9 之前添加添加一个脚本,该脚本将在以下情况之一中进行评估:
- 每当在浏览器上下文中创建页面或导航页面时。
- 每当在浏览器上下文中的任何页面中附加或导航子框架时。在这种情况下,脚本在新附加的框架的上下文中进行评估。
脚本在文档创建后但在任何脚本运行之前进行评估。这对于修改 JavaScript 环境非常有用,例如,为 Math.random
设置种子。
用法
在页面加载之前覆盖 Math.random
的示例
// preload.js
Math.random = () => 42;
// In your playwright script, assuming the preload.js file is in same directory.
await browserContext.addInitScript({
path: 'preload.js'
});
通过 browserContext.addInitScript() 和 page.addInitScript() 安装的多个脚本的评估顺序未定义。
参数
返回
backgroundPages
新增于: v1.11后台页面仅在基于 Chromium 的浏览器上支持。
上下文中所有现有的后台页面。
用法
browserContext.backgroundPages();
返回
browser
v1.9 之前添加获取拥有该上下文的浏览器实例。如果该上下文在正常浏览器之外创建(例如 Android 或 Electron),则返回 null
。
用法
browserContext.browser();
返回
clearCookies
v1.9 之前添加从上下文清除 cookie。接受可选的过滤器。
用法
await context.clearCookies();
await context.clearCookies({ name: 'session-id' });
await context.clearCookies({ domain: 'my-origin.com' });
await context.clearCookies({ domain: /.*my-origin\.com/ });
await context.clearCookies({ path: '/api/v1' });
await context.clearCookies({ name: 'session-id', domain: 'my-origin.com' });
参数
options
Object (可选)
返回
clearPermissions
v1.9 之前添加清除浏览器上下文的所有权限覆盖。
用法
const context = await browser.newContext();
await context.grantPermissions(['clipboard-read']);
// do stuff ..
context.clearPermissions();
返回
close
v1.9 之前添加关闭浏览器上下文。所有属于该浏览器上下文的页面都将被关闭。
默认的浏览器上下文不能被关闭。
用法
await browserContext.close();
await browserContext.close(options);
参数
返回
cookies
v1.9 之前添加如果未指定 URL,此方法将返回所有 cookie。如果指定了 URL,则仅返回影响这些 URL 的 cookie。
用法
await browserContext.cookies();
await browserContext.cookies(urls);
参数
返回
exposeBinding
v1.9 之前添加此方法在上下文中的每个页面的每个框架的 window
对象上添加一个名为 name 的函数。调用时,该函数执行 callback 并返回一个解析为 callback 返回值的 Promise。如果 callback 返回一个 Promise,则会对其进行等待。
callback 函数的第一个参数包含调用者的信息:{ browserContext: BrowserContext, page: Page, frame: Frame }
。
请参阅 page.exposeBinding() 以获取仅限页面的版本。
用法
将页面 URL 公开给上下文中所有页面的所有框架的示例
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
(async () => {
const browser = await webkit.launch({ headless: false });
const context = await browser.newContext();
await context.exposeBinding('pageURL', ({ page }) => page.url());
const page = await context.newPage();
await page.setContent(`
<script>
async function onClick() {
document.querySelector('div').textContent = await window.pageURL();
}
</script>
<button onclick="onClick()">Click me</button>
<div></div>
`);
await page.getByRole('button').click();
})();
参数
-
窗口对象上函数的名称。
-
将在 Playwright 上下文中调用的回调函数。
-
options
Object (可选)
返回
exposeFunction
v1.9 之前添加此方法在上下文中的每个页面的每个框架的 window
对象上添加一个名为 name 的函数。调用时,该函数执行 callback 并返回一个解析为 callback 返回值的 Promise。
如果 callback 返回一个 Promise,则会对其进行等待。
请参阅 page.exposeFunction() 以获取仅限页面的版本。
用法
向上下文中所有页面添加 sha256
函数的示例
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
const crypto = require('crypto');
(async () => {
const browser = await webkit.launch({ headless: false });
const context = await browser.newContext();
await context.exposeFunction('sha256', text =>
crypto.createHash('sha256').update(text).digest('hex'),
);
const page = await context.newPage();
await page.setContent(`
<script>
async function onClick() {
document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
}
</script>
<button onclick="onClick()">Click me</button>
<div></div>
`);
await page.getByRole('button').click();
})();
参数
返回
grantPermissions
v1.9 之前添加授予浏览器上下文指定的权限。如果指定了来源,则仅授予给定来源相应的权限。
用法
await browserContext.grantPermissions(permissions);
await browserContext.grantPermissions(permissions, options);
参数
-
要授予的权限列表。
危险不同浏览器之间,甚至相同浏览器的不同版本之间,支持的权限也不同。任何权限都可能在更新后停止工作。
以下是一些可能受某些浏览器支持的权限:
'accelerometer'
'ambient-light-sensor'
'background-sync'
'camera'
'clipboard-read'
'clipboard-write'
'geolocation'
'gyroscope'
'magnetometer'
'microphone'
'midi-sysex'
(系统专属 midi)'midi'
'notifications'
'payment-handler'
'storage-access'
'local-fonts'
-
options
Object (可选)-
要授予权限的 来源,例如 "https://example.com"。
-
返回
newCDPSession
新增于: v1.11CDP 会话仅在基于 Chromium 的浏览器上受支持。
返回新创建的会话。
用法
await browserContext.newCDPSession(page);
参数
返回
newPage
v1.9 之前添加在浏览器上下文中创建新页面。
用法
await browserContext.newPage();
返回
pages
v1.9 之前添加返回上下文中所有打开的页面。
用法
browserContext.pages();
返回
removeAllListeners
新增于: v1.47删除给定类型的所有侦听器(如果未给定类型,则删除所有注册的侦听器)。允许等待异步侦听器完成或忽略这些侦听器后续的错误。
用法
await browserContext.removeAllListeners();
await browserContext.removeAllListeners(type, options);
参数
type
string (可选)#options
Object (可选)-
behavior
"wait" | "ignoreErrors" | "default" (可选)#指定是否等待已运行的侦听器以及如果它们抛出错误该怎么做
'default'
- 不等待当前侦听器调用 (如果有) 完成,如果侦听器抛出错误,可能会导致未处理的错误'wait'
- 等待当前侦听器调用 (如果有) 完成'ignoreErrors'
- 不等待当前侦听器调用 (如果有) 完成,移除后侦听器抛出的所有错误都将被静默捕获
-
返回
route
v1.9 之前添加路由提供了修改浏览器上下文中任何页面发出的网络请求的能力。一旦启用路由,每个匹配 URL 模式的请求都将暂停,除非它被继续、完成或中止。
browserContext.route() 不会拦截 Service Worker 拦截的请求。请参阅 此 问题。我们建议在使用请求拦截时通过将 serviceWorkers 设置为 'block'
来禁用 Service Worker。
用法
一个简单地中止所有图片请求的处理程序示例
const context = await browser.newContext();
await context.route('**/*.{png,jpg,jpeg}', route => route.abort());
const page = await context.newPage();
await page.goto('https://example.com');
await browser.close();
或者使用正则表达式模式的相同片段
const context = await browser.newContext();
await context.route(/(\.png$)|(\.jpg$)/, route => route.abort());
const page = await context.newPage();
await page.goto('https://example.com');
await browser.close();
可以检查请求以决定路由操作。例如,模拟所有包含某些 POST 数据的请求,并保留所有其他请求不变
await context.route('/api/**', async route => {
if (route.request().postData().includes('my-string'))
await route.fulfill({ body: 'mocked-data' });
else
await route.continue();
});
当请求同时匹配页面路由(使用 page.route() 设置)和浏览器上下文路由时,页面路由优先。
要删除带有其处理程序的路由,可以使用 browserContext.unroute()。
启用路由会禁用 HTTP 缓存。
参数
-
url
string | RegExp | function(URL):boolean#一个 glob 模式、正则表达式模式或谓词,接收一个 URL 以在路由期间匹配。如果在上下文选项中设置了 baseURL,并且提供的 URL 是不以
*
开头的字符串,则使用new URL()
构造函数进行解析。 -
handler
function(路由, 请求):Promise<Object> | Object#用于路由请求的处理函数。
-
options
Object (可选)
返回
routeFromHAR
新增于: v1.23如果指定,上下文中发出的网络请求将从 HAR 文件中提供。阅读有关 从 HAR 重放 的更多信息。
Playwright 不会从 HAR 文件中提供被 Service Worker 拦截的请求。请参阅 此 问题。我们建议在使用请求拦截时通过将 serviceWorkers 设置为 'block'
来禁用 Service Worker。
用法
await browserContext.routeFromHAR(har);
await browserContext.routeFromHAR(har, options);
参数
-
带有预录网络数据的 HAR 文件路径。如果
path
是相对路径,则它相对于当前工作目录解析。 -
options
Object (可选)-
notFound
"abort" | "fallback" (可选)#- 如果设置为 'abort',则 HAR 文件中未找到的任何请求都将被中止。
- 如果设置为 'fallback',则会退回到处理程序链中的下一个路由处理程序。
默认为中止。
-
如果指定,则使用实际网络信息更新给定的 HAR,而不是从文件中提供。在调用 browserContext.close() 时将文件写入磁盘。
-
updateContent
"embed" | "attach" (可选)新增于: v1.32#可选设置以控制资源内容管理。如果指定
attach
,资源将作为单独的文件或 ZIP 档案中的条目持久化。如果指定embed
,内容将内联存储在 HAR 文件中。 -
updateMode
"full" | "minimal" (可选)新增于: v1.32#当设置为
minimal
时,仅记录从 HAR 路由所需的信息。这会省略 HAR 信息中不用于从 HAR 重放的大小、时间、页面、cookie、安全性和其他类型的信息。默认为minimal
。 -
一个 glob 模式、正则表达式或谓词,用于匹配请求 URL。只有 URL 匹配模式的请求将从 HAR 文件中提供。如果未指定,所有请求都将从 HAR 文件中提供。
-
返回
routeWebSocket
新增于: v1.48此方法允许修改浏览器上下文中任何页面进行的 WebSocket 连接。
请注意,只有在此方法调用后创建的 WebSocket
才会路由。建议在创建任何页面之前调用此方法。
用法
下面是一个简单处理程序的示例,它阻止某些 WebSocket 消息。有关更多详细信息和示例,请参阅 WebSocketRoute。
await context.routeWebSocket('/ws', async ws => {
ws.routeSend(message => {
if (message === 'to-be-blocked')
return;
ws.send(message);
});
await ws.connect();
});
参数
-
url
string | RegExp | function(URL):boolean#只有 URL 匹配此模式的 WebSockets 才会被路由。字符串模式可以是相对于 baseURL 上下文选项的。
-
handler
function(WebSocketRoute):Promise<Object> | Object#用于路由 WebSocket 的处理函数。
返回
serviceWorkers
新增于: v1.11Service Worker 仅在基于 Chromium 的浏览器上受支持。
上下文中所有现有的 Service Worker。
用法
browserContext.serviceWorkers();
返回
setDefaultNavigationTimeout
v1.9 之前添加此设置将更改以下方法和相关快捷方式的默认最大导航时间
用法
browserContext.setDefaultNavigationTimeout(timeout);
参数
setDefaultTimeout
v1.9 之前添加此设置将更改所有接受 timeout 选项的方法的默认最大时间。
用法
browserContext.setDefaultTimeout(timeout);
参数
setExtraHTTPHeaders
v1.9 之前添加额外的 HTTP 头将随上下文中任何页面发起的每个请求一起发送。这些头将与使用 page.setExtraHTTPHeaders() 设置的页面特定额外 HTTP 头合并。如果页面覆盖了某个特定头,将使用页面特定头的值,而不是浏览器上下文头的值。
browserContext.setExtraHTTPHeaders() 不保证传出请求中头的顺序。
用法
await browserContext.setExtraHTTPHeaders(headers);
参数
返回
setGeolocation
v1.9 之前添加设置上下文的地理位置。传入 null
或 undefined
模拟位置不可用。
用法
await browserContext.setGeolocation({ latitude: 59.95, longitude: 30.31667 });
考虑使用 browserContext.grantPermissions() 授予浏览器上下文页面读取其地理位置的权限。
参数
返回
setOffline
v1.9 之前添加用法
await browserContext.setOffline(offline);
参数
返回
storageState
v1.9 之前添加返回此浏览器上下文的存储状态,包含当前 cookie、本地存储快照和 IndexedDB 快照。
用法
await browserContext.storageState();
await browserContext.storageState(options);
参数
options
Object (可选)
返回
unroute
v1.9 之前添加移除使用 browserContext.route() 创建的路由。如果未指定 handler,则移除 url 的所有路由。
用法
await browserContext.unroute(url);
await browserContext.unroute(url, handler);
参数
-
url
string | RegExp | function(URL):boolean#用于通过 browserContext.route() 注册路由的 glob 模式、正则表达式模式或接收 URL 的谓词。
-
handler
function(路由, 请求):Promise<Object> | Object (可选)#可选的处理函数,用于通过 browserContext.route() 注册路由。
返回
unrouteAll
新增于: v1.41移除所有通过 browserContext.route() 和 browserContext.routeFromHAR() 创建的路由。
用法
await browserContext.unrouteAll();
await browserContext.unrouteAll(options);
参数
options
Object (可选)-
behavior
"wait" | "ignoreErrors" | "default" (可选)#指定是否等待已运行的处理程序以及如果它们抛出错误该怎么做
'default'
- 不等待当前处理程序调用 (如果有) 完成,如果未路由的处理程序抛出错误,可能会导致未处理的错误'wait'
- 等待当前处理程序调用 (如果有) 完成'ignoreErrors'
- 不等待当前处理程序调用 (如果有) 完成,取消路由后处理程序抛出的所有错误都将被静默捕获
-
返回
waitForEvent
v1.9 之前添加等待事件触发并将其值传递给谓词函数。当谓词返回真值时返回。如果上下文在事件触发前关闭,将抛出错误。返回事件数据值。
用法
const pagePromise = context.waitForEvent('page');
await page.getByRole('button').click();
const page = await pagePromise;
参数
-
事件名称,与
browserContext.on(event)
中传入的相同。 -
optionsOrPredicate
function | Object (可选)#-
predicate
function接收事件数据,并在等待应该解决时解析为真值。
-
timeout
number (可选)最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项或使用 browserContext.setDefaultTimeout() 方法更改。
一个接收事件的谓词或一个选项对象。可选。
-
-
options
Object (可选)
返回
属性
clock
新增于: v1.45Playwright 能够模拟时钟和时间流逝。
用法
browserContext.clock
类型
request
添加于:v1.16与此上下文关联的 API 测试助手。使用此 API 发出的请求将使用上下文 cookie。
用法
browserContext.request
类型
tracing
新增于: v1.12用法
browserContext.tracing
类型
事件
on('backgroundpage')
新增于: v1.11仅适用于 Chromium 浏览器的持久上下文。
当在上下文中创建新的后台页面时触发。
const backgroundPage = await context.waitForEvent('backgroundpage');
用法
browserContext.on('backgroundpage', data => {});
事件数据
on('close')
v1.9 之前添加当浏览器上下文关闭时触发。这可能由于以下原因之一发生:
- 浏览器上下文已关闭。
- 浏览器应用程序已关闭或崩溃。
- 调用了 browser.close() 方法。
用法
browserContext.on('close', data => {});
事件数据
on('console')
新增于: v1.34当页面中的 JavaScript 调用其中一个 console API 方法(例如 console.log
或 console.dir
)时触发。
传递给 console.log
的参数和页面可在 ConsoleMessage 事件处理程序参数中获取。
用法
context.on('console', async msg => {
const values = [];
for (const arg of msg.args())
values.push(await arg.jsonValue());
console.log(...values);
});
await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));
事件数据
on('dialog')
新增于: v1.34当出现 JavaScript 对话框时触发,例如 alert
, prompt
, confirm
或 beforeunload
。监听器**必须** dialog.accept() 或 dialog.dismiss() 该对话框——否则页面将 冻结 等待对话框,并且像点击这样的操作将永远不会完成。
用法
context.on('dialog', dialog => {
dialog.accept();
});
当没有 page.on('dialog') 或 browserContext.on('dialog') 监听器存在时,所有对话框都会自动关闭。
事件数据
on('page')
v1.9 之前添加当 BrowserContext 中创建新页面时触发此事件。页面可能仍在加载中。此事件也适用于弹出页面。另请参阅 page.on('popup') 以接收与特定页面相关的弹出窗口事件。
页面最早可用的时刻是当它导航到初始 URL 时。例如,当使用 window.open('http://example.com')
打开弹出窗口时,此事件将在对 "http://example.com" 的网络请求完成且其响应开始在弹出窗口中加载时触发。如果您想路由/监听此网络请求,请使用 browserContext.route() 和 browserContext.on('request'),而不是 页面 上的类似方法。
const newPagePromise = context.waitForEvent('page');
await page.getByText('open new page').click();
const newPage = await newPagePromise;
console.log(await newPage.evaluate('location.href'));
使用 page.waitForLoadState() 等待页面达到特定状态(在大多数情况下您不需要它)。
用法
browserContext.on('page', data => {});
事件数据
on('request')
新增于: v1.12当通过此上下文创建的任何页面发出请求时触发。请求 对象是只读的。要仅监听特定页面发出的请求,请使用 page.on('request')。
要拦截和修改请求,请参阅 browserContext.route() 或 page.route()。
用法
browserContext.on('request', data => {});
事件数据
on('requestfailed')
新增于: v1.12当请求失败时触发,例如超时。要仅监听特定页面发出的失败请求,请使用 page.on('requestfailed')。
HTTP 错误响应,例如 404 或 503,从 HTTP 角度来看仍然是成功的响应,因此请求将以 browserContext.on('requestfinished') 事件完成,而不是以 browserContext.on('requestfailed') 完成。
用法
browserContext.on('requestfailed', data => {});
事件数据
on('requestfinished')
新增于: v1.12当请求成功完成响应体下载时触发。对于成功的响应,事件序列是 request
, response
和 requestfinished
。要监听特定页面发出的成功请求,请使用 page.on('requestfinished')。
用法
browserContext.on('requestfinished', data => {});
事件数据
on('response')
新增于: v1.12当请求的 响应 状态和头信息被接收时触发。对于成功的响应,事件序列是 request
、response
和 requestfinished
。要监听特定页面发出的响应事件,请使用 page.on('response')。
用法
browserContext.on('response', data => {});
事件数据
on('serviceworker')
新增于: v1.11Service Worker 仅在基于 Chromium 的浏览器上受支持。
当在上下文中创建新的 Service Worker 时触发。
用法
browserContext.on('serviceworker', data => {});
事件数据
on('weberror')
新增于: v1.38当此上下文中任何页面中出现未处理异常时触发。要监听特定页面中的错误,请改用 page.on('pageerror')。
用法
browserContext.on('weberror', data => {});
事件数据
已弃用
setHTTPCredentials
v1.9 之前添加浏览器在成功认证后可能会缓存凭据。请改为创建新的浏览器上下文。
用法
await browserContext.setHTTPCredentials(httpCredentials);
参数
返回