分享方式:


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

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

完成本快速入門之後,您會獲得一個 CI 工作流程,其會使用 Microsoft Playwright Testing 大規模地執行 Playwright 測試套件。

重要

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

必要條件

  • GitHub 帳戶。 如果您沒有 GitHub 帳戶,您可免費建立帳戶
  • GitHub 存放庫,其中包含您的 Playwright 測試規格和 GitHub Actions 工作流程。 若要建立存放庫,請參閱建立新的存放庫 (英文)。
  • GitHub Actions 工作流程。 如果您需要協助以便開始使用 GitHub Actions,請參閱建立您的第一個工作流程 (英文)

設定服務的存取權杖

Microsoft Playwright Testing 會使用存取權杖來授權使用者使用該服務執行 Playwright 測試。 您可以在 Playwright 入口網站中產生服務的存取權杖,然後在服務組態檔中指定該存取權杖。

若要產生存取權杖,並將其儲存為 CI 工作流程祕密,請執行下列步驟:

  1. 使用您的 Azure 帳戶登入 Playwright 入口網站 (英文)。

  2. 選取工作區設定圖示,然後移至 [存取權杖] 頁面。

    螢幕擷取畫面:顯示 Playwright Testing 入口網站中的存取權杖設定頁面。

  3. 選取 [產生新權杖],為您的 CI 工作流程建立新的存取權杖。

  4. 輸入存取權杖的詳細資料,然後選取 [產生權杖]

    螢幕擷取畫面:顯示 Playwright Testing 入口網站中的設定指南,其中醒目提示 [產生權杖] 按鈕。

    螢幕擷取畫面:顯示如何在 Playwright Testing 入口網站中複製所產生的存取權杖。

  5. 將存取權杖儲存在 CI 工作流程秘密中,以避免在工作流程定義中以純文字指定權杖:

    1. 移至您的 GitHub 存放庫,然後選取 [設定]>[秘密和變數]>[動作]

    2. 選取 [新增存放庫祕密]。

    3. 輸入秘密的詳細資料,然後選取 [新增秘密] 以建立 CI/CD 秘密。

      參數
      名稱 PLAYWRIGHT_SERVICE_ACCESS_TOKEN
      貼上您先前複製的工作區存取權杖。
    4. 選取 [確定] 以建立工作流程祕密。

取得服務區域端點 URL

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

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

  1. 使用您的 Azure 帳戶登入 Playwright 入口網站 (英文)。

  2. 在工作區首頁上,選取 [檢視設定指南]

    提示

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

  3. 在 [在設定中新增區域端點] 中,複製服務端點 URL。

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

  4. 將服務端點 URL 儲存在 CI 工作流程秘密中:

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

新增服務組態檔

如果您尚未設定 Playwright 測試,以在雲端裝載的瀏覽器上執行這些測試,請將服務組態檔新增至您的存放庫。 在下一個步驟中,您接著會在 Playwright CLI 上指定此服務組態檔。

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

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

  2. 將下列內容新增至其中:

    /*
    * 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 : [{}]
    });
    
  3. 將檔案儲存並認可至您的原始程式碼存放庫。

更新工作流程定義

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

  1. 開啟 CI 工作流程定義

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

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

    - 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:
        # Access token and regional endpoint for Microsoft Playwright Testing
        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 }}
      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
    
  3. 儲存並認可您的變更。

    觸發 CI 工作流程時,Playwright 測試便會在雲端裝載的瀏覽器上的 Microsoft Playwright Testing 工作區中,跨 20 個平行背景工作角色來執行。

警告

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

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

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

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

啟用測試結果報告

Microsoft Playwright Testing 現在支援在 Playwright 入口網站中檢視測試結果。 在預覽期間,只有獲得邀請才能存取。

重要

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

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

  1. 從工作區首頁,瀏覽至 [設定]

    螢幕擷取畫面:顯示 Playwright Testing 入口網站中的工作區設定選取。

  2. 從 [設定] 中,選取 [一般],並確定報告 [已啟用]

    螢幕擷取畫面:顯示如何在 Playwright Testing 入口網站中啟用工作區的報告。

  3. 遵循下列步驟,以建立 GitHub 個人存取權杖。

    您必須向權杖提供 read:packages 權限。 本文其餘部分將此權杖稱為 PAT_TOKEN_PACKAGE

  4. 將 GitHub 權杖儲存在 CI 工作流程秘密中,以避免在工作流程定義中以純文字指定權杖:

    1. 移至您的 GitHub 存放庫,然後選取 [設定]>[秘密和變數]>[動作]

    2. 選取 [新增存放庫祕密]。

    3. 輸入秘密的詳細資料,然後選取 [新增秘密] 以建立 CI/CD 秘密。

      參數
      名稱 PAT_TOKEN_PACKAGE
      貼上您先前複製的工作區存取權杖。
    4. 選取 [確定] 以建立工作流程祕密。

  5. 使用套件更新 package.json 檔案。

        "dependencies": {
            "@microsoft/mpt-reporter": "0.1.0-22052024-private-preview"
        }
    
  6. 更新 Playwright 組態檔。

    以使用其他報告程式的相同方式,將 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',
        }
    
  7. 先更新 CI 工作流程定義以安裝報告套件,再執行測試以在 Microsoft Playwright Testing 中發佈 Playwright 測試的報告。

    - name: Install reporting package
      working-directory: path/to/playwright/folder # update accordingly
      run: |
        npm config set @microsoft:registry=https://npm.pkg.github.com
        npm set //npm.pkg.github.com/:_authToken ${{secrets.PAT_TOKEN_PACKAGE}} 
        npm install
    
    - name: Run Playwright tests
      working-directory: path/to/playwright/folder # update accordingly
      env:
        # Access token and regional endpoint for Microsoft Playwright Testing
        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 }}
      run: npx playwright test
    

    提示

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

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