Newman Reporters — HTML, JUnit, Allure — API Testing with Postman Advanced

Mở đầu — vì sao bài này quan trọng

Hãy tưởng tượng bạn vừa chạy xong một collection Newman với 240 request trong pipeline CI. Có 6 request fail. Bạn mở terminal ra và thấy… một bức tường chữ đỏ trắng dài lê thê, cuộn màn hình cả phút mới hết. Câu hỏi đặt ra: request nào fail? Assertion nào không pass? Response body lúc đó trông thế nào? Và quan trọng nhất — làm sao gửi kết quả này cho một Product Owner không biết đọc terminal, hoặc để chính Jenkins hiểu được "build này pass hay fail bao nhiêu test case"?

Đây chính là lý do Newman Reporters tồn tại. Ở Bài 13, bạn đã học cách chạy collection bằng Newman trên command line. Nhưng chạy được và đọc được kết quả là hai chuyện hoàn toàn khác nhau. Một lần chạy Newman tạo ra một khối dữ liệu khổng lồ: mỗi request có status code, thời gian phản hồi, kích thước response, danh sách assertion pass/fail, lỗi script… Reporter chính là "ống kính" quyết định khối dữ liệu đó được trình bày ra sao — thành log terminal cho developer, thành file HTML đẹp cho quản lý, hay thành XML chuẩn cho công cụ CI ăn vào.

Nắm vững reporter là ranh giới giữa một người "biết chạy Newman" và một QA engineer thực thụ — người mà kết quả test của họ được cả đội tin tưởng, đọc được và hành động được. Bài này sẽ đi sâu vào ba nhóm reporter quan trọng nhất trong thực tế: HTML (đọc bằng mắt người), JUnit (máy CI ăn), và Allure (báo cáo cấp doanh nghiệp).

Khái niệm cốt lõi

Reporter là gì và cơ chế hoạt động

Reporter trong Newman là một plugin nhận sự kiện (event) trong suốt quá trình chạy collection và biến chúng thành output theo một định dạng nhất định. Newman phát ra các event như start, beforeItem, request, assertion, item, done… Reporter "lắng nghe" các event này rồi vẽ ra kết quả. Điều quan trọng: bạn có thể bật nhiều reporter cùng lúc trong một lần chạy — ví dụ vừa in log ra terminal để dev xem, vừa xuất file HTML, vừa xuất JUnit XML cho CI. Newman chỉ chạy collection một lần nhưng "phát sóng" ra nhiều kênh.

Reporter built-in — có sẵn không cần cài

Newman đóng gói sẵn 5 reporter, bạn dùng ngay không cần cài thêm gì:

cli — reporter mặc định. In bảng kết quả có màu ra terminal: tên request, assertion pass/fail, và bảng tổng kết (summary table) ở cuối. Đây là thứ bạn thấy khi chạy newman run collection.json.
json — xuất toàn bộ kết quả ra một file JSON. Đây là "nguồn sự thật" thô nhất: chứa mọi request, response, assertion, timing. Cực kỳ hữu ích khi bạn muốn tự viết script phân tích hoặc feed vào dashboard riêng.
junit — xuất file XML theo chuẩn JUnit. Đây là "ngôn ngữ chung" mà gần như mọi công cụ CI (Jenkins, GitLab, Azure DevOps) đều hiểu để hiển thị số test pass/fail.
progress — hiện thanh tiến trình dạng phần trăm, gọn hơn cli, hợp khi chạy collection dài mà không muốn spam log.
emojitrain — reporter "vui vẻ", in kết quả bằng emoji. Thú vị để nghịch nhưng thực tế hiếm dùng trong production.

Cú pháp bật reporter là cờ -r (hoặc --reporters), nối nhiều reporter bằng dấu phẩy:

newman run collection.json -r cli,json,junit

Reporter cộng đồng — cài thêm qua npm

Ngoài built-in, cộng đồng đóng góp nhiều reporter mạnh hơn. Ba cái đáng học nhất:

htmlextra (gói newman-reporter-htmlextra) — báo cáo HTML đẹp, có thể tương tác, filter được, xem chi tiết request/response. Đây là lựa chọn số một khi cần gửi báo cáo cho người không đọc terminal.
allure (gói newman-reporter-allure) — xuất dữ liệu để công cụ Allure dựng báo cáo cấp doanh nghiệp: có lịch sử (trend qua các lần chạy), phân loại theo severity, gom nhóm test.
json-summary — bản JSON gọn nhẹ chỉ chứa số liệu tổng kết, tiện khi bạn chỉ cần "pass/fail bao nhiêu" mà không cần chi tiết.

Quy tắc đặt tên rất nhất quán: gói npm luôn có tiền tố newman-reporter-, còn khi truyền vào cờ -r bạn bỏ tiền tố đó đi. Cài newman-reporter-htmlextra nhưng gọi -r htmlextra.

Reporter options — tùy biến sâu

Mỗi reporter nhận thêm option riêng theo cú pháp --reporter-<tên>-<option>. Ví dụ đổi đường dẫn file xuất, đặt tiêu đề báo cáo, ẩn các request pass để chỉ xem cái fail:

newman run collection.json \
  -r cli,htmlextra \
  --reporter-htmlextra-export ./reports/ket-qua.html \
  --reporter-htmlextra-title "Regression API - Sprint 24"

Tình huống thực tế

Tình huống 1 — Tiki: từ "tường chữ đỏ" đến báo cáo HTML gửi PO

Đội QA của một sàn thương mại điện tử lớn tại Việt Nam (giả định lấy bối cảnh kiểu Tiki) có một regression suite 180 request cho API giỏ hàng và thanh toán. Ban đầu họ chỉ chạy newman run với reporter cli mặc định. Mỗi lần có lỗi, QA phải chụp màn hình terminal, khoanh vùng bằng bút đỏ rồi paste vào group chat — Product Owner nhìn vào chẳng hiểu gì, còn hỏi ngược lại "vậy chức năng thêm giỏ hàng có chạy không?".

Đội chuyển sang htmlextra. Sau mỗi lần chạy, họ có một file HTML: trang tổng quan hiện 180 request, 174 pass, 6 fail, tổng thời gian 42 giây, biểu đồ tròn xanh-đỏ. Click vào từng request fail thấy ngay request headers, body gửi lên, response trả về và đúng dòng assertion nào không pass ("Expected status 200 but got 500"). PO chỉ cần mở file HTML trong trình duyệt là tự hiểu.

Bài học rút ra: Reporter không chỉ là công cụ kỹ thuật — nó là công cụ giao tiếp. Chọn đúng reporter giúp kết quả test của bạn "nói chuyện" được với người không phải developer, giảm hẳn vòng hỏi-đáp qua lại.

Tình huống 2 — Fintech Đông Nam Á: JUnit để Jenkins fail đúng lúc

Một công ty fintech ở Singapore có pipeline Jenkins chạy Newman mỗi lần merge code. Vấn đề của họ lúc đầu: dù có test fail, Jenkins vẫn báo build xanh (SUCCESS), vì họ chỉ nhìn output cli và Jenkins không "đọc" được nó. Có lần một bug ở API tính phí giao dịch lọt qua vì test fail nhưng build vẫn pass.

Họ thêm reporter junit và cấu hình Jenkins đọc file newman-report.xml bằng plugin JUnit. Từ đó, Jenkins hiển thị được "6 tests failed out of 180" ngay trên trang build, đánh dấu build là UNSTABLE, và trend chart cho thấy số test fail tăng dần qua các sprint. Kết hợp thêm cờ để Newman trả exit code khác 0 khi có fail, pipeline thực sự chặn merge khi test đỏ.

Bài học rút ra: Với con người thì HTML, nhưng với máy CI thì JUnit XML mới là ngôn ngữ chuẩn. Một QA giỏi luôn xuất song song cả hai: HTML cho người đọc, JUnit cho pipeline hành động.

Tình huống 3 — Agency outsourcing: Allure để chứng minh chất lượng qua thời gian

Một agency phần mềm ở TP.HCM nhận outsource kiểm thử API cho khách hàng Nhật. Khách hàng không chỉ hỏi "hôm nay bao nhiêu test pass" mà còn hỏi "xu hướng chất lượng 3 tháng qua thế nào, test nào hay flaky (lúc pass lúc fail), test nào critical".

Đội dùng newman-reporter-allure để xuất dữ liệu, sau đó dùng Allure command line dựng báo cáo. Kết quả là một dashboard chuyên nghiệp: có tab Trends hiện đồ thị pass-rate qua từng ngày, phân loại test theo mức severity, đánh dấu retry, và gom test theo feature. Mỗi tuần agency gửi link báo cáo Allure, khách hàng Nhật cực kỳ hài lòng vì thấy được "bức tranh chất lượng" chứ không chỉ con số một lần chạy.

Bài học rút ra: Khi cần lịch sử và xu hướng (chứ không chỉ ảnh chụp một lần chạy), Allure là lựa chọn nặng ký. Đổi lại nó cần thêm bước dựng report và cài công cụ Allure — phù hợp cho dự án dài hạn, quy mô lớn.

Hướng dẫn từng bước

Hãy làm một quy trình hoàn chỉnh từ built-in đến báo cáo doanh nghiệp.

Bước 1 — Chạy với reporter built-in để hiểu output cơ bản. Xuất đồng thời JSON và JUnit:

newman run collection.json -e staging.json \
  -r cli,json,junit \
  --reporter-json-export report.json \
  --reporter-junit-export report.xml

Sau khi chạy, bạn có report.json (chi tiết đầy đủ) và report.xml (chuẩn JUnit). Mở report.xml xem cấu trúc <testsuite>/<testcase> — chính cấu trúc này giúp CI hiểu được.

Bước 2 — Cài và dùng htmlextra cho báo cáo đọc bằng mắt:

npm install -g newman-reporter-htmlextra

newman run collection.json -e staging.json \ -r cli,htmlextra \ --reporter-htmlextra-export ./reports/report.html \ --reporter-htmlextra-title "API Regression - $(date +%F)" \ --reporter-htmlextra-showOnlyFails

Cờ --reporter-htmlextra-showOnlyFails cực kỳ hữu ích khi collection lớn: báo cáo chỉ hiện các request fail, bạn không phải cuộn qua hàng trăm request xanh.

Bước 3 — Xuất nhiều reporter cùng lúc (kết hợp người + máy):

newman run collection.json -e staging.json \
  -r cli,htmlextra,junit \
  --reporter-htmlextra-export ./reports/report.html \
  --reporter-junit-export ./reports/junit.xml

Đây là công thức "vàng" cho CI: cli để xem log live, htmlextra để lưu artifact cho người xem, junit để CI đọc.

Bước 4 — Dựng báo cáo Allure (nếu dự án cần):

npm install -g newman-reporter-allure
newman run collection.json -e staging.json \
  -r cli,allure \
  --reporter-allure-export ./allure-results
Sau đó dùng công cụ Allure để dựng và mở báo cáo
allure serve ./allure-results

Lưu ý Allure có hai giai đoạn: Newman chỉ xuất dữ liệu thô vào thư mục allure-results, còn việc dựng báo cáo đẹp là do công cụ Allure (cài riêng qua Scoop/Homebrew/npm) đảm nhiệm. Để có trend qua nhiều lần chạy, bạn giữ lại thư mục allure-report/history giữa các build.

Bước 5 — Cấu hình reporter bằng file thay vì gõ cờ dài. Khi lệnh quá dài, dùng newman run với file cấu hình JSON (--config) hoặc gói lệnh vào npm script trong package.json để tái sử dụng.

Lỗi thường gặp & mẹo

Lỗi 1 — Quên tiền tố newman-reporter- khi cài. Bạn cài npm install -g htmlextra (sai) rồi gọi -r htmlextra và nhận lỗi "reporter could not be loaded". Nhớ: cài thì có tiền tố (newman-reporter-htmlextra), gọi thì bỏ tiền tố (htmlextra).

Lỗi 2 — Cài local nhưng chạy global (hoặc ngược lại). Nếu bạn cài Newman global (-g) thì reporter cũng phải cài global. Nếu Newman nằm trong devDependencies của project và chạy qua npx newman, thì reporter phải cài local vào project. Không khớp phạm vi cài đặt là nguyên nhân "not found" phổ biến nhất, đặc biệt trong môi trường CI sạch.

Lỗi 3 — Đường dẫn export không tồn tại. Chỉ định --reporter-htmlextra-export ./reports/report.html mà thư mục reports chưa có sẽ gây lỗi ghi file trên một số phiên bản. Mẹo: tạo trước thư mục (mkdir -p reports) hoặc để Newman tự tạo, và luôn dùng đường dẫn tương đối rõ ràng trong CI.

Lỗi 4 — Reporter fail nhưng nghĩ là test fail. Đôi khi build đỏ vì reporter không ghi được file (quyền thư mục, thiếu gói), chứ không phải vì API lỗi. Khi debug CI, phân biệt rõ "collection fail" và "reporter fail" bằng cách đọc kỹ dòng lỗi.

Mẹo 1 — Đặt tên file report có timestamp (report-$(date +%F-%H%M).html) để không ghi đè, dễ so sánh giữa các lần chạy khi chưa dùng Allure.

Mẹo 2 — Trong CI, lưu report như artifact. Xuất HTML/JUnit ra thư mục rồi khai báo là build artifact (GitHub Actions upload-artifact, GitLab artifacts:paths) để tải về xem sau. Reporter vô nghĩa nếu file bị xóa ngay khi job kết thúc.

Mẹo 3 — Dùng --reporter-htmlextra-showEnvironmentData cẩn thận. Nó nhúng cả biến môi trường vào report — tiện để debug nhưng có thể lộ token/secret nếu report bị chia sẻ rộng. Với môi trường nhạy cảm, tắt tính năng này.

Bài tập thực hành

Cơ bản: Chạy một collection bất kỳ với đồng thời 3 reporter built-in cli,json,junit, xuất report.json và report.xml. Mở file XML và xác định: có bao nhiêu <testcase>, cái nào chứa thẻ <failure>?

HTML report: Cài newman-reporter-htmlextra, tạo báo cáo HTML với tiêu đề tùy chỉnh và bật showOnlyFails. Cố tình sửa một assertion để nó fail, chạy lại và kiểm tra report có hiện đúng request fail kèm response body không.

Kết hợp cho CI: Viết một lệnh Newman xuất cùng lúc HTML (cho người) và JUnit (cho máy) vào thư mục reports/. Giải thích trong 2 câu vì sao cần cả hai định dạng.

Nâng cao (Allure): Cài newman-reporter-allure và công cụ Allure, chạy collection 3 lần liên tiếp (giữ lại history), rồi dùng allure serve để xem tab Trends. Quan sát đồ thị pass-rate thay đổi thế nào giữa các lần chạy.

Suy ngẫm: Với ba đối tượng — developer trong đội, Product Owner, và pipeline Jenkins — bạn sẽ chọn reporter nào cho mỗi người và vì sao?

Tóm tắt

Reporter là lớp biến kết quả thô của Newman thành output có ý nghĩa, và bạn có thể bật nhiều reporter cùng lúc trong một lần chạy. Newman có sẵn 5 reporter built-in (cli, json, junit, progress, emojitrain) dùng ngay không cần cài. Cộng đồng bổ sung các reporter mạnh hơn qua npm với quy tắc đặt tên newman-reporter-<tên> (cài có tiền tố, gọi bỏ tiền tố).

Ba định dạng cốt lõi ứng với ba mục đích: HTML (htmlextra) để con người đọc và gửi báo cáo trực quan; JUnit XML làm ngôn ngữ chuẩn cho công cụ CI hiểu số test pass/fail và fail build đúng lúc; Allure cho báo cáo cấp doanh nghiệp có lịch sử, xu hướng và phân loại. Công thức thực chiến trong CI là xuất song song cli,htmlextra,junit — vừa xem log live, vừa lưu artifact cho người, vừa để pipeline hành động. Nhớ cẩn thận với phạm vi cài đặt (local/global), đường dẫn export, và luôn lưu report thành artifact để nó thực sự có ích. Khi bạn chọn đúng reporter, kết quả test của bạn không còn là "tường chữ đỏ" khó hiểu, mà trở thành thứ cả đội tin tưởng và hành động được.

Học xong bài này rồi? Tạo tài khoản miễn phí để lưu lại — lần sau vào là biết ngay đang dở ở đâu, và học hết khóa thì có chứng chỉ. Lưu tiến độ của tôi