# 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.

Bản gốc: https://fdetimes.net/vi/cong-cu/hurl-test-api-khach-bang-file-van-ban/

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:

```hurl
# 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:

```bash
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.

**Điểm mấu chốt:** Bộ test tốt nhất để lại cho khách là bộ mà đội của họ đọc hiểu được mà không cần bạn.

## 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ế.

**Thử ngay tuần này:**

- Cài Hurl bằng Homebrew, Cargo hoặc Docker image chính thức, rồi viết một file .hurl gọi endpoint health của một API bạn đang tích hợp
- Viết thêm một file nối hai request: capture một id từ request đầu rồi assert trạng thái ở request sau
- Chạy cả thư mục với --test và --report-junit, rồi đưa lệnh đó vào một job CI thử nghiệm

## Nguồn

- [Hurl - Run and Test HTTP Requests](https://hurl.dev/)

- [Orange-OpenSource/hurl: Hurl, run and test HTTP requests with plain text](https://github.com/Orange-OpenSource/hurl)

- [Running Tests - Hurl Documentation](https://hurl.dev/docs/running-tests.html)

- [CI/CD Integration - Hurl Tutorial](https://hurl.dev/docs/tutorial/ci-cd-integration.html)

- [hurl 6.0.0 README (docs.rs)](https://docs.rs/crate/hurl/6.0.0/source/README.md)

- [Samples - Hurl Documentation](https://hurl.dev/docs/samples.html)

- [Installation - Hurl Documentation](https://hurl.dev/docs/installation.html)
