在本快速入門中,您將了解如何使用 劇作家工作區 的可觀察性功能來對 劇作家工作區 瀏覽器工作階段進行偵錯。 使用 劇作家工作區 的可觀測性功能,將工作階段錄製或測試報告儲存到 Azure Storage,並在 Azure 入口網站中檢視,以對您的瀏覽器自動化執行作業和 Playwright 測試進行進階診斷。
Prerequisites
- 一個有有效訂閱的 Azure 帳號。 如果您沒有 Azure 訂用帳戶,請在開始前建立免費帳戶。
- 您的 Azure 帳戶需要擁有者 (部分機器翻譯)、參與者 (部分機器翻譯) 或其中一個傳統管理員角色 (部分機器翻譯)。
- 一個使用 Playwright 運行工具和 JavaScript SDK 的 Playwright 專案(目前不支援 NUnit 和其他運行工具)。 如果你還沒有專案,可以用 Playwright 入門文件 或 劇作家工作區 範例專案來建立。
- Azure CLI。 如果您沒有 Azure CLI,請參閱安裝 Azure CLI。
- Playwright Workspace 必須使用 Microsoft Entra ID 認證。 不支援使用存取權杖進行可觀察性驗證。
啟用可觀察性並將儲存帳戶連結至工作區
要開始使用 劇作家工作區 的可觀察性,請先在工作區啟用它,並連結儲存帳戶以儲存工件。 你可以先用新工作區,或是使用現有的工作區。
使用您 Azure 訂閱的認證來登入 Azure 入口網站。
從入口網站首頁搜尋並選擇 Azure 應用程式測試。
在 Azure 應用程式測試 中心,選擇 劇作家工作區 下的「建立」。
在 「建立 Playwright 工作區」資源 頁面,於 「基本」 索引標籤中輸入以下資訊:
Field Description 訂閱 選取要用於此 Playwright 工作區的 Azure 訂閱。 資源群組 選取現有的資源群組。 或選取 [新建],然後為新的資源群組輸入唯一的名稱。 姓名 為您的工作區輸入一個獨特的名稱。
名稱只能由字母數字和連字號組成,長度介於 3 到 24 個字元之間。位置 選擇一個地理位置作為工作區。
此位置還決定了測試執行結果的儲存位置。前往「功能設定」標籤,並輸入以下資訊:
Field Description 可觀察性 Toggle 預設為啟用,以讓使用者能從 Playwright Workspace 儲存並查看他們的測試報告。 如果您想關閉可觀察性,請將設定切換為「停用」。 記憶體帳戶 Toggle 預設為啟用,以讓使用者能從 Playwright Workspace 儲存並查看他們的測試報告。 如果您想關閉可觀察性,請將設定切換為「停用」。 Note
劇作家工作區 的可觀察性使用 Azure 儲存體 來儲存您的測試報告及其他資料。 儲存費用是根據你儲存帳戶的資料保留設定來決定的。
Note
您也可以選擇性地在「 標籤」 索引標籤中設定更多詳細資訊。標籤是名稱/值對,您用來分類資源並檢視合併帳單,方法是將相同標籤套用到多個資源及資源群組。
Note
目前,將可觀察性成品儲存到客戶管理的 Azure 儲存體 帳戶時,需要對該儲存帳戶的公開端點進行網路存取。 設定為僅限私有端點存取的儲存帳戶不支援工件儲存情境。
完成資源設定後,請選取 [檢閱 + 建立]。
檢閱您提供的設定,然後選取 建立。 建立工作區需要幾分鐘。 繼續進行之前,請等候入口網站頁面顯示 [您的部署已完成] 訊息。
為連結儲存帳號新增基於角色的存取控制(RBAC)角色
在 Azure 入口網站開啟連結的儲存帳號。
前往 [存取控制 (IAM)] 索引標籤。
選擇 新增角色指派。
在 「職務功能角色」 下,搜尋並選取 「Storage Blob 資料參與者」 角色,然後選取 「下一步」。
選取並新增所有執行測試的成員。
選擇 檢閱 + 指派。
安裝 劇作家工作區 套件
要使用 劇作家工作區,請安裝 劇作家工作區 套件。
npm init @azure/playwright@latest
此指令會產生一個 playwright.service.config.ts 檔案,將 Playwright 導向並認證至 Playwright 工作區。
如果您已經有此檔案,套件會要求您覆寫它。
啟用 HTML 與 劇作家工作區 報告器
若要使用 劇作家工作區 的可觀察性功能,請在檔案中playwright.service.config.ts新增以下設定來啟用 HTML 與 劇作家工作區 報告器 –
reporter: [
["html", { open: "never" }], // HTML reporter must come first
["@azure/playwright/reporter"], // Azure reporter uploads HTML report
]
在 Playwright 設定中啟用成品
在您的項目檔案playwright.config.ts中,請確定您正在收集所有必要的構件。
use:
{
trace: 'on-first-retry',
video:'retain-on-failure',
screenshot:'on'
}
設定瀏覽器端點
在您的設定中,請提供區域特定的瀏覽器端點。 此端點取決於您在建立工作區時選取的 Azure 區域。
要取得瀏覽器端點 URL,請依照以下步驟操作:
使用您的 Azure 帳戶登入 Azure 入口網站,然後前往您的工作區。
選取 [開始使用] 頁面。
在將 瀏覽器端點新增至您的設定中,複製端點 URL。
請確保此 URL 可在
PLAYWRIGHT_SERVICE_URL環境變數中使用。
設定您的環境
若要設定您的環境,請使用您在先前步驟中取得的值來設定 PLAYWRIGHT_SERVICE_URL 環境變數。
利用這個 dotenv 模組來管理你的環境。 透過使用此 dotenv 模組,您可以在 .env 檔案中定義環境變數。
將模組
dotenv加入您的專案中。npm i --save-dev dotenv在
playwright.service.config.ts中新增以下程式碼片段。require('dotenv').config();在你的 Playwright 專案中,建立一個
playwright.config.ts檔案,並放在.env檔案旁。PLAYWRIGHT_SERVICE_URL={MY-REGION-ENDPOINT}請確保您以先前複製的值取代
{MY-REGION-ENDPOINT}文字佔位符。
設定認證
若要在 Playwright 工作區中執行 Playwright 測試,您需要將執行測試的 Playwright 用戶端與服務進行驗證。 從你本地的開發機或 CI 機進行驗證。
Note
劇作家工作區 的測試自動化可觀察性僅支援基於 Microsoft Entra ID 的驗證。 如果你用存取權杖來做認證,就不能使用可觀察性。
使用 Microsoft Entra ID 設定驗證
Microsoft Entra ID 是在 Playwright 工作區中使用可觀測性功能的唯一支援驗證方式。 從你的本機開發機,你可以用 Azure CLI 登入
az login
Note
如果您屬於多個 Microsoft Entra 租用戶,請務必登入您的工作區所屬的租用戶。 您可以從 Azure 入口網站取得租用戶識別碼。 請參閱尋找您的 Microsoft Entra 租用戶。 取得 ID 後,使用指令 az login --tenant <TenantID>登入。
請使用 劇作家工作區 進行測試
你已經完成了用 劇作家工作區 在雲端執行 Playwright 測試的設定。 您可以使用 Playwright CLI 來執行測試,或使用 Playwright Test Visual Studio Code 擴充功能。
開啟終端機視窗。
輸入下列命令,在工作區中的遠端瀏覽器上執行 Playwright 測試套件:
npx playwright test --config=playwright.service.config.ts --workers=20視測試套件的大小而定,此命令最多可在 20 個平行背景工作角色上執行測試。
在 Azure 入口網站中對測試執行與結果進行除錯
為連結儲存帳號新增基於角色的存取控制(RBAC)角色
在 Azure 入口網站開啟連結的儲存帳號。
前往 [存取控制 (IAM)] 索引標籤。
選擇 新增角色指派。
在「 特權管理員角色」下,搜尋並選取「 Storage Blob 資料檢視器 角色」,然後選擇 「下一步」。
選取並新增所有能查看測試報告的成員。
選擇 檢閱 + 指派。
(僅在啟用追蹤時)允許在連結的儲存帳號中列出公開追蹤檢視器
在 Azure 入口網站開啟連結的儲存帳號。
前往設定>資源共用(CORS)。
在 Blob 服務下,新增一條紀錄:
- 允許的原始來源:
https://trace.playwright.dev - 允許的方法:
GET,OPTIONS - 最大年齡:輸入介於0到2147483647之間的數值。
- 允許的原始來源:
選取 [儲存]。
在 Azure 入口網站查看已儲存的測試報告
你現在可以在 Azure 入口網站中排解失敗的測試案例。
測試執行結束後,報告器會在 Azure 入口網站產生一個測試執行頁面的連結。 開啟此連結以檢視詳細的測試結果和相關聯的成品。
測試執行頁面提供所有故障排除所需的資訊。 您可以:
- 查看 詳細的錯誤日誌、 測試步驟,以及附帶的影像,如 截圖 或 影片。
- 直接瀏覽至追蹤檢視器以進行更深入的分析。
Trace Viewer 讓你能以視覺方式逐步檢視測試執行過程。 您可以:
- 使用時間軸將滑鼠停留在個別步驟上,並顯示每個動作前後的頁面狀態。
- 檢查 詳細日誌、 DOM 快照、 網路活動、 錯誤及每個步驟的 主控台輸出 。
Tip
為了獲得更好的體驗,請在新的瀏覽器分頁中按 Ctrl 鍵並選擇 「檢視追蹤」來開啟追蹤檢視器。
Prerequisites
開始之前,請確定您有下列項目:
- 一個有有效訂閱的 Azure 帳號。 如果您沒有 Azure 訂用帳戶,請建立免費帳戶。
- 擁有者、參與者,或您 Azure 帳戶中的其中一種傳統管理員角色。
- 若要讓Azure入口網站為您將儲存體權限指派給受控識別,您必須具備可在儲存體帳戶上指派角色的角色,例如 擁有者、使用者存取管理員 或 Role Based 存取控制 Administrator。 如果你沒有這些角色,請有權限的人幫你指派權限。
- 連接至 劇作家工作區 遠端 MCP 伺服器的 MCP 用戶端,例如 GitHub Copilot 應用程式、搭配 GitHub Copilot 的 Visual Studio Code,或 GitHub Copilot CLI。 若要設定,請參閱 快速入門:使用遠端 MCP 伺服器自動化瀏覽器任務。
啟用可觀察性並設定儲存體
會話錄製會儲存在與您的工作區連結的 Azure 儲存帳戶中。 劇作家工作區 使用受管理身份將工件寫入該儲存帳戶。 若要設定此設定,請開啟可觀察性,選擇儲存體帳戶,並選擇受控識別。 您可以建立新工作區或更新現有工作區。
使用您 Azure 訂閱的認證來登入 Azure 入口網站。
在入口網站首頁,搜尋並選擇 Azure 應用程式測試。
在 Azure 應用程式測試 中心的 劇作家工作區 下,選取 建立。
在「基礎」索引標籤中的「建立 Playwright 工作區」頁面上,輸入以下資訊:
Field Description 訂閱 選取要用於此 Playwright 工作區的 Azure 訂閱。 資源群組 選取現有的資源群組。 或選取 [新建],然後為新的資源群組輸入唯一的名稱。 姓名 為您的工作區輸入一個獨特的名稱。 名稱只能包含字母數字和連字號,且長度必須為 3 到 24 個字元。 位置 選擇一個地理位置作為工作區。 選擇「 功能 」標籤,然後輸入以下資訊:
Field Description 可觀察性 開啟以擷取報告、追蹤及工作階段錄製。 記憶體帳戶 選取現有的儲存帳戶,或選擇 「建立新帳戶」 以建立一個。 劇作家工作區 會將你的工作階段記錄和其他資料儲存在這個儲存帳戶中。 身份類型 選擇 劇作家工作區 用來存取儲存帳戶的管理身份:系統指派或使用者指派。 如果您選擇 「使用者指派」,請選擇由使用者指派的管理識別碼。 身份權限 選取「代表我為受管理身分指派權限」,讓 Azure 入口網站將儲存帳戶上的Storage Blob Data Contributor角色指派給受管理身分。 只有當您有權限指派儲存帳戶角色時,才選擇此選項。 否則,請清除並手動 指派角色。 您也可以選擇在「 標籤」 索引標籤中新增標籤。標籤是用於分類資源並檢視合併帳單的名稱/值對,方法是將相同標籤套用至多個資源及資源群組。
選擇 評論 + 創建。 檢視你的設定,然後選擇 建立。
建立工作區需要幾分鐘。 請等待入口網站顯示「 您的部署已完成 」後再繼續。
Note
所有需要儲存帳戶的工作區功能,例如工作階段錄製、報告及瀏覽器設定檔,皆使用您在 功能 頁面設定的相同儲存帳戶及管理身份。
Note
劇作家工作區 可觀察性會將您的工作階段錄音和其他產物儲存在 Azure 儲存體 中。 儲存費用取決於您的儲存帳戶的資料保留設定。
Note
要儲存工件,儲存帳戶必須允許透過其公共端點進行網路存取。 僅允許透過私有端點存取的儲存帳戶目前不支援儲存產物。
為受控識別指派儲存體權限
如果您已取消「代 我指派受管理身份」權限,或您沒有權限指派儲存帳戶的角色,請手動指派該角色。 如果您沒有所需的權限,請要求在儲存帳戶上具有擁有者、使用者存取管理員或Role Based 存取控制 Administrator角色的人員完成這些步驟。
在 Azure 入口網站中,前往與您工作區連結的儲存帳戶。
選擇存取控制 (IAM)>新增>新增角色指派。
在 「角色」 索引標籤上,搜尋並選取「 Storage Blob Data Contributor」,然後選擇 「下一步」。
在 [ 成員] 索引標籤上,針對 [ 指派存取權] 選取 [ 受控識別]。
選擇「 選取成員」,然後選擇您為工作區所選擇的管理身份:
- 對於系統指派的身份,請選擇 Playwright 工作區 作為管理身份類型,然後選擇您的工作區。
- 對於使用者指派的識別,選擇 「使用者指派的受控識別」,然後選擇該識別。
選取 選取,然後選取 檢閱與指派。
Tip
角色分配可能需要幾分鐘才能生效。 如果錄製內容沒有立即顯示,請等待幾分鐘後重新進行該工作階段。
在您的 MCP 用戶端中啟用工作階段錄製
遠端 MCP 伺服器只會在您的 MCP 用戶端要求時錄製瀏覽器會話。 要啟用錄製,請在您的 MCP 用戶端遠端 MCP 伺服器設定中新增以下 HTTP 標頭:
| Header | Value |
|---|---|
x-ms-enable-sessionartifacts |
Enabled |
用戶端透過此 MCP 伺服器連線建立的每一個瀏覽器工作階段都會被記錄下來。 來自未傳送標頭的用戶端會話不會被記錄。 新增標頭時,請保留您現有的 URL 與驗證設定。
Tip
如果您的伺服器項目已有其他 劇作家工作區 標頭,例如 x-ms-browser-profile-id 或 x-ms-secret-store-id,請加入x-ms-enable-sessionartifacts同一組標頭。
與您的代理程式執行瀏覽器工作階段
請你的代理程式執行瀏覽器任務。 例如,輸入以下提示字句:
Open https://playwright.dev, open the Docs page, and tell me the title of the page.
代理程式會在你的工作區開啟雲端瀏覽器,完成任務後關閉工作階段。 由於您的 MCP 用戶端會傳送 x-ms-enable-sessionartifacts 標頭,工作階段的產物會儲存在連結的儲存帳戶中。
代理程式會回傳 Azure 入口網站中已儲存瀏覽器會話的連結。
Caution
會話錄影記錄瀏覽器所顯示的內容,包括每個頁面的截圖、頁面內容及網路流量。 如果您的代理程式處理敏感資料,請限制誰能讀取連結的儲存帳戶,並設定符合您組織需求的資料保留政策。
在 Azure 入口網站檢視工作階段錄製
若要在 Azure 入口網站中檢視錄影,您需要對已連結的儲存帳戶具有讀取權限,且該儲存帳戶必須允許追蹤檢視器載入追蹤檔案。
為檢視錄影的人員指派儲存角色
在 Azure 入口網站中,前往與您工作區連結的儲存帳戶。
選擇存取控制 (IAM)>新增>新增角色指派。
在 「角色」 索引標籤中,搜尋並選取 「儲存 Blob 資料讀取器」,然後選擇 「下一步」。
在 「成員」 標籤中,選取並新增所有需要檢視會話錄影的人。
選擇 檢閱 + 指派。
允許追蹤檢視器從儲存帳戶讀取
在 Azure 入口網站中,前往連結的儲存帳戶。
選擇設定>資源共用(CORS)。
在 Blob 服務 索引標籤上,新增一個具有下列值的記錄:
Field Value 允許的來源 https://trace.playwright.dev允許的方法 GET,OPTIONS最大年齡 介於 0與2147483647之間的值。選取 [儲存]。
檢視錄製的會話
在 Azure 入口網站中,前往您的 Playwright 工作區。
選擇瀏覽器工作階段>瀏覽器活動記錄。
瀏覽器活動記錄會列出您工作區中的瀏覽器工作階段。 每個工作階段會顯示名稱、工作階段 ID、建立者、來源類型、開始時間、來源 ID、計費時間、瀏覽器類型及狀態。 要尋找工作階段,請依 時間範圍、 來源類型、 狀態或來源 ID 篩選清單。 您的 MCP 用戶端會建立來源類型為 MCP 的會話。
選擇您的代理程式執行的會話名稱。
工作階段頁面會顯示 工作階段詳細資訊 及 工作階段回放。 在播放時,你可以:
- 沿著時間軸移動,即可在工作階段的任何時間點查看該頁面。
- 在動作清單中選擇一個動作,以查看動作前和後的頁面。
- 使用 定位器、 呼叫、 記錄、 錯誤、 主控台、 網路、 來源及 附件 等標籤來檢視每個動作的詳細資料。
- 請在 追蹤檢視器 中開啟該工作階段以進行更深入的分析。
若要返回清單,請選擇 「檢視所有工作階段」。
停止記錄工作階段
若要停止錄製新的工作階段,請從 MCP 用戶端設定中移除 x-ms-enable-sessionartifacts 標頭。 現有的錄音會保留在您的儲存帳戶中,直到您刪除它們,或直到您的儲存帳戶的資料保留設定將其移除為止。
資料存放位置
所有工作階段錄製及其他產物都會儲存在您連結至工作區的 Azure 儲存帳戶中。 您擁有並控制此儲存帳戶,包括其區域、存取權限、網路設定及資料保留。
劇作家工作區 僅儲存列出和管理工作階段所需的元資料,例如工作階段名稱與 ID、建立者、狀態、開始與結束時間、可計費時間、來源類型及瀏覽器類型。 劇作家工作區 不會儲存瀏覽器工作階段中的任何用戶端資料,例如頁面內容、截圖、影片、追蹤、主控台訊息或網路流量。