Dữ liệu FDE TimesViệc làm FDE đang mở 873▼9 Thay đổi số việc đang mở trong 7 ngày, so sánh cùng phạm vi: không tính việc của các công ty mới được theo dõi tuần nàyMới trong 7 ngày 55Công ty đang tuyển 181Nhận làm từ xa 25%Lương trung vị (Mỹ) $200kTuyển nhiều nhất Databricks 98
中文EN

Tờ báo của nghề Forward Deployed Engineer

Công cụ

Bộ test API để lại cho khách có thể chỉ là vài file văn bản

Hurl chạy được trên laptop của bạn lẫn trong pipeline CI của khách, và đội của khách đọc hiểu được từng dòng.

Chia sẻLinkedInFacebookX

Tóm tắt nhanh

  • Hurl là một binary nhẹ viết bằng Rust, đọc file văn bản thuần mô tả HTTP request rồi chạy chúng
  • Cờ --test chạy song song nhiều file và in bản tóm tắt; --report-junit và --report-html sinh báo cáo cho CI
  • Với FDE, giá trị lớn nhất là để lại cho khách một bộ smoke test mà đội của họ đọc và sửa được
Hình so sánh trước và sau. Bên trái, phần "Trước": các lời gọi API nằm rải rác trong lịch sử terminal và trong collection của ai đó, nên lúc bàn giao không còn gì để chạy lại. Bên phải, phần "Sau": một file create_job.hurl được commit vào repo, review trong pull request và chạy trong CI bằng một lệnh.
Hurl gom các lời gọi API thành một file văn bản. Đội của khách commit được file đó vào repo, review trong pull request và chạy trong CI của họ bằng một lệnh.

Tuần đầu ở chỗ khách, bạn sẽ gọi API của họ cả trăm lần: lấy token, tạo bản ghi, kiểm tra trạng thái. Những lần gọi đó thường nằm rải rác trong lịch sử terminal hoặc trong một collection của ai đó. Đến lúc bàn giao thì không còn lại gì để đội của khách chạy lại.

Hurl giải quyết đúng khoảng trống này. Theo trang chính thức, đây là công cụ dòng lệnh chạy các HTTP request được định nghĩa bằng định dạng văn bản thuần. Nó là một binary nhẹ viết bằng Rust và dùng libcurl làm engine HTTP.

Dự án nằm trong tổ chức Orange-OpenSource trên GitHub, dùng giấy phép Apache-2.0; nếu khách có quy trình duyệt phần mềm mã nguồn mở, bạn nên hỏi sớm xem giấy phép này có nằm trong danh sách được phép không.

Với một FDE, điểm đáng giá không nằm ở tốc độ. Nó nằm ở chỗ một file văn bản có thể commit vào repo của khách, review trong pull request và chạy trong CI của họ bằng đúng một lệnh.

Một file, cả một luồng nghiệp vụ

Thử hình dung bạn tích hợp với API điều phối job của khách. Luồng cần kiểm là tạo job, lấy id, rồi xác nhận job đang chạy. Viết bằng Hurl, file integration/create_job.hurl có thể trông như sau:

# Tạo job mới
POST https://{{host}}/api/jobs
Content-Type: application/json
{
  "name": "nightly-sync"
}
HTTP 201
[Captures]
job_id: jsonpath "$.id"

# Kiểm tra job vừa tạo
GET https://{{host}}/api/jobs/{{job_id}}
HTTP 200
[Asserts]
jsonpath "$.state" == "running"

Mỗi khối là một request kèm dòng status mong đợi. Mục [Captures] lấy một giá trị từ response để request sau dùng lại. README của Hurl minh họa việc này bằng XPath, khi lấy CSRF token từ thẻ meta của một trang HTML. Mục [Asserts] thì kiểm tra nội dung trả về, chẳng hạn so sánh một trường JSON qua JSONPath như tài liệu mẫu chính thức.

Chi tiết đáng chú ý là {{host}}. Bạn không ghi cứng địa chỉ staging hay production vào file, vì thế cùng một bộ test chạy được trên mọi môi trường của khách.

Từ laptop sang CI chỉ cần thêm cờ

Khi gỡ lỗi, bạn chạy file bình thường để xem response cuối cùng. Khi muốn kiểm thử, thêm cờ --test. Tài liệu của Hurl cho biết chế độ này thêm bản tóm tắt lần chạy và tắt phần in response cuối, còn các assert vẫn chạy. Nhiều file .hurl cũng được chạy song song để rút ngắn thời gian.

Hướng dẫn tích hợp CI/CD chính thức đưa ra một lệnh gần như dùng được ngay:

hurl --variable host="$1" --test integration/*.hurl

Thêm --report-junit report.xml là hầu hết hệ thống CI đọc được kết quả và hiển thị test nào hỏng. Hurl còn xuất báo cáo dạng text, TAP và HTML, trong đó HTML được sinh bằng --report-html DIR để người không quen đọc log cũng xem được.

Cài đặt cũng không làm khó bạn. Hurl có trên Homebrew, Cargo và có Docker image chính thức tại ghcr.io/orange-opensource/hurl. Ở những công ty khóa chặt máy build, chạy qua image Docker thường là con đường ít phải xin phép nhất.

Hai cái bẫy trước khi đưa vào pipeline của khách

Cái bẫy thứ nhất đến từ chính tính năng chạy song song. Nếu file A tạo dữ liệu mà file B cần, hai file có thể chạy cùng lúc và test sẽ hỏng lúc được lúc không. Nguyên tắc an toàn là giữ mỗi file tự đủ: luồng nào cần nối request thì để trong cùng một file và truyền dữ liệu bằng capture.

Cái bẫy thứ hai nằm ở báo cáo HTML. Tài liệu ghi rõ kết quả mới được nối thêm vào báo cáo cũ. Trên một runner CI dùng lại thư mục làm việc, bạn nên xóa thư mục báo cáo trước mỗi lần chạy, nếu không người xem sẽ lẫn kết quả hôm nay với hôm qua.

Cũng nên hiểu đúng phạm vi của công cụ. Hurl kiểm tra hành vi HTTP nhìn từ bên ngoài. Nó cho bạn biết API trả sai, nhưng muốn biết vì sao thì bạn vẫn phải đọc log và code phía khách.

Nên học gì trước

Nắm ba thứ theo thứ tự: cấu trúc một khối request và dòng status, cách capture giá trị để nối request, rồi cú pháp JSONPath cho assert. Đủ ba thứ đó là bạn viết được smoke test cho phần lớn API REST. Sau đó mới đến --variable, --test và các cờ báo cáo.

Ở chỗ khách, việc nên làm đầu tiên là viết một file kiểm tra endpoint quan trọng nhất của bản tích hợp, commit vào repo của họ và chạy nó trong CI trước buổi demo đầu tiên. Từ đó, mỗi lỗi bạn tìm ra nên đi kèm một file .hurl tái hiện được lỗi đó.

Cố tình làm hỏng một test trước khi tin nó

Một bài tập nhỏ đáng làm trước khi giao bộ test cho khách: trong file ví dụ ở trên, đổi "running" thành một giá trị chắc chắn sai, như "no-such-state". Rồi chạy hurl --variable host=... --test --report-junit report.xml integration/*.hurl.

Việc của bạn là đọc ba chỗ. Bản tóm tắt cuối lần chạy phải cho thấy file create_job.hurl hỏng trong khi các file khác vẫn qua. File report.xml phải ghi nhận đúng lần hỏng đó, và khi đưa lên job CI thử nghiệm, pipeline phải chuyển sang đỏ.

Nếu một trong ba chỗ không phản ánh lỗi, bộ test của bạn chưa đáng tin, dù hôm nay mọi thứ đều xanh. Sửa assert về giá trị đúng, chạy lại, và chỉ bàn giao khi đã thấy nó vừa biết đỏ vừa biết xanh.

Về mặt nghề nghiệp, một thư mục .hurl trong repo portfolio cho nhà tuyển dụng thấy bạn biết kiểm thử một API mà bạn không viết ra. Khi tin tuyển dụng FDE nhắc đến “API integration” hay “CI/CD”, hãy ghi vào CV kết quả cụ thể, chẳng hạn bạn đã dựng bộ smoke test chạy trên pipeline của khách, thay vì chỉ liệt kê tên công cụ.

Khi bạn rời dự án, code tích hợp có thể sẽ bị viết lại. Những file văn bản ghi rõ API phải trả về gì thì thường ở lại lâu hơn thế.

Bài này có hữu ích không?

Dùng cùng trợ lý AIHỏi Claude ↗Hỏi ChatGPT ↗
7 nguồn
Đọc tiếp trên lộ trình · Chặng 2: Kỹ thuật rộngVì sao FDE nên sở hữu code giao diện thay vì cài thư viện UIshadcn/ui chép component thẳng vào repo của bạn, nên màn hình quản trị sửa được theo ý khách mà không phải chờ ai.