從 Postman 到 Newman 的 API 自動化測試整合實務

在現代軟體開發生命週期中，API 測試的自動化是提升交付速度與品質的關鍵環節。將手動操作的 Postman 測試遷移至可透過命令行執行的 Newman 工具，不僅解決了重複性的人力耗損，更為測試案例的版本控制與標準化奠定了基礎。此流程的核心在於將測試資產（Collection 與 Environment）程式碼化，使其能無縫地嵌入持續整合與持續交付（CI/CD）的自動化工作流中。當測試成為每次程式碼提交或部署的內建步驟時，團隊便能更早發現潛在問題，降低整合風險，並確保 API 的穩定性與可靠性，進而加速產品迭代並支持 DevOps 文化轉型。

Postman Collection 與環境匯出及 Newman 命令行執行

本節將指導您如何將在 Postman 中創建的 Collection 和 Environment 匯出為 JSON 文件，以便後續使用 Newman 工具在命令行環境中執行這些測試。

匯出 Postman Collection

Postman Collection 匯出功能會生成一個 JSON 文件，其中包含了 Collection 的所有配置、請求定義以及相關的測試腳本。Newman 工具將使用這個 JSON 文件來執行與在 Postman GUI 中相同的測試。

1. 啟動匯出流程:

   • 在 Postman 左側面板中，找到您要匯出的 Collection（例如「DemoBook」）。
   • 點擊 Collection 名稱旁邊的「…」上下文菜單。
   • 選擇「Export」。

2. 配置匯出選項:

   • 在彈出的匯出窗口中，通常會提供不同的 Collection 版本選項。為了確保最大的兼容性，建議選擇較舊的版本，例如 Collection v1 或 Collection v2（請注意，原文中提到「uncheck the Collection v2.1 (recommended) checkbox」，這意味著選擇非 v2.1 版本，具體選擇哪個版本取決於 Newman 的兼容性，通常 v1 或 v2 兼容性較好）。
   • 點擊「Export」按鈕。

3. 保存文件:

   • 系統會提示您選擇保存位置。將匯出的 JSON 文件（例如 DemoBook.postman_collection.json）保存在一個專門用於存放 Newman 測試配置的資料夾中。

匯出 Postman Environment

由於 Collection 中的請求可能依賴於環境變量（如基礎 URL、API Key 等），因此也需要將環境配置匯出。

1. 進入 Environments 視圖:

   • 在 Postman 左側面板中，點擊「Environments」選項。

2. 匯出單個環境:

   • 找到您要匯出的環境（例如「Local」）。
   • 點擊該環境名稱旁邊的「Export」按鈕。
   • 同樣，選擇一個兼容的版本（通常是 v1 或 v2），然後點擊「Export」。
   • 將匯出的環境 JSON 文件（例如 Local.postman_environment.json）保存在與 Collection 相同的資料夾中。

3. 重複匯出其他環境:

   • 對您使用的所有其他環境（例如「QA」）重複上述步驟，將它們各自的 JSON 文件也保存在同一個資料夾。

完成這些步驟後，您的專用資料夾中將包含 Collection 的 JSON 文件和每個環境的 JSON 文件。

運行 Newman 命令行

有了匯出的 Collection 和 Environment 文件後，就可以使用 Newman 在命令行中執行測試了。

1. 打開終端機:

   • 啟動您的終端機或命令提示符。

2. 導航至配置資料夾:

   • 使用 cd 命令切換到您保存 Collection 和 Environment JSON 文件的資料夾。

3. 執行 Newman 命令:

   • 使用 newman run 命令，並指定 Collection 文件和環境文件作為參數。
   • 基本語法如下：

   newman run <collection_file.json> -e <environment_file.json>
   

   • 例如，如果您匯出的 Collection 文件名為 DemoBook.postman_collection.json，Local 環境文件為 Local.postman_environment.json，則命令為：

   newman run DemoBook.postman_collection.json -e Local.postman_environment.json
   

   • -e 參數用於指定要使用的環境文件。

Newman 會讀取指定的 Collection 文件，並使用指定的環境文件中的變量來執行 Collection 中的所有請求和測試。執行結果（包括測試通過/失敗情況）將直接顯示在終端機中。

視覺化 Postman 匯出與 Newman 執行流程

以下圖示展示了 Postman Collection 和 Environment 的匯出過程，以及如何使用 Newman 在命令行中執行這些匯出的配置。

@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

title Postman Export & Newman CLI Execution Flow

package "Postman GUI" {
  component "Collections" as POSTMAN_COLLECTIONS
  component "Environments" as POSTMAN_ENVIRONMENTS
  artifact "Export Collection Action" as EXPORT_COLLECTION_ACTION
  artifact "Export Environment Action" as EXPORT_ENV_ACTION
}

package "Exported Files" {
  artifact "Collection JSON (.json)" as COLLECTION_JSON
  artifact "Environment JSON (.json)" as ENVIRONMENT_JSON
}

package "Newman CLI" {
  artifact "Terminal/Command Prompt" as TERMINAL
  artifact "Newman Run Command" as NEWMAN_RUN_CMD
  artifact "Execution Results" as EXECUTION_RESULTS
}

artifact "API Endpoint" as API_ENDPOINT

POSTMAN_COLLECTIONS --> EXPORT_COLLECTION_ACTION : User initiates export
EXPORT_COLLECTION_ACTION --> COLLECTION_JSON : Generates collection configuration file

POSTMAN_ENVIRONMENTS --> EXPORT_ENV_ACTION : User initiates export
EXPORT_ENV_ACTION --> ENVIRONMENT_JSON : Generates environment configuration file

COLLECTION_JSON --> TERMINAL : Saved in a dedicated folder
ENVIRONMENT_JSON --> TERMINAL : Saved in the same folder

TERMINAL --> NEWMAN_RUN_CMD : User types command (newman run ... -e ...)
NEWMAN_RUN_CMD --> COLLECTION_JSON : Reads collection configuration
NEWMAN_RUN_CMD --> ENVIRONMENT_JSON : Reads environment variables

NEWMAN_RUN_CMD --> API_ENDPOINT : Executes API requests based on config
NEWMAN_RUN_CMD --> EXECUTION_RESULTS : Displays test outcomes in terminal

note right of POSTMAN_COLLECTIONS
  User creates and configures
  tests interactively.
end note

note left of COLLECTION_JSON
  JSON files containing
  all test configurations.
end note

note right of TERMINAL
  Automated execution of
  Postman tests via command line.
end note

@enduml

看圖說話：

此圖示展示了將 Postman 的測試配置匯出，並使用 Newman 在命令行中執行的完整流程。

首先，在 Postman GUI 中，用戶會對 Collections 和 Environments 進行操作。通過「Export Collection Action」和「Export Environment Action」，用戶將這些配置匯出，生成相應的 Collection JSON 和 Environment JSON 文件。這些文件被保存在一個專門的資料夾中，作為後續自動化測試的基礎。

接著，流程轉移到 Newman CLI 環境。用戶打開 Terminal/Command Prompt，並在保存了 JSON 文件的資料夾中，輸入 Newman Run Command（例如 newman run collection.json -e environment.json）。

Newman 命令會讀取指定的 Collection JSON 文件和 Environment JSON 文件。它利用這些配置信息，向 API Endpoint 發送請求，執行測試，並將最終的 Execution Results（測試通過/失敗狀態、響應時間等）顯示在終端機中。這個流程實現了 Postman 測試的自動化執行，是將測試集成到 CI/CD 管道的關鍵步驟。

Newman 整合 CI/CD 管道：實現自動化 API 測試

本節將深入探討如何將 Newman 工具無縫整合到持續整合與持續交付 (CI/CD) 的管道流程中，以實現 API 測試的完全自動化。

Newman 執行結果與錯誤處理

當 Newman 在命令行中運行時，它會詳細報告每個請求的執行情況和測試結果。

• 成功執行: 如果所有測試都通過，Newman 會顯示一個清晰的成功標誌，並可能匯總執行時間和通過的測試數量。
• 測試失敗: 如果任何一個測試腳本未能通過，Newman 會用紅色標記標示失敗的測試，並提供失敗的具體原因以及預期的結果。這對於快速定位和修復 API 中的問題至關重要。

將 Newman 整合至 CI/CD 管道

Newman 的命令行特性使其非常適合整合到自動化構建和部署流程中。以下是將 Newman 整合到 CI/CD 管道的基本步驟：

1. 準備項目結構:

   • 創建一個專用的資料夾，其中包含從 Postman 匯出的 Collection JSON 文件、Environment JSON 文件。
   • 在此資料夾中，創建一個 package.json 文件。這個文件將定義項目依賴（包括 Newman）以及用於執行測試的腳本。

2. 配置 package.json:

   • 在 package.json 的 scripts 部分，定義用於運行 Newman 的命令。每個腳本可以對應一個特定的環境或測試場景。
   • 例如：

     {
       "name": "api-testing",
       "version": "1.0.0",
       "scripts": {
         "test:local": "newman run DemoBook.postman_collection.json -e Local.postman_environment.json -r junit,cli --reporter-junit-export results-local.xml",
         "test:qa": "newman run DemoBook.postman_collection.json -e QA.postman_environment.json -r junit,cli --reporter-junit-export results-qa.xml"
       },
       "devDependencies": {
         "newman": "^5.3.0" // 指定 Newman 版本
       }
     }
     

     • newman run: 啟動 Newman 執行。
     • <collection_file.json>: 指定要運行的 Collection 文件。
     • -e <environment_file.json>: 指定要使用的環境文件。
     • -r junit,cli: 指定報告格式，這裡同時輸出 JUnit 格式和命令行格式。
     • --reporter-junit-export <filename.xml>: 指定 JUnit 報告的輸出文件名。
   • 在 devDependencies 部分，列出 newman 作為項目依賴。

3. 版本控制:

   • 將包含所有 JSON 文件和 package.json 的項目資料夾提交到一個版本控制系統（如 Git）。這確保了 CI/CD 系統可以訪問到這些測試配置。

4. 配置 CI/CD 管道 (以 Azure Pipelines 為例):

   • 創建 Build Definition:
     • 設置一個構建任務，用於從版本控制系統簽出代碼。
     • 添加一個任務來將包含測試配置的資料夾（包括 JSON 文件和 package.json）作為構建產物（Artifacts）發布。
     • 啟用持續集成 (CI) 觸發器，以便在代碼提交時自動觸發構建。
   • 創建 Release Definition:
     • 配置一個發布管道，該管道將使用構建階段產生的 Artifacts。
     • 創建不同的 Stage（階段），例如「DEV」和「QA」，分別對應不同的部署環境。
     • 在每個 Stage 中，配置一系列任務來執行 Newman 測試：
       1. Install Newman: 使用 npm install 命令來安裝 package.json 中定義的 Newman 依賴。
       2. Run Newman: 執行 npm run <script_name> 命令（例如 npm run test:local 或 npm run test:qa），來運行 Newman 腳本。
       3. Publish Test Results: 配置一個任務來解析 Newman 生成的 JUnit 報告（.xml 文件），並將測試結果發布到 CI/CD 平台的可視化界面中。這使得開發者可以直觀地看到每次構建或部署的測試狀態。

視覺化 CI/CD 管道整合流程

以下圖示展示了 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

title Newman Integration into CI/CD Pipeline

package "Source Control (Git)" {
  artifact "Repository" as REPO
  artifact "Test Config Files (.json, package.json)" as TEST_CONFIG_FILES
}

package "CI Server (e.g., Azure Pipelines)" {
  component "Build Pipeline" as BUILD_PIPELINE
  component "Release Pipeline" as RELEASE_PIPELINE

  artifact "Build Artifacts" as BUILD_ARTIFACTS
}

package "Execution Environment" {
  artifact "Node.js Runtime" as NODE_RUNTIME
  artifact "Newman CLI" as NEWMAN_CLI
}

package "Testing & Reporting" {
  artifact "API Endpoint" as API_ENDPOINT
  artifact "Test Reports (XML)" as TEST_REPORTS_XML
}

artifact "CI/CD Platform UI" as CI_CD_UI

REPO --> BUILD_PIPELINE : Trigger Build
TEST_CONFIG_FILES --> REPO : Committed to repository

BUILD_PIPELINE --> TEST_CONFIG_FILES : Check out code
BUILD_PIPELINE --> BUILD_ARTIFACTS : Publish test files

BUILD_ARTIFACTS --> RELEASE_PIPELINE : Used by Release Stages

RELEASE_PIPELINE --> NODE_RUNTIME : Installs Node.js
RELEASE_PIPELINE --> NEWMAN_CLI : Installs Newman (via npm install)
RELEASE_PIPELINE --> API_ENDPOINT : Executes Newman commands
RELEASE_PIPELINE --> TEST_REPORTS_XML : Generates test reports

TEST_REPORTS_XML --> CI_CD_UI : Publish results for visualization

note right of CI_CD_UI
  Provides dashboards for
  build/release status,
  test results.
end note

@enduml

看圖說話：

此圖示詳細展示了 Newman 如何被整合到 CI/CD 管道的整個生命週期中。

流程始於 Source Control (Git)，開發者將包含 Postman Collection JSON、Environment JSON 和 package.json 的測試配置文件提交到 Repository。

當代碼變更觸發 CI Server (e.g., Azure Pipelines) 的 Build Pipeline 時，代碼會被簽出。構建階段的主要任務是將這些測試配置文件打包成 Build Artifacts 並發布。

隨後，Release Pipeline 會獲取這些構建產物。在發布管道的執行環境中，首先需要確保 Node.js Runtime 可用，並通過 npm install 安裝 Newman CLI。

Newman CLI 接著會被調用，它會讀取測試配置文件，並向 API Endpoint 發送請求執行測試。測試執行後，會生成 Test Reports (XML)。

最後，這些測試報告會被發布到 CI/CD Platform UI，例如 Azure Pipelines 的儀表板上。這使得團隊成員能夠直觀地查看每次構建或發布的測試狀態，從而快速發現和解決潛在問題，確保軟體品質。

結論

從提升團隊績效與確保交付品質的維度來看，將零散的手動 API 驗證，轉化為整合於 CI/CD 流程中的系統性自動化測試，是現代軟體開發團隊成熟度的關鍵指標。這不僅是工具鏈的導入，更是將品質責任內建於開發文化中的核心實踐。

此整合路徑的價值，在於將品質驗證從開發週期的末端，前移至每次程式碼提交的即時回饋點，實現了真正的「左移測試」。然而，其挑戰亦不容忽視：初期需投入資源建構與維護穩健的測試集，且團隊成員必須具備跨職能的協作紀律，以防自動化腳本淪為新的技術債。相較於傳統 QA 模式，此法雖增加了前期的建置成本，卻能大幅降低後期修復缺陷的隱性代價，實現更可預測的交付節奏。

未來2至3年，這類「品質即程式碼」(Quality as Code) 的實踐將從領先團隊普及為業界標準，測試工程師的角色也將更偏向於設計自動化策略與維護測試基礎設施。

玄貓認為，對於追求卓越工程文化的團隊而言，導入此自動化測試流程是戰略性的必要投資。建議優先從核心業務功能的 API 開始，逐步建立起堅實的品質安全網，這將是釋放團隊開發潛能、加速價值交付的最有效路徑。