Apache JMeter 使用教學手冊

版本：v1.1（已完成第 1-16 章與附錄 A-E；持續維護優化）
最後更新：2026-02-12（對應 JMeter 5.6.3 版本）
適用對象：完全未接觸過效能測試 / JMeter 的新進開發與測試人員
文件目標：協助 1~2 天內快速具備撰寫並執行基本壓力測試腳本的能力，並建立後續進階自學基礎。

快速導讀

若你是第一次接觸 JMeter，建議依序閱讀：

1. Part 1（必讀）：了解 JMeter 是什麼、安裝、基礎 GUI 操作。
2. Part 2：學會設計一個可維護的測試計畫（參數化、控制器、Assertion）。
3. Part 3：掌握報表分析與常見最佳實務（非 GUI、分散式、效能瓶頸初步診斷）。
4. Part 4：實戰情境（API / Web / DB / 企業案例）。
5. Part 5：若需考 JMeter 認證或建置團隊基準能力。
6. 附錄：錯誤排除、報告範本、學習資源、Checklist。

目錄（Table of Contents）

Part 1. 基礎入門（Ch.1-3）

• 1. JMeter 簡介

  • 1.1 JMeter 的定位與用途
  • 1.2 常見測試類型
  • 1.3 與其他工具比較
  • 1.4 概念流程圖
  • 1.5 本章實務案例
  • 1.6 注意事項（初學者常犯）

• 2. 安裝與環境設定

  • 2.1 系統需求
  • 2.2 下載來源
  • 2.3 安裝流程
  • 2.4 目錄結構
  • 2.5 常見安裝問題
  • 2.6 調整啟動參數
  • 2.7 本章實務練習
  • 2.8 注意事項

• 3. JMeter 使用者介面 (GUI)

  • 3.1 元件總覽
  • 3.2 建立第一個測試計畫（Hello HTTP）
  • 3.3 儲存與版本控管
  • 3.4 GUI 效能使用守則
  • 3.5 Mermaid：基本測試計畫組成
  • 3.6 本章實務練習
  • 3.7 常見初階錯誤
  • 3.8 小結

Part 2. 測試計畫設計（Ch.4-7）

• 4. 測試計畫基礎

  • 4.1 目標與原則
  • 4.2 命名規範建議
  • 4.3 推薦資料夾結構
  • 4.4 Mermaid：資源關聯示意
  • 4.5 Thread Group 策略
  • 4.6 API 測試模板（可複製）
  • 4.7 指標定義（在 README 或測試說明中標準化）
  • 4.8 Include Controller 與 Test Fragment 模組化
  • 4.9 變數與屬性作用域（預告）
  • 4.10 Mermaid：執行流程（含變數注入）
  • 4.11 非 GUI 執行模板指令
  • 4.12 實務練習
  • 4.13 常見錯誤與陷阱
  • 4.14 小結

• 5. 參數化與資料驅動測試

  • 5.1 為什麼需要參數化
  • 5.2 變數來源一覽
  • 5.3 CSV Data Set Config 深入
  • 5.4 User Defined Variables vs Properties
  • 5.5 Correlation（動態值提取）
  • 5.6 API 回應範例與抽取
  • 5.7 函數助手（Functions）常用清單
  • 5.8 變數覆蓋與優先序（邏輯觀念）
  • 5.9 Groovy / JSR223 活用
  • 5.10 非 GUI 參數覆寫技巧
  • 5.11 常見錯誤與排除
  • 5.12 實務練習
  • 5.13 小結

• 6. 控制器與流程控制 (Logic Controllers)

  • 6.1 控制器分類概覽
  • 6.2 Loop / While / ForEach 差異
  • 6.3 If / Switch / Runtime Controller
  • 6.4 Throughput Controller 與場景比例
  • 6.5 Transaction Controller 與聚合分析
  • 6.6 Module / Include Controller 模組化
  • 6.7 Flow Control Action 中斷與暫停
  • 6.8 控制器選擇決策矩陣
  • 6.9 常見 Anti-pattern 與重構
  • 6.10 綜合實務案例
  • 6.11 練習
  • 6.12 小結

• 7. Assertion 斷言與結果驗證策略

  • 7.1 為什麼需要明確斷言策略
  • 7.2 常見 Assertion 類型比較
  • 7.3 狀態碼與錯誤分類
  • 7.4 JSON / 正則 / XPath / Size 使用情境
  • 7.5 Duration / SLA 與 P95 判讀
  • 7.6 動態門檻 Baseline / Properties
  • 7.7 失敗策略：Fail Fast vs 收集模式
  • 7.8 減少斷言開銷的最佳實務
  • 7.9 錯誤訊息標準化
  • 7.10 實務案例：登入 + 查詢 + 下單
  • 7.11 練習
  • 7.12 小結

Part 3. 進階應用（Ch.8-10）

• 8. 報表與結果分析

  • 8.1 核心指標再回顧
  • 8.2 Summary / Aggregate Report 差異
  • 8.3 HTML Dashboard 產出與指標
  • 8.4 百分位數 Percentile 判讀策略
  • 8.5 Error 分類與來源拆解
  • 8.6 建立 Baseline 與版本對比流程
  • 8.7 異常模式（Pattern）辨識
  • 8.8 Active Threads 與 Throughput 關聯
  • 8.9 實務指標判讀工作表
  • 8.10 自動化輸出建議
  • 8.11 小結

• 效能最佳實務

  • 9.1 Thread 數 vs RPS (Requests Per Second) 推估
  • 9.2 升壓模式與-ramp-up-策略
  • 9.3 暖機-warm-up-與資料清洗
  • 9.4 減少腳本端資源干擾
  • 9.5 測試資料生命週期與汙染防護
  • 9.6 脚本組織與模組化回顧
  • 9.7 系統資源觀測建議 (外部協同)
  • 9.8 性能退化-regression-早期偵測
  • 9.9 GC 與 JVM 觀察（若系統為 JVM）
  • 9.10 常見瓶頸快速定位路徑
  • 9.11 測試環境一致性與可重複性
  • 9.12 anti-pattern-與改進建議
  • 9.13 小結

• 10. CI/CD 與自動化整合

  • 10.1 測試類型在 Pipeline 的定位
  • 10.2 非 GUI 執行標準化腳本
  • 10.3 退出碼策略 Exit Code Policy
  • 10.4 基準值 Baseline 檔與差異比較
  • 10.5 GitHub Actions 範例 (Smoke Performance)
  • 10.6 Jenkins Pipeline 範例
  • 10.7 多環境參數化與組態管理
  • 10.8 Artifacts 與報告留存策略
  • 10.9 Baseline 自動更新準則
  • 10.10 測試分層在 Pipeline 的選擇
  • 10.11 常見整合問題與排除
  • 10.12 小結

Part 4. 專案實戰（Ch.11-13）

• 11. API 實戰案例

  • 11.1 場景拆解與使用者行為模型
  • 11.2 測試計畫結構範例
  • 11.3 Correlation 與資料流
  • 11.4 測試資料策略
  • 11.5 控制器設計與比例實現
  • 11.6 SLA 與 Assertions 範例
  • 11.7 交易 Transaction 分析
  • 11.8 失敗恢復與重試策略
  • 11.9 定時器 Timer 與節奏 Pacing
  • 11.10 報表截取與指標彙整模板
  • 11.11 常見錯誤與排查清單（本案例）
  • 11.12 小結

• 12. Web / 前端資源載入

  • 12.1 瀏覽器 vs JMeter 差異
  • 12.2 靜態資源測試策略
  • 12.3 Cache 與條件式請求模擬
  • 12.4 GZIP / Brotli 壓縮觀察
  • 12.5 SPA (Single Page App) API 測試
  • 12.6 下載資源組合測試範例
  • 12.7 資源異常與退化判斷
  • 12.8 與前端效能工具協同
  • 12.9 報表與度量聚合
  • 12.10 小結

• 13. 資料庫 / 第三方整合

  • 13.1 JDBC Sampler 基礎
  • 13.2 連線池 (Connection Pool) 考量
  • 13.3 查詢分類與指標
  • 13.4 慢查詢模擬與觀測
  • 13.5 測試資料與回滾策略
  • 13.6 外部依賴模擬 Stub / Mock
  • 13.7 佇列 / 非同步行為測試
  • 13.8 整合指標交叉分析
  • 13.9 與後端團隊協同流程
  • 13.10 小結

Part 5. 認證與進階知識（Ch.14-16）

• 14. 認證考試重點

  • 14.1 主題分佈映射
  • 14.2 必背術語速覽
  • 14.3 高頻陷阱類型
  • 14.4 模擬測驗檢查清單
  • 14.5 考前 24 小時節奏
  • 14.6 Flash Cards（示例）
  • 14.7 小結

• 15. 題庫與解析框架

  • 15.1 題型分類維度
  • 15.2 題目 YAML 標準
  • 15.3 解析四段式框架
  • 15.4 題庫品質控制構想
  • 15.5 題庫版本流程
  • 15.6 練習集建議配置
  • 15.7 小結

• 16. 進階學習與延伸

  • 16.1 進階主題地圖
  • 16.2 性能成熟度模型
  • 16.3 延遲與異常分析起步
  • 16.4 Trace 整合實務
  • 16.5 持續優化季度節奏
  • 16.6 推薦延伸資源
  • 16.7 小結
  • 16.2 性能成熟度模型
  • 16.3 延遲與異常分析起步
  • 16.4 Trace 整合實務
  • 16.5 持續優化季度節奏
  • 16.6 推薦延伸資源
  • 16.7 小結

Part 6. 附錄（Appendices）

• 附錄 A. 最終測試計畫 Checklist
• 附錄 B. 常見錯誤 / 緊急排障對照
• 附錄 C. 範例報告模板（摘要草稿）
• 附錄 D. 建議檔案 / 目錄標準化命名
• 附錄 E. 後續可延伸主題（進階）

1. JMeter 簡介

1.1 JMeter 的定位與用途

Apache JMeter 是一款開源（100% Java 編寫）的負載與效能測試工具，最初設計用於 Web(HTTP) 測試，如今已支援多種協定與應用類型：

支援的協定/服務類型：

• Web：HTTP、HTTPS（Java, NodeJS, PHP, ASP.NET 等）
• SOAP / REST Webservices
• FTP
• 資料庫：透過 JDBC
• LDAP
• 訊息導向中介軟體 (MOM)：透過 JMS
• 郵件：SMTP(S)、POP3(S)、IMAP(S)
• 原生命令或 Shell 腳本
• TCP
• Java Objects
• gRPC、MQTT 等（透過外掛）

其核心使命：模擬多使用者併發，量測系統在壓力下的反應時間、吞吐量、錯誤率，協助定位瓶頸。

重要提醒：JMeter 不是瀏覽器，它在協定層級運作。JMeter 不會執行 HTML 頁面中的 JavaScript，也不會像瀏覽器一樣渲染頁面。

典型使用場景：

• 測試 API 在 100 / 500 / 1000 併發下之平均延遲 (Avg / P95 / P99)
• 驗證新版本部署後的效能回歸
• 預估硬體或雲端資源擴充需求（容量規劃）
• 模擬高峰（行銷活動、批次入帳、補貨作業）

1.2 常見測試類型

1.3 與其他工具比較

選擇建議：若需快速導入 + 多人圖形化協作 + 可擴充 → 先選 JMeter。後續若腳本維護變複雜或需高度程式化，再評估 Gatling / k6。

1.4 概念流程圖

flowchart LR
  A["需求/測試目標"] --> B["場景設計"]
  B --> C["建置 JMeter Test Plan"]
  C --> D["參數化 / 控制器 / 驗證"]
  D --> E["本機驗證 (GUI)"]
  E --> F["非 GUI / 分散式執行"]
  F --> G["結果彙整 / HTML 報表"]
  G --> H["分析瓶頸 / 產出結論"]
  H --> I["調校 / 回饋開發 / 再測"]

1.5 本章實務案例

需求：行銷活動預期 500 同時使用者查詢商品 API，需確認 API P95 < 800ms。 行動：建立 JMeter 測試計畫 → Thread Group 設定 500 使用者，Ramp-up 300 秒，持續 5 分鐘 → 檢視 Summary / Aggregate Report。 輸出：若 P95 超標，記錄指標並回報後端做索引或快取優化。

1.6 注意事項（初學者常犯）

• 直接用 GUI 模式跑 1000+ threads 導致本機資源飽和 → 應改非 GUI / 分散式
• 沒加 Assertion 導致錯誤頁面也被當成功 → 一律加 Response Code 或字串驗證
• 無計畫地升壓（一次丟極大併發）→ 無法定位臨界點，改用階梯式（階段性提升）

2. 安裝與環境設定

2.1 系統需求

• Java：JDK 8+（JMeter 5.6.x 最低需求），建議使用 Java 17 LTS
  • 下一個主要版本將需要 Java 17+
• 記憶體：建議 8GB 以上（壓測機依併發放大）
• OS：Windows / Linux / macOS 均可

⚠️ JavaScript 引擎注意事項：

• Java 11+ 時 Nashorn JavaScript 引擎已被棄用，會顯示警告
• Java 15+ 時 Nashorn 已被移除，若需要 JavaScript 支援可使用 Mozilla Rhino 或 OpenJDK Nashorn
• 建議優先使用 Groovy (JSR223) 取代 JavaScript，效能更佳且無版本相容問題

2.2 下載來源

• 官方站：https://jmeter.apache.org/
• 下載 Binary (zip / tgz) 套件即可（無需 Source）

2.3 安裝流程

Windows：

1. 安裝 JDK（確認 java -version）
2. 下載 Apache JMeter 二進位壓縮檔
3. 解壓至例如：C:\tools\apache-jmeter-5.6.3
4. 執行 bin\jmeter.bat

Linux / macOS：

tar -xzf apache-jmeter-*.tgz
export JMETER_HOME=~/apache-jmeter-5.6.3
export PATH="$JMETER_HOME/bin:$PATH"
jmeter &

2.4 目錄結構

2.5 常見安裝問題

2.6 調整啟動參數

編輯 bin/jmeter.properties 或 user.properties：

# 增加結果緩衝 (大量取樣時降低 IO)
mode=batch
# 禁用不必要的 GUI 元件提升穩定性
jmeter.reportgenerator.overall_granularity=60000

建議：自訂屬性盡量放 user.properties，方便版本控制。

2.7 本章實務練習

1. 完成安裝後，執行 jmeter -v 確認版本。
2. 調整記憶體參數：設定 HEAP=-Xms1024m -Xmx4096m。
3. 建立一個 user.properties 並加入：sample_variables=SESSION_ID。

2.8 注意事項

• 測試機與被測系統（SUT）應分離 → 避免 CPU / I/O 競爭影響評估
• 控制版本：將 *.jmx、user.properties、CSV、啟動腳本 納入 Git
• 測試數據與環境隔離：避免對生產資料造成污染

3. JMeter 使用者介面 (GUI)

3.1 元件總覽

3.2 建立第一個測試計畫（Hello HTTP）

步驟：

1. 開啟 JMeter，右鍵 Test Plan → Add → Threads → Thread Group
2. Thread Group 設定：Threads=5、Ramp-up=5、Loop=2
3. 右鍵 Thread Group → Add → Sampler → HTTP Request
   • Server Name: postman-echo.com
   • Method: GET
   • Path: /get
   • (可加參數) Add → Parameter: foo=bar
4. 加入 Listener：右鍵 Thread Group → Add → Listener → View Results Tree、Summary Report
5. 按「綠色 Start」執行
6. 在 View Results Tree 檢視 Request / Response；大量壓測時移除該 Listener，改只保留 Summary Report。

3.3 儲存與版本控管

• 檔案 → Save Test Plan As → api_basic.jmx
• 建議：一個主計畫 + 多個模組化 Include Controller（後續 Part 2 說明）
• 以 Git 管理：提交時附測試說明 README（含測試目標、指標、版本）

3.4 GUI 效能使用守則

3.5 Mermaid：基本測試計畫組成

graph TD
  TP[Test Plan] --> TG[Thread Group]
  TG -->|執行順序| S1[HTTP Sampler]
  TG --> S2[JDBC Sampler]
  S1 --> A1[Assertion]
  S1 --> L1[Listener]
  S2 --> L1
  TG --> C1[Config: CSV Data]
  TG --> T1[Timer]

3.6 本章實務練習

建立 postman-echo 測試：

1. Threads=10，Ramp-up=10，Loop=3
2. 新增 Uniform Random Timer：延遲 500ms ±300ms
3. 新增 Response Assertion：包含字串 "args"
4. 執行後觀察錯誤率=0 並記錄 Avg、Min、Max。

3.7 常見初階錯誤

• 把 Ramp-up=0：所有 threads 同時啟動 → 導致服務突刺
• 忘記加 Timer：與實際使用者行為不符
• 不加 Assertion：錯誤回應被忽略

3.8 小結

你現在應能：

• 安裝並啟動 JMeter
• 認識主要元件類別
• 建立並執行簡單 HTTP 測試 接下來 Part 2 將深化：參數化、控制流程、可維護架構與驗證策略。

（後續章節將於下一階段回覆補上）

4. 測試計畫基礎

4.1 目標與原則

設計一個可維護、可重複、可擴充的測試計畫，重點：

• 可讀性：命名清楚、層次分明
• 可參數化：資料與腳本分離
• 可重複：環境差異靠變數 / properties 切換
• 可驗證：Assertion 一致、指標明確
• 可擴充：模組化（登入、下單、查詢）可被重用

4.2 命名規範建議

4.3 推薦資料夾結構

測試資源與腳本放入版本控管（例：/perf-test）：

perf-test/
  README.md                 # 測試目標與指標定義
  env/
    dev.properties
    qa.properties
    prod.properties.disabled
  data/
    users.csv
    products.csv
  scripts/
    ecommerce-login.jmx
    ecommerce-search.jmx
    modules/
      login-fragment.jmx    # Test Fragment (登入流程)
      search-fragment.jmx   # 可被多場景 include
  reports/
    2025-09-17-search-load-test/
      dashboard/            # HTML 報表輸出
      raw.jtl               # 原始結果
  bin/
    run-search-dev.bat
    run-search-dev.sh

4.4 Mermaid：資源關聯示意

graph LR
  A[Test Plan] --> B[Thread Group]
  B --> C{Modules / Include}
  C --> C1[Login Fragment]
  C --> C2[Search Fragment]
  A --> D[User Defined Variables]
  A --> E["Properties(env.*)"]
  B --> F[CSV Data]
  B --> G[Samplers]
  G --> H[Assertions]
  G --> I[Listeners]

4.5 Thread Group 策略

計算基礎：

併發數 (Concurrency) ≈ 每秒請求數 (RPS) * 平均回應時間(秒)

例如：目標 RPS=100，Avg RT=0.5s → 須約 50 Threads（可加 10~20% buffer）。

4.6 API 測試模板（可複製）

建立一個「模組化可重用」HTTP Sampler + 變數設計：

元件階層：
Test Plan
  -> User Defined Variables (udv_baseUrl, udv_authPath)
  -> Thread Group [TG]LoginAndQuery-100-Steady
    -> CSV Data Set Config (users.csv: username,password)
    -> HTTP Request: POST ${udv_authPath}/login
      Body(JSON): {"user":"${username}","pwd":"${password}"}
    -> JSON Extractor: token 目標路徑 $.data.token 儲存為 resp_token
    -> HTTP Header Manager: Authorization=Bearer ${resp_token}
    -> HTTP Request: GET ${udv_baseUrl}/api/products?id=${__CSVRead(products.csv,0)}
    -> Response Assertion: Contains "success"
    -> Listener: Summary Report

建議使用 JSON Extractor (新版) 取代舊式 Regular Expression 抽取 JSON。

4.7 指標定義（在 README 或測試說明中標準化）

4.8 Include Controller 與 Test Fragment 模組化

拆分重複流程：

1. 新建一個 login-fragment.jmx，在其中建立 Test Fragment（非 Thread Group）。
2. 主測試計畫使用 Include Controller 引用該檔。
3. 好處：

• 多場景共用登入 / 取得 token
• 異動集中維護
• 減少複製貼上導致的版本漂移

4.9 變數與屬性作用域（預告）

本章先理解：User Defined Variables 在 Test Plan 載入時解析；CSV 在執行階段 per thread 讀取；抽取器（Extractor）在 Sampler 執行後注入。詳細優先序 Part 5 展開。

4.10 Mermaid：執行流程（含變數注入）

sequenceDiagram
  participant T as Thread
  participant CSV as CSV Data
  participant S1 as Login Sampler
  participant EX as JSON Extractor
  participant S2 as Query Sampler
  Note over T: 啟動 Thread → 載入 UDV / Properties
  T->>CSV: 讀取使用者帳密
  T->>S1: POST /login (username,password)
  S1-->>EX: 回應 JSON
  EX-->>T: 設定變數 resp_token
  T->>S2: GET /products (Header: token)
  S2-->>T: 回應 + 驗證 Assertion

4.11 非 GUI 執行模板指令

jmeter -n -t scripts/ecommerce-search.jmx -q env/dev.properties -l reports/2025-09-17-search-load-test/raw.jtl -e -o reports/2025-09-17-search-load-test/dashboard

參數說明：

• -n 非 GUI 模式
• -t 指定 jmx 腳本
• -q 載入環境屬性檔（可多次）
• -l 輸出 jtl 結果檔
• -e -o 生成 HTML Dashboard

Windows 批次檔範例（bin/run-search-dev.bat）：

@echo off
set DATE=%DATE:~0,10%
set REPORT_DIR=reports\%DATE%-search-load-test
mkdir %REPORT_DIR%\dashboard 2>nul
jmeter -n -t scripts\ecommerce-search.jmx -q env\dev.properties -l %REPORT_DIR%\raw.jtl -e -o %REPORT_DIR%\dashboard

4.12 實務練習

目標：建立「登入 + 查詢」組合場景，100 使用者，Ramp-up 60 秒，持續 5 分鐘（可用 Loop Controller 搭配 Scheduler 或 Constant Throughput Timer 調整）。

1. 建立資料檔 users.csv：user01,password01 …
2. 建立 login-fragment.jmx 含 Login Sampler + JSON Extractor。
3. 主場景引用 Include Controller。
4. 加入 Search Sampler 使用 token。
5. 設定 Assertion：HTTP 200 + 回應包含 "success"。
6. 非 GUI 執行並匯出 HTML 報表。
7. 記錄：Avg / P95 / Throughput / Error%。

4.13 常見錯誤與陷阱

• 在多 Thread Group 中各自複製登入邏輯 → 無法集中維護 → 請改 Test Fragment
• 無斷言（Error%=0 但實際 500）→ 一律加至少 1 個成功判斷
• CSV 未勾選 Recycle on EOF 且資料不足 → 後續使用者空值錯誤
• Ramp-up 設為極低導致瞬間尖峰不符合真實行為
• 將結果 Listener 全部保留在大壓測 → 記憶體爆滿

4.14 小結

你現在應能：

• 制定命名規範與資料夾結構
• 以模組化方式重用登入 / 查詢流程
• 依據指標設定 Thread Group 策略
• 使用非 GUI 模式生成報表

接下來第 5 章將處理「參數化、變數作用域與 Correlation」。

5. 參數化與資料驅動測試

5.1 為什麼需要參數化？

避免硬編（hardcode）提高可維護性、可重複性與環境可移植性：

• 測試資料可批次更新（CSV）
• 環境位址、認證、Port 改動不需修改多處 Sampler
• 支援多場景共享登入 Token / 動態 ID
• 強化可觀測性（變數命名即文件）

5.2 變數來源一覽

5.3 CSV Data Set Config 深入

關鍵設定：

避免常見錯誤：

• 資料列不足 → Threads > CSV 行數且未回捲
• 共享模式錯誤 → 多 Thread 爭用導致資料覆寫（應拆多檔或改 Sharing Mode）

5.4 User Defined Variables vs Properties

示例：在 env/dev.properties：

env.host.api=https://dev.api.example.com
env.timeout.ms=3000

HTTP Request Server Name 可寫：${__P(env.host.api,https://fallback)}。

5.5 Correlation（動態值提取）

動態值（Token、Session、動態 ID）需從回應中抽出再帶入下一請求。流程：

sequenceDiagram
  participant C as Client Thread
  participant S as Server
  C->>S: POST /login
  S-->>C: { token: "abc123", userId: 901 }
  Note over C: JSON Extractor token,userId
  C->>S: GET /orders?uid=${userId}
  S-->>C: 訂單列表 (驗證)

常用抽取器：

JSON Extractor 設定範例：

5.6 API 回應範例與抽取

假設登入回應：

{
  "status":"success",
  "token":"eyJhbGciOi...",
  "user":{ "id":901, "roles":["USER","VIP"] },
  "expires":1694863200000
}

後續查詢訂單：GET /api/orders?uid=${resp_userId}，Header：Authorization: Bearer ${resp_token}。

5.7 函數助手（Functions）常用清單

5.8 變數覆蓋與優先序（邏輯觀念）

從「最近、動態」到「最早、靜態」：

graph TD
  A[Extractor 變數] --> B[函數生成]
  B --> C[CSV Data]
  C --> D[User Defined Variables]
  D --> E["Properties (__P)"]
  E --> F[系統屬性 -D]

解析順序說明：

1. Test Plan 載入：UDV、Properties、系統屬性已可解析
2. 執行階段：CSV 每 Thread/迴圈填入
3. Sampler 回應後：Extractor 注入 -> 覆蓋同名早期值

命名防衝突建議：

• 抽取變數加前綴：resp_ 或 ext_
• CSV 來源加前綴：csv_
• 只讀屬性加前綴：prop_（透過 props 轉存時）

5.9 Groovy / JSR223 活用

優先使用 JSR223 + Groovy（效能佳）。

設定腳本 cache：在 JSR223 元件勾選「Cache compiled script」以降低反覆編譯成本。

範例：動態組合查詢參數與基本驗證：

// 於 JSR223 PreProcessor
def id = vars.get('resp_userId') ?: '0'
def q = "status=ACTIVE&userId=${id}&ts=" + System.currentTimeMillis()
vars.put('queryString', q)

// 簡單防呆
if(!vars.get('resp_token')) {
  log.warn('token missing, will mark next request')
}

後續 Sampler Path：/api/orders?${queryString}。

5.10 非 GUI 參數覆寫技巧

啟動時覆寫/補充 Properties：

jmeter -n -t scripts/ecommerce-search.jmx -q env/dev.properties -Jenv.host.api=https://override.dev.local -Jramp.users=200

在腳本使用：${__P(ramp.users,100)}。

5.11 常見錯誤與排除

5.12 實務練習

建立「登入 → 查詢 → 建立訂單」場景：

1. users.csv：帳號密碼 50 筆
2. Login Sampler + JSON Extractor：resp_token、resp_userId
3. GET /products 使用 CSV 產品列表（products.csv）
4. POST /orders：Body 帶 ${resp_userId} 與隨機產品 ID
5. Assertion：訂單建立回應包含 orderId
6. 變數命名統一：resp_ 前綴
7. 以 -Jramp.users 傳入不同併發觀察 P95 差異

5.13 小結

你現在應能：

• 使用 CSV/UDV/Properties 區分資料層級
• 實作 Correlation（Token / ID 抽取）
• 理解變數優先序與覆蓋策略
• 使用 Groovy 動態組裝請求
• 以啟動參數覆寫環境設定

下一章（第 6 章）將深入控制流程（Loop / If / Transaction / Throughput）與測試場景組合技術。

6. 控制器與流程控制 (Logic Controllers)

本章目標：

• 理解各種邏輯控制器用途與差異
• 建立可重用模組（Module / Include）
• 使用 Transaction Controller 衡量事務耗時
• 使用 Throughput / Runtime / If / Switch 控制動態路徑
• 避免過度巢狀與維護風險
• 實作多情境配比（例如 70% 瀏覽 / 20% 搜尋 / 10% 下單）

章節結構：

6.1 控制器分類概覽
6.2 Loop / While / ForEach 差異
6.3 If / Switch / Runtime Controller
6.4 Throughput Controller 與場景比例
6.5 Transaction Controller 與聚合分析
6.6 Module / Include Controller 模組化
6.7 Flow Control Action 中斷與暫停
6.8 控制器選擇決策矩陣
6.9 常見 anti-pattern 與重構
6.10 綜合實務案例
6.11 練習
6.12 小結

6.1 控制器分類概覽

Mermaid：控制器作用層級概念圖：

graph TD
  A[Test Plan] --> B[Thread Group]
  B --> C[Throughput Controller]
  C --> D[Transaction Controller]
  D --> E[Sampler 1]
  D --> F[Sampler 2]
  B --> G[If Controller]
  G --> H[Sampler 3]
  B --> I[Module Controller -> Fragment]
  I --> J[Login Steps]

6.2 Loop / While / ForEach 差異

最佳實務：

• While 條件使用明確變數，如 ${__groovy(vars.get('done')=='true')}
• 加入最大迴圈防護：可在條件中遞增計數達上限跳出
• ForEach 搭配 JSON Extractor 使用 names + matchNr 生成 var_1..var_n

While 監控狀態範例（輪詢直到成功或超時）：

// JSR223 PreProcessor (設於 While 子節點第一個 Sampler 前)
def cnt = (vars.get('pollCnt') ?: '0').toInteger() + 1
vars.put('pollCnt', cnt.toString())
if (cnt > 20) { // 超過 20 次跳出
  vars.put('done','true')
}

While 條件：${__groovy(vars.get('done')=='true')} 然後選擇「Interpret Condition as Variable Expression」。

6.3 If / Switch / Runtime Controller

Runtime Controller 適合：快速抽樣 API 行為特徵，不用等整個測試結束。

6.4 Throughput Controller 與場景比例

模式：

• Percent Execution：每個 Thread 依百分比機率執行
• Total Executions：跨 Threads 總次數上限

模擬 70% 瀏覽 / 20% 搜尋 / 10% 下單：

graph LR
  TG[Thread Group] --> A[Throughput 70% Browse]
  TG --> B[Throughput 20% Search]
  TG --> C[Throughput 10% Order]

注意：Percent 模式是獨立評估每個子控制器，不會自動保證總合精確比例（統計上接近）。需嚴格比例時應使用自訂亂數路由（JSR223 + Switch）。

亂數路由精確實現（總和 100）：

// JSR223 Sampler 於 Thread Group 開頭
def r = (int)(Math.random()*100)
def path = r < 70 ? 'BROWSE' : (r < 90 ? 'SEARCH' : 'ORDER')
vars.put('scenario', path)

Switch Controller 名稱對應：BROWSE、SEARCH、ORDER。

6.5 Transaction Controller 與聚合分析

用途：將多個 Sampler 視為單一「事務」以衡量端到端耗時（例如：搜尋 + 過濾 + 載入結果）。

設定建議：

• 勾選「Generate parent sample」：在報表中得到整體事務一筆紀錄
• 保持內部 Sampler 原始：方便分析細節瓶頸
• 事務粒度避免過大（>10 個 Sampler）

常見錯誤：

• 過度巢狀（Transaction 包 Transaction）→ 難以判讀
• 把單一 Sampler 包成 Transaction → 無意義

6.6 Module / Include Controller 模組化

Test Fragment：僅供引用，不會自行執行，通常存放公共步驟（Login、Setup Token、Health Check）。

結構示例：

graph TD
  TP[Test Plan] --> TG[Thread Group]
  TP --> FR1[Test Fragment Login]
  TP --> FR2[Test Fragment Browse]
  TG --> M1[Module -> Login]
  TG --> M2[Module -> Browse]

6.7 Flow Control Action 中斷與暫停

功能：在執行期強制控制流程：

6.8 控制器選擇決策矩陣

6.9 常見 Anti-pattern 與重構

6.10 綜合實務案例

目標：模擬電商行為比例（瀏覽 65% / 搜尋 20% / 下單 10% / 其餘健康檢查 5%），並量測「下單事務」端到端耗時。

結構：

graph TD
  TG[Thread Group]
  TG --> P1[JSR223 路由變數 scenario]
  TG --> SW[Switch Controller]
  SW --> BR["Browse Flow (Module)"]
  SW --> SR["Search Flow (Transaction)"]
  SW --> OR["Order Flow (Transaction)"]
  SW --> HC["Health Check (If)"]

路由變數腳本（置於第一個 JSR223 Sampler）：

def r = (int)(Math.random()*100)
def scn = r < 65 ? 'BROWSE' : (r < 85 ? 'SEARCH' : (r < 95 ? 'ORDER' : 'HEALTH'))
vars.put('scenario', scn)

Switch Controller 子節點命名需與 scenario 值一致。

Order Flow Transaction：

• Step1: 加入購物車
• Step2: 建立訂單
• Step3: 取得訂單狀態

報表觀察指標：

• ORDER Transaction 平均 / P95
• ORDER 流程內部哪個 Sampler 最慢（可能是建立訂單 API）

6.11 練習

練習目標：建立「登入 → 根據使用者身分（VIP / 一般）走不同場景」：

1. 登入抽取 resp_userType
2. 使用 If：resp_userType == 'VIP' 走 VIP Fragment
3. 其他走一般 Fragment
4. VIP Fragment 內包 Transaction（複合查詢）
5. 一般流程使用 Loop 重複瀏覽 3 次
6. 加入 Flow Control Action 在 VIP Fragment 中條件不符時 Break

挑戰延伸：改用 Switch + 路由變數（將 VIP、NORMAL 標準化）。

6.12 小結

你現在應能：

• 正確選擇 Loop / While / ForEach 控制流程
• 使用 If / Switch / 自訂亂數 建立分支路由
• 用 Throughput / Transaction 建模比例與端到端耗時
• 用 Module / Include 模組化共用步驟
• 用 Flow Control Action 安全中斷或節奏控制
• 辨識並重構控制器 Anti-pattern

下一章（第 7 章）將深入 Assertion：如何驗證結果、分類錯誤、控制失敗策略與提升報表可解讀性。

7. Assertion 斷言與結果驗證策略

本章目標：

• 正確選擇 Assertion 類型 (狀態碼/Body/JSON/時間/大小)
• 控制失敗策略：Fail Fast vs 寬鬆收集
• 建立錯誤分類（功能錯 / 性能錯 / 資料錯 / 環境錯）
• 動態門檻設定（環境差異 / 基準波動）
• 減少過度斷言導致的性能負擔

章節結構：

7.1 為什麼需要明確斷言策略
7.2 常見 Assertion 類型比較
7.3 狀態碼與錯誤分類
7.4 JSON / 正則 / XPath / Size 使用情境
7.5 Duration / SLA 驗證與 P95 判讀
7.6 動態門檻 (Baseline / Properties) 7.7 失敗策略：Fail Fast vs 收集模式
7.8 減少斷言開銷的最佳實務
7.9 錯誤訊息標準化（Log 與報表對齊）
7.10 實務案例：登入 + 查詢 + 下單
7.11 練習
7.12 小結

7.1 為什麼需要明確斷言策略

沒有斷言 = 僅測速度；有錯誤卻視為成功會得出失真指標。過多斷言又會：

• 增加 CPU/記憶體（特別是大型回應解析）
• 造成回應樹檢視困難（失敗訊息冗長）
• 增加調校門檻（門檻硬編）

目標：最少且關鍵、可維護、可調整。

7.2 常見 Assertion 類型比較

7.3 狀態碼與錯誤分類

分類矩陣：

Response Assertion（字串包含）配置技巧：

• 包含："status":"success"
• 不包含："error"、"Exception"
• 忽略大小寫：勾選 Ignore Status（依版本功能）

7.4 JSON / 正則 / XPath / Size 使用情境

JSR223 Assertion 範例（集中輸出）：

def json = new groovy.json.JsonSlurper().parseText(prev.getResponseDataAsString())
def errors = []
if(json.status != 'success') errors << 'status!=success'
if(!json.user?.id) errors << 'user.id missing'
if(json.durationMs && json.durationMs > 800) errors << 'duration SLA fail'
if(errors) {
    AssertionResult.setFailure(true)
    AssertionResult.setFailureMessage(errors.join(';'))
}

7.5 Duration / SLA 與 P95 判讀

單筆 SLA：用 Duration Assertion，例如：< 800 ms。缺點：尖峰抖動可能造成大量失敗。建議配合：

• 報表中觀察 P95/P99 是否穩定
• 使用 Transaction Controller 衡量完整流程 SLA
• 允許少量超標（報表層面評估，而非全部標 Fail）

策略：單筆超時記錄但不 Fail 整測，於報表彙整（以聚合報表/HTML Dashboard 判讀）。

7.6 動態門檻 (Baseline / Properties)

避免硬編：利用 properties + 前置抽取基準。

1. 先跑基準測得 login.avg=320
2. 設定門檻：login.sla.ms = baseline * 1.5
3. 啟動前寫入 baseline.properties

JSR223 Assertion 動態門檻：

def base = props.get('login.baseline.ms')?.toInteger() ?: 300
def limit = (base * 1.5) as int
def rt = prev.getTime()
if(rt > limit) {
  AssertionResult.setFailure(true)
  AssertionResult.setFailureMessage("login rt=${rt} > limit=${limit}")
}

7.7 失敗策略：Fail Fast vs 收集模式

建議：用 Flow Control Action + 變數旗標控制提前停止某流程。

7.8 減少斷言開銷的最佳實務

• 只對必要 Sampler 加 Assertion（高價值 API）
• 避免對巨大回應反覆用 Regex（改 JSONPath + 限縮抽取）
• 合併多個欄位驗證於單一 JSR223（降低管理成本）
• JSON 解析可重用 groovy.json.JsonSlurper 實例（或快取字串）
• 測試初期可開啟詳細，穩定後減少低價值驗證

7.9 錯誤訊息標準化

格式範例：[TYPE=SLA][API=login][RT=920][LIMIT=800] 或 {"type":"DATA","field":"user.id"}。

標準化好處：

• 日誌可用工具聚合統計類型比例
• 減少人工閱讀成本
• 可輸出為後處理報表（例如自訂 Parser）

7.10 實務案例：登入 + 查詢 + 下單

需求：驗證登入成功、查詢結果含商品、下單回傳訂單編號且總耗時 < 2500ms。

設計：

1. Login Sampler：Response Code + JSON Assertion（status=success）
2. Query Products：字串包含 "items" + Size > 200 bytes
3. Order Transaction：使用 Transaction Controller 包含建立 / 查詢狀態兩步
4. Transaction SLA：不在 Sampler 直接 Fail，改報表層觀察 P95 < 2500
5. 若 Login 失敗 → Flow Control Action 停止當前 Thread

額外：JSR223 Assertion 聚合錯誤：

def err = []
def json = new groovy.json.JsonSlurper().parseText(prev.getResponseDataAsString())
if(!json.orderId) err << 'missing orderId'
if(json.total && json.total < 0) err << 'total negative'
if(err) { AssertionResult.setFailure(true); AssertionResult.setFailureMessage(err.join('|')) }

7.11 練習

練習題：為「登入 → 搜尋 → 下單」腳本新增：

1. 登入：狀態碼 200 且 JSON token 不為空
2. 搜尋：回應包含關鍵字 "price" 且大小 > 300 bytes
3. 下單：回應 JSON orderId、status='CREATED'
4. 端到端（Transaction）P95 需 < 3000ms（於報表分析）
5. 過載時允許 2% 內 SLA 超標（報表手動計算）

延伸：以 properties order.sla.ms=2800 動態驅動 JSR223 Assertion。

7.12 小結

你現在應能：

• 根據場景挑選適當 Assertion 類型
• 實作錯誤分類與訊息標準化
• 動態設定 SLA 門檻避免硬編
• 平衡 Fail Fast 與收集完整證據
• 降低不必要解析開銷

下一章（第 8 章）將解析報表與指標解讀與常見誤區。

8. 報表與結果分析

本章目標：能正確解讀常見報表（Summary / Aggregate / HTML Dashboard），理解 P95 與平均數差異、錯誤率來源分類、指標趨勢與異常型態，並建立基準值 (Baseline) 與版本對比流程。

適用情境：功能腳本驗證完成後的效能 / 負載 / 壓力 / 回歸測試分析。

8.1 核心指標再回顧

判讀原則：延遲看 P95 + P99 是否穩定、吞吐需搭配 Active Threads 曲線是否平穩、Error% 需拆分類型後再判斷。

8.2 Summary / Aggregate Report 差異

最佳實務：腳本調試階段可用 View Results Tree；正式負載測試僅保留必要 Listener（Summary + Backend Listener 或直接用 non-GUI + HTML Dashboard）。

8.3 HTML Dashboard 產出與指標

產出方式（非 GUI 完成後）：

jmeter -g results.jtl -o reports/html

或於執行時直接產出：

jmeter -n -t test.jmx -l results.jtl -e -o reports/html

主要頁面重點：

8.4 百分位數 (Percentile) 判讀策略

百分位顯示尾部延遲：

可用「Baseline vs Current」比較：若 P95 增幅 > (基準 * 1.15) 則標記黃燈；>1.3 標記紅燈。

8.5 Error% 分類與來源拆解

分類維度：

1. 功能錯誤（狀態碼 4xx/5xx、商業邏輯返回）
2. Assertion SLA 超時（自訂性能門檻）
3. 網路/連線類（連線重設 / 超時 / DNS）
4. 腳本錯誤（變數為空、未成功登入造成後續失敗）

動作：於 JSR223 Assertion 將錯誤統一前綴，如：FUNC_ / SLA_ / NET_ / SCRIPT_，利於報表後分組。

8.6 建立 Baseline 與版本對比流程

推薦檔案：baseline.properties（收錄上一穩定版本指標）。

流程：

flowchart LR
  A[測試執行完成] --> B[擷取 HTML Dashboard 指標]
  B --> C[寫入 current.properties]
  C --> D{與 baseline 差異}
  D -- 門檻內 --> E[標記 PASS]
  D -- 超出門檻 --> F[標記 WARN/FAIL]
  F --> G[建立 JIRA / Issue]
  E --> H{需要更新 baseline?}
  H -- 是 --> I[人工審核後覆寫 baseline]
  H -- 否 --> J[保留觀察]

差異比較（簡化示例）：

8.7 異常模式（Pattern）辨識

8.8 Active Threads 與 Throughput 關聯

期望情境：Active Threads 按 Ramp-up 平滑上升並在 plateau 維持，Throughput 對應提升後趨於穩定。

偏差判讀：

8.9 實務：指標判讀工作表

可建立一個分析模板（每次測試填寫）：

8.10 自動化輸出建議

腳本化擷取 HTML Statistics 表：

grep 'Transactions' -n reports/html/statistics.json > /dev/null # 示意：實際可用 jq 解析
jq '.Total | {samples:.sampleCount,avg:.meanResTime,p95:.pct95ResTime,error:.errorPct}' reports/html/statistics.json > stats-current.json

與 baseline JSON 對比（Pseudo）：

jq -s '.[0] as $base | .[1] as $cur | {p95_delta: (($cur.p95-$base.p95)/$base.p95)}' baseline.json stats-current.json

退出碼策略：若 p95_delta > 0.15 或 error > 0.02 則退出碼 1（Fail）。

8.11 小結

你現在應能：

• 區分各類報表用途並在正式測試中減少 Listener 開銷
• 正確解讀 P95 / P99 與平均差異，避免只看平均
• 透過百分位與 Active Threads / Throughput 交叉判讀飽和點
• 建立 Error% 分類與 Baseline 對比流程
• 識別常見異常模式並規劃後續調查方向

下一章（第 9 章）將整理效能最佳實務與腳本 / 系統層雙向調優建議。

9. 效能最佳實務

本章聚焦於「如何讓測試結果可信、可重複、可擴充」以及「如何降低腳本與執行環境本身的性能干擾」，並涵蓋容量規劃、資料治理、觀測與調優流程。

9.1 Thread 數 vs RPS (Requests Per Second) 推估

估算步驟：

1. 先以小規模 (e.g. 20 threads) 實測單使用者平均 think time 與回應時間。
2. RPS 近似：Threads / (ResponseTime + ThinkTime)（秒）。
3. 若需求 RPS 為 200，且單行為 (RT+Think) 約 1.2s，理論 Threads ≈ 240。再考量：

• 長尾延遲 → 需加 10~20% buffer。
• 排程/外部依賴不穩定 → 避免一次極限壓滿。

對照表（示例）：

注意：當系統接近飽和，RT 增加會反過來要求更多 Threads → 形成誤導。需用漸進升壓曲線找拐點。

9.2 升壓模式與 Ramp-up 策略

推薦：階梯式 (Stair-step) 或 線性漸進。避免瞬間 0→1000。

9.3 暖機 (Warm-up) 與資料清洗

避免將 JIT 編譯、Cache 建立、連線池預熱納入正式統計。方式：

jmeter -n -t test.jmx -l warmup.jtl -Jduration=120 -Jwarmup=true # 暖機階段
jmeter -n -t test.jmx -l run.jtl -Jduration=600                 # 正式階段

或於單次執行後裁剪初段樣本（HTML Dashboard 觀察 Active Threads 已穩定後起算）。

9.4 減少腳本端資源干擾

9.5 測試資料生命週期與汙染防護

原則：可重複、可追蹤、避免交叉干擾。

策略：

1. 讀取模式：CSV Data Set → 每 thread 專用 vs 共用（避免主鍵衝突）。
2. 資料結束行動：不足時是否循環？若不循環必須監控樣本數 vs 資料量。
3. 測試後清理：建立清理腳本還原資料（訂單、暫存表）。
4. 敏感資料：去識別化 / 假資料生成（以 Faker / 事前 SQL 產出）。

9.6 脚本組織與模組化回顧 (與第 4 / 6 章呼應)

分層：

9.7 系統資源觀測建議 (外部協同)

測試報告需交叉引用：延遲異常時是否對應 CPU 飆升或 DB 慢查詢激增。

9.8 性能退化 (Regression) 早期偵測

做法：於 CI 中每日（或每合併）執行「輕量基準測試」(Smoke Performance)。指標：小樣本 3~5 分鐘 / 50 threads。

策略表：

9.9 GC 與 JVM 觀察（若系統為 JVM）

重點：

1. Minor GC 頻率規律且停頓 < 100ms → 正常。
2. Full GC 出現頻率 > 1 次/10 分鐘需調查（Heap、物件膨脹）。
3. 尾延遲暴增時對比 GC log 時戳。

示例啟動（被測系統）建議：

-Xms4G -Xmx4G -XX:+UseG1GC -XX:MaxGCPauseMillis=300 -Xlog:gc*,safepoint:file=gc.log:time,uptime,level,tags

9.10 常見瓶頸快速定位路徑

9.11 測試環境一致性與可重複性

風險：測試環境規模 < 正式 → 指標過於樂觀；或多服務共享環境 → 背景噪音。

治理：

1. 版本固定（Image Tag / Commit Hash）。
2. 基礎設施參數記錄（CPU/記憶體/節點數）。
3. 測試執行前健康檢查（Login / Ping / 依賴服務）。
4. 測試期間禁止非測試人員變更。

9.12 Anti-pattern 與改進建議

9.13 小結

你現在應能：

• 以科學方式估算 Threads 與 RPS 並建立升壓策略
• 區分暖機與正式統計，控制測試端干擾
• 治理測試資料生命週期與避免汙染
• 與系統/DB/GC 觀測數據交叉分析瓶頸
• 建立早期性能退化偵測與 Anti-pattern 清單

下一章（第 10 章）將聚焦 CI/CD 整合：自動執行、門檻判定與報告發佈。

10. CI/CD 與自動化整合

目標：將性能腳本納入持續整合流程，於每次合併或排程執行輕量/回歸性能測試，自動產生報表、比較基準並回饋狀態（Pass / Warn / Fail）。

10.1 測試類型在 Pipeline 的定位

10.2 非 GUI 執行標準化腳本

建立 perf-test/bin/run-test.sh（Linux/Mac）與 run-test.bat（Windows），統一參數：

#!/usr/bin/env bash
set -euo pipefail
SCENARIO=${1:-login}
ENV=${2:-dev}
TS=$(date +%Y%m%d-%H%M%S)
OUT=perf-test/reports/${TS}-${SCENARIO}-${ENV}
mkdir -p "$OUT"
jmeter -n -t perf-test/scripts/${SCENARIO}.jmx \
  -q perf-test/env/${ENV}.properties \
  -l "$OUT/results.jtl" -e -o "$OUT/html" \
  -Jbuild.sha=${GIT_COMMIT:-local} || EXIT_CODE=$?
python perf-test/tools/eval.py "$OUT" || EXIT_CODE=$?
exit ${EXIT_CODE:-0}

重點：由腳本本身統一輸出目錄命名規則，利於後續收集 artifacts。

10.3 退出碼策略 (Exit Code Policy)

Warn 可用 pipeline 訊息或標籤通知人工審核。

10.4 基準值 (Baseline) 檔與差異比較

baseline.json（示例）：

{
  "scenario":"login", "p95":780, "errorPct":0.8, "throughput":930
}

stats-current.json（從 HTML Dashboard statistics.json 解析精簡）：

{ "scenario":"login", "p95":820, "errorPct":1.1, "throughput":950 }

比較腳本（Pseudo）：

p95_base=$(jq .p95 baseline.json); p95_cur=$(jq .p95 stats-current.json)
delta=$(awk -v b=$p95_base -v c=$p95_cur 'BEGIN{printf("%.2f", (c-b)/b)}')
echo "P95 Delta=${delta}"
if awk -v d=$delta 'BEGIN{exit !(d>0.30)}'; then echo FAIL; exit 1; fi

10.5 GitHub Actions 範例 (Smoke Performance)

.github/workflows/perf-smoke.yml：

name: Perf Smoke
on:
  pull_request:
    paths:
      - 'perf-test/**'
  workflow_dispatch:
jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
      - name: Cache JMeter
        uses: actions/cache@v4
        with:
          path: ~/.jmeter
          key: jmeter-5.6.3
      - name: Download JMeter
        run: |
          if [ ! -d ~/.jmeter/apache-jmeter-5.6.3 ]; then \
            curl -sSL https://downloads.apache.org/jmeter/binaries/apache-jmeter-5.6.3.tgz | tar zx -C ~/.jmeter; fi
          echo "JMETER_HOME=$HOME/.jmeter/apache-jmeter-5.6.3" >> $GITHUB_ENV
      - name: Run Smoke Scenario
        run: |
          export PATH=$JMETER_HOME/bin:$PATH
          bash perf-test/bin/run-test.sh login dev
      - name: Archive Report
        uses: actions/upload-artifact@v4
        with:
          name: perf-report
          path: perf-test/reports/*/html

10.6 Jenkins Pipeline 範例

Jenkinsfile：

pipeline {
  agent any
  options { timestamps() }
  environment { JMETER_VERSION = '5.6.3' }
  stages {
    stage('Checkout') { steps { checkout scm } }
    stage('Setup JMeter') {
      steps {
        sh '''
        if [ ! -d tools/apache-jmeter-$JMETER_VERSION ]; then \
          curl -sSL https://downloads.apache.org/jmeter/binaries/apache-jmeter-$JMETER_VERSION.tgz | tar zx -C tools; fi
        export PATH=$PWD/tools/apache-jmeter-$JMETER_VERSION/bin:$PATH
        '''
      }
    }
    stage('Run Smoke') {
      steps {
        sh 'bash perf-test/bin/run-test.sh login dev'
      }
    }
  }
  post {
    always { archiveArtifacts artifacts: 'perf-test/reports/**', fingerprint: true }
    failure { mail to: 'perf-alerts@example.com', subject: 'Perf Smoke Fail', body: 'Check Jenkins job.' }
  }
}

10.7 多環境參數化與組態管理

避免：把 Token / 密碼寫入 Git。改用環境變數於 run-test.sh 注入再轉為 JMeter property。

10.8 Artifacts 與報告留存策略

可再另行產出：perf-index.json 聚合每次 run 的 p95/error%、生成趨勢圖。

10.9 Baseline 自動更新準則

避免「自動覆蓋導致真實退化被吞噬」。

流程：人工審核 stats-current.json → 手動 PR 更新 baseline.json。

10.10 測試分層在 Pipeline 的選擇

10.11 常見整合問題與排除

10.12 小結

你現在應能：

• 撰寫標準化非 GUI 執行腳本並於 CI 引用
• 以 Exit Code 控制 Pipeline 成敗與 Warn 分級
• 比較 Baseline 與當前指標並做審核更新
• 管理多環境組態與安全注入敏感資訊
• 規劃報表留存與層級化性能測試策略

下一章（第 11 章）將以電商 API 為例示範端到端腳本設計與 Correlation、比例流量與聚合事務分析。

11. API 實戰案例

案例背景：模擬電商平台「登入 → 瀏覽商品 → 搜尋 → 加入購物車 → 下單 → 查詢訂單狀態」之 6 個核心 API，並混入推薦查詢。目標：500 併發下 P95 < 1200ms，Error% < 1.5%。

11.1 場景拆解與使用者行為模型

使用 Throughput Controller（百分比模式）或 Switch Controller（隨機加權）實現比例。

11.2 測試計畫結構範例

Test Plan
  + Thread Group (500 users, Ramp-up 300s)
    + CSV Data Set (users.csv)
    + HTTP Header Manager (Auth / JSON)
    + Module Controller (Login Fragment)
    + Throughput Controller (50%) -> Module: Browse Flow
    + Throughput Controller (20%) -> Module: Search Flow
    + Throughput Controller (20%) -> Module: Order Flow
    + Throughput Controller (10%) -> Module: Recommend Flow
    + Post-Processor Extractors
    + Assertions (SLA + 功能)
    + JS223 Listener (聚合錯誤 / SLA)
  + Test Fragment: Login Fragment
  + Test Fragment: Browse Flow
  + Test Fragment: Search Flow
  + Test Fragment: Order Flow
  + Test Fragment: Recommend Flow

11.3 Correlation 與資料流

命名規則仍沿用第 5 章：resp_ (回應派生)、ext_ (Extractor)、此處以語意清晰為主。

11.4 測試資料策略

重點：資料池需足夠支援最大迴圈次數；若 users.csv 少於 threads 則需允許重複並註記風險。

11.5 控制器設計與比例實現

採 Throughput Controller（百分比模式）重播一次迴圈中各行為比例。若需使用「長時間持續比例」且避免單迴圈偏差，可考慮：

1. 設定 Thread Group 為循環 -1（Forever）+ Duration；
2. 對高頻場景加入 Timer 平衡節奏；
3. 或改用 Switch Controller + ${__Random(1,100)} 門檻分流。

11.6 SLA 與 Assertions 範例

JSR223 Assertion（動態 SLA 簡例）：

def api = SampleResult.getSampleLabel()
def p95Limit = props.get("sla.p95.default","1200").toInteger()
if(api.contains('checkout')) p95Limit = props.get("sla.p95.checkout","1500").toInteger()
// 實際 P95 需在報表後計算；此處示例針對單請求時間的即時閾值
if(SampleResult.getTime() > p95Limit*2) { AssertionResult.setFailure(true); AssertionResult.setFailureMessage("HARD_SLA_X2:"+SampleResult.getTime()) }

單次請求無法直接判斷 P95，只能做硬性上界（例如 2 倍 SLA）。真正 P95 判讀於第 8 章流程後處理。

11.7 交易 (Transaction) 分析

將購物流程包成 Transaction Controller (ORDER_FLOW)：

若 ORDER_FLOW P95 過高，需細分哪個子段落佔比最大（可另將子請求做單獨 Transaction Controller）。

11.8 失敗恢復與重試策略

實作：在流程前以 If Controller 判斷 auth_token 是否存在，否則呼叫 Login Fragment。

11.9 定時器 (Timer) 與節奏 (Pacing)

避免過度壓縮請求造成非真實行為：

11.10 報表截取與指標彙整模板

執行完成後建立 order-flow-analysis.md：

Scenario: ORDER_FLOW  併發=500  Duration=10m
ORDER_FLOW: Avg 980 / P95 1580 / Error 1.1%
  LOGIN      Avg 300 / P95 520
  LIST       Avg 260 / P95 480
  ADD_CART   Avg 180 / P95 400
  CHECKOUT   Avg 620 / P95 1100 (瓶頸)
  STATUS     Avg 140 / P95 300
建議：檢視 CHECKOUT 涉及之扣庫存 SQL / 支付服務延遲。

11.11 常見錯誤與排查清單（本案例）

11.12 小結

你現在應能：

• 設計多比例複合行為的 API 測試場景
• 實作關鍵值 Correlation 與資料池管理
• 以 Transaction Controller 分析端到端耗時構成
• 動態處理登入失效與基礎重試策略
• 產出針對單一業務流程的瓶頸分析摘要

下一章（第 12 章）將聚焦 Web / 前端資源載入與 API 壓測差異、靜態資源與快取策略評估（骨架待擴充）。

12. Web / 前端資源載入

本章說明為何 JMeter 不等於「瀏覽器真實行為」，以及如何針對前端資源與 API 分離測試、評估快取/壓縮策略與靜態資源最佳化影響。

12.1 瀏覽器 vs JMeter 差異

結論：JMeter 適合測後端 API / 靜態資源傳輸能力，不適合衡量 FP/LCP/CLS 等體驗指標，需配合 Lighthouse 或 RUM。

12.2 靜態資源測試策略

目的：確保 CDN / 靜態伺服器在併發下載下的吞吐延遲。

方式：

1. 建立資源 URL 清單（JS/CSS/IMG 大小 > 0.5MB 或關鍵資源）。
2. 使用 HTTP Request + 循環控制器下載資源。
3. 可設定 Constant Throughput Timer 模擬每秒請求速率。
4. 觀察 Bytes/sec、P95 latency、Error%（連線重設）。

12.3 Cache 與條件式請求模擬

實作：在 JMeter 加 Header Manager 手動加上 If-None-Match 或 If-Modified-Since 模擬瀏覽器重訪。

12.4 GZIP / Brotli 壓縮觀察

結論：JMeter 只能看到傳輸層大小差異，不評估前端解壓渲染開銷。

12.5 SPA (Single Page App) API 測試

SPA 內部 API 多為 JSON 資料交換 → 使用第 11 章策略：聚合典型行為 + Token / Session 抽取。

避免：模擬下載所有 chunks/js split 檔案（因 JMeter 無執行 JS 意義不大）。

建議：針對 API 回應時間 + 功能完整性（關鍵欄位）即可。

12.6 下載資源組合測試範例

Thread Group (100 VU)
  + CSV: resources.csv (url,size)
  + HTTP Request (GET ${url})
  + Response Assertion (Size >= ${size})
  + Constant Throughput Timer (Target 300 req/min)

12.7 資源異常與退化判斷

12.8 與前端效能工具協同

12.9 報表與度量聚合

蒐集：資源平均下載時間、Bytes/sec、304 比例、Error%。可輸出 static-metrics.json：

{ "bytesTotal": 58200000, "avgLatency": 240, "p95Latency": 420, "cacheHit304Pct": 62.5 }

12.10 小結

你現在應能：

• 理解 JMeter 在前端領域的適用邊界
• 模擬靜態資源下載與 Cache 行為差異
• 評估壓縮策略對傳輸的影響（非渲染）
• 區分 API vs 靜態資源測試策略
• 與 Lighthouse / RUM / APM 協同建立完整觀測

下一章（第 13 章）將聚焦資料庫與外部依賴模擬策略。

13. 資料庫 / 第三方整合

本章聚焦以 JMeter 測試 DB 層（讀/寫查詢）與外部服務（支付、佇列、第三方 API）模擬策略，並討論如何避免測試造成資料汙染。

13.1 JDBC Sampler 基礎

前置：/lib 放對應 JDBC Driver (e.g. mysql-connector-j.jar)。

配置：JDBC Connection Configuration → 設定 URL / 驗證 / Max Connections。

13.2 連線池 (Connection Pool) 考量

13.3 查詢分類與指標

13.4 慢查詢模擬與觀測

策略：

1. 設置查詢參數觸發非最佳化路徑（如無索引欄位）。
2. 使用不同資料規模（小/中/大表）對比延遲曲線。
3. 觀測 DB 慢查詢日誌 / EXPLAIN 計畫差異。

13.5 測試資料與回滾策略

13.6 外部依賴模擬 (Stub / Mock)

13.7 佇列 / 非同步行為測試

JMeter 不適合等待長尾非同步處理結果。策略：

1. 發送消息後輪詢狀態（加上最大重試與超時）。
2. 或只測入口吞吐（忽略下游消費）。

13.8 整合指標交叉分析

13.9 與後端團隊協同流程

sequenceDiagram
  participant T as Tester
  participant D as DBA
  participant A as App Dev
  T->>T: 設計查詢分類清單
  T->>D: 確認索引/資料規模
  T->>A: 提供延遲/錯誤樣本
  D-->>T: 回傳 EXPLAIN / 慢查詢分析
  A-->>T: 提供應用層 log/Thread dump
  T->>T: 更新報告與建議

13.10 小結

你現在應能：

• 使用 JDBC Sampler 測試 DB 查詢並理解連線池要素
• 分類查詢類型並對應指標與優化方向
• 設計慢查詢模擬並收集 EXPLAIN / 慢查詢 log
• 採用資料回滾與模擬策略避免汙染與副作用
• 區分外部依賴模擬層級並與後端/DBA 協同分析

接下來將細化認證與進階學習章節骨架。

14. 認證考試重點

本章彙整常見 JMeter / 效能測試認證或內部能力評估的出題主題映射、術語、陷阱與考前節奏建議，協助集中複習。

14.1 主題分佈映射

14.2 必背術語速覽

14.3 高頻陷阱類型

14.4 模擬測驗檢查清單

14.5 考前 24 小時節奏

14.6 Flash Cards（示例）

P95 vs P99 → 代表長尾敏感度不同
Throughput 變動但 Threads 不變 → 後端延遲或資源瓶頸
Error% 上升但 2xx 仍多 → 可能 Assertion 失敗混入
Warm-up 為何必要 → 移除環境與 JVM 初期不穩定
Baseline 何時重建 → 架構/設定/版本重大改變

14.7 小結

本章提供認證聚焦與術語集，可與第 8 / 9 / 10 / 11 章實戰練習交叉加深記憶。

15. 題庫與解析框架

建立可維護題庫格式 + 解析結構，支援自動統計與品質管控。

15.1 題型分類維度

15.2 題目 YAML 標準

- id: Q011
  type: scenario
  tags: [controller, throughput, percent]
  question: 某腳本使用 Throughput Controller 50% + Switch Controller，報表顯示實際占比 35%，原因可能為何?
  options:
    - 配置生效，屬正常波動
    - 外層還有其它請求影響比例母數
    - 百分比會自動調整為實際 RPS
    - JMeter 版本 bug
  answer: 1
  rationale: 分母包含其它取樣導致實際比例低於設定值

15.3 解析四段式框架

15.4 題庫品質控制構想

15.5 題庫版本流程

flowchart LR
  A[新增題案] --> B[標籤審核]
  B --> C[技術複核]
  C --> D[主題庫合併]
  D --> E[統計覆蓋報告]
  E --> F{缺口?}
  F -- 是 --> A
  F -- 否 --> G[標記版本]

15.6 練習集建議配置

15.7 小結

題庫框架 = 結構化 YAML + 解析四段式 + 覆蓋統計，可納入 CI 做品質門檻。

16. 進階學習與延伸

由工具層面進入觀測、方法論、治理與資料化性能優化路徑。

16.1 進階主題地圖

16.2 性能成熟度模型

16.3 延遲與異常分析起步

16.4 Trace 整合實務

在 HTTP Header 注入 X-Perf-Trace-Id=${__UUID()}；APM / Tracing 平臺以此聚合 Transaction → 對照 Thread dump / DB 慢查詢縮小瓶頸面。

16.5 持續優化季度節奏

16.6 推薦延伸資源

16.7 小結

進階能力 = 工具多樣化 + 觀測鏈整合 + 自動化退化偵測 + 治理節奏，使性能測試從一次性活動轉為持續資產。

附錄 A. 最終測試計畫 Checklist

附錄 B. 常見錯誤 / 緊急排障對照

附錄 C. 範例報告模板（摘要草稿）

專案：<ProjectName>   測試日期：2025-09-17  版本：vX.Y
場景描述：100 Threads，Ramp-up 2m，循環 10，模擬 70% 瀏覽 / 20% 搜尋 / 10% 下單

環境：
  - 測試端：8 vCPU / 16GB RAM
  - 目標環境：staging-cluster-3 nodes
  - Java 版本：Temurin 17

指標摘要：
  - 總請求數：120,000
  - Throughput：950 req/s
  - Avg RT：420 ms  | P95：780 ms | P99：1100 ms
  - Error%：0.85% （功能 0.4% / SLA 0.3% / 環境 0.15%）
  - 最大併發（Active Threads 曲線）：平穩達標

關鍵事務 (Transaction) 指標：
  - ORDER_FLOW：Avg 980 ms / P95 1600 ms / Error 1.2%
  - LOGIN：Avg 300 ms / P95 520 ms / Error 0.2%

資源觀察：
  - App CPU 最高 72%，無明顯飽和
  - DB 平均連線使用 65%（峰值 85%）
  - GC 停頓最大 150 ms，無 Full GC

發現與建議：
  1. ORDER_FLOW P95 接近 1.6s（門檻 1.5s）需檢視 DB 查詢計畫
  2. 少量 502 來自第 2 節點，建議檢視反向代理健康檢查設定
  3. 建議對登入 token 增加快取，減少重複驗證耗時

後續行動：<Owner / Due Date>

附錄 D. 建議檔案 / 目錄標準化命名

附錄 E. 後續可延伸主題（進階）

• 分散式執行（Remote / Distributed / Kubernetes）
• 與 APM (e.g., Prometheus + Grafana) 對接
• 壓測資料遮罩與脫敏機制
• 混合協定（HTTP + Kafka + DB）端到端壓測
• Performance Budget 與自動化回歸趨勢線