快速入門：使用 Microsoft Playwright Testing 預覽版來設定持續的端對端測試

發行項
12/30/2024

在本快速入門中，您會使用 Microsoft Playwright Testing 預覽版來設定持續的端對端測試，以驗證 Web 應用程式可搭配每一個程式碼認可，在不同瀏覽器和作業系統之間正確執行，並使用服務儀錶板來輕鬆疑難排解測試。請了解如何將 Playwright 測試新增至持續整合 (CI) 工作流程，例如 GitHub Actions、Azure Pipelines 或其他 CI 平台。

完成本快速入門之後，您會獲得一個 CI 工作流程，其會使用 Microsoft Playwright Testing 大規模地執行 Playwright 測試套件並幫助您輕鬆疑難排解測試。

重要

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

必要條件

具有有效訂用帳戶的 Azure 帳戶。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
Microsoft Playwright Testing 工作區。完成快速入門：大規模執行 Playwright 測試並建立工作區。

GitHub 動作
Azure Pipelines

GitHub 帳戶。如果您沒有 GitHub 帳戶，您可免費建立帳戶。
GitHub 存放庫，其中包含您的 Playwright 測試規格和 GitHub Actions 工作流程。若要建立存放庫，請參閱建立新的存放庫 (英文)。
GitHub Actions 工作流程。如果您需要協助以便開始使用 GitHub Actions，請參閱建立您的第一個工作流程 (英文)
設定從 GitHub Actions 到 Azure 的驗證。查看使用 GitHub Actions 連線到 Azure

取得服務區域端點 URL

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

若要取得服務端點 URL，並將其儲存為 CI 工作流程祕密，請執行下列步驟：

使用您的 Azure 帳戶登入 Playwright 入口網站 (英文)。
在工作區首頁上，選取 [檢視設定指南]。

提示

如果您有多個工作區，則可以藉由選取頁面頂端的工作區名稱來切換至另一個工作區，然後選取 [管理所有工作區]。
在 [在設定中新增區域端點] 中，複製服務端點 URL。

此端點 URL 會符合您在建立工作區時選取的 Azure 區域。
將服務端點 URL 儲存在 CI 工作流程秘密中：

祕密名稱值

PLAYWRIGHT_SERVICE_URL 貼上您先前複製的端點 URL。

祕密名稱	值
PLAYWRIGHT_SERVICE_URL	貼上您先前複製的端點 URL。

新增服務組態檔

如果您沒有將 Playwright 測試設定為使用服務執行，請將服務組態檔新增至您的存放庫。在下一個步驟中，您接著會在 Playwright CLI 上指定此服務組態檔。

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

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

將下列內容新增至其中：

import { defineConfig } from '@playwright/test';
import { getServiceConfig, ServiceOS } from '@azure/microsoft-playwright-testing';
import config from './playwright.config';

/* Learn more about service configuration at https://aka.ms/mpt/config */
export default defineConfig(
  config,
  getServiceConfig(config, {
    exposeNetwork: '<loopback>',
    timeout: 30000,
    os: ServiceOS.LINUX,
    useCloudHostedBrowsers: true
  }),
  {
    /* 
    Playwright Testing service reporter is added by default.
    This will override any reporter options specified in the base playwright config.
    If you are using more reporters, please update your configuration accordingly.
    */
    reporter: [['list'], ['@azure/microsoft-playwright-testing/reporter']],
  }
);

根據預設，服務組態可讓您：

使用雲端裝載的瀏覽器平行執行測試，以加速建置管線。
簡化疑難解答，輕鬆存取發佈至服務的測試結果和成品。

不過，您可以選擇使用這些功能或兩者。請參閱如何使用服務功能，並根據您的需求更新服務組態檔。

將檔案儲存並認可至您的原始程式碼存放庫。

更新 package.json 檔案

更新存放庫中的 package.json 檔案，以在 devDependencies 區段中新增Microsoft Playwright Testing 服務套件的詳細資料。

"devDependencies": {
    "@azure/microsoft-playwright-testing": "^1.0.0-beta.6"
}

在 Playwright 設定中啟用成品

在項目的檔案中 playwright.config.ts ，確定您正在收集所有必要的成品。

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

設定服務組態

在專案的根目錄中建立新檔案 PlaywrightServiceSetup.cs 。此檔案可協助驗證客戶端與服務。

將下列內容新增至其中：

using Azure.Developer.MicrosoftPlaywrightTesting.NUnit;
using NUnit.Framework;

namespace PlaywrightTests; // Remember to change this as per your project namespace

[SetUpFixture]
public class PlaywrightServiceSetup : PlaywrightServiceNUnit { };

將檔案儲存並認可至您的原始程式碼存放庫。

安裝服務套件

在您的專案中，安裝 Microsoft Playwright Testing 套件。

dotnet add package Azure.Developer.MicrosoftPlaywrightTesting.NUnit --prerelease

此命令會將服務套件詳細數據新增至 ItemGroup 區段，以更新項目的csproj檔案。請記得認可這些變更。

  <ItemGroup>
    <PackageReference Include="Azure.Developer.MicrosoftPlaywrightTesting.NUnit" Version="1.0.0-beta.2" />
  </ItemGroup>

新增或更新 `.runsettings` 項目的檔案。

如果您尚未設定 Playwright 測試以使用服務執行它們，請將檔案新增 .runsettings 至您的存放庫。在下一個步驟中，您接著會在 Playwright CLI 上指定此服務組態檔。

建立新的 .runsettings 檔案。

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

將下列內容新增至其中：

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
    <TestRunParameters>
        <!-- The below parameters are optional -->
        <Parameter name="Os" value="linux" />
        <!--<Parameter name="RunId" value="sample-run-id1" />-->
        <Parameter name="ServiceAuthType" value="EntraId" />
        <Parameter name="UseCloudHostedBrowsers" value="true" />
        <Parameter name="AzureTokenCredentialType" value="DefaultAzureCredential" />
        <!--<Parameter name="ManagedIdentityClientId" value="{clientId-value}" />-->
        <Parameter name="EnableGitHubSummary" value="false" />
        <!--<Parameter name="ExposeNetwork" value="*" />-->
    </TestRunParameters>
  <!-- NUnit adapter -->  
  <NUnit>
    <!-- Adjust parallel workers, parallel worker would also be bound by number of unit test files -->
    <NumberOfTestWorkers>10</NumberOfTestWorkers>
  </NUnit>
  <!-- General run configuration -->
  <RunConfiguration>
    <EnvironmentVariables>
      <!-- For debugging selectors, it's recommend to set the following environment variable -->
        <!--<DEBUG>pw:api*</DEBUG>--> 
    </EnvironmentVariables>
  </RunConfiguration>
  <!-- Playwright -->  
  <Playwright>
    <BrowserName>chromium</BrowserName>
    <ExpectTimeout>5000</ExpectTimeout>
    <LaunchOptions>
      <Headless>false</Headless>
      <!--Channel>msedge</Channel-->
    </LaunchOptions>
  </Playwright>
    <LoggerRunSettings>
        <Loggers>
            <!--microsoft playwright testing service logger for reporting -->
            <Logger friendlyName="microsoft-playwright-testing" enabled="True" />
            <!--could enable any logger additionally -->
            <Logger friendlyName="trx" enabled="false" />
        </Loggers>
    </LoggerRunSettings>
</RunSettings>

此檔案中的設定可讓您：

使用雲端裝載的瀏覽器平行執行測試，以加速建置管線。
將測試結果和成品發佈至服務，以更快速地進行疑難解答。

不過，您可以選擇使用這些功能或兩者。請參閱如何使用服務功能，並根據您的需求更新服務組態檔。

將檔案儲存並認可至您的原始程式碼存放庫。

在劇作家設定中啟用成品

設定 Playwright 以擷取螢幕快照、影片和追蹤等成品。

如需螢幕快照，請參閱擷取螢幕快照
針對影片，請參閱錄製測試的影片
如需追蹤，請參閱錄製追蹤

收集這些成品之後，請將它們附加至 TestContext ，以確保這些成品可在您的測試報告中使用。如需詳細資訊，請參閱 NUnit 的範例專案。

設定驗證

執行 Playwright 測試的 CI 機器必須向 Playwright Testing 服務進行驗證，才能讓瀏覽器執行測試並發佈測試結果和成品。

此服務提供兩種驗證方法：Microsoft Entra ID 和存取權杖。強烈建議使用 Microsoft Entra 識別碼來驗證管線。

如果您使用 GitHub Actions，您可以使用 GitHub OpenID Connect 連線到服務。請遵循步驟來設定整合：

必要條件

選項 1：Microsoft Entra 應用程式

透過 Azure 入口網站、Azure CLI 或 Azure PowerShell，建立具有服務主體的 Microsoft Entra 應用程式。
複製用戶端標識碼、訂用帳戶標識碼和目錄（租用戶）標識碼的值，以便稍後在 GitHub Actions 工作流程中使用。
將 Owner 或 Contributor 角色指派給在上一個步驟中建立的服務主體。這些角色必須在 Playwright Testing 工作區上指派。如需詳細資訊，請參閱如何管理存取權。
在 Microsoft Entra 應用程式上設定同盟身分識別認證，以信任 GitHub Actions 簽發給 GitHub 存放庫的令牌。

選項 2：使用者指派的受控識別

建立使用者指派的受控識別。
複製用戶端標識碼、訂用帳戶標識碼和目錄（租用戶）標識碼的值，以便稍後在 GitHub Actions 工作流程中使用。
將 Owner 或 Contributor 角色指派給在上一個步驟中建立的使用者指派受控識別。這些角色必須在 Playwright Testing 工作區上指派。如需詳細資訊，請參閱如何管理存取權。
在使用者指派的受控識別上設定同盟身分識別認證，以信任 GitHub Actions 簽發給 GitHub 存放庫的令牌。

建立 GitHub 祕密

將您在上一個步驟中取得的值新增為 GitHub 存放庫的秘密。請參閱設定 GitHub 動作秘密。後續步驟中的 GitHub Action 工作流程會使用這些變數。

GitHub 祕密	來源（Microsoft Entra Application 或 Managed Identity）
`AZURE_CLIENT_ID`	Client ID
`AZURE_SUBSCRIPTION_ID`	訂用帳戶識別碼
`AZURE_TENANT_ID`	目錄（租使用者）識別碼

注意

為了增強安全性，強烈建議使用 GitHub 秘密來儲存敏感性值，而不是直接包含在工作流程檔案中。

使用存取權杖設定驗證

警告

我們強烈建議使用 Microsoft Entra ID 對服務進行驗證。如果您使用存取令牌，請參閱如何管理存取令牌

您可以從 Playwright Testing 工作區產生存取權杖，並在您的設定中使用該權杖。不過，我們強烈建議使用 Microsoft Entra ID 進行驗證，因為其安全性更高。存取權杖雖然方便，但功能類似長期密碼，而且更容易遭到入侵。

根據預設，使用存取權杖進行驗證會停用。若要使用，請啟用存取令牌型驗證。
使用存取令牌設定驗證。
將存取令牌儲存在 CI 工作流程秘密中，並在 GitHub Actions 工作流程或 Azure Pipeline yaml 檔案中使用。

祕密名稱	值
PLAYWRIGHT_SERVICE_ACCESS_TOKEN	貼上您先前建立的存取令牌值。

更新工作流程定義

更新 CI 工作流程定義，以使用 Playwright CLI 來執行 Playwright 測試。將服務組態檔作為 Playwright CLI 的輸入參數來傳遞。您可以藉由指定環境變數來設定環境。

開啟 CI 工作流程定義

新增下列步驟，以在 Microsoft Playwright Testing 中執行 Playwright 測試。

下列步驟說明 GitHub Actions 或 Azure Pipelines 的工作流程變更。同樣地，您也可以在其他 CI 平台中使用 Playwright CLI 來執行 Playwright 測試。

GitHub 動作
Azure Pipelines


  # This step is to sign-in to Azure to run tests from GitHub Action workflow. 
  # Choose how to set up authentication to Azure from GitHub Actions. This is one example. 
  name: Playwright Tests (Microsoft Playwright Testing)
  on:
    push:
      branches: [main, master]
    pull_request:
      branches: [main, master]

  permissions: # Required when using Microsoft Entra ID to authenticate
    id-token: write
    contents: read

  jobs:
    test:
      timeout-minutes: 60
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4

        - name: Login to Azure with AzPowershell (enableAzPSSession true)
          uses: azure/login@v2
          with:
            client-id: ${{ secrets.AZURE_CLIENT_ID }} # GitHub Open ID connect values copied in previous steps
            tenant-id: ${{ secrets.AZURE_TENANT_ID }}
            subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
            enable-AzPSSession: true

        - name: Install dependencies
          working-directory: path/to/playwright/folder # update accordingly
          run: npm ci

        - name: Run Playwright tests
          working-directory: path/to/playwright/folder # update accordingly
          env:
            # Regional endpoint for Microsoft Playwright Testing
            PLAYWRIGHT_SERVICE_URL: ${{ secrets.PLAYWRIGHT_SERVICE_URL }}
            # PLAYWRIGHT_SERVICE_ACCESS_TOKEN: ${{ secrets.PLAYWRIGHT_SERVICE_ACCESS_TOKEN }} # Not recommended, use Microsoft Entra ID authentication. 
          run: npx playwright test -c playwright.service.config.ts --workers=20

        - name: Upload Playwright report
          uses: actions/upload-artifact@v3
          if: always()
          with:
            name: playwright-report
            path: path/to/playwright/folder/playwright-report/ # update accordingly
            retention-days: 10

- task: PowerShell@2
  enabled: true
  displayName: "Install dependencies"
  inputs:
    targetType: 'inline'
    script: 'npm ci'
    workingDirectory: path/to/playwright/folder # update accordingly

- task: AzureCLI@2
  displayName: Run Playwright Test  
    env:
    PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)
    # PLAYWRIGHT_SERVICE_ACCESS_TOKEN: $(PLAYWRIGHT_SERVICE_ACCESS_TOKEN) # Not recommended, use Microsoft Entra ID authentication. 

  inputs:
    azureSubscription: My_Service_Connection # Service connection used to authenticate this pipeline with Azure to use the service
    scriptType: 'pscore'
    scriptLocation: 'inlineScript'
    inlineScript: |
      npx playwright test -c playwright.service.config.ts --workers=20
  addSpnToEnvironment: true
  workingDirectory: path/to/playwright/folder # update accordingly

- task: PublishPipelineArtifact@1
  displayName: Upload Playwright report
  inputs:
    targetPath: path/to/playwright/folder/playwright-report/ # update accordingly
    artifact: 'Playwright tests'
    publishLocation: 'pipeline'

更新 CI 工作流程定義，以使用 Playwright NUnit CLI 執行 Playwright 測試。傳遞 .runsettings 檔案作為 Playwright CLI 的輸入參數。您可以藉由指定環境變數來設定環境。

開啟 CI 工作流程定義。

新增下列步驟，以在 Microsoft Playwright Testing 中執行 Playwright 測試。

下列步驟說明 GitHub Actions 或 Azure Pipelines 的工作流程變更。同樣地，您也可以在其他 CI 平台中使用 Playwright CLI 來執行 Playwright 測試。

GitHub 動作
Azure Pipelines

on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
permissions: # Required when using AuthType as EntraId
  id-token: write
  contents: read
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
      steps:
      - uses: actions/checkout@v4
    # This step is to sign-in to Azure to run tests from GitHub Action workflow. 
    # Choose how to set up authentication to Azure from GitHub Actions. This is one example. 

      - name: Login to Azure with AzPowershell (enableAzPSSession true) 
        uses: azure/login@v2 
        with: 
          client-id: ${{ secrets.AZURE_CLIENT_ID }} # GitHub Open ID connect values copied in previous steps
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}  
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}  
          enable-AzPSSession: true 

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 8.0.x

      - name: Restore dependencies
        run: dotnet restore
        working-directory: path/to/playwright/folder # update accordingly

      - name: Build
        run: dotnet build --no-restore
        working-directory: path/to/playwright/folder # update accordingly

      - name: Run Playwright tests
          working-directory: path/to/playwright/folder # update accordingly
        env:
          # Regional endpoint for Microsoft Playwright Testing
          PLAYWRIGHT_SERVICE_URL: ${{ secrets.PLAYWRIGHT_SERVICE_URL }}
          # PLAYWRIGHT_SERVICE_ACCESS_TOKEN: ${{ secrets.PLAYWRIGHT_SERVICE_ACCESS_TOKEN }} # Not recommended, use Microsoft Entra ID authentication. 
        run: dotnet test --settings:.runsettings --logger "microsoft-playwright-testing" -- NUnit.NumberOfTestWorkers=20

      - name: Upload Playwright report
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-report
          path: path/to/playwright/folder/playwright-report/ # update accordingly
          retention-days: 10

- task: UseDotNet@2
  inputs:
    packageType: 'sdk'
    version: '8.x'
    installationPath: $(Agent.ToolsDirectory)/dotnet

- checkout: self

- script: dotnet restore
  displayName: 'Restore dependencies'
  workingDirectory: path/to/playwright/folder # update accordingly

- script: dotnet build --no-restore
  displayName: 'Build'
  workingDirectory: path/to/playwright/folder # update accordingly

- task: AzureCLI@2
  displayName: Run Playwright Test  
    env:
    PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)
    # PLAYWRIGHT_SERVICE_ACCESS_TOKEN: $(PLAYWRIGHT_SERVICE_ACCESS_TOKEN) # Not recommended, use Microsoft Entra ID authentication. 

  inputs:
    azureSubscription: My_Service_Connection # Service connection used to authenticate this pipeline with Azure to use the service using Microsoft Entra ID.
    scriptType: 'pscore'
    scriptLocation: 'inlineScript'
    inlineScript: |
      dotnet test --settings:.runsettings --logger "microsoft-playwright-testing" -- NUnit.NumberOfTestWorkers=20
  addSpnToEnvironment: true
  workingDirectory: path/to/playwright/folder # update accordingly

- task: PublishPipelineArtifact@1
  displayName: Upload Playwright report
  inputs:
    targetPath: path/to/playwright/folder/playwright-report/ # update accordingly
    artifact: 'Playwright tests'
    publishLocation: 'pipeline'

儲存並認可您的變更。

觸發 CI 工作流程時，Playwright 測試便會在雲端裝載的瀏覽器上的 Microsoft Playwright Testing 工作區中，跨 20 個平行背景工作角色來執行。收集的結果和成品會發佈至服務，而且可以在服務入口網站上檢視。

測試回合的設定可以在檔案中 .runsettings 定義。如需詳細資訊，請參閱如何使用服務套件選項

注意

預設會針對現有的工作區啟用報告功能。這會分階段推出，需要幾天的時間。若要避免失敗，請先確認工作區的 Rich diagnostics using reporting 設定為 [開啟]，然後再繼續。如需詳細資訊，請參閱啟用工作區的報告。

警告

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

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

您可以使用下列命令列，搭配服務來執行單一測試：

npx playwright test {name-of-file.spec.ts} --config=playwright.service.config.ts

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

您現在可以在 Playwright 入口網站中針對 CI 管線進行疑難解答，

測試回合完成之後，會產生劇作家入口網站的連結。開啟此連結以檢視詳細的測試結果和相關聯的成品。入口網站會顯示基本資訊，包括：
- CI 組建詳細數據
- 整體測試回合狀態
- 連結至測試回合的認可標識碼
Playwright 入口網站提供疑難解答所需的所有資訊。您可以：
- 在重試之間切換。
- 檢視詳細的錯誤記錄、測試步驟和附加成品，例如螢幕快照或影片。
- 直接流覽至 追蹤查看器 以進行更深入的分析。
追蹤查看器可讓您以可視化方式逐步執行測試。您可以：
- 使用時間軸將滑鼠停留在個別步驟上，並顯示每個動作前後的頁面狀態。
- 檢查每個步驟的詳細記錄、DOM 快照集、網路活動、錯誤和控制台輸出。

測試回合完成之後，您會在終端機中取得 Playwright 入口網站的連結。開啟此連結以檢視詳細的測試結果和相關聯的成品。入口網站會顯示基本資訊，包括：
- CI 組建詳細數據
- 整體測試回合狀態
- 連結至測試回合的認可標識碼
Playwright 入口網站提供疑難解答所需的所有資訊。您可以：
- 檢視詳細的錯誤記錄檔，以及附加的成品，例如螢幕快照或影片。
- 直接流覽至 追蹤查看器 以進行更深入的分析。

注意

服務儀錶板上目前不會顯示某些元數據，例如擁有者、描述和類別。如果您想要看到包含的其他資訊，請在我們的存放庫中提交 GitHub 問題。

追蹤查看器可讓您以可視化方式逐步執行測試。您可以：
- 使用時間軸將滑鼠停留在個別步驟上，並顯示每個動作前後的頁面狀態。
- 檢查每個步驟的詳細記錄、DOM 快照集、網路活動、錯誤和控制台輸出。

提示

您可以獨立使用 Microsoft Playwright Testing 服務功能。您可以在不使用雲端裝載瀏覽器功能的情況下，將測試結果發佈至入口網站，您也可以只使用雲端裝載瀏覽器來加速您的測試套件，而不發佈測試結果。如需詳細資訊，請參閱如何使用服務功能。

注意

您發佈的測試結果和成品會在服務上保留 90 天。之後，系統會自動將它們刪除。

您已成功設定持續的端對端測試工作流程，以在雲端裝載的瀏覽器上大規模地執行 Playwright 測試。

向使用者授與工作區的存取權 (部分機器翻譯)
管理工作區 (部分機器翻譯)

共用方式為

快速入門：使用 Microsoft Playwright Testing 預覽版來設定持續的端對端測試

必要條件

取得服務區域端點 URL

新增服務組態檔

更新 package.json 檔案

在 Playwright 設定中啟用成品

設定服務組態

安裝服務套件

新增或更新 `.runsettings` 項目的檔案。

在劇作家設定中啟用成品

設定驗證

使用 Microsoft Entra ID 設定驗證

必要條件

建立 GitHub 祕密

使用存取權杖設定驗證

更新工作流程定義

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

意見反應

其他資源

共用方式為

快速入門：使用 Microsoft Playwright Testing 預覽版來設定持續的端對端測試

必要條件

取得服務區域端點 URL

新增服務組態檔

更新 package.json 檔案

在 Playwright 設定中啟用成品

設定服務組態

安裝服務套件

新增或更新 .runsettings 項目的檔案。

在劇作家設定中啟用成品

設定驗證

使用 Microsoft Entra ID 設定驗證

必要條件

建立 GitHub 祕密

使用存取權杖設定驗證

更新工作流程定義

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

相關內容

意見反應

其他資源

新增或更新 `.runsettings` 項目的檔案。