BrowserContext
浏览器上下文 (BrowserContexts) 提供了一种操作多个独立浏览器会话的方式。
如果一个页面打开另一个页面,例如通过 window.open
调用,则弹出的页面将属于父页面的浏览器上下文。
Playwright 允许使用 Browser.NewContextAsync() 方法创建独立的非持久性浏览器上下文。非持久性浏览器上下文不会将任何浏览数据写入磁盘。
using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Firefox.LaunchAsync(new() { Headless = false });
// Create a new incognito browser context
var context = await browser.NewContextAsync();
// Create a new page inside context.
var page = await context.NewPageAsync();
await page.GotoAsync("https://bing.com");
// Dispose context once it is no longer needed.
await context.CloseAsync();
方法
AddCookiesAsync
v1.9 之前添加将 Cookie 添加到此浏览器上下文。此上下文中的所有页面都将安装这些 Cookie。Cookie 可以通过 BrowserContext.CookiesAsync() 获取。
用法
await context.AddCookiesAsync(new[] { cookie1, cookie2 });
参数
cookies
IEnumerable<Cookie
>#-
Name
string -
Value
string -
Url
string? (可选)需要提供 url 或 domain/path。可选。
-
Domain
string? (可选)要使 cookie 也适用于所有子域,请在 domain 前加上点,例如:".example.com"。需要提供 url 或 domain/path。可选。
-
Path
string? (可选)需要提供 url 或 domain/path。可选。
-
Expires
[浮点数]? (可选)Unix 时间(秒)。可选。
-
HttpOnly
bool? (可选)可选。
-
Secure
bool? (可选)可选。
-
SameSite
enum SameSiteAttribute { Strict, Lax, None }?
(可选)可选。
-
PartitionKey
string? (可选)对于分区的第三方 cookie (又称 CHIPS),分区键。可选。
-
返回
AddInitScriptAsync
v1.9 之前添加添加一个脚本,该脚本将在以下情况之一中进行评估:
- 每当在浏览器上下文中创建页面或导航页面时。
- 每当在浏览器上下文中的任何页面中附加或导航子框架时。在这种情况下,脚本在新附加的框架的上下文中进行评估。
脚本在文档创建后但在任何脚本运行之前进行评估。这对于修改 JavaScript 环境非常有用,例如,为 Math.random
设置种子。
用法
在页面加载之前覆盖 Math.random
的示例
// preload.js
Math.random = () => 42;
await Context.AddInitScriptAsync(scriptPath: "preload.js");
通过 BrowserContext.AddInitScriptAsync() 和 Page.AddInitScriptAsync() 安装的多个脚本的评估顺序未定义。
参数
返回
BackgroundPages
添加于:v1.11后台页面仅在基于 Chromium 的浏览器上支持。
上下文中所有现有的后台页面。
用法
BrowserContext.BackgroundPages
返回
Browser
v1.9 之前添加获取拥有该上下文的浏览器实例。如果该上下文在正常浏览器之外创建(例如 Android 或 Electron),则返回 null
。
用法
BrowserContext.Browser
返回
ClearCookiesAsync
v1.9 之前添加从上下文清除 cookie。接受可选的过滤器。
用法
await context.ClearCookiesAsync();
await context.ClearCookiesAsync(new() { Name = "session-id" });
await context.ClearCookiesAsync(new() { Domain = "my-origin.com" });
await context.ClearCookiesAsync(new() { Path = "/api/v1" });
await context.ClearCookiesAsync(new() { Name = "session-id", Domain = "my-origin.com" });
参数
options
BrowserContextClearCookiesOptions?
(可选)
返回
ClearPermissionsAsync
v1.9 之前添加清除浏览器上下文的所有权限覆盖。
用法
var context = await browser.NewContextAsync();
await context.GrantPermissionsAsync(new[] { "clipboard-read" });
// Alternatively, you can use the helper class ContextPermissions
// to specify the permissions...
// do stuff ...
await context.ClearPermissionsAsync();
返回
CloseAsync
v1.9 之前添加关闭浏览器上下文。所有属于该浏览器上下文的页面都将被关闭。
默认的浏览器上下文不能被关闭。
用法
await BrowserContext.CloseAsync(options);
参数
返回
CookiesAsync
v1.9 之前添加如果未指定 URL,此方法将返回所有 cookie。如果指定了 URL,则仅返回影响这些 URL 的 cookie。
用法
await BrowserContext.CookiesAsync(urls);
参数
-
urls
string? | IEnumerable?<string> (可选)#可选的 URL 列表。
返回
- IReadOnlyList<
BrowserContextCookiesResult
>#
ExposeBindingAsync
v1.9 之前添加该方法在上下文中每个页面的每个框架的 window
对象上添加一个名为 name 的函数。调用时,该函数执行 callback 并返回一个解析为 callback 返回值的 Promise。如果 callback 返回一个 Promise,它将被等待。
callback 函数的第一个参数包含有关调用者的信息:{ browserContext: BrowserContext, page: Page, frame: Frame }
。
有关仅限页面的版本,请参见 Page.ExposeBindingAsync()。
用法
将页面 URL 公开给上下文中所有页面的所有框架的示例
using Microsoft.Playwright;
using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Webkit.LaunchAsync(new() { Headless = false });
var context = await browser.NewContextAsync();
await context.ExposeBindingAsync("pageURL", source => source.Page.Url);
var page = await context.NewPageAsync();
await page.SetContentAsync("<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>");
await page.GetByRole(AriaRole.Button).ClickAsync();
参数
-
窗口对象上函数的名称。
-
callback
Action<BindingSource, T, [TResult]>#将在 Playwright 上下文中调用的回调函数。
-
options
BrowserContextExposeBindingOptions?
(可选)
返回
ExposeFunctionAsync
v1.9 之前添加该方法在上下文中每个页面的每个框架的 window
对象上添加一个名为 name 的函数。调用时,该函数执行 callback 并返回一个解析为 callback 返回值的 Promise。
如果 callback 返回一个 Promise,它将被等待。
有关仅限页面的版本,请参见 Page.ExposeFunctionAsync()。
用法
向上下文中所有页面添加 sha256
函数的示例
using Microsoft.Playwright;
using System;
using System.Security.Cryptography;
using System.Threading.Tasks;
class BrowserContextExamples
{
public static async Task Main()
{
using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Webkit.LaunchAsync(new() { Headless = false });
var context = await browser.NewContextAsync();
await context.ExposeFunctionAsync("sha256", (string input) =>
{
return Convert.ToBase64String(
SHA256.Create().ComputeHash(System.Text.Encoding.UTF8.GetBytes(input)));
});
var page = await context.NewPageAsync();
await page.SetContentAsync("<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>");
await page.GetByRole(AriaRole.Button).ClickAsync();
Console.WriteLine(await page.TextContentAsync("div"));
}
}
参数
返回
GrantPermissionsAsync
v1.9 之前添加授予浏览器上下文指定的权限。如果指定了来源,则仅授予给定来源相应的权限。
用法
await BrowserContext.GrantPermissionsAsync(permissions, options);
参数
-
permissions
IEnumerable<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'
'local-fonts'
-
options
BrowserContextGrantPermissionsOptions?
(可选)-
授予权限的 Origin,例如 "https://example.com"。
-
返回
NewCDPSessionAsync
添加于:v1.11CDP 会话仅在基于 Chromium 的浏览器上受支持。
返回新创建的会话。
用法
await BrowserContext.NewCDPSessionAsync(page);
参数
返回
NewPageAsync
v1.9 之前添加在浏览器上下文中创建新页面。
用法
await BrowserContext.NewPageAsync();
返回
Pages
v1.9 之前添加返回上下文中所有打开的页面。
用法
BrowserContext.Pages
返回
RouteAsync
v1.9 之前添加路由提供了修改浏览器上下文中任何页面发出的网络请求的能力。一旦启用路由,每个匹配 URL 模式的请求都将暂停,除非它被继续、完成或中止。
BrowserContext.RouteAsync() 不会拦截 Service Worker 拦截的请求。请参阅 此 问题。我们建议在使用请求拦截时通过将 ServiceWorkers 设置为 'block'
来禁用 Service Worker。
用法
一个简单地中止所有图片请求的处理程序示例
var context = await browser.NewContextAsync();
var page = await context.NewPageAsync();
await context.RouteAsync("**/*.{png,jpg,jpeg}", r => r.AbortAsync());
await page.GotoAsync("https://theverge.com");
await browser.CloseAsync();
或者使用正则表达式模式的相同片段
var context = await browser.NewContextAsync();
var page = await context.NewPageAsync();
await context.RouteAsync(new Regex("(\\.png$)|(\\.jpg$)"), r => r.AbortAsync());
await page.GotoAsync("https://theverge.com");
await browser.CloseAsync();
可以检查请求以决定路由操作。例如,模拟所有包含某些 POST 数据的请求,并保留所有其他请求不变
await page.RouteAsync("/api/**", async r =>
{
if (r.Request.PostData.Contains("my-string"))
await r.FulfillAsync(new() { Body = "mocked-data" });
else
await r.ContinueAsync();
});
当请求与两个处理程序都匹配时,页面路由(使用 Page.RouteAsync() 设置)优先于浏览器上下文路由。
要使用其处理程序删除路由,可以使用 BrowserContext.UnrouteAsync()。
启用路由会禁用 HTTP 缓存。
参数
-
url
string | Regex | Func<string, bool>#一个全局模式、正则表达式模式或谓词,它接收一个 URL 以在路由期间进行匹配。如果上下文选项中设置了 BaseURL 并且提供的 URL 是不以
*
开头的字符串,则使用new URL()
构造函数解析它。 -
用于路由请求的处理函数。
-
options
BrowserContextRouteOptions?
(可选)
返回
RouteFromHARAsync
添加于:v1.23如果指定,上下文中的网络请求将从 HAR 文件提供。阅读更多关于 从 HAR 重放。
Playwright 不会从 HAR 文件中提供 Service Worker 拦截的请求。请参阅 此 问题。我们建议在使用请求拦截时通过将 ServiceWorkers 设置为 'block'
来禁用 Service Worker。
用法
await BrowserContext.RouteFromHARAsync(har, options);
参数
-
带有预录网络数据的 HAR 文件路径。如果
path
是相对路径,则它相对于当前工作目录解析。 -
options
BrowserContextRouteFromHAROptions?
(可选)-
NotFound
enum HarNotFound { Abort, Fallback }?
(可选)#- 如果设置为 'abort',则 HAR 文件中未找到的任何请求都将被中止。
- 如果设置为 'fallback',则会退回到处理程序链中的下一个路由处理程序。
默认为中止。
-
如果指定,则使用实际的网络信息更新给定的 HAR,而不是从文件提供。当调用 BrowserContext.CloseAsync() 时,文件将写入磁盘。
-
UpdateContent
enum RouteFromHarUpdateContentPolicy { Embed, Attach }?
(可选)新增于: v1.32#可选设置以控制资源内容管理。如果指定
attach
,资源将作为单独的文件或 ZIP 档案中的条目持久化。如果指定embed
,内容将内联存储在 HAR 文件中。 -
UpdateMode
enum HarMode { Full, Minimal }?
(可选)新增于: v1.32#当设置为
minimal
时,仅记录从 HAR 路由所需的信息。这会省略 HAR 信息中不用于从 HAR 重放的大小、时间、页面、cookie、安全性和其他类型的信息。默认为minimal
。 -
Url|UrlRegex
string? | Regex? (可选)#一个 glob 模式、正则表达式或谓词,用于匹配请求 URL。只有 URL 匹配模式的请求将从 HAR 文件中提供。如果未指定,所有请求都将从 HAR 文件中提供。
-
返回
RouteWebSocketAsync
新增于: v1.48此方法允许修改浏览器上下文中任何页面进行的 WebSocket 连接。
请注意,只有在此方法调用后创建的 WebSocket
才会路由。建议在创建任何页面之前调用此方法。
用法
以下是一个阻止某些 WebSocket 消息的简单处理程序示例。有关更多详细信息和示例,请参见 WebSocketRoute。
await context.RouteWebSocketAsync("/ws", async ws => {
ws.RouteSend(message => {
if (message == "to-be-blocked")
return;
ws.Send(message);
});
await ws.ConnectAsync();
});
参数
-
url
string | Regex | Func<string, bool>#只有 URL 匹配此模式的 WebSockets 才会被路由。字符串模式可以相对于 BaseURL 上下文选项。
-
handler
Action<WebSocketRoute>#用于路由 WebSocket 的处理函数。
返回
RunAndWaitForConsoleMessageAsync
新增于: v1.34执行操作并等待上下文中页面记录的 ConsoleMessage。如果提供了谓词,它会将 ConsoleMessage 值传递给 predicate
函数,并等待 predicate(message)
返回一个真值。如果页面在 BrowserContext.Console 事件触发之前关闭,将抛出错误。
用法
await BrowserContext.RunAndWaitForConsoleMessageAsync(action, options);
参数
-
触发事件的操作。
-
options
BrowserContextRunAndWaitForConsoleMessageOptions?
(可选)-
Predicate
Func<ConsoleMessage?, bool> (可选)#接收 ConsoleMessage 对象,并在等待应该解决时解析为真值。
-
Timeout
[浮点数]? (可选)#最长等待时间,以毫秒为单位。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 更改。
-
返回
WaitForConsoleMessageAsync
新增于: v1.34执行操作并等待上下文中页面记录的 ConsoleMessage。如果提供了谓词,它会将 ConsoleMessage 值传递给 predicate
函数,并等待 predicate(message)
返回一个真值。如果页面在 BrowserContext.Console 事件触发之前关闭,将抛出错误。
用法
await BrowserContext.WaitForConsoleMessageAsync(action, options);
参数
options
BrowserContextRunAndWaitForConsoleMessageOptions?
(可选)-
Predicate
Func<ConsoleMessage?, bool> (可选)#接收 ConsoleMessage 对象,并在等待应该解决时解析为真值。
-
Timeout
[浮点数]? (可选)#最长等待时间,以毫秒为单位。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 更改。
-
返回
RunAndWaitForPageAsync
添加于:v1.9执行操作并等待在上下文中创建新的 Page。如果提供了谓词,它会将 Page 值传递给 predicate
函数,并等待 predicate(event)
返回一个真值。如果上下文在创建新的 Page 之前关闭,将抛出错误。
用法
await BrowserContext.RunAndWaitForPageAsync(action, options);
参数
-
触发事件的操作。
-
options
BrowserContextRunAndWaitForPageOptions?
(可选)
返回
WaitForPageAsync
添加于:v1.9执行操作并等待在上下文中创建新的 Page。如果提供了谓词,它会将 Page 值传递给 predicate
函数,并等待 predicate(event)
返回一个真值。如果上下文在创建新的 Page 之前关闭,将抛出错误。
用法
await BrowserContext.WaitForPageAsync(action, options);
参数
options
BrowserContextRunAndWaitForPageOptions?
(可选)
返回
SetDefaultNavigationTimeout
v1.9 之前添加此设置将更改以下方法和相关快捷方式的默认最大导航时间
- Page.GoBackAsync()
- Page.GoForwardAsync()
- Page.GotoAsync()
- Page.ReloadAsync()
- Page.SetContentAsync()
- Page.RunAndWaitForNavigationAsync()
用法
BrowserContext.SetDefaultNavigationTimeout(timeout);
参数
-
timeout
[浮点数]#最大导航时间(毫秒)
SetDefaultTimeout
v1.9 之前添加此设置将更改所有接受 timeout 选项的方法的默认最大时间。
用法
BrowserContext.SetDefaultTimeout(timeout);
参数
-
timeout
[浮点数]#最大时间(毫秒)。传入
0
禁用超时。
SetExtraHTTPHeadersAsync
v1.9 之前添加额外的 HTTP 头将随上下文中任何页面发起的每个请求一起发送。这些头与使用 Page.SetExtraHTTPHeadersAsync() 设置的页面特定额外 HTTP 头合并。如果页面覆盖了某个特定的头,将使用页面特定头的值而不是浏览器上下文头的值。
BrowserContext.SetExtraHTTPHeadersAsync() 不保证传出请求中头的顺序。
用法
await BrowserContext.SetExtraHTTPHeadersAsync(headers);
参数
-
headers
IDictionary<string, string>#一个包含要随每个请求发送的额外 HTTP 标头的对象。所有标头值必须是字符串。
返回
SetGeolocationAsync
v1.9 之前添加设置上下文的地理位置。传入 null
或 undefined
模拟位置不可用。
用法
await context.SetGeolocationAsync(new Geolocation()
{
Latitude = 59.95f,
Longitude = 30.31667f
});
考虑使用 BrowserContext.GrantPermissionsAsync() 授予浏览器上下文页面读取其地理位置的权限。
参数
geolocation
Geolocation?#-
Latitude
[浮点数]纬度,介于 -90 和 90 之间。
-
Longitude
[浮点数]经度,介于 -180 和 180 之间。
-
Accuracy
[浮点数]? (可选)非负精度值。默认为
0
。
-
返回
SetOfflineAsync
v1.9 之前添加用法
await BrowserContext.SetOfflineAsync(offline);
参数
返回
StorageStateAsync
v1.9 之前添加返回此浏览器上下文的存储状态,包含当前 cookie、本地存储快照和 IndexedDB 快照。
用法
await BrowserContext.StorageStateAsync(options);
参数
options
BrowserContextStorageStateOptions?
(可选)
返回
UnrouteAsync
v1.9 之前添加删除使用 BrowserContext.RouteAsync() 创建的路由。如果未指定 handler,则删除 url 的所有路由。
用法
await BrowserContext.UnrouteAsync(url, handler);
参数
-
url
string | Regex | Func<string, bool>#一个全局模式、正则表达式模式或谓词,接收用于使用 BrowserContext.RouteAsync() 注册路由的 URL。
-
可选的处理程序函数,用于使用 BrowserContext.RouteAsync() 注册路由。
返回
UnrouteAllAsync
新增于: v1.41删除使用 BrowserContext.RouteAsync() 和 BrowserContext.RouteFromHARAsync() 创建的所有路由。
用法
await BrowserContext.UnrouteAllAsync(options);
参数
options
BrowserContextUnrouteAllOptions?
(可选)-
Behavior
enum UnrouteBehavior { Wait, IgnoreErrors, Default }?
(可选)#指定是否等待已运行的处理程序以及如果它们抛出错误该怎么做
'default'
- 不等待当前处理程序调用 (如果有) 完成,如果未路由的处理程序抛出错误,可能会导致未处理的错误'wait'
- 等待当前处理程序调用 (如果有) 完成'ignoreErrors'
- 不等待当前处理程序调用 (如果有) 完成,取消路由后处理程序抛出的所有错误都将被静默捕获
-
返回
属性
APIRequest
添加于:v1.16与此上下文关联的 API 测试助手。使用此 API 发出的请求将使用上下文 cookie。
用法
BrowserContext.APIRequest
类型
Clock
新增于: v1.45Playwright 能够模拟时钟和时间流逝。
用法
BrowserContext.Clock
类型
Tracing
添加于:v1.12用法
BrowserContext.Tracing
类型
事件
事件 BackgroundPage
添加于:v1.11仅适用于 Chromium 浏览器的持久上下文。
当在上下文中创建新的后台页面时触发。
context.BackgroundPage += (_, backgroundPage) =>
{
Console.WriteLine(backgroundPage.Url);
};
用法
BrowserContext.BackgroundPage += async (_, page) => {};
事件数据
事件 Close
v1.9 之前添加当浏览器上下文关闭时触发。这可能由于以下原因之一发生:
- 浏览器上下文已关闭。
- 浏览器应用程序已关闭或崩溃。
- 调用了 Browser.CloseAsync() 方法。
用法
BrowserContext.Close += async (_, browserContext) => {};
事件数据
事件 Console
新增于: v1.34当页面中的 JavaScript 调用其中一个 console API 方法(例如 console.log
或 console.dir
)时触发。
传递给 console.log
和页面的参数可在 ConsoleMessage 事件处理程序参数中获取。
用法
context.Console += async (_, msg) =>
{
foreach (var arg in msg.Args)
Console.WriteLine(await arg.JsonValueAsync<object>());
};
await page.EvaluateAsync("console.log('hello', 5, { foo: 'bar' })");
事件数据
事件 Dialog
新增于: v1.34当出现 JavaScript 对话框时发出,例如 alert
、prompt
、confirm
或 beforeunload
。监听器 必须 Dialog.AcceptAsync() 或 Dialog.DismissAsync() 对话框 - 否则页面将 冻结 等待对话框,并且像点击这样的操作将永远不会完成。
用法
Context.Dialog += async (_, dialog) =>
{
await dialog.AcceptAsync();
};
当没有 Page.Dialog 或 BrowserContext.Dialog 监听器存在时,所有对话框都会自动关闭。
事件数据
事件 Page
v1.9 之前添加当在 BrowserContext 中创建新 Page 时会发出此事件。页面可能仍在加载中。此事件也会针对弹出页面触发。另请参阅 Page.Popup 以接收与特定页面相关的弹出窗口事件。
页面可用的最早时刻是当它导航到初始 URL 时。例如,当使用 window.open('http://example.com')
打开一个弹出窗口时,当对 "http://example.com" 的网络请求完成并且其响应开始在弹出窗口中加载时,此事件将触发。如果您想路由/监听此网络请求,请使用 BrowserContext.RouteAsync() 和 BrowserContext.Request,而不是 Page 上的类似方法。
var popup = await context.RunAndWaitForPageAsync(async =>
{
await page.GetByText("open new page").ClickAsync();
});
Console.WriteLine(await popup.EvaluateAsync<string>("location.href"));
使用 Page.WaitForLoadStateAsync() 等待页面达到特定状态(在大多数情况下您不需要它)。
用法
BrowserContext.Page += async (_, page) => {};
事件数据
事件 Request
添加于:v1.12当通过此上下文创建的任何页面发出请求时发出。 请求 对象是只读的。要仅监听来自特定页面的请求,请使用 Page.Request。
要拦截和更改请求,请参阅 BrowserContext.RouteAsync() 或 Page.RouteAsync()。
用法
BrowserContext.Request += async (_, request) => {};
事件数据
事件 RequestFailed
添加于:v1.12当请求失败时发出,例如超时。要仅监听来自特定页面的失败请求,请使用 Page.RequestFailed。
HTTP 错误响应,例如 404 或 503,从 HTTP 角度来看仍然是成功响应,因此请求将以 BrowserContext.RequestFinished 事件而不是 BrowserContext.RequestFailed 完成。
用法
BrowserContext.RequestFailed += async (_, request) => {};
事件数据
事件 RequestFinished
添加于:v1.12当请求在下载响应体后成功完成时发出。对于成功响应,事件序列是 request
、response
和 requestfinished
。要监听来自特定页面的成功请求,请使用 Page.RequestFinished。
用法
BrowserContext.RequestFinished += async (_, request) => {};
事件数据
事件 Response
添加于:v1.12当接收到请求的 响应 状态和头时发出。对于成功响应,事件序列是 request
、response
和 requestfinished
。要监听来自特定页面的响应事件,请使用 Page.Response。
用法
BrowserContext.Response += async (_, response) => {};
事件数据
事件 WebError
新增于: v1.38当此上下文中任何页面中发生未处理的异常时发出。要监听来自特定页面的错误,请改用 Page.PageError。
用法
BrowserContext.WebError += async (_, webError) => {};
事件数据