跳到主要内容

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 版本前添加 browserContext.addCookies

将 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 也适用于所有子域，请在域名前加上一个点，例如：".example.com"。url 或 domain / path 是必需的。可选。

    • path string (可选)

      url 或 domain / path 是必需的可选。

    • expires number (可选)

      Unix 时间戳，单位为秒。可选。

    • httpOnly boolean (可选)

      可选。

    • secure boolean (可选)

      可选。

    • sameSite "Strict" | "Lax" | "None" (可选)

      可选。

返回值

addInitScript​

在 v1.9 版本前添加 browserContext.addInitScript

添加一个脚本，该脚本将在以下场景之一中执行

  • 每当在浏览器上下文中创建或导航页面时。
  • 每当在浏览器上下文中的任何页面中附加或导航子框架时。在这种情况下，脚本在新附加的框架的上下文中执行。

该脚本在文档创建后但在其任何脚本运行之前执行。这对于修改 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 function | string | Object#

    • path string (可选)

      JavaScript 文件的路径。如果 path 是相对路径，则它相对于当前工作目录解析。可选。

    • content string (可选)

      原始脚本内容。可选。

    要在浏览器上下文中所有页面中评估的脚本。

  • arg Serializable (可选)#

    传递给 script 的可选参数（仅在传递函数时支持）。

返回值

backgroundPages​

添加于: v1.11 browserContext.backgroundPages
注意

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

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

用法

browserContext.backgroundPages();

返回值

browser​

在 v1.9 版本前添加 browserContext.browser

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

用法

browserContext.browser();

返回值

clearCookies​

在 v1.9 版本前添加 browserContext.clearCookies

从上下文中移除 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 (可选)

    • domain string | RegExp (可选)添加于: v1.43#

      仅删除具有给定域的 Cookie。

    • name string | RegExp (可选)添加于: v1.43#

      仅删除具有给定名称的 Cookie。

    • path string | RegExp (可选)添加于: v1.43#

      仅删除具有给定路径的 Cookie。

返回值

clearPermissions​

在 v1.9 版本前添加 browserContext.clearPermissions

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

用法

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

返回值

close​

在 v1.9 版本前添加 browserContext.close

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

注意

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

用法

await browserContext.close();
await browserContext.close(options);

参数

  • options Object (可选)

    • reason string (可选)添加于: v1.40#

      要报告给上下文关闭中断操作的原因。

返回值

cookies​

在 v1.9 版本前添加 browserContext.cookies

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

用法

await browserContext.cookies();
await browserContext.cookies(urls);

参数

返回值

exposeBinding​

在 v1.9 版本前添加 browserContext.exposeBinding

此方法在上下文中每个页面的每个框架的 window 对象上添加一个名为 name 的函数。当调用该函数时，它会执行 callback 并返回一个 Promise，该 Promise 解析为 callback 的返回值。如果 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();
})();

参数

  • name string#

    window 对象上函数的名称。

  • callback function#

    将在 Playwright 的上下文中调用的回调函数。

  • options Object (可选)

    • handle boolean (可选)#

      已弃用

      此选项将在未来版本中移除。

      是否将参数作为句柄传递，而不是按值传递。当传递句柄时，仅支持一个参数。当按值传递时，支持多个参数。

返回值

exposeFunction​

在 v1.9 版本前添加 browserContext.exposeFunction

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

如果 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();
})();

参数

  • name string#

    window 对象上函数的名称。

  • callback function#

    将在 Playwright 的上下文中调用的回调函数。

返回值

grantPermissions​

在 v1.9 版本前添加 browserContext.grantPermissions

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

用法

await browserContext.grantPermissions(permissions);
await browserContext.grantPermissions(permissions, options);

参数

  • permissions Array<string>#

    要授予的权限列表。

    危险

    支持的权限在浏览器之间有所不同，甚至在同一浏览器的不同版本之间也不同。任何权限都可能在更新后停止工作。

    以下是一些某些浏览器可能支持的权限

    • 'accelerometer'
    • 'ambient-light-sensor'
    • 'background-sync'
    • 'camera'
    • 'clipboard-read'
    • 'clipboard-write'
    • 'geolocation'
    • 'gyroscope'
    • 'magnetometer'
    • 'microphone'
    • 'midi-sysex' (系统独占 midi)
    • 'midi'
    • 'notifications'
    • 'payment-handler'
    • 'storage-access'

  • options Object (可选)

返回值

newCDPSession​

添加于: v1.11 browserContext.newCDPSession
注意

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

返回新创建的会话。

用法

await browserContext.newCDPSession(page);

参数

  • page Page | Frame#

    要为其创建新会话的目标。为了向后兼容，此参数名为 page，但它可以是 Page 或 Frame 类型。

返回值

newPage​

在 v1.9 版本前添加 browserContext.newPage

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

用法

await browserContext.newPage();

返回值

pages​

在 v1.9 版本前添加 browserContext.pages

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

用法

browserContext.pages();

返回值

removeAllListeners​

添加于: v1.47 browserContext.removeAllListeners

移除给定类型的所有监听器（如果未给定类型，则移除所有已注册的监听器）。允许等待异步监听器完成或忽略来自这些监听器的后续错误。

用法

await browserContext.removeAllListeners();
await browserContext.removeAllListeners(type, options);

参数

  • type string (可选)#
  • options Object (可选)

    • behavior "wait" | "ignoreErrors" | "default" (可选)#

      指定是否等待已运行的监听器，以及如果它们抛出错误该怎么做

      • 'default' - 不等待当前监听器调用（如果有）完成，如果监听器抛出错误，则可能导致未处理的错误
      • 'wait' - 等待当前监听器调用（如果有）完成
      • 'ignoreErrors' - 不等待当前监听器调用（如果有）完成，移除后监听器抛出的所有错误都将被静默捕获

返回值

route​

在 v1.9 版本前添加 browserContext.route

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

注意

browserContext.route() 不会拦截 Service Worker 拦截的请求。请参阅 this 问题。我们建议在使用请求拦截时禁用 Service Worker，方法是将 serviceWorkers 设置为 'block'。

用法

一个简单的处理程序示例，该处理程序中止所有图像请求

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 缓存。

参数

返回值

routeFromHAR​

添加于: v1.23 browserContext.routeFromHAR

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

Playwright 不会处理 Service Worker 从 HAR 文件拦截的请求。请参阅此 issue。我们建议在使用请求拦截时禁用 Service Worker，方法是将 serviceWorkers 设置为 'block'。

用法

await browserContext.routeFromHAR(har);
await browserContext.routeFromHAR(har, options);

参数

  • har 字符串#

    预先录制网络数据的 HAR 文件路径。如果 path 是相对路径，则它相对于当前工作目录解析。

  • options Object (可选)

    • notFound "abort" | "fallback" (可选)#

      • 如果设置为 'abort'，则任何在 HAR 文件中找不到的请求都将被中止。
      • 如果设置为 'fallback'，则会传递给处理程序链中的下一个路由处理程序。

      默认为 abort。

    • update 布尔值 (可选)#

      如果指定，则使用实际的网络信息更新给定的 HAR，而不是从文件提供服务。当调用 browserContext.close() 时，该文件将写入磁盘。

    • updateContent "embed" | "attach" (可选)添加于版本：v1.32#

      可选设置，用于控制资源内容管理。如果指定 attach，资源将作为单独的文件或 ZIP 存档中的条目持久保存。如果指定 embed，内容将以内联方式存储在 HAR 文件中。

    • updateMode "full" | "minimal" (可选)添加于版本：v1.32#

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

    • url 字符串 | RegExp (可选)#

      用于匹配请求 URL 的 glob 模式、正则表达式或谓词。只有 URL 与模式匹配的请求才会从 HAR 文件提供服务。如果未指定，则所有请求都将从 HAR 文件提供服务。

返回值

routeWebSocket​

添加于版本：v1.48 browserContext.routeWebSocket

此方法允许修改浏览器上下文中任何页面建立的 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();
});

参数

返回值

serviceWorkers​

添加于: v1.11 browserContext.serviceWorkers
注意

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

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

用法

browserContext.serviceWorkers();

返回值

setDefaultNavigationTimeout​

在 v1.9 版本前添加 browserContext.setDefaultNavigationTimeout

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

注意

page.setDefaultNavigationTimeout() 和 page.setDefaultTimeout() 的优先级高于 browserContext.setDefaultNavigationTimeout()。

用法

browserContext.setDefaultNavigationTimeout(timeout);

参数

  • timeout 数字#

    最大导航时间（毫秒）

setDefaultTimeout​

在 v1.9 版本前添加 browserContext.setDefaultTimeout

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

注意

page.setDefaultNavigationTimeout()、page.setDefaultTimeout() 和 browserContext.setDefaultNavigationTimeout() 的优先级高于 browserContext.setDefaultTimeout()。

用法

browserContext.setDefaultTimeout(timeout);

参数

  • timeout 数字#

    最大时间（毫秒）。传递 0 以禁用超时。

setExtraHTTPHeaders​

在 v1.9 版本前添加 browserContext.setExtraHTTPHeaders

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

注意

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

用法

await browserContext.setExtraHTTPHeaders(headers);

参数

  • headers Object<字符串, 字符串>#

    一个对象，包含要与每个请求一起发送的附加 HTTP 标头。所有标头值都必须是字符串。

返回值

setGeolocation​

在 v1.9 版本前添加 browserContext.setGeolocation

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

用法

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

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

参数

  • geolocation null | Object#

    • latitude 数字

      纬度，介于 -90 和 90 之间。

    • longitude 数字

      经度，介于 -180 和 180 之间。

    • accuracy 数字 (可选)

      非负精度值。默认为 0。

返回值

setOffline​

在 v1.9 版本前添加 browserContext.setOffline

用法

await browserContext.setOffline(offline);

参数

  • offline 布尔值#

    是否为浏览器上下文模拟网络离线。

返回值

storageState​

在 v1.9 版本前添加 browserContext.storageState

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

用法

await browserContext.storageState();
await browserContext.storageState(options);

参数

  • options Object (可选)

    • path 字符串 (可选)#

      用于保存存储状态的文件路径。如果 path 是相对路径，则它相对于当前工作目录解析。如果未提供路径，则仍会返回存储状态，但不会保存到磁盘。

返回值

unroute​

在 v1.9 版本前添加 browserContext.unroute

移除使用 browserContext.route() 创建的路由。当未指定 handler 时，移除 url 的所有路由。

用法

await browserContext.unroute(url);
await browserContext.unroute(url, handler);

参数

返回值

unrouteAll​

添加于版本：v1.41 browserContext.unrouteAll

移除所有使用 browserContext.route() 和 browserContext.routeFromHAR() 创建的路由。

用法

await browserContext.unrouteAll();
await browserContext.unrouteAll(options);

参数

  • options Object (可选)

    • behavior "wait" | "ignoreErrors" | "default" (可选)#

      指定是否等待已运行的处理程序，以及如果它们抛出错误该如何处理

      • 'default' - 不等待当前处理程序调用（如果有）完成，如果未路由的处理程序抛出错误，则可能导致未处理的错误
      • 'wait' - 等待当前处理程序调用（如果有）完成
      • 'ignoreErrors' - 不等待当前处理程序调用（如果有）完成，所有在取消路由后处理程序抛出的错误都会被静默捕获

返回值

waitForEvent​

在 v1.9 版本前添加 browserContext.waitForEvent

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

用法

const pagePromise = context.waitForEvent('page');
await page.getByRole('button').click();
const page = await pagePromise;

参数

  • event 字符串#

    事件名称，与传递到 browserContext.on(event) 中的名称相同。

  • optionsOrPredicate 函数 | Object (可选)#

    • predicate 函数

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

    • timeout 数字 (可选)

      最大等待时间（毫秒）。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项或使用 browserContext.setDefaultTimeout() 方法更改。

    接收事件的谓词或选项对象。可选。

  • options Object (可选)

    • predicate 函数 (可选)#

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

返回值

属性​

clock​

添加于版本：v1.45 browserContext.clock

Playwright 具有模拟时钟和时间流逝的能力。

用法

browserContext.clock

Type

request​

添加于版本：v1.16 browserContext.request

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

用法

browserContext.request

Type

tracing​

添加于版本：v1.12 browserContext.tracing

用法

browserContext.tracing

Type

事件​

on('backgroundpage')​

添加于: v1.11 browserContext.on('backgroundpage')
注意

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

当在上下文中创建新的 background page 时发出。

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

用法

browserContext.on('backgroundpage', data => {});

事件数据

on('close')​

在 v1.9 版本前添加 browserContext.on('close')

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

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

用法

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

事件数据

on('console')​

添加于版本：v1.34 browserContext.on('console')

当页面内的 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 browserContext.on('dialog')

当出现 JavaScript 对话框时发出，例如 alert、prompt、confirm 或 beforeunload。监听器必须 dialog.accept() 或 dialog.dismiss() 对话框 - 否则页面将 冻结 等待对话框，并且像 click 这样的操作将永远不会完成。

用法

context.on('dialog', dialog => {
  dialog.accept();
});
注意

当没有 page.on('dialog') 或 browserContext.on('dialog') 监听器存在时，所有对话框都将自动关闭。

事件数据

on('page')​

在 v1.9 版本前添加 browserContext.on('page')

当在 BrowserContext 中创建新页面时发出此事件。页面可能仍在加载中。此事件也适用于弹出页面。另请参阅 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 browserContext.on('request')

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

为了拦截和修改请求，请参阅 browserContext.route() 或 page.route()。

用法

browserContext.on('request', data => {});

事件数据

on('requestfailed')​

添加于版本：v1.12 browserContext.on('requestfailed')

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

注意

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

用法

browserContext.on('requestfailed', data => {});

事件数据

on('requestfinished')​

添加于版本：v1.12 browserContext.on('requestfinished')

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

用法

browserContext.on('requestfinished', data => {});

事件数据

on('response')​

添加于版本：v1.12 browserContext.on('response')

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

用法

browserContext.on('response', data => {});

事件数据

on('serviceworker')​

添加于: v1.11 browserContext.on('serviceworker')
注意

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

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

用法

browserContext.on('serviceworker', data => {});

事件数据

on('weberror')​

添加于版本：v1.38 browserContext.on('weberror')

当在此上下文中的任何页面中未处理异常时发出。要监听来自特定页面的错误，请改用 page.on('pageerror')。

用法

browserContext.on('weberror', data => {});

事件数据

已弃用​

setHTTPCredentials​

在 v1.9 版本前添加 browserContext.setHTTPCredentials
已弃用

浏览器可能会在成功身份验证后缓存凭据。请创建新的浏览器上下文。

用法

await browserContext.setHTTPCredentials(httpCredentials);

参数

返回值