快速入門：使用 Microsoft Playwright Testing 預覽版來大規模地執行端對端測試

發行項
05/22/2024

在本快速入門中，您會了解如何使用 Microsoft Playwright Testing 預覽版，以高度平行的雲端瀏覽器執行 Playwright 測試。使用雲端基礎結構，以便跨多個瀏覽器、裝置和作業系統來驗證您的應用程式。

完成本快速入門之後，您會獲得一個可大規模執行 Playwright 測試的 Microsoft Playwright Testing 工作區。

重要

Microsoft Playwright Testing 目前為預覽版。如需適合測試版、處於預覽狀態或其他尚未發行正式推出之 Azure 功能的法律條款，請參閱 Microsoft Azure 預覽版補充使用條款。

必要條件

具有有效訂用帳戶的 Azure 帳戶。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
您的 Azure 帳戶需要擁有者 (部分機器翻譯)、參與者 (部分機器翻譯) 或其中一個傳統管理員角色 (部分機器翻譯)。
Playwright 專案。如果您沒有專案，請使用 Playwright 使用者入門文件 (英文) 建立專案，或使用我們的 Microsoft Playwright Testing 範例專案 (英文)。

建立工作區

若要開始在雲端瀏覽器上大規模執行 Playwright 測試，請先在 Playwright 入口網站中建立 Microsoft Playwright Testing 工作區。

使用您的 Azure 帳戶登入 Playwright 入口網站 (英文)。
如果您已經有工作區，請選取現有的工作區，然後移至下一個步驟。

提示

如果您有多個工作區，則可以藉由選取頁面頂端的工作區名稱來切換至另一個工作區，然後選取 [管理所有工作區]。

如果您還沒有工作區，請選取 [+ 新增工作區]，然後提供下列資訊：

欄位	描述
工作區名稱	輸入唯一的名稱來識別您的工作區。名稱中只能包含英數字元，且長度在 3 到 64 個字元之間。
Azure 訂用帳戶	選取您要用於此 Microsoft Playwright Testing 工作區的 Azure 訂用帳戶。
區域	選取用來裝載工作區的地理位置。這是用來為工作區儲存測試回合資料的位置。

選取 [建立工作區] 以在訂用帳戶中建立工作區。

在工作區建立期間，系統會在 Azure 訂用帳戶中建立新的資源群組和 Microsoft Playwright Testing Azure 資源。

當工作區建立完成時，系統會將您重新導向至設定指南。

建立用於驗證服務的存取權杖

Microsoft Playwright Testing 會使用存取權杖來授權使用者使用該服務執行 Playwright 測試。請先在 Playwright 入口網站中產生服務的存取權杖，然後將該值儲存在環境變數中。

若要產生存取權杖，請執行下列步驟：

在工作區設定指南的 [建立存取權杖] 中，選取 [產生權杖]。
複製工作區的存取權杖。

您需要存取權杖值，以便在稍後的步驟中設定環境。

設定服務區域端點

在服務組態中，您必須提供區域特定的服務端點。此端點取決於您在建立工作區時選取的 Azure 區域。

若要取得服務端點 URL，請執行下列步驟：

在 [在設定中新增區域端點] 中，複製工作區的區域端點。

此端點 URL 會符合您在建立工作區時選取的 Azure 區域。

設定您的環境

若要設定環境，您必須使用自先前步驟中取得的值來設定 PLAYWRIGHT_SERVICE_ACCESS_TOKEN 和 PLAYWRIGHT_SERVICE_URL 環境變數。

建議您使用 dotenv 模組來管理環境。使用 dotenv 可在 .env 檔案中定義環境變數。

將 dotenv 模組新增至您的專案：
```
npm i --save-dev dotenv
```
在 Playwright 專案中，連同 playwright.config.ts 檔案一起建立 .env 檔案：
```
PLAYWRIGHT_SERVICE_ACCESS_TOKEN={MY-ACCESS-TOKEN}
PLAYWRIGHT_SERVICE_URL={MY-REGION-ENDPOINT}
```
請務必將 {MY-ACCESS-TOKEN} 和 {MY-REGION-ENDPOINT} 文字預留位置取代為您稍早複製的值。

警告

請務必不要將 .env 檔案新增至原始程式碼存放庫，以免洩漏存取權杖值。

新增服務組態檔

若要在 Microsoft Playwright Testing 工作區中執行 Playwright 測試，您需要連同 Playwright 組態檔一起新增服務組態檔。服務組態檔會參考環境變數，以取得工作區端點和存取權杖。

若要將服務組態新增至您的專案：

連同 playwright.config.ts 檔案一起建立新檔案 playwright.service.config.ts。

(選擇性) 使用範例存放庫 (英文) 中的 playwright.service.config.ts 檔案。

將下列內容新增至其中：

/*
* This file enables Playwright client to connect to remote browsers.
* It should be placed in the same directory as playwright.config.ts.
*/

import { defineConfig } from '@playwright/test';
import config from './playwright.config';
import dotenv from 'dotenv';

// Define environment on the dev box in .env file:
//  .env:
//    PLAYWRIGHT_SERVICE_ACCESS_TOKEN=XXX
//    PLAYWRIGHT_SERVICE_URL=XXX

// Define environment in your GitHub workflow spec.
//  env:
//    PLAYWRIGHT_SERVICE_ACCESS_TOKEN: ${{ secrets.PLAYWRIGHT_SERVICE_ACCESS_TOKEN }}
//    PLAYWRIGHT_SERVICE_URL: ${{ secrets.PLAYWRIGHT_SERVICE_URL }}
//    PLAYWRIGHT_SERVICE_RUN_ID: ${{ github.run_id }}-${{ github.run_attempt }}-${{ github.sha }}

dotenv.config();

// Name the test run if it's not named yet.
process.env.PLAYWRIGHT_SERVICE_RUN_ID = process.env.PLAYWRIGHT_SERVICE_RUN_ID || new Date().toISOString();

// Can be 'linux' or 'windows'.
const os = process.env.PLAYWRIGHT_SERVICE_OS || 'linux';

export default defineConfig(config, {
  // Define more generous timeout for the service operation if necessary.
  // timeout: 60000,
  // expect: {
  //   timeout: 10000,
  // },
  workers: 20,

  // Enable screenshot testing and configure directory with expectations.
  // https://learn.microsoft.com/azure/playwright-testing/how-to-configure-visual-comparisons
  ignoreSnapshots: false,
  snapshotPathTemplate: `{testDir}/__screenshots__/{testFilePath}/${os}/{arg}{ext}`,
  
  use: {
    // Specify the service endpoint.
    connectOptions: {
      wsEndpoint: `${process.env.PLAYWRIGHT_SERVICE_URL}?cap=${JSON.stringify({
        // Can be 'linux' or 'windows'.
        os,
        runId: process.env.PLAYWRIGHT_SERVICE_RUN_ID
      })}`,
      timeout: 30000,
      headers: {
        'x-mpt-access-key': process.env.PLAYWRIGHT_SERVICE_ACCESS_TOKEN!
      },
      // Allow service to access the localhost.
      exposeNetwork: '<loopback>'
    }
  },
  // Tenmp workaround for config merge bug in OSS https://github.com/microsoft/playwright/pull/28224
  projects: config.projects? config.projects : [{}]
});

儲存檔案。

使用 Microsoft Playwright Testing 來大規模地執行測試

您現在已經準備好可在雲端中使用 Microsoft Playwright Testing 來執行 Playwright 測試的組態。您可以使用 Playwright CLI 來執行測試，也可以使用 Playwright Test Visual Studio Code 延伸模組 (英文)。

大規模地執行單一測試

使用 Microsoft Playwright Testing 時，您必須根據測試總分鐘數來付費。如果您是第一次使用的使用者，或透過免費試用來開始使用，則一開始可以大規模地執行單一測試，而不是執行完整的測試套件，以免耗盡免費的測試分鐘數。

驗證測試回合成功後，便可以透過搭配服務來執行更多測試，逐漸增加測試負載。

執行下列步驟，以使用 Microsoft Playwright Testing 來執行單一 Playwright 測試：

Playwright CLI
Visual Studio Code

若要使用 Playwright CLI 搭配 Microsoft Playwright Testing 來執行測試，請以命令列參數的形式傳遞服務組態檔。

開啟終端機視窗。
輸入下列命令，在工作區中的遠端瀏覽器上執行 Playwright 測試：

將 {name-of-file.spec.ts} 文字預留位置取代為測試規格檔案的名稱。
```
npx playwright test {name-of-file.spec.ts} --config=playwright.service.config.ts
```
測試完成後，可以在終端中檢視測試狀態。
```
Running 1 test using 1 worker
    1 passed (2.2s)

To open last HTML report run:

npx playwright show-report
```

若要使用 Microsoft Playwright Testing 在 Visual Studio Code 中執行單一 Playwright 測試，請在 [測試清單編輯器] 檢視中選取服務組態檔。然後，從測試清單中選取並執行測試。

安裝 Playwright Test Visual Studio Code 延伸模組 (英文)。
在活動列中開啟 [測試清單編輯器] 檢視。

測試清單編輯器會自動偵測您的 Playwright 測試和專案中的服務組態。
選取 [選取預設設定檔]，然後從服務組態檔中選取您的預設專案。

請注意，服務執行設定檔來自您先前新增的 playwright.service.config.ts 檔案。

藉由設定預設設定檔，您可以使用該服務自動執行測試，或同時執行多個 Playwright 專案。
從測試清單中，選取測試旁邊的 [執行測試] 按鈕以執行測試。

測試會在您於預設設定檔中選取的專案上執行。如果您從服務組態中選取一或多個專案，則測試會在工作區中的遠端瀏覽器上執行。

提示

當您使用 [對測試偵錯] 按鈕在遠端瀏覽器上執行測試時，您仍然可以對測試的程式碼進行偵錯。
您可以直接在 Visual Studio Code 中檢視測試結果。

您現在可以使用該服務來執行多個測試，或在遠端瀏覽器上執行整個測試套件。

警告

視測試套件大小而定，測試分鐘數超過所分配到的免費測試分鐘數的部分可能會產生額外費用。

大規模地執行完整測試套件

您現已驗證您可以使用 Microsoft Playwright Testing 來執行單一測試，接下來您可以大規模地執行完整的 Playwright 測試套件。

執行下列步驟，以使用 Microsoft Playwright Testing 來執行完整的 Playwright 測試套件：

Playwright CLI
Visual Studio Code

當您使用 Microsoft Playwright Testing 執行多個 Playwright 測試或完整測試套件時，您可以選擇性地以命令列參數的形式指定平行背景工作角色數目。

開啟終端機視窗。
輸入下列命令，在工作區中的遠端瀏覽器上執行 Playwright 測試套件：
```
npx playwright test --config=playwright.service.config.ts --workers=20
```
視測試套件大小而定，此命令會在最多 20 個平行背景工作角色上執行測試。

測試完成後，可以在終端中檢視測試狀態。
```
Running 6 tests using 6 workers
    6 passed (18.2s)

To open last HTML report run:

    npx playwright show-report
```

在 Playwright 入口網站中檢視測試回合

移至 Playwright 入口網站，以檢視工作區的測試回合中繼資料和活動記錄。

活動記錄會針對每個測試回合列出下列詳細資料：測試完成時間總計、平行背景工作角色數目，以及測試分鐘數。

在 Playwright 入口網站中檢視測試結果

Microsoft Playwright Testing 現在支援在 Playwright 入口網站中檢視測試結果。此功能僅以受邀功能的形式來提供。

重要

Microsoft Playwright Testing 服務的報告功能在僅限邀請的預覽期間是免費的。不過，任何雲端裝載瀏覽器的現有功能會繼續根據 Azure 定價方案來計費。

可以存取報告工具後，請使用下列步驟來設定測試。

從工作區首頁，瀏覽至 [設定]。
從 [設定] 中，選取 [一般]，並確定報告 [已啟用]。
請確定環境已正確設定，如設定環境一節中所述。
安裝報告套件

此功能目前並未公開，因此您必須另外執行一些步驟才能安裝此套件。此功能正式公開後，便不需要執行這些步驟。
1. 在與 Playwright 組態檔相同的位置建立名稱為 .npmrc 的檔案。
2. 將下列內容新增至檔案，並進行儲存。
```
@microsoft:registry=https://npm.pkg.github.com
```
3. 遵循下列步驟，以建立 GitHub 個人存取權杖。
您必須向權杖提供 read:packages 權限。本文其餘部分將此權杖稱為 PAT_TOKEN_PACKAGE。
1. 在終端中，於 Playwright 組態檔的位置執行下列命令。將 PAT_TOKEN_PACKAGE 取代為上一個步驟中產生的權杖。
```
    npm set //npm.pkg.github.com/:_authToken PAT_TOKEN_PACKAGE
```
2. 使用套件更新 package.json 檔案。
```
 "dependencies": {
            "@microsoft/mpt-reporter": "0.1.0-22052024-private-preview"
    }
```
3. 執行 npm install 以安裝套件。

更新 Playwright.config 檔案

以使用其他報告程式的相同方式，將 Playwright Testing 報告程式新增至 Playwright.config.ts。

import { defineConfig } from '@playwright/test';

export default defineConfig({
    reporter: [
    ['list'],
    ['json', {  outputFile: 'test-results.json' }],
    ['@microsoft/mpt-reporter'] // Microsoft Playwright Testing reporter
    ],
});

請務必要在組態中啟用成品，以便能更好的進行疑難排解。

use: {
    // ...
    trace: 'on-first-retry',
    video:'retain-on-failure',
    screenshot:'only-on-failure',
    }

執行 Playwright 測試

您可以在 Playwright Testing 入口網站上執行 npx playwright test 命令並檢視結果和成品。

提示

您可以使用 Microsoft Playwright Testing 服務，不受雲端裝載瀏覽器功能影響地將測試結果發佈至入口網站。

將平行背景工作角色的組態最佳化

測試能搭配服務順利執行後，請實驗不同數目的平行背景工作角色，以判斷可將測試完成時間降到最低的最佳組態。

使用 Microsoft Playwright Testing 時，您最多可以搭配 50 個平行背景工作角色來執行。有數個因素會影響專案的最佳組態，例如用戶端機器的 CPU、記憶體和網路資源、目標應用程式的負載處理容量，以及測試中所執行的動作類型。

您可以在 Playwright CLI 命令列上指定平行背景工作角色數目，或在 Playwright 服務組態檔中設定 workers 屬性。

深入了解如何判斷可將測試套件完成時間最佳化的最佳組態 (部分機器翻譯)。

後續步驟

您已成功在 Playwright 入口網站中建立 Microsoft Playwright Testing 工作區，並在雲端瀏覽器上執行 Playwright 測試。

請繼續進行下一個快速入門，在 CI/CD 工作流程中執行 Playwright 測試，以設定持續的端對端測試。

在 CI/CD 中設定持續的端對端測試 (部分機器翻譯)

共用方式為