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。可以通过 browserContext.cookies() 获取 cookie。
用法
await browserContext.addCookies([cookieObject1, cookieObject2]);
参数
cookies数组<对象>#-
name字符串 -
value字符串 -
url字符串 (可选)url 或 domain / path 是必需的（指 cookie 对象）。可选。
-
domain字符串 (可选)要使 cookie 也适用于所有子域，请在 domain 前面加上一个点，例如：".example.com"。url 或 domain / path 是必需的。可选。
-
path字符串 (可选)url 或 domain / path 是必需的。可选。
-
expires数字 (可选)Unix 时间（秒）。可选。
-
httpOnly布尔值 (可选)可选。
-
secure布尔值 (可选)可选。
-
sameSite"Strict" | "Lax" | "None" (可选)可选。
-
返回值
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() 安装的多个脚本的执行顺序未定义。
参数
-
将在浏览器上下文的所有页面中执行的脚本。
-
要传递给 script 的可选参数（仅在传递函数时支持）。
返回值
backgroundPages
添加于: v1.11背景页仅在基于 Chromium 的浏览器上受支持。
上下文中所有现有的背景页。
用法
browserContext.backgroundPages();
返回值
browser
在 v1.9 之前添加返回上下文的浏览器实例。如果作为持久化上下文启动，则返回 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对象 (可选)
返回值
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 并返回一个 Promise，该 Promise 将解析为 callback 的返回值。如果 callback 返回一个 Promise，它将被等待（await）。
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();
})();
参数
-
window对象上的函数名称。 -
在 Playwright 上下文中调用的回调函数。
-
options对象 (可选)
返回值
exposeFunction
在 v1.9 之前添加此方法在上下文中每个页面中每个框架的 window 对象上添加一个名为 name 的函数。调用时，该函数执行 callback 并返回一个 Promise，该 Promise 将解析为 callback 的返回值。
如果 callback 返回 Promise，它将被等待（await）。
请参阅 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'(system-exclusive midi)'midi''notifications''payment-handler''storage-access'
-
options对象 (可选)-
要授予权限的 源，例如 "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字符串 (可选)#options对象 (可选)-
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字符串 | RegExp | 函数(URL):布尔值#用于路由匹配的 glob 模式、正则表达式模式或接收 URL 的谓词。如果在上下文选项中设置了 baseURL，并且提供的 URL 是不以
*开头的字符串，则使用new URL()构造函数解析它。 -
handler函数(Route, Request):Promise<对象> | 对象#用于路由请求的处理程序函数。
-
options对象 (可选)
返回值
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对象 (可选)-
notFound"abort" | "fallback" (可选)#- 如果设置为 'abort'，则 HAR 文件中未找到的任何请求将被中止。
- 如果设置为 'fallback'，则会回退到处理程序链中的下一个路由处理程序。
默认为 abort。
-
如果指定，则使用实际网络信息更新给定的 HAR 文件，而不是从文件中提供服务。文件在调用 browserContext.close() 时写入磁盘。
-
updateContent"embed" | "attach" (可选)添加于: v1.32#控制资源内容管理的可选设置。如果指定
attach，资源将作为单独的文件或 ZIP 档案中的条目持久化。如果指定embed，内容将存储在 HAR 文件中。 -
updateMode"full" | "minimal" (可选)添加于: v1.32#当设置为
minimal时，仅记录从 HAR 路由所需的信息。这将忽略大小、时间、页面、cookie、安全以及其他在从 HAR 回放时不使用的 HAR 信息类型。默认为minimal。 -
用于匹配请求 URL 的 glob 模式、正则表达式或判断函数。只有 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();
});
参数
-
urlstring | RegExp | function(URL):boolean#只有 URL 与此模式匹配的 WebSockets 才会被路由。字符串模式可以相对于 baseURL 上下文选项。
-
handlerfunction(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对象 (可选)
返回值
unroute
在 v1.9 之前添加移除使用 browserContext.route() 创建的路由。如果未指定 handler，则移除 url 的所有路由。
用法
await browserContext.unroute(url);
await browserContext.unroute(url, handler);
参数
-
urlstring | RegExp | function(URL):boolean#用于注册 browserContext.route() 路由的 glob 模式、正则表达式模式或接收 URL 的判断函数。
-
handlerfunction(Route, Request):Promise<Object> | Object (可选)#用于注册 browserContext.route() 路由的可选处理函数。
返回值
unrouteAll
添加于: v1.41移除使用 browserContext.route() 和 browserContext.routeFromHAR() 创建的所有路由。
用法
await browserContext.unrouteAll();
await browserContext.unrouteAll(options);
参数
options对象 (可选)-
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)的相同。 -
optionsOrPredicatefunction | Object (可选)#-
predicatefunction接收事件数据并在等待应该解析时解析为真值。
-
timeoutnumber (可选)最大等待时间（毫秒）。默认为
0- 无超时。可以通过配置中的actionTimeout选项或使用 browserContext.setDefaultTimeout() 方法更改默认值。
可以是接收事件的判断函数，也可以是选项对象。可选。
-
-
options对象 (可选)
返回值
属性
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 调用控制台 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 时触发此事件。页面可能仍在加载。此事件也会针对弹出页面触发。另请参阅 page.on('popup')，以接收与特定页面相关的弹出窗口事件。
页面最早可用的时刻是当它已导航到初始 URL 时。例如，当使用 window.open('http://example.com') 打开一个弹出窗口时，当对 "http://example.com" 的网络请求完成并且其响应已开始在弹出窗口中加载时，此事件将触发。如果您想路由/监听此网络请求，请分别使用 browserContext.route() 和 browserContext.on('request')，而不是在 Page 上使用类似方法。
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当通过此上下文创建的任何页面发出请求时触发。 request 对象是只读的。要仅监听来自特定页面的请求，请使用 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当收到请求的 response 状态和请求头时触发。对于成功响应，事件序列是 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);
参数
返回值