BrowserContext

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

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

Playwright允许通过Browser.newContext()方法创建隔离的非持久性浏览器上下文。非持久性浏览器上下文不会向磁盘写入任何浏览数据。

// Create a new incognito browser context
BrowserContext context = browser.newContext();
// Create a new page inside context.
Page page = context.newPage();
page.navigate("https://example.com");
// Dispose context once it is no longer needed.
context.close();

方法​

addCookies​

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

用法

browserContext.addCookies(Arrays.asList(cookieObject1, cookieObject2));

参数

• cookies 列表<Cookie>#

  • setName String

  • setValue String

  • setUrl String (可选)

    url或domain/path中必须提供一个。可选参数。

  • setDomain String (可选)

    要使cookie适用于所有子域名，请在域名前加上点号，例如：".example.com"。必须提供url或domain/path。可选参数。

  • setPath String (可选)

    必须提供url或domain/path中的一项，此项为可选参数。

  • setExpires double (可选)

    以秒为单位的Unix时间。可选参数。

  • setHttpOnly boolean (可选)

    可选参数。

  • setSecure boolean (可选)

    可选参数。

  • setSameSite enum SameSiteAttribute { STRICT, LAX, NONE } (可选)

    可选项。

返回

• void#

addInitScript​

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

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

脚本会在文档创建后但在其任何脚本运行前被评估。这对于修改JavaScript环境非常有用，例如用于初始化Math.random。

用法

在页面加载前覆盖Math.random的示例：

// preload.js
Math.random = () => 42;

// In your playwright script, assuming the preload.js file is in same directory.
browserContext.addInitScript(Paths.get("preload.js"));

参数

• script String | Path#

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

返回

• void#

backgroundPages​

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

用法

BrowserContext.backgroundPages();

返回

• 列表<页面>#

浏览器​

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

用法

BrowserContext.browser();

返回

• null | 浏览器#

清除Cookies​

从上下文中移除cookies。接受可选过滤器。

用法

context.clearCookies();
context.clearCookies(new BrowserContext.ClearCookiesOptions().setName("session-id"));
context.clearCookies(new BrowserContext.ClearCookiesOptions().setDomain("my-origin.com"));
context.clearCookies(new BrowserContext.ClearCookiesOptions().setPath("/api/v1"));
context.clearCookies(new BrowserContext.ClearCookiesOptions()
                         .setName("session-id")
                         .setDomain("my-origin.com"));

参数

• options BrowserContext.ClearCookiesOptions (optional)

  • setDomain String | Pattern (可选) 新增于: v1.43#

    仅移除具有给定域的cookie。

  • setName String | Pattern (可选) 添加于: v1.43#

    仅移除具有指定名称的cookies。

  • setPath String | Pattern (可选) 添加于: v1.43#

    仅移除具有给定路径的cookies。

返回

• void#

clearPermissions​

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

用法

BrowserContext context = browser.newContext();
context.grantPermissions(Arrays.asList("clipboard-read"));
// do stuff ..
context.clearPermissions();

返回

• void#

关闭​

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

用法

BrowserContext.close();
BrowserContext.close(options);

参数

• options BrowserContext.CloseOptions (optional)

  • setReason String (可选) 添加于: v1.40#

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

返回

• void#

cookies​

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

用法

BrowserContext.cookies();
BrowserContext.cookies(urls);

参数

• urls String | List<String> (可选)#

  可选的URL列表。

返回

• 列表<Cookie>#

  • name String

  • value String

  • domain String

  • path String

  • expires double

    Unix时间，单位为秒。

  • httpOnly boolean

  • secure boolean

  • sameSite enum SameSiteAttribute { STRICT, LAX, NONE }

exposeBinding​

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

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

请参阅Page.exposeBinding()获取仅限页面的版本。

用法

一个示例，展示如何在上下文中向所有页面中的所有框架公开页面URL：

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      BrowserType webkit = playwright.webkit();
      Browser browser = webkit.launch(new BrowserType.LaunchOptions().setHeadless(false));
      BrowserContext context = browser.newContext();
      context.exposeBinding("pageURL", (source, args) -> source.page().url());
      Page page = context.newPage();
      page.setContent("<script>\n" +
        "  async function onClick() {\n" +
        "    document.querySelector('div').textContent = await window.pageURL();\n" +
        "  }\n" +
        "</script>\n" +
        "<button onclick=\"onClick()\">Click me</button>\n" +
        "<div></div>");
      page.getByRole(AriaRole.BUTTON).click();
    }
  }
}

参数

• name String#

  窗口对象上的函数名称。

• callback BindingCallback#

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

• options BrowserContext.ExposeBindingOptions (可选)

  • setHandle boolean (可选)#

    已弃用

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

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

返回

• void#

exposeFunction​

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

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

仅限页面的版本请参见 Page.exposeFunction()。

用法

一个在上下文中为所有页面添加sha256函数的示例：

import com.microsoft.playwright.*;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      BrowserType webkit = playwright.webkit();
      Browser browser = webkit.launch(new BrowserType.LaunchOptions().setHeadless(false));
      BrowserContext context = browser.newContext();
      context.exposeFunction("sha256", args -> {
        String text = (String) args[0];
        MessageDigest crypto;
        try {
          crypto = MessageDigest.getInstance("SHA-256");
        } catch (NoSuchAlgorithmException e) {
          return null;
        }
        byte[] token = crypto.digest(text.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(token);
      });
      Page page = context.newPage();
      page.setContent("<script>\n" +
        "  async function onClick() {\n" +
        "    document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');\n" +
        "  }\n" +
        "</script>\n" +
        "<button onclick=\"onClick()\">Click me</button>\n" +
        "<div></div>\n");
      page.getByRole(AriaRole.BUTTON).click();
    }
  }
}

参数

• name String#

  窗口对象上的函数名称。

• callback FunctionCallback#

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

返回

• void#

grantPermissions​

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

用法

BrowserContext.grantPermissions(permissions);
BrowserContext.grantPermissions(permissions, options);

参数

• permissions List<String>#

  授予的权限列表。

  danger

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

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

  • '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 BrowserContext.GrantPermissionsOptions (可选)

  • setOrigin String (可选)#

    授予权限的origin，例如"https://example.com"。

返回

• void#

newCDPSession​

返回新创建的会话。

用法

BrowserContext.newCDPSession(page);

参数

• page Page | Frame#

  创建新会话的目标对象。为了向后兼容，这个参数被命名为page，但它可以是Page或Frame类型。

返回

• CDPSession#

newPage​

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

用法

BrowserContext.newPage();

返回

• 页面#

页面​

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

用法

BrowserContext.pages();

返回

• 列表<页面>#

路由​

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

用法

一个简单的处理程序示例，它会中止所有图片请求：

BrowserContext context = browser.newContext();
context.route("**/*.{png,jpg,jpeg}", route -> route.abort());
Page page = context.newPage();
page.navigate("https://example.com");
browser.close();

或者使用正则表达式模式替代的相同代码片段：

BrowserContext context = browser.newContext();
context.route(Pattern.compile("(\\.png$)|(\\.jpg$)"), route -> route.abort());
Page page = context.newPage();
page.navigate("https://example.com");
browser.close();

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

context.route("/api/**", route -> {
  if (route.request().postData().contains("my-string"))
    route.fulfill(new Route.FulfillOptions().setBody("mocked-data"));
  else
    route.resume();
});

当请求同时匹配多个处理程序时，页面路由（通过Page.route()设置）的优先级高于浏览器上下文路由。

要移除一个路由及其处理程序，您可以使用BrowserContext.unroute()。

参数

• url String | Pattern | Predicate<String>#

  一个用于路由匹配的全局模式、正则表达式模式或接收[URL]的谓词。当通过上下文选项提供了setBaseURL且传入的URL是路径时，它会通过new URL()构造函数进行合并。

• handler Consumer<Route>#

  用于路由请求的处理函数。

• options BrowserContext.RouteOptions (可选)

  • setTimes int (可选参数) 添加于: v1.15#

    路由应被使用的频率。默认情况下每次都会被使用。

返回

• void#

从HAR文件创建路由​

如果指定了该选项，上下文中的网络请求将从HAR文件提供。了解更多关于从HAR回放的信息。

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

用法

BrowserContext.routeFromHAR(har);
BrowserContext.routeFromHAR(har, options);

参数

• har Path#

  指向包含预录制网络数据的HAR文件的路径。如果path是相对路径，则会相对于当前工作目录进行解析。

• options BrowserContext.RouteFromHAROptions (可选)

  • setNotFound enum HarNotFound { ABORT, FALLBACK } (可选)#

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

    默认为中止。

  • setUpdate boolean (可选)#

    如果指定此参数，将使用实际的网络信息更新给定的HAR文件，而不是从文件读取。文件会在调用BrowserContext.close()时写入磁盘。

  • setUpdateContent enum RouteFromHarUpdateContentPolicy { EMBED, ATTACH } (可选) 添加于: v1.32#

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

  • setUpdateMode enum HarMode { FULL, MINIMAL } (可选) 添加于: v1.32#

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

  • setUrl String | Pattern (可选)#

    用于匹配请求URL的通配符模式、正则表达式或谓词。只有URL匹配该模式的请求才会从HAR文件中获取响应。如果未指定，则所有请求都将从HAR文件中获取响应。

返回

• void#

routeWebSocket​

该方法允许修改浏览器上下文中任何页面建立的websocket连接。

请注意，只有在此方法调用后创建的WebSocket才会被路由。建议在创建任何页面之前调用此方法。

用法

以下是一个简单处理程序的示例，它可以阻止某些WebSocket消息。更多详情和示例请参阅WebSocketRoute。

context.routeWebSocket("/ws", ws -> {
  ws.routeSend(message -> {
    if ("to-be-blocked".equals(message))
      return;
    ws.send(message);
  });
  ws.connect();
});

参数

• url String | Pattern | Predicate<String>#

  只有URL匹配此模式的WebSocket会被路由。字符串模式可以相对于setBaseURL上下文选项。

• handler Consumer<WebSocketRoute>#

  用于路由WebSocket的处理函数。

返回

• void#

setDefaultNavigationTimeout​

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

• Page.goBack()
• Page.goForward()
• Page.navigate()
• Page.reload()
• Page.setContent()
• Page.waitForNavigation()

用法

BrowserContext.setDefaultNavigationTimeout(timeout);

参数

• timeout double#

  最大导航时间（毫秒）

setDefaultTimeout​

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

用法

BrowserContext.setDefaultTimeout(timeout);

参数

• timeout double#

  最大时间（毫秒）。传入0表示禁用超时。

setExtraHTTPHeaders​

额外的HTTP头信息将与上下文中任何页面发起的每个请求一起发送。这些头信息会与通过Page.setExtraHTTPHeaders()设置的页面特定额外HTTP头信息合并。如果页面覆盖了特定头信息，则页面特定的头信息值将替代浏览器上下文头信息值。

用法

BrowserContext.setExtraHTTPHeaders(headers);

参数

• headers Map<String, String>#

  一个包含要随每个请求发送的额外HTTP头信息的对象。所有头值必须是字符串。

返回

• void#

设置地理位置​

设置上下文的定位地理位置。传入null或undefined将模拟位置不可用状态。

用法

browserContext.setGeolocation(new Geolocation(59.95, 30.31667));

参数

• geolocation null | Geolocation#

  • setLatitude double

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

  • setLongitude double

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

  • setAccuracy double (可选)

    非负精度值。默认为 0。

返回

• void#

setOffline​

用法

BrowserContext.setOffline(offline);

参数

• offline boolean#

  是否模拟浏览器上下文处于离线网络状态。

返回

• void#

storageState​

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

用法

BrowserContext.storageState();
BrowserContext.storageState(options);

参数

• options BrowserContext.StorageStateOptions (optional)

  • setIndexedDB boolean (可选) 添加于: v1.51#

    设置为 true 以在存储状态快照中包含 IndexedDB。如果您的应用程序使用IndexedDB存储认证令牌（如Firebase认证），请启用此选项。

    注意

    目前不支持包含类型化数组的IndexedDB。

  • setPath Path (可选)#

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

返回

• String#

取消路由​

移除通过BrowserContext.route()创建的路由。当未指定handler时，会移除该url的所有路由。

用法

BrowserContext.unroute(url);
BrowserContext.unroute(url, handler);

参数

• url String | Pattern | Predicate<String>#

  用于接收[URL]的全局匹配模式、正则表达式模式或断言函数，用于通过BrowserContext.route()注册路由。

• handler Consumer<Route> (可选)#

  用于通过BrowserContext.route()注册路由的可选处理函数。

返回

• void#

unrouteAll​

移除所有通过BrowserContext.route()和BrowserContext.routeFromHAR()创建的路由。

用法

BrowserContext.unrouteAll();

返回

• void#

waitForCondition​

该方法将阻塞，直到条件返回true。在方法等待条件期间，所有Playwright事件都将被分发。

用法

使用该方法等待依赖于页面事件的条件：

List<String> failedUrls = new ArrayList<>();
context.onResponse(response -> {
  if (!response.ok()) {
    failedUrls.add(response.url());
  }
});
page1.getByText("Create user").click();
page2.getByText("Submit button").click();
context.waitForCondition(() -> failedUrls.size() > 3);

参数

• condition [BooleanSupplier]#

  需要等待的条件。

• options BrowserContext.WaitForConditionOptions (可选)

  • setTimeout double (可选)#

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

返回

• void#

等待控制台消息​

执行操作并等待上下文中的页面记录ConsoleMessage。如果提供了predicate，它会将ConsoleMessage值传递给predicate函数，并等待predicate(message)返回真值。如果在触发BrowserContext.onConsoleMessage(handler)事件之前页面被关闭，将会抛出错误。

用法

BrowserContext.waitForConsoleMessage(callback);
BrowserContext.waitForConsoleMessage(callback, options);

参数

• options BrowserContext.WaitForConsoleMessageOptions (可选)

  • setPredicate Predicate<ConsoleMessage> (可选)#

    接收ConsoleMessage对象，当等待应该解决时解析为真值。

  • setTimeout double (可选)#

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

• callback Runnable#

  执行触发事件动作的回调函数。

返回

• ConsoleMessage#

waitForPage​

执行操作并等待上下文中创建一个新的Page。如果提供了predicate，它会将Page值传递给predicate函数，并等待predicate(event)返回真值。如果在创建新的Page之前上下文关闭，将会抛出错误。

用法

BrowserContext.waitForPage(callback);
BrowserContext.waitForPage(callback, options);

参数

• options BrowserContext.WaitForPageOptions (可选)

  • setPredicate Predicate<Page> (可选)#

    接收Page对象，当等待应该解决时解析为真值。

  • setTimeout double (可选)#

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

• callback Runnable#

  执行触发事件动作的回调函数。

返回

• 页面#

属性​

clock()​

Playwright 具备模拟时钟和时间流逝的功能。

用法

BrowserContext.clock()

返回

• 时钟

request()​

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

用法

BrowserContext.request()

返回

• APIRequestContext

tracing()​

用法

BrowserContext.tracing()

返回

• Tracing

事件​

onBackgroundPage(handler)​

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

context.onBackgroundPage(backgroundPage -> {
  System.out.println(backgroundPage.url());
});

用法

BrowserContext.onBackgroundPage(handler)

事件数据

• Page

onClose(handler)​

当浏览器上下文关闭时触发。这可能由以下原因之一导致：

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

用法

BrowserContext.onClose(handler)

事件数据

• BrowserContext

onConsoleMessage(handler)​

当页面中的JavaScript调用控制台API方法时触发，例如 console.log 或 console.dir。

传递给console.log的参数和页面内容可在ConsoleMessage事件处理程序参数中使用。

用法

context.onConsoleMessage(msg -> {
  for (int i = 0; i < msg.args().size(); ++i)
    System.out.println(i + ": " + msg.args().get(i).jsonValue());
});
page.evaluate("() => console.log('hello', 5, { foo: 'bar' })");

事件数据

• ConsoleMessage

onDialog(handler)​

当出现JavaScript对话框时触发，例如alert、prompt、confirm或beforeunload。监听器必须选择Dialog.accept()或Dialog.dismiss()来处理对话框 - 否则页面将冻结等待对话框响应，点击等操作将无法完成。

用法

context.onDialog(dialog -> {
  dialog.accept();
});

事件数据

• Dialog

onPage(handler)​

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

页面可用的最早时刻是当它已导航至初始URL时。例如，当使用window.open('http://example.com')打开弹窗时，此事件将在对"http://example.com"的网络请求完成且其响应已开始在弹窗中加载时触发。如果您想路由/监听此网络请求，请分别使用BrowserContext.route()和BrowserContext.onRequest(handler)，而不是Page上的类似方法。

Page newPage = context.waitForPage(() -> {
  page.getByText("open new page").click();
});
System.out.println(newPage.evaluate("location.href"));

用法

BrowserContext.onPage(handler)

事件数据

• Page

onRequest(处理函数)​

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

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

用法

BrowserContext.onRequest(handler)

事件数据

• Request

onRequestFailed(handler)​

当请求失败时触发，例如超时。若只想监听特定页面的失败请求，请使用Page.onRequestFailed(handler)。

用法

BrowserContext.onRequestFailed(handler)

事件数据

• Request

onRequestFinished(handler)​

当请求在下载响应体后成功完成时触发。对于一个成功的响应，事件顺序是request、response和requestfinished。要监听特定页面的成功请求，请使用Page.onRequestFinished(handler)。

用法

BrowserContext.onRequestFinished(handler)

事件数据

• Request

onResponse(handler)​

当请求接收到response状态和头部时触发。对于成功的响应，事件顺序为request、response和requestfinished。要监听特定页面的响应事件，请使用Page.onResponse(handler)。

用法

BrowserContext.onResponse(handler)

事件数据

• Response

onWebError(handler)​

当此上下文中任何页面出现未捕获的异常时触发。若要监听特定页面的错误，请改用Page.onPageError(handler)。

用法

BrowserContext.onWebError(handler)

事件数据

• WebError