整合 Newman 於 CI/CD 實現 API 自動化測試

– 6 分鐘閱讀

在現代軟體開發生命週期中，API 已成為系統間溝通的核心骨幹。為確保其功能正確性與穩定性，自動化測試是不可或缺的一環。本文將探討如何從手動的 API 驗證，進階到自動化的測試流程。我們將以 Postman 作為測試腳本的開發平台，並利用其命令行工具 Newman 將這些測試腳本轉化為可在任何環境中執行的自動化任務。此方法的關鍵價值在於能夠將 API 測試無縫整合至 CI/CD 管道，例如 Azure Pipelines 或 GitHub Actions。透過在每次程式碼提交後自動觸發測試，開發團隊能即時發現並修復問題，從而實現持續整合與持續交付的核心目標，確保產品的快速迭代與高品質交付。

API 自動化測試與 CI/CD 整合：Newman 實踐指南

深入解析 Newman 的核心概念與應用，學習如何為 Newman 準備 Postman Collection 和環境，並透過命令行執行 API 測試。重點探討如何將 Newman 整合到 CI/CD 管道中，實現 API 自動化測試的流程化與效率提升

本節將聚焦於 API 自動化測試的關鍵工具——Newman。我們將深入解析 Newman 的核心概念，理解它如何作為 Postman Collection 的命令行運行器。隨後，我們將學習如何為 Newman 準備所需的 Postman Collection 和環境文件，並通過命令行執行這些測試。最後，我們將重點講解如何將 Newman 整合到 CI/CD 管道中，實現 API 自動化測試的流程化與效率提升，從而確保應用程式的品質與穩定性。

Newman：Postman Collection 的命令行運行器

Newman 是 Postman 的一個開源命令行介面（CLI）運行器，它允許您在本地或 CI/CD 環境中執行 Postman Collection。

  1. Newman 的核心概念:

    • 命令行執行: 與 Postman 應用程式不同，Newman 直接在終端或腳本中運行。
    • 自動化測試: 能夠執行 Postman Collection 中定義的所有請求和測試腳本。
    • 報告生成: 可以生成多種格式的測試報告，方便查看測試結果。
    • CI/CD 整合: 非常適合集成到自動化構建和部署流程中。

  2. 安裝 Newman:

    • Newman 是基於 Node.js 的工具，需要先安裝 Node.js 和 npm（Node Package Manager）。
    • 全局安裝: 
      npm install -g newman
      全局安裝後，您可以在任何目錄下直接運行 newman 命令。

  3. 為 Newman 準備 Postman Collection:

    • 導出 Collection: 在 Postman 應用程式中，右鍵點擊您想要導出的 Collection，選擇「Export」。選擇一個合適的格式（通常是預設的 JSON 格式）。將導出的 .json 文件保存到您的專案中。
    • 導出環境 (Environment): 如果您的 Collection 使用了環境變數，您也需要導出相應的環境文件。
      1. 在 Postman 中，點擊右上角的齒輪圖標，選擇「Manage Environments」。
      2. 選擇您要導出的環境，點擊「Export」。
      3. 將導出的 .json 文件保存到您的專案中。

在命令行執行 Newman 測試

準備好 Collection 和環境文件後，就可以使用 Newman 在命令行執行 API 測試了。

  1. 運行 Newman 命令:

    • 基本命令: 
      newman run <collection.json>
      這將執行指定的 Collection，並在控制台中顯示基本的測試結果。
    • 指定環境: 
      newman run <collection.json> -e <environment.json>
      使用 -e 或 --environment 參數指定要使用的環境文件。
    • 指定報告格式: 
      newman run <collection.json> -e <environment.json> --reporters cli,junit --reporter-junit-export report.xml
      • --reporters: 指定要使用的報告器。cli 是默認的命令行報告器，junit 可以生成 JUnit 格式的報告，適合 CI/CD 系統解析。
      • --reporter-junit-export: 指定 JUnit 報告的輸出文件。
    • 其他常用選項:
      • -g <global.json>: 指定全局變量文件。
      • --folder <folder-name>: 只運行 Collection 中的特定文件夾。
      • --iteration-count <number>: 指定運行 Collection 的次數。
      • --delay <ms>: 在每次請求之間添加延遲。

  2. 理解測試結果:

    • Newman 會在執行過程中顯示每個請求的狀態（通過、失敗）以及總體的測試統計信息。
    • JUnit 報告文件可以被 Jenkins, Azure Pipelines, GitHub Actions 等 CI/CD 工具解析，用於展示測試結果和構建狀態。

將 Newman 整合到 CI/CD 管道

將 Newman 集成到 CI/CD 管道是實現 API 自動化測試的標準實踐，確保每次代碼變更都能觸發 API 測試。

  1. CI/CD 管道配置:

    • 選擇 CI/CD 工具: 如 Azure Pipelines, GitHub Actions, Jenkins, GitLab CI 等。
    • 管道步驟:
      1. Checkout 程式碼: 從版本控制系統獲取最新的應用程式代碼和測試腳本。
      2. 構建應用程式: 編譯代碼，構建 Docker 映像檔，或部署應用程式到測試環境。
      3. 部署到測試環境: 將應用程式部署到一個臨時的測試環境，確保 API 可訪問。
      4. 運行 Newman 測試: 在測試環境準備就緒後，執行 newman run 命令。
      5. 解析測試報告: CI/CD 工具解析 Newman 生成的報告（如 JUnit 報告），並根據測試結果決定構建是否成功。
      6. 發布報告: 將測試報告作為構建的產物發布，方便查看。
      7. 後續階段: 如果 API 測試通過，則可以觸發後續的 CD 階段，如部署到預生產或生產環境。

  2. 管道執行範例 (以 Azure Pipelines 為例):

    • 在 azure-pipelines.yml 文件中添加一個任務來運行 Newman： 
      - task: Npm@1
  displayName: 'Install Newman'
  inputs:
    command: 'install'
    workingDir: '$(System.DefaultWorkingDirectory)'
    verbose: true
    customCommand: 'install -g newman' # 全局安裝 newman

- task: Bash@3
  displayName: 'Run Newman API Tests'
  inputs:
    targetType: 'inline'
    script: |
      # 確保你的 collection.json 和 environment.json 在工作目錄中
      newman run $(Build.SourcesDirectory)/path/to/your/collection.json \
        --environment $(Build.SourcesDirectory)/path/to/your/environment.json \
        --reporters cli,junit \
        --reporter-junit-export $(Build.ArtifactStagingDirectory)/report.xml
      # 設置 newman 退出代碼，以便管道能夠正確識別測試失敗
      # 如果 newman 運行失敗，退出代碼將非零
      exit 0 # 總是退出 0，讓 Azure Pipelines 處理 JUnit 報告

- task: PublishTestResults@2
  displayName: 'Publish API Test Results'
  inputs:
    testResultsFormat: 'JUnit'
    testResultsFiles: '$(Build.ArtifactStagingDirectory)/report.xml'
    mergeTestResults: true
    failTaskOnFailedTests: true # 如果有測試失敗，則此任務將失敗，整個管道將標記為失敗
    • 關鍵點:
      • 確保 Newman 已在管道代理上安裝。
      • 正確指定 Collection 和 Environment 文件的路徑。
      • 使用 junit 報告器並將報告輸出到 CI/CD 工具可訪問的位置。
      • 配置 failTaskOnFailedTests: true 以便在 API 測試失敗時，整個構建流程停止。

Newman 整合 CI/CD 流程圖示

@startuml
!define DISABLE_LINK
!define PLANTUML_FORMAT svg
!theme _none_

skinparam dpi auto
skinparam shadowing false
skinparam linetype ortho
skinparam roundcorner 5
skinparam defaultFontName "Microsoft JhengHei UI"
skinparam defaultFontSize 16
skinparam minClassWidth 100

start

partition "API 自動化測試與 CI/CD 整合" {
  partition "準備階段" {
    :1. 在 Postman 中編寫 API 請求與測試;
    :2. 導出 Collection (.json);
    :3. 導出 Environment (.json);
    :4. 安裝 Newman (npm install -g newman);
  }

  partition "CI/CD 管道執行" {
    partition "CI 階段" {
      :5. 程式碼簽入觸發管道;
      :6. 獲取最新程式碼與測試文件;
      :7. 構建與部署應用程式到測試環境;
    }
    partition "API 測試階段" {
      :8. 執行 Newman 測試命令;
      :   `newman run collection.json -e environment.json --reporters cli,junit --reporter-junit-export report.xml`;
      :9. Newman 執行 Collection 中的所有請求與測試;
      :10. 生成 JUnit 測試報告 (report.xml);
    }
    partition "結果處理與部署" {
      :11. CI/CD 工具解析 JUnit 報告;
      :12. 根據測試結果決定構建狀態 (Pass/Fail);
      :13. 發布測試報告作為構建產物;
      :14. 若測試通過，觸發 CD 階段 (部署到 Staging/Production);
    }
  }
}

stop

@enduml

看圖說話：

此圖示清晰地展示了如何將 API 自動化測試整合到 CI/CD 流程中，核心是利用 Newman 工具。開頭的「準備階段」列出了在 Postman 中完成測試並導出 Collection 和 Environment 的必要步驟，以及安裝 Newman 的命令。圖示的主體「CI/CD 管道執行」部分，將整個流程分解為 CI、API 測試和結果處理與部署三個階段。在 CI 階段，完成程式碼獲取和應用部署。隨後，「API 測試階段」展示了 Newman 命令的執行，包括指定 Collection、Environment 和報告生成。最後，「結果處理與部署」階段說明了 CI/CD 工具如何解析 JUnit 報告，判斷構建狀態，並基於測試結果觸發後續的部署流程。這張圖有效地呈現了自動化 API 測試在現代軟體開發中的關鍵作用。

結論

縱觀現代軟體開發的高效能要求，將 Newman 整合至 CI/CD 管道不僅是技術工具的導入，更是品質管理思維的策略性躍升。此方法將 API 測試從孤立的手動驗證環節，轉化為開發流程中內建的、自動化的品質閘門，其核心價值在於將潛在風險在生命週期的最早階段暴露並解決。

相較於傳統的後期整合測試，此模式雖在初期需投入資源建構測試腳本與環境，但其帶來的即時回饋循環與持續性的品質監控，能顯著降低後期修復的巨大成本與時間壓力。真正的挑戰不在於工具的學習，而在於團隊是否能將測試腳本視為一等公民，建立起與應用程式碼同等重要的維護與審查文化。

展望未來，這套自動化測試基礎將是實踐更進階品質工程，如契約測試（Contract Testing）與混沌工程（Chaos Engineering）的穩固基石。對於追求卓越工程文化與穩定交付能力的團隊而言，這套整合實踐已非選項，而是確保產品競爭力與團隊效能的關鍵基礎建設。

玄貓

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。