瀏覽器上下文
瀏覽器上下文提供了一種操作多個獨立瀏覽器會話的方法。
如果一個頁面開啟另一個頁面，例如使用 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。Cookie 可以透過 browserContext.cookies() 取得。
用法
await browserContext.addCookies([cookieObject1, cookieObject2]);
參數
cookiesArray<Object>#-
namestring -
valuestring -
urlstring (選填)url 或 domain / path 為必填。選填。
-
domainstring (選填)若要讓 Cookie 也適用於所有子網域，請在網域前加上一個點，例如：「.example.com」。url 或 domain / path 為必填。選填。
-
pathstring (選填)url 或 domain / path 為必填 選填。
-
expiresnumber (選填)Unix 時間，以秒為單位。選填。
-
httpOnlyboolean (選填)選填。
-
secureboolean (選填)選填。
-
sameSite"Strict" | "Lax" | "None" (選填)選填。
-
回傳
addInitScript
在 v1.9 之前新增新增一個腳本，該腳本將在以下其中一種情況下評估
- 每當在瀏覽器上下文中建立或導航頁面時。
- 每當在瀏覽器上下文中的任何頁面中附加或導航子框架時。在這種情況下，腳本會在新附加框架的上下文中評估。
腳本在文件建立後但在其任何腳本執行之前評估。這對於修改 JavaScript 環境很有用，例如，用於 seed 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() 安裝的多個腳本的評估順序未定義。
參數
-
scriptfunction | string | Object#要在瀏覽器上下文中所有頁面中評估的腳本。
-
argSerializable (選填)#要傳遞給 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' });
參數
optionsObject (選填)
回傳
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，則會等待它完成。
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 的上下文中呼叫的回調函數。
-
optionsObject (選填)
回傳
exposeFunction
在 v1.9 之前新增此方法在上下文中每個頁面的每個框架的 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();
})();
參數
回傳
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'(系統專屬 MIDI)'midi' (MIDI)'notifications' (通知)'payment-handler' (付款處理常式)'storage-access' (儲存空間存取)
-
optionsObject (選填)-
要授予權限的 來源，例如 "https://example.com"。
-
回傳
newCDPSession
在 v1.11 中新增CDP 會話僅在基於 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);
參數
typestring (選填)#optionsObject (選填)-
behavior"wait" | "ignoreErrors" | "default" (選填)#指定是否等待已在運行的監聽器，以及如果它們拋出錯誤時該怎麼做
'default'- 不等待目前的監聽器呼叫 (如果有的話) 完成，如果監聽器拋出錯誤，可能會導致未處理的錯誤'wait'- 等待目前的監聽器呼叫 (如果有的話) 完成'ignoreErrors'- 不等待目前的監聽器呼叫 (如果有的話) 完成，移除後監聽器拋出的所有錯誤都會被靜默捕獲
-
回傳
route
在 v1.9 之前新增路由功能提供了修改瀏覽器上下文中任何頁面發出的網路請求的功能。一旦啟用路由，每個符合 URL 模式的請求都會停滯，除非它被繼續、實現或中止。
browserContext.route() 不會攔截 Service Worker 攔截的請求。請參閱 此 問題。我們建議在使用請求攔截時停用 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();
或使用 regex 模式的相同程式碼片段
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 快取。
參數
-
urlstring | RegExp | function(URL):boolean#一個 glob 模式、regex 模式或謂詞，接收 URL 以在路由時比對。當透過上下文選項提供 baseURL 且傳遞的 URL 是路徑時，它會透過
new URL()建構函式合併。 -
handlerfunction(Route, Request):Promise<Object> | Object#用於路由請求的處理常式函數。
-
optionsObject (選填)
回傳
routeFromHAR
在 v1.23 中新增如果指定，則在此上下文中發出的網路請求將從 HAR 檔案提供。閱讀更多關於 從 HAR 重新播放。
Playwright 不會從 HAR 檔案提供 Service Worker 攔截的請求。請參閱 此 問題。我們建議在使用請求攔截時停用 Service Worker，方法是將 serviceWorkers 設定為 'block'。
用法
await browserContext.routeFromHAR(har);
await browserContext.routeFromHAR(har, options);
參數
-
具有預先錄製的網路資料的 HAR 檔案的路徑。如果
path是相對路徑，則會相對於目前的工作目錄解析。 -
optionsObject (選填)-
notFound"abort" | "fallback" (選填)#- 如果設定為 'abort'，則 HAR 檔案中找不到的任何請求都將被中止。
- 如果設定為 'fallback'，則會退回到處理常式鏈中的下一個路由處理常式。
預設為中止。
-
如果指定，則使用實際的網路資訊更新給定的 HAR，而不是從檔案提供服務。當呼叫 browserContext.close() 時，該檔案會寫入磁碟。
-
updateContent"embed" | "attach" (選填)在 v1.32 中新增#用於控制資源內容管理的選填設定。如果指定
attach，則資源會以個別檔案或 ZIP 封存中的條目形式持久保存。如果指定embed，則內容會內嵌儲存在 HAR 檔案中。 -
updateMode"full" | "minimal" (選填)在 v1.32 中新增#當設定為
minimal時，僅記錄從 HAR 路由所需的資訊。這會省略大小、時間、頁面、Cookie、安全性以及其他在從 HAR 重新播放時未使用的 HAR 資訊。預設為minimal。 -
一個 glob 模式、正則表達式或謂詞，用於比對請求 URL。只有 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 符合此模式的 WebSocket 會被路由。字串模式可以是相對於 baseURL 環境選項的相對路徑。
-
handlerfunction(WebSocketRoute):Promise<Object> | Object#用於路由 WebSocket 的處理函式。
回傳
serviceWorkers
在 v1.11 中新增Service 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 和本地儲存快照。
用法
await browserContext.storageState();
await browserContext.storageState(options);
參數
optionsObject (選填)
回傳
unroute
在 v1.9 之前新增移除使用 browserContext.route() 建立的路由。當未指定 handler 時，會移除 url 的所有路由。
用法
await browserContext.unroute(url);
await browserContext.unroute(url, handler);
參數
-
urlstring | RegExp | function(URL):boolean#Glob 模式、正則表達式模式或接收 URL 的述詞，用於向 browserContext.route() 註冊路由。
-
handlerfunction(Route, Request):Promise<Object> | Object (選用)#選用的處理函式，用於向 browserContext.route() 註冊路由。
回傳
unrouteAll
新增於：v1.41移除所有使用 browserContext.route() 和 browserContext.routeFromHAR() 建立的路由。
用法
await browserContext.unrouteAll();
await browserContext.unrouteAll(options);
參數
optionsObject (選填)-
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() 方法來變更。
述詞或選項物件。選用。
-
-
optionsObject (選填)
回傳
屬性
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 呼叫其中一個 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當 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.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.11 中新增Service 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);
參數
回傳