Một lần chạy thử nghiệm mà không in ra bất cứ điều gì hữu ích là một lần chạy thử nghiệm không ai tin tưởng. Pipeline của bạn chuyển sang màu đỏ, ai đó mở nhật ký build, và tất cả những gì họ tìm thấy là một "bức tường" các dấu thời gian và mã thoát khác 0. Khẳng định nào đã bị lỗi? Chống lại môi trường nào? Trên hàng nào của tệp dữ liệu? Lần chạy đó biết. Nhưng nó chưa bao giờ ghi lại ở bất cứ đâu để bạn có thể đọc được sau này.
Đó chính là khoảng trống mà một trình báo cáo (reporter) lấp đầy. Khi bạn chạy các bài kiểm tra API từ dòng lệnh, báo cáo là phần bạn thực sự làm việc cùng: hiện vật bạn lưu trữ, tệp mà bảng điều khiển CI của bạn phân tích, thứ bạn đưa cho đồng đội lúc 9 giờ sáng mà người đó không theo dõi pipeline lúc 2 giờ sáng. Phán quyết của bài kiểm tra chỉ là một nửa công việc. Nửa còn lại là làm cho phán quyết đó dễ đọc đối với con người và cả máy móc cùng một lúc.
Trình chạy dòng lệnh Apidog xử lý cả hai. Apidog cung cấp một CLI chạy các kịch bản kiểm thử mà bạn đã xây dựng trực quan trong ứng dụng, và một cờ duy nhất điều khiển mọi báo cáo mà nó tạo ra: -r, --reporters. Bạn truyền vào một danh sách được phân tách bằng dấu phẩy, trình chạy sẽ ghi từng định dạng vào đĩa, và bạn quyết định ai đọc cái gì. Hướng dẫn này nói về cờ đó và các tệp mà nó tạo ra: mỗi trình báo cáo dùng để làm gì, cái gì được lưu vào đĩa, lưu ở đâu, và cách kết nối từng cái vào một quy trình làm việc thực tế. Nếu bạn muốn tìm hiểu sâu hơn về tất cả các cờ mà trình chạy chấp nhận, tài liệu tham khảo lệnh apidog run bao quát toàn bộ; trang này tập trung vào các báo cáo.
Tại sao báo cáo quan trọng hơn lần chạy
Chạy một kịch bản cục bộ và bạn sẽ thấy nó diễn ra. Bạn thấy từng yêu cầu được gửi đi, từng khẳng định chuyển sang màu xanh, và tóm tắt ở cuối. Vòng phản hồi là thiết bị đầu cuối ngay trước mặt bạn, trực tiếp.
Trong CI, vòng lặp đó không còn. Lần chạy diễn ra trên một máy mà bạn không bao giờ thấy, vào thời điểm bạn không theo dõi, và bản ghi duy nhất là bất cứ thứ gì được ghi vào đĩa trước khi trình chạy thoát. Nếu lần chạy không tạo ra báo cáo nào, một lỗi chỉ cho bạn biết rằng có gì đó đã hỏng. Bạn sẽ phải chạy lại toàn bộ cục bộ và hy vọng nó hỏng theo cùng một cách.
Một báo cáo tốt sẽ rút ngắn khoảng cách đó. Nó ghi lại kịch bản nào đã chạy, chống lại môi trường nào, bao nhiêu lần lặp, khẳng định nào đã vượt qua, khẳng định nào đã thất bại, và chi tiết yêu cầu và phản hồi đằng sau mỗi lần thất bại. Có được điều đó trên đĩa và một lỗi lúc 2 giờ sáng sẽ trở thành một bài đọc năm phút vào sáng hôm sau thay vì một cuộc săn tìm tái tạo lỗi. Đó là toàn bộ lý do tồn tại của cờ báo cáo, và đó là lý do tại sao việc chọn định dạng phù hợp cho từng đối tượng đáng để dành vài phút suy nghĩ.
Cờ duy nhất kiểm soát mọi báo cáo
Apidog CLI là một gói npm có tên apidog-cli. Cài đặt nó một lần và bạn sẽ có một tệp thực thi duy nhất, apidog, với lệnh con chính là run. Cài đặt nó toàn cục:
npm install -g apidog-cli
Mọi báo cáo mà trình chạy có thể tạo ra đều đến từ một cờ trên lệnh đó: -r, --reporters. Nó nhận một danh sách được phân tách bằng dấu phẩy, và bốn giá trị mà nó chấp nhận là cli, html, json, và junit. Mặc định, nếu bạn không truyền gì cả, sẽ là cli.
Một lần chạy hoàn chỉnh với hai trình báo cáo trông như thế này:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
Lệnh đó sẽ xác thực bằng một token, chạy kịch bản kiểm thử 605067 trên môi trường 1629989 một lần, và xuất cả tệp HTML lẫn đầu ra terminal dễ đọc. Các ID là ID kịch bản và ID môi trường; bạn sao chép cả hai, cùng với access token, từ tab CI/CD của kịch bản trong Apidog thay vì gõ thủ công. Nếu bất kỳ phần thiết lập nào đó không quen thuộc, hướng dẫn đầy đủ về Apidog CLI sẽ hướng dẫn bạn qua cài đặt, token và lần chạy đầu tiên từ đầu đến cuối.
Ý tưởng chính: một lần chạy có thể tạo ra nhiều báo cáo cùng lúc. Bạn không chọn một định dạng duy nhất. Bạn đang chọn đối tượng cho mỗi đầu ra và liệt kê chúng cùng nhau. Một dòng CI điển hình tạo ra một tệp HTML dễ đọc cho con người và một tệp JUnit có thể đọc được bằng máy từ cùng một lần thực thi, vì vậy cùng một lần chạy phục vụ cả con người và bảng điều khiển.
cli: báo cáo bạn đọc trong nhật ký build
Trình báo cáo cli in ra một bản tóm tắt dễ đọc trực tiếp ra terminal. Đây là mặc định, và là cái mà con người thường xem qua đầu tiên.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Những gì nó cung cấp cho bạn là phán quyết trực tiếp: bao nhiêu yêu cầu đã chạy, bao nhiêu khẳng định đã vượt qua và thất bại, và khẳng định cụ thể nào đã bị lỗi. Trong nhật ký build CI, đây là khối mà ai đó đọc khi họ nhấp vào một công việc thất bại. Nó cho họ biết ngay lập tức liệu lỗi là do một khẳng định bị hỏng hay năm mươi, và điểm cuối nào có liên quan, trước khi họ bận tâm tải xuống bất cứ thứ gì.
Hãy giữ cli ngay cả khi bạn đang ghi các định dạng máy. Nó không tốn gì và giữ cho nhật ký build hữu ích theo cách riêng của nó. Một pipeline chỉ xuất JUnit XML sẽ tạo ra một bảng điều khiển hoàn hảo và một nhật ký vô dụng; bất kỳ ai đọc đầu ra thô sẽ không thấy gì ngoài việc trình chạy khởi động và thoát. Thêm cli vào danh sách sẽ khắc phục điều đó:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
Hai cờ nữa định hình những gì cli in ra. --verbose mở rộng nó thành yêu cầu và phản hồi đầy đủ cho mỗi bước, đây là bước đầu tiên của bạn khi một kịch bản vượt qua trên máy tính xách tay của bạn nhưng thất bại trong pipeline; chi tiết truyền tải cho bạn thấy chính xác những gì trình chạy đã gửi và nhận được. --silent làm điều ngược lại và chặn hoàn toàn đầu ra console, phù hợp với một công việc theo lịch trình ồn ào mà bạn chỉ quan tâm đến mã thoát và tệp đã lưu.
html: báo cáo bạn gửi cho con người
Trình báo cáo html ghi một tệp HTML độc lập. Mở nó trong bất kỳ trình duyệt nào và bạn sẽ thấy toàn bộ quá trình chạy được trình bày trực quan: mọi yêu cầu, các khẳng định trên đó, trạng thái vượt qua và thất bại, cùng với chi tiết yêu cầu và phản hồi đằng sau mỗi bước. Không cần cài đặt gì, không cần chạy máy chủ; đó là một tệp bạn chỉ cần nhấp đúp.
Đây là định dạng bạn lưu trữ và chia sẻ. Lưu nó dưới dạng một hiện vật build và báo cáo sẽ tồn tại lâu hơn lần chạy pipeline, vì vậy một tuần sau bạn vẫn có thể mở báo cáo chính xác từ lần triển khai đã bị lỗi. Đây cũng là thứ bạn gửi cho người hỏi "cái gì đã lỗi?" mà không bắt họ phải cài đặt CLI hoặc chạy lại bất cứ thứ gì. Họ mở tệp, thấy bước màu đỏ, đọc nội dung phản hồi đã gây ra lỗi khẳng định, và họ đã hoàn thành.
HTML thể hiện giá trị nhất trong một lần chạy theo dữ liệu. Khi một kịch bản lặp qua một tệp CSV gồm năm mươi hàng, báo cáo HTML sẽ hiển thị cho bạn kết quả trên mỗi lần lặp, để bạn có thể thấy rằng các hàng từ 1 đến 49 đã vượt qua và hàng 50 đã thất bại vì một tài khoản có token cũ. Chỉ riêng số lượng vượt qua hoặc thất bại không thể cho bạn biết điều đó. Nếu bạn chạy các kịch bản với các tệp dữ liệu, mẫu này được đề cập trong kiểm thử API theo dữ liệu với CSV và JSON.
Sự đánh đổi: HTML dành cho mắt người, không phải để phân tích cú pháp. Đừng cố gắng quét nó để lấy trạng thái vượt qua/thất bại trong một tập lệnh. Đó là việc của JSON và JUnit.
junit: báo cáo mà bảng điều khiển CI của bạn phân tích cú pháp
Trình báo cáo junit xuất ra XML theo định dạng JUnit tiêu chuẩn. Định dạng đó quan trọng vì nó là ngôn ngữ chung của việc báo cáo kiểm thử CI. Hầu hết mọi hệ thống CI, GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, đều biết cách đọc JUnit XML và biến nó thành cây vượt qua/thất bại, hiển thị các lỗi trong một widget yêu cầu hợp nhất, và theo dõi xu hướng kết quả qua các bản build theo thời gian.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
Nếu bạn chọn chính xác một định dạng máy cho CI, hãy chọn định dạng này. Lợi ích là kết quả kiểm thử của bạn không chỉ tồn tại trong tệp nhật ký mà còn hiển thị trên bảng điều khiển mà nhóm của bạn đã xem. Người đánh giá mở một pull request và thấy các khẳng định nào đã thất bại được hiển thị ngay trong dòng, không cần phải mò mẫm nhật ký, không cần tải xuống hiện vật.
Thiết lập nó gồm hai bước: tạo ra XML, sau đó cho hệ thống CI của bạn biết nơi tìm thấy nó. Trong GitLab CI, bước thứ hai là khối reports: junit::
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli --out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
Trong Jenkins, tương đương là bước junit trong một khối post trỏ đến cùng các tệp. Trong GitHub Actions, bạn tải thư mục lên dưới dạng một hiện vật và để một hành động nhận biết JUnit hiển thị nó. Quy trình làm việc GitHub đầy đủ, bao gồm việc tải lên hiện vật chạy ngay cả khi các bài kiểm thử thất bại, nằm trong chạy kiểm thử Apidog CLI trong GitHub Actions.
json: báo cáo mà các tập lệnh của bạn xử lý hậu kỳ
Trình báo cáo json tạo ra kết quả có cấu trúc thô. Nơi HTML dành cho mắt và JUnit dành cho bảng điều khiển, JSON dành cho mã bạn tự viết.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
Hãy sử dụng nó khi các định dạng tích hợp không phù hợp với những gì bạn muốn làm với kết quả. Đẩy các chỉ số tỷ lệ vượt qua đến hệ thống giám sát. Xây dựng một bản tóm tắt Slack tùy chỉnh. Đưa kết quả vào một tập lệnh quyết định có nên rollback một lần triển khai hay không. So sánh lần chạy hôm nay với lần chạy hôm qua. Bất cứ điều gì có tính lập trình đều bắt đầu từ JSON, bởi vì đó là định dạng bạn có thể phân tích cú pháp mà không cần phải đoán cấu trúc.
Một cờ báo cáo được xây dựng đặc biệt cho đầu ra JSON. --out-json-failures-separated <value> tách các lỗi vào tệp JSON riêng của chúng. Điều đó cung cấp cho bạn một tài liệu chỉ chứa các lỗi, dễ đọc và dễ so sánh hơn nhiều so với việc quét toàn bộ kết quả để tìm vài bước bị lỗi. Trong một đợt kiểm thử hồi quy lớn mà hầu hết các bước đều vượt qua, một tệp chỉ chứa lỗi tạo ra sự khác biệt giữa việc chỉ xem qua và việc tìm kiếm chi tiết.
Nơi các tệp được lưu: --out-dir, --out-file, và các phần giữ chỗ
Việc chọn định dạng chỉ là một nửa vấn đề. Nửa còn lại là kiểm soát nơi các tệp được lưu và cách chúng được đặt tên, điều này quan trọng khi bạn muốn giữ lại nhiều hơn một báo cáo của một lần chạy.
--out-dir <dir> đặt thư mục mà báo cáo sẽ được ghi vào. Mặc định là ./apidog-reports. Trong CI, hãy chỉ nó đến một nơi mà bước tạo hiện vật của bạn có thể tìm thấy, và giữ nó nhất quán để cấu hình tải lên của bạn không bao giờ phải thay đổi:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name> đặt tên tệp báo cáo, và đây là lúc nó trở nên hữu ích. Nếu không có nó, mỗi lần chạy có xu hướng ghi đè lên lần trước, vì vậy bạn chỉ giữ được báo cáo gần đây nhất. Cờ này chấp nhận các phần giữ chỗ mà trình chạy sẽ điền vào khi ghi:
{SCENARIO_NAME}trở thành tên của kịch bản đã chạy.{FOLDER_NAME}trở thành tên thư mục khi bạn chạy một thư mục chứa các kịch bản.{GENERATE_TIME}trở thành một dấu thời gian.
Đặt tên tệp bằng tên kịch bản và dấu thời gian và mỗi lần chạy sẽ ghi một tệp riêng biệt, tự mô tả thay vì ghi đè lên tệp trước đó:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
Bây giờ thư mục báo cáo của bạn trông giống như một lịch sử. Bạn có thể biết báo cáo nào đến từ kịch bản nào và khi nào nó chạy mà không cần mở một tệp nào, đây chính xác là điều bạn muốn khi quét một thư mục chứa các lần chạy hàng đêm để tìm lần đầu tiên mọi thứ gặp sự cố.
Một cờ báo cáo nữa hoàn thiện phía đám mây. --upload-report [value] tải lên một bản tóm tắt báo cáo lên đám mây Apidog, vì vậy lần chạy cũng hiển thị trong lịch sử dự án của bạn cùng với các tệp cục bộ. Đây là tùy chọn để sử dụng khi bạn muốn kết quả hiển thị bên trong chính Apidog, không chỉ là một tệp trên trình chạy CI.
Chiến lược báo cáo theo đối tượng
Cách dễ nhất để quyết định là ánh xạ từng trình báo cáo với người đọc nó, sau đó truyền những cái bạn cần cùng nhau.
- Một người đang quét nhật ký build ngay bây giờ sẽ đọc
cli. Luôn luôn bao gồm nó. - Một người mở báo cáo đã lưu sau này sẽ đọc
html. Lưu trữ nó như một hiện vật. - Bảng điều khiển CI đọc
junit. Đây là cái hiển thị các lỗi trong yêu cầu hợp nhất và xu hướng kết quả qua các bản build. - Một tập lệnh bạn đã viết sẽ đọc
json. Đây là định dạng duy nhất được thiết kế để mã của bạn phân tích cú pháp.
Đối với hầu hết các pipeline CI, sự kết hợp hiệu quả là HTML cho con người và JUnit cho bảng điều khiển, với CLI được bật để nhật ký thô vẫn dễ đọc:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
Một lần chạy đó tạo ra một nhật ký dễ đọc, một hiện vật có thể duyệt được và một tệp XML có thể phân tích cú pháp. Ba đối tượng, một lần thực thi, không trùng lặp.
Một lưu ý đáng nói rõ ràng: báo cáo cho bạn biết điều gì đã xảy ra, nhưng mã thoát là thứ khiến pipeline hành động dựa trên nó. Apidog CLI thoát với mã khác 0 khi bất kỳ khẳng định nào thất bại, và mã thoát đó, chứ không phải báo cáo, là thứ làm cho build thất bại và chặn việc hợp nhất. Báo cáo giải thích lỗi; mã thoát thực thi nó. Đừng gói lệnh trong bất cứ thứ gì nuốt mất mã đó, như thêm || true trong một shell, nếu không bạn sẽ nhận được một báo cáo đỏ hoàn hảo đính kèm với một bản build vẫn hiển thị màu xanh. Phiên bản sâu hơn của logic cổng chất lượng đó nằm trong hướng dẫn tự động hóa kiểm thử API trong CI/CD.
Kết hợp lại
Chạy một kịch bản trong CI và tạo ra cả ba hiện vật hữu ích cho ba đối tượng:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
Chạy quét thư mục hàng đêm, thu thập mọi lỗi vào một báo cáo, và đặt tên tự mô tả cho mỗi tệp:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
Chạy một kịch bản theo dữ liệu và giữ một tệp JSON chỉ chứa lỗi để so sánh nhanh:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
Nếu bạn không muốn cài đặt CLI toàn cục trên một trình chạy tạm thời, hãy thay đổi cài đặt bằng npx và giữ nguyên các cờ báo cáo:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
Hành vi của trình báo cáo là giống hệt nhau trong cả hai trường hợp; việc lựa chọn giữa cài đặt toàn cục và npx là về vấn đề quản lý trình chạy, không phải về loại báo cáo bạn nhận được.
Tên cờ, giá trị mặc định và trình báo cáo có thể thay đổi giữa các bản phát hành CLI, vì vậy trình chạy luôn là nguồn đáng tin cậy nhất. Chạy apidog run --help trên phiên bản bạn đã cài đặt và tin tưởng vào đó hơn bất kỳ bài viết nào, bao gồm cả bài này. Để thiết lập kịch bản mà CLI chạy ban đầu, hãy Tải Apidog, xây dựng một kịch bản trong ứng dụng, sau đó sao chép lệnh được tạo từ tab CI/CD của nó và thêm các trình báo cáo bạn cần.