BrowserContext

extends: EventEmitter

BrowserContext 提供了一种操作多个独立浏览器会话的方法。

如果一个页面打开了另一个页面，例如使用 window.open 调用，弹出窗口将属于父页面的浏览器上下文。

Playwright 允许使用 browser.newContext([options]) 方法创建“隐身”浏览器上下文。“隐身”浏览器上下文不会将任何浏览数据写入磁盘。

// 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();

browserContext.on('backgroundpage')

Added in: v1.11

type: <Page>

note

仅适用于 Chromium 浏览器的持久上下文。

当在上下文中创建新的后台页面时触发。

const backgroundPage = await context.waitForEvent('backgroundpage');

browserContext.on('close')

Added in: v1.8

type: <BrowserContext>

当浏览器上下文关闭时触发。这可能是由于以下原因之一发生的：

浏览器上下文已关闭。
浏览器应用程序已关闭或崩溃。
调用了 browser.close() 方法。

browserContext.on('page')

Added in: v1.8

type: <Page>

当在 BrowserContext 中创建新页面时触发此事件。页面可能仍在加载中。该事件也会针对弹出页面触发。另请参阅 page.on('popup') 以接收与特定页面相关的弹出窗口事件。

页面可用的最早时刻是它导航到初始 url 时。例如，当使用 window.open('http://example.com') 打开弹出窗口时，此事件将在对 "http://example.com" 的网络请求完成且其响应已开始在弹出窗口中加载时触发。

const [newPage] = await Promise.all([
  context.waitForEvent('page'),
  page.locator('a[target=_blank]').click(),
]);
console.log(await newPage.evaluate('location.href'));

note

使用 page.waitForLoadState([state, options]) 等待页面达到特定状态（大多数情况下不需要这样做）。

browserContext.on('request')

Added in: v1.12

type: <Request>

当通过此上下文创建的任何页面发出请求时触发。request 对象是只读的。要仅监听来自特定页面的请求，请使用 page.on('request')。

为了拦截和修改请求，请参阅 browserContext.route(url, handler[, options]) 或 page.route(url, handler[, options])。

browserContext.on('requestfailed')

Added in: v1.12

type: <Request>

当请求失败时触发，例如超时。要仅监听来自特定页面的失败请求，请使用 page.on('requestfailed')。

note

HTTP 错误响应（如 404 或 503）从 HTTP 角度来看仍然是成功的响应，因此请求将以 browserContext.on('requestfinished') 事件完成，而不是 browserContext.on('requestfailed')。

browserContext.on('requestfinished')

Added in: v1.12

type: <Request>

当请求在下载响应体后成功完成时触发。对于成功的响应，事件序列为 request、response 和 requestfinished。要监听来自特定页面的成功请求，请使用 page.on('requestfinished')。

browserContext.on('response')

Added in: v1.12

type: <Response>

当接收到请求的 response 状态和标头时触发。对于成功的响应，事件序列为 request、response 和 requestfinished。要监听来自特定页面的响应事件，请使用 page.on('response')。

browserContext.on('serviceworker')

Added in: v1.11

type: <Worker>

note

Service workers 仅在基于 Chromium 的浏览器上受支持。

当在上下文中创建新的 service worker 时触发。

browserContext.addCookies(cookies)

Added in: v1.8

cookies <Array<Object>>#
- name <string>
- value <string>
- url? <string> either url or domain / path are required. Optional.
- domain? <string> either url or domain / path are required Optional.
- path? <string> either url or domain / path are required Optional.
- expires? <number> Unix time in seconds. Optional.
- httpOnly? <boolean> Optional.
- secure? <boolean> Optional.
- sameSite? <"Strict"|"Lax"|"None"> Optional.
returns: <Promise<void>>#

将 cookie 添加到此浏览器上下文中。此上下文中的所有页面都将安装这些 cookie。可以通过 browserContext.cookies([urls]) 获取 cookie。

await browserContext.addCookies([cookieObject1, cookieObject2]);

browserContext.addInitScript(script[, arg])

Added in: v1.8

script <function|string|Object> 要在浏览器上下文中的所有页面中评估的脚本。#
- path? <string> Path to the JavaScript file. If path is a relative path, then it is resolved relative to the current working directory. Optional.
- content? <string> Raw script content. Optional.
arg? <Serializable> Optional argument to pass to script (only supported when passing a function).#
returns: <Promise<void>>#

添加一个脚本，该脚本将在以下场景之一中进行评估：

每当在浏览器上下文中创建页面或导航页面时。
每当子帧附加到浏览器上下文中的任何页面或在其中导航时。在这种情况下，脚本将在新附加的帧的上下文中进行评估。

脚本在文档创建之后但在运行任何脚本之前进行评估。这对于修改 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'
});

note

通过 browserContext.addInitScript(script[, arg]) 和 page.addInitScript(script[, arg]) 安装的多个脚本的评估顺序未定义。

browserContext.backgroundPages()

Added in: v1.11

returns: <Array<Page>>#

note

后台页面仅在基于 Chromium 的浏览器上受支持。

上下文中的所有现有后台页面。

browserContext.browser()

Added in: v1.8

returns: <null|Browser>#

返回上下文的浏览器实例。如果它是作为持久上下文启动的，则返回 null。

browserContext.clearCookies()

Added in: v1.8

returns: <Promise<void>>#

清除上下文 cookie。

browserContext.clearPermissions()

Added in: v1.8

returns: <Promise<void>>#

清除浏览器上下文的所有权限覆盖。

const context = await browser.newContext();
await context.grantPermissions(['clipboard-read']);
// do stuff ..
context.clearPermissions();

browserContext.close()

Added in: v1.8

returns: <Promise<void>>#

关闭浏览器上下文。属于浏览器上下文的所有页面都将关闭。

note

无法关闭默认浏览器上下文。

browserContext.cookies([urls])

Added in: v1.8

urls? <string|Array<string>> 可选的 URL 列表。#
returns: <Promise<Array<Object>>>#
- name <string>
- value <string>
- domain <string>
- path <string>
- expires <number> Unix time in seconds.
- httpOnly <boolean>
- secure <boolean>
- sameSite <"Strict"|"Lax"|"None">

如果未指定 URL，则此方法返回所有 cookie。如果指定了 URL，则仅返回影响这些 URL 的 cookie。

browserContext.exposeBinding(name, callback[, options])

Added in: v1.8

name <string> window 对象上的函数名称。#
callback <function> 将在 Playwright 上下文中调用的回调函数。#
options? <Object>
- handle? <boolean> 是否将参数作为句柄传递，而不是按值传递。传递句柄时，仅支持一个参数。按值传递时，支持多个参数。#
returns: <Promise<void>>#

该方法在上下文中每个页面的每个帧的 window 对象上添加一个名为 name 的函数。当调用该函数时，它执行 callback 并返回一个 Promise，该 Promise 解析为 callback 的返回值。如果 callback 返回一个 Promise，它将被等待。

callback 函数的第一个参数包含有关调用者的信息：{ browserContext: BrowserContext, page: Page, frame: Frame }。

有关仅页面版本，请参阅 page.exposeBinding(name, callback[, options])。

将页面 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();
})();

传递元素句柄的示例：

await context.exposeBinding('clicked', async (source, element) => {
  console.log(await element.textContent());
}, { handle: true });
await page.setContent(`
  <script>
    document.addEventListener('click', event => window.clicked(event.target));
  </script>
  <div>Click me</div>
  <div>Or click me</div>
`);

browserContext.exposeFunction(name, callback)

Added in: v1.8

name <string> window 对象上的函数名称。#
callback <function> 将在 Playwright 上下文中调用的回调函数。#
returns: <Promise<void>>#

该方法在上下文中每个页面的每个帧的 window 对象上添加一个名为 name 的函数。当调用该函数时，它执行 callback 并返回一个 Promise，该 Promise 解析为 callback 的返回值。

如果 callback 返回一个 Promise，它将被等待。

有关仅页面版本，请参阅 page.exposeFunction(name, callback)。

向上下文中的所有页面添加 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();
})();

browserContext.grantPermissions(permissions[, options])

Added in: v1.8

permissions <Array<string>> 要授予的权限或权限数组。权限可以是以下值之一：#
- 'geolocation'
- 'midi'
- 'midi-sysex' (system-exclusive midi)
- 'notifications'
- 'camera'
- 'microphone'
- 'background-sync'
- 'ambient-light-sensor'
- 'accelerometer'
- 'gyroscope'
- 'magnetometer'
- 'accessibility-events'
- 'clipboard-read'
- 'clipboard-write'
- 'payment-handler'
options? <Object>
- origin? <string> 要授予权限的 origin，例如 "https://example.com"。#
returns: <Promise<void>>#

向浏览器上下文授予指定权限。如果指定了 origin，则仅向该 origin 授予相应的权限。

browserContext.newCDPSession(page)

Added in: v1.11

page <Page|Frame> 为其创建新会话的目标。为了向后兼容，此参数名为 page，但它可以是 Page 或 Frame 类型。#
returns: <Promise<CDPSession>>#

note

CDP 会话仅在基于 Chromium 的浏览器上受支持。

返回新创建的会话。

browserContext.newPage()

Added in: v1.8

returns: <Promise<Page>>#

在浏览器上下文中创建一个新页面。

browserContext.pages()

Added in: v1.8

returns: <Array<Page>>#

返回上下文中所有打开的页面。

browserContext.route(url, handler[, options])

Added in: v1.8

url <string|RegExp|function(URL):boolean> 用于在路由时匹配的 glob 模式、正则表达式模式或接收 URL 的谓词。当通过上下文选项提供了 baseURL 且传递的 URL 是路径时，它将通过 new URL() 构造函数进行合并。#
handler <function(Route, Request)> 用于路由请求的处理函数。#
options? <Object>
- times? <number> 路由应使用的频率。默认情况下，每次都会使用。Added in: v1.15#
returns: <Promise<void>>#

路由提供了修改浏览器上下文中任何页面发出的网络请求的功能。一旦启用路由，每个匹配 url 模式的请求都将暂停，除非它被继续、满足或中止。

note

browserContext.route(url, handler[, options]) 不会拦截被 Service Worker 拦截的请求。请参阅此问题。我们建议在使用请求拦截时通过将 Browser.newContext.serviceWorkers 设置为 'block' 来禁用 Service Workers。

中止所有图像请求的简单处理程序示例：

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();

可以检查请求以决定路由操作。例如，模拟包含某些发布数据的所有请求，并保持所有其他请求不变：

await context.route('/api/**', route => {
  if (route.request().postData().includes('my-string'))
    route.fulfill({ body: 'mocked-data' });
  else
    route.continue();
});

当请求同时匹配两个处理程序时，页面路由（使用 page.route(url, handler[, options]) 设置）优先于浏览器上下文路由。

要删除带有其处理程序的路由，可以使用 browserContext.unroute(url[, handler])。

note

启用路由会禁用 http 缓存。

browserContext.routeFromHAR(har[, options])

Added in: v1.23

har <string> 包含预先录制的网络数据的 HAR 文件路径。如果 path 是相对路径，则相对于当前工作目录解析。#
options? <Object>
- notFound? <"abort"|"fallback"> 如果设置为 'abort'，则任何在 HAR 文件中未找到的请求都将被中止。#
  - 如果设置为 'fallback'，则会继续执行处理程序链中的下一个路由处理程序。
  默认为 abort。
- update? <boolean> 如果指定，则使用实际网络信息更新给定的 HAR，而不是从文件提供服务。#
- url? <string|RegExp> 用于匹配请求 URL 的 glob 模式、正则表达式或谓词。只有 URL 匹配模式的请求才会从 HAR 文件提供服务。如果未指定，则所有请求都从 HAR 文件提供服务。#
returns: <Promise<void>>#

如果指定，则上下文中发出的网络请求将从 HAR 文件提供服务。阅读更多关于 Replaying from HAR 的信息。

Playwright 不会从 HAR 文件提供被 Service Worker 拦截的请求。请参阅此问题。我们建议在使用请求拦截时通过将 Browser.newContext.serviceWorkers 设置为 'block' 来禁用 Service Workers。

browserContext.serviceWorkers()

Added in: v1.11

returns: <Array<Worker>>#

note

Service workers 仅在基于 Chromium 的浏览器上受支持。

上下文中的所有现有 service workers。

Added in: v1.8

timeout <number> 最大导航时间（毫秒）#
returns: <void>#

此设置将更改以下方法和相关快捷方式的默认最大导航时间：

note

page.setDefaultNavigationTimeout(timeout) 和 page.setDefaultTimeout(timeout) 优先于 browserContext.setDefaultNavigationTimeout(timeout)。

browserContext.setDefaultTimeout(timeout)

Added in: v1.8

timeout <number> 最大时间（毫秒）#
returns: <void>#

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

note

page.setDefaultNavigationTimeout(timeout)、page.setDefaultTimeout(timeout) 和 browserContext.setDefaultNavigationTimeout(timeout) 优先于 browserContext.setDefaultTimeout(timeout)。

browserContext.setExtraHTTPHeaders(headers)

Added in: v1.8

headers <Object<string, string>> 包含要随每个请求发送的附加 HTTP 标头的对象。所有标头值必须是字符串。#
returns: <Promise<void>>#

额外的 HTTP 标头将随上下文中任何页面发起的每个请求一起发送。这些标头与使用 page.setExtraHTTPHeaders(headers) 设置的页面特定额外 HTTP 标头合并。如果页面覆盖特定标头，则将使用页面特定标头值而不是浏览器上下文标头值。

note

browserContext.setExtraHTTPHeaders(headers) 不保证传出请求中标头的顺序。

browserContext.setGeolocation(geolocation)

Added in: v1.8

geolocation <null|Object>#
- latitude <number> Latitude between -90 and 90.
- longitude <number> Longitude between -180 and 180.
- accuracy? <number> Non-negative accuracy value. Defaults to 0.
returns: <Promise<void>>#

设置上下文的地理位置。传递 null 或 undefined 会模拟位置不可用。

await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667});

note

考虑使用 browserContext.grantPermissions(permissions[, options]) 授予浏览器上下文页面读取其地理位置的权限。

browserContext.setHTTPCredentials(httpCredentials)

Added in: v1.8

httpCredentials <null|Object>#
- username <string>
- password <string>
returns: <Promise<void>>#

已弃用 浏览器可能会在成功验证后缓存凭据。请改为创建新的浏览器上下文。

browserContext.setOffline(offline)

Added in: v1.8

offline <boolean> 是否为浏览器上下文模拟网络离线。#
returns: <Promise<void>>#

browserContext.storageState([options])

Added in: v1.8

options? <Object>
- path? <string> 保存存储状态的文件路径。如果 path 是相对路径，则相对于当前工作目录解析。如果未提供路径，则仍返回存储状态，但不会保存到磁盘。#
returns: <Promise<Object>>#
- cookies <Array<Object>>
  - name <string>
  - value <string>
  - domain <string>
  - path <string>
  - expires <number> Unix time in seconds.
  - httpOnly <boolean>
  - secure <boolean>
  - sameSite <"Strict"|"Lax"|"None">
- origins <Array<Object>>
  - origin <string>
  - localStorage <Array<Object>>
    - name <string>
    - value <string>

返回此浏览器上下文的存储状态，包含当前 cookie 和本地存储快照。

browserContext.unroute(url[, handler])

Added in: v1.8

url <string|RegExp|function(URL):boolean> 用于通过 browserContext.route(url, handler[, options]) 注册路由的 glob 模式、正则表达式模式或接收 URL 的谓词。#
handler? <function(Route, Request)> 用于通过 browserContext.route(url, handler[, options]) 注册路由的可选处理函数。#
returns: <Promise<void>>#

删除通过 browserContext.route(url, handler[, options]) 创建的路由。如果未指定 handler，则删除 url 的所有路由。

browserContext.waitForEvent(event[, optionsOrPredicate, options])

Added in: v1.8

event <string> 事件名称，与传递给 browserContext.on(event) 的名称相同。#
optionsOrPredicate? <function|Object> 接收事件的谓词或选项对象。可选。#
- predicate <function> receives the event data and resolves to truthy value when the waiting should resolve.
- timeout? <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout).
options? <Object>
- predicate? <function> 接收事件数据并在等待应解析时解析为真值的函数。#
returns: <Promise<Object>>#

等待事件触发并将其值传递给谓词函数。当谓词返回真值时返回。如果上下文在事件触发前关闭，将抛出错误。返回事件数据值。

const [page, _] = await Promise.all([
  context.waitForEvent('page'),
  page.getByRole('button').click()
]);

browserContext.request

Added in: v1.16

type: <APIRequestContext>

与此上下文关联的 API 测试助手。使用此 API 发出的请求将使用上下文 cookie。

browserContext.tracing

Added in: v1.12

type: <Tracing>

browserContext.on('backgroundpage')​

browserContext.on('close')​

browserContext.on('page')​

browserContext.on('request')​

browserContext.on('requestfailed')​

browserContext.on('requestfinished')​

browserContext.on('response')​

browserContext.on('serviceworker')​

browserContext.addCookies(cookies)​

browserContext.addInitScript(script[, arg])​

browserContext.backgroundPages()​

browserContext.browser()​

browserContext.clearCookies()​

browserContext.clearPermissions()​

browserContext.close()​

browserContext.cookies([urls])​

browserContext.exposeBinding(name, callback[, options])​

browserContext.exposeFunction(name, callback)​

browserContext.grantPermissions(permissions[, options])​

browserContext.newCDPSession(page)​

browserContext.newPage()​

browserContext.pages()​

browserContext.route(url, handler[, options])​

browserContext.routeFromHAR(har[, options])​

browserContext.serviceWorkers()​

browserContext.setDefaultNavigationTimeout(timeout)​

browserContext.setDefaultTimeout(timeout)​

browserContext.setExtraHTTPHeaders(headers)​

browserContext.setGeolocation(geolocation)​

browserContext.setHTTPCredentials(httpCredentials)​

browserContext.setOffline(offline)​

browserContext.storageState([options])​

browserContext.unroute(url[, handler])​

browserContext.waitForEvent(event[, optionsOrPredicate, options])​

browserContext.request​

browserContext.tracing​

browserContext.on('backgroundpage')

browserContext.on('close')

browserContext.on('page')

browserContext.on('request')

browserContext.on('requestfailed')

browserContext.on('requestfinished')

browserContext.on('response')

browserContext.on('serviceworker')

browserContext.addCookies(cookies)

browserContext.addInitScript(script[, arg])

browserContext.backgroundPages()

browserContext.browser()

browserContext.clearCookies()

browserContext.clearPermissions()

browserContext.close()

browserContext.cookies([urls])

browserContext.exposeBinding(name, callback[, options])

browserContext.exposeFunction(name, callback)

browserContext.grantPermissions(permissions[, options])

browserContext.newCDPSession(page)

browserContext.newPage()

browserContext.pages()

browserContext.route(url, handler[, options])

browserContext.routeFromHAR(har[, options])

browserContext.serviceWorkers()

browserContext.setDefaultNavigationTimeout(timeout)

browserContext.setDefaultTimeout(timeout)

browserContext.setExtraHTTPHeaders(headers)

browserContext.setGeolocation(geolocation)

browserContext.setHTTPCredentials(httpCredentials)

browserContext.setOffline(offline)

browserContext.storageState([options])

browserContext.unroute(url[, handler])

browserContext.waitForEvent(event[, optionsOrPredicate, options])

browserContext.request

browserContext.tracing