Keploy tự động tạo API test từ traffic thật

Thứ sáu cuối tuần, bạn sửa một dòng code trong API thanh toán: chỉ đổi thứ tự một field trong response cho khớp tài liệu mới của đối tác. Unit test vẫn xanh. Sau deploy, app cũ của khách hàng báo lỗi, cron job đồng bộ đơn hàng chạy lệch, webhook trả về trạng thái mà hệ thống kho không nhận ra. Không ai nhớ luồng đó đi qua những service nào, vì API đã chạy ba năm, người viết đầu tiên đã nghỉ, còn test viết tay chỉ bao phủ những đường đi người viết test nghĩ ra vào thời điểm đó.

Vấn đề không nằm ở kỷ luật viết test. Để viết test cho API đang chạy, bạn phải dựng lại toàn bộ thế giới xung quanh nó — Postgres, hàng đợi message, API đối tác — rồi đoán client thật đã gửi những gì. Trong khi đó, traffic thật đi qua hệ thống mỗi ngày, mang theo trường hợp biên, client cũ và luồng nghiệp vụ mà không tài liệu nào ghi lại. Bài này nói về cách tận dụng chính traffic đó: ghi lại rồi phát lại thành test.

Vấn đề thực tế: API đã chạy ổn định nhưng không có bộ test nào dám chạm vào

Sửa một dòng code, vỡ một luồng nghiệp vụ không ai nhớ

API kế thừa thường đi kèm database đã phình to, hàng đợi message mà vài consumer không còn ai rõ, và API đối tác mà hợp đồng tích hợp chỉ còn trong email cũ. Viết test tay cho hệ thống như vậy đồng nghĩa dựng lại toàn bộ hạ tầng phụ thuộc, tạo fixture cho từng bảng, giả lập từng message, rồi hy vọng đoán đúng request và response mà client thật vẫn đang dùng.

Test viết tay còn có điểm mù cố hữu: nó chỉ bao phủ đường đi người viết nghĩ ra. Traffic thật chứa request từ app mobile cũ mà team đã ngừng hỗ trợ trên giấy tờ nhưng khách hàng vẫn dùng, cron job chạy lúc 2 giờ sáng, webhook retry sau timeout, field client gửi thừa nhưng server vẫn âm thầm xử lý. Khi bộ test không thấy những luồng đó, mỗi lần refactor đều là đánh cược.

Vì sao mock HTTP thuần túy chưa đủ

Mock HTTP chỉ chặn request HTTP đi ra ngoài và trả về response cố định. Nhưng API thật hiếm khi chỉ nói chuyện bằng HTTP. Nó truy vấn Postgres, ghi MongoDB, đẩy event lên Kafka, chờ consumer xử lý rồi mới trả kết quả. Nếu chỉ mock tầng HTTP, phần còn lại vẫn phải dựng thật hoặc mock rời rạc bằng tay, và test chạy được trên máy dev vẫn có thể sai lệch ở môi trường tích hợp.

Keploy là gì và giải quyết vấn đề nào

Keploy là nền tảng mã nguồn mở, giấy phép Apache-2.0, tạo test cho API, integration và E2E test bằng cách ghi lại traffic thật rồi phát lại thành test. Dự án ở repo github.com/keploy/keploy, khoảng 19.346 stars và 2.448 forks, bản v3.6.216 phát hành ngày 2026-11-03. Nó ghi không chỉ API call mà cả truy vấn database và streaming event, rồi phát lại toàn bộ như bộ test có assertion, không cần sửa code ứng dụng hay gắn SDK.

Cách làm này giải quyết đúng bài toán ở đầu bài: thay vì đoán traffic, bạn ghi lại traffic đã xảy ra, rồi dùng chính bản ghi đó làm lưới an toàn cho lần sửa code tiếp theo. Test sinh ra không chứng minh code đúng theo đặc tả — phần cuối bài sẽ nói rõ — nhưng nó chứng minh code mới vẫn cư xử giống code cũ trên những luồng đã từng chạy thật.

Ai nên dùng Keploy, ai chưa cần vội

Keploy phù hợp với backend developer, QA, DevOps/SRE và sysadmin vận hành API có phụ thuộc database, hàng đợi hoặc API ngoài, đặc biệt API legacy sắp refactor nhưng thiếu test. Ngược lại, dự án mới chưa có traffic thật thì không có gì để ghi. API còn đổi schema hàng ngày cũng chưa nên khóa test vội, vì mỗi lần đổi schema là một lần phải ghi lại. Hệ thống cần chứng minh tính đúng đắn theo đặc tả — logic tính toán, phân quyền, hợp đồng API giữa các team — vẫn cần test viết theo đặc tả và contract test, vì replay chỉ so sánh với quá khứ.

Kiến trúc và cơ chế hoạt động của Keploy

Luồng record: chặn traffic ở tầng mạng, không chạm code ứng dụng

Điểm chặn của Keploy nằm ngoài code ứng dụng. Trên Linux, nó bắt network call bằng eBPF; trên macOS Apple Silicon và Windows x86-64, nó dùng hook ở user space. Vì không cần SDK, nó không phụ thuộc ngôn ngữ: ứng dụng Python, Go, Java hay Node.js đều ghi theo cùng một cách, miễn là chạy được dưới lệnh Keploy điều khiển.

Trong lúc record, Keploy ghi đồng thời request và response của ứng dụng cùng toàn bộ tương tác với hạ tầng phụ thuộc — truy vấn Postgres, MySQL, MongoDB, event Kafka, RabbitMQ và response từ API ngoài. Kết quả là một cặp tài sản: testcase giữ request đầu vào và response kỳ vọng, mock giữ dữ liệu hạ tầng phụ thuộc đã trả về, theo đúng thứ tự và ngữ cảnh.

Luồng replay: mock server thay toàn bộ hạ tầng phụ thuộc

Khi chạy test, Keploy khởi động lại ứng dụng bằng đúng lệnh đã dùng lúc record, nhưng thay toàn bộ hạ tầng phụ thuộc bằng một mock server. Database không cần dựng thật, Kafka không cần chạy thật, API đối tác không cần gọi thật. Nhờ đó bộ test chạy offline, trên máy dev hoặc trong CI, mà không cần duy trì cụm phụ thuộc riêng cho test.

Hai cơ chế giúp replay ổn định. Time freezing cố định thời gian trong lúc replay, để logic phụ thuộc thời gian không cho kết quả khác nhau mỗi lần chạy. Diff engine so sánh response thực tế với response đã ghi và báo rõ điểm lệch, thay vì chỉ báo pass hay fail chung chung. Keploy còn mở rộng coverage từ bản ghi kết hợp schema OpenAPI: phát hiện giá trị biên, field thiếu hoặc thừa, sai kiểu dữ liệu, sai thứ tự và trường hợp retry hay timeout. Theo mình, phần này cần QA duyệt tay, vì ca sinh từ schema có thể hợp lệ về kiểu dữ liệu nhưng vô nghĩa về nghiệp vụ.

Báo cáo coverage chia theo đối tượng: statement và branch coverage cho developer, API schema và business coverage cho QA. Mock dùng chung được quản lý qua mock registry, để nhiều service hoặc pipeline cùng dùng một kho mock mà không copy file lung tung.

Giới hạn kỹ thuật cần hiểu trước khi dùng

Giới hạn quan trọng nhất: Keploy chỉ bao phủ đường đi từng xuất hiện trong traffic đã ghi. Endpoint chưa từng được gọi, nhánh lỗi chưa từng xảy ra, ca biên chưa từng xuất hiện ngoài production sẽ không có test, bất kể AI có sinh thêm ca từ schema hay không, vì ca sinh vẫn cần người duyệt tính hợp lệ nghiệp vụ.

Giới hạn thứ hai là dữ liệu phi xác định: timestamp, UUID, số ngẫu nhiên, sequence của database, thứ tự message và response từ API ngoài thay đổi theo thời gian đều là nguồn gây flaky nếu không được khử nhiễu. Giới hạn thứ ba là độ trung thực khác nhau giữa eBPF trên Linux và hook user space trên macOS và Windows — test pass trên máy dev chưa chắc pass trong CI chạy Linux, nên cần chuẩn hóa môi trường chạy test. Cuối cùng, các yêu cầu cụ thể về phiên bản kernel Linux và chế độ chạy Docker như privileged hay host-network, mình chưa đối chiếu được với trang platform-requirements chính thức của dự án, nên bài này không nêu con số hay yêu cầu cụ thể nào cho hai mục đó. Hãy kiểm tra trang đó trước khi triển khai trên Linux hoặc trong container.

Sơ đồ duy nhất của bài viết

flowchart TB
    subgraph Record["Làn RECORD — ghi traffic thật"]
        A1[Client / traffic thật] --> A2[Ứng dụng đang chạy]
        A2 --> A3[Bộ chặn Keploy<br/>eBPF trên Linux / hook user-space<br/>trên macOS, Windows — ngoài code]
        A3 --> A4a[Ghi request/response API]
        A3 --> A4b[Ghi truy vấn Postgres / MySQL / MongoDB,<br/>event Kafka / RabbitMQ, response API ngoài]
        A4a --> A5[Kho ghi: Testcase + Mock]
        A4b --> A5
    end
    subgraph Replay["Làn REPLAY — so sánh với quá khứ"]
        B1[Test Runner] --> B2[Khởi động lại ứng dụng<br/>bằng cùng lệnh]
        B2 --> B3[Mock Server thay toàn bộ<br/>DB / queue / API ngoài]
        B3 --> B4[Ứng dụng xử lý, trả response]
        B4 --> B5[Diff Engine so sánh response thực tế<br/>với response đã ghi — có Time Freeze]
        B5 --> B6[Báo cáo pass/fail và coverage]
    end
    A5 -.-> B1

Sơ đồ thể hiện ba ý chính: điểm chặn nằm ngoài code ứng dụng, mock thay toàn bộ hạ tầng phụ thuộc chứ không chỉ chặn HTTP, và replay là so sánh với quá khứ chứ không phải đối chiếu đặc tả.

Hướng dẫn triển khai Keploy: từ cài đặt đến test đầu tiên

Điều kiện tiên quyết và phiên bản tham chiếu

Phiên bản tham chiếu là v3.6.216, phát hành ngày 2026-11-03. Môi trường hỗ trợ theo tài liệu của dự án gồm Linux với eBPF, macOS Apple Silicon và Windows x86-64 với hook user space. Bạn cần curl để tải installer và một lệnh chạy được ứng dụng, ví dụ python main.py. Phần này mình chưa chạy thử thực tế, chỉ đối chiếu tài liệu. Nguyên tắc trước khi record: chỉ ghi traffic trên staging, hoặc trên traffic đã tách dữ liệu nhạy cảm.

Cài đặt Keploy

Lệnh cài đặt theo hướng dẫn Quick Start của dự án:

source /dev/stdin <<<"$(curl -fsSL https://keploy.io/install.sh || echo 'echo Keploy installer download failed >&2; return 1')"

Phương án thay thế từ trang chủ của dự án, nếu bạn muốn xem file installer trước khi chạy:

curl --silent -O -L https://keploy.io/install.sh && source install.sh

Kiểm tra cài đặt bằng keploy --help. Kết quả kỳ vọng: CLI phản hồi và liệt kê các lệnh record và test.

Record traffic thật và chạy lại bộ test

Bắt đầu record bằng cách cho Keploy chạy ứng dụng của bạn:

keploy record -c "python main.py"

Thay python main.py bằng lệnh khởi động thật của ứng dụng. Trong lúc record đang chạy, tạo traffic thật qua ứng dụng: gọi các API chính, chạy qua luồng nghiệp vụ quan trọng, để cả cron job hoặc webhook nếu có thể. Khi đã đủ traffic, dừng record để Keploy sinh testcase và mock.

Chạy lại bộ test bằng:

keploy test -c "python main.py" --delay 10

Tham số --delay 10 cho ứng dụng thời gian khởi động trước khi test bắt đầu. Kết quả kỳ vọng: báo cáo từng testcase pass hay fail, kèm diff khi response lệch khỏi bản ghi. Sau khi bộ test ổn định, đưa testcase và mock vào Git để team cùng dùng và chạy lại offline, không cần dựng lại database, hàng đợi hay API ngoài. Theo mình, lần record đầu tiên nên chọn một service và một luồng nghiệp vụ, thay vì ghi toàn bộ hệ thống.

Đưa Keploy vào CI/CD và rollback

Keploy chạy qua CLI nên đưa vào GitHub Actions, Jenkins hoặc Kubernetes không cần kiến trúc riêng. Giai đoạn đầu, hãy để bước Keploy chạy song song, không chặn pipeline, để đo độ flaky thực tế qua nhiều lần chạy. Khi tỷ lệ fail giả đã thấp và team đã quen cách đọc diff, mới chuyển dần sang chặn release. Mock dùng chung nên đưa qua mock registry thay vì copy file giữa các repo. Khi schema đổi, ghi lại traffic thay vì sửa tay file mock đã ghi.

Rollback cũng đơn giản, vì Keploy không sửa code ứng dụng: khi cần dừng, tắt bước Keploy trong CI và gỡ mock khỏi pipeline, bộ test viết tay hiện có không bị ảnh hưởng. Giữ nguyên bộ test cũ trong suốt giai đoạn chạy song song chính là phương án rollback an toàn nhất.

Lỗi thường gặp và cách xử lý

Không ghi được traffic trên Linux thường liên quan đến quyền của cơ chế bắt gói và cách ứng dụng đang chạy, ví dụ trong container hay máy ảo. Hướng xử lý là kiểm tra lại quyền chạy và tài liệu platform-requirements chính thức, thay vì đoán yêu cầu quyền cụ thể khi tài liệu chưa xác nhận.

Test flaky thường do timestamp, ID ngẫu nhiên, sequence của database hoặc thứ tự message. Cách xử lý là dùng denoising và time freezing của Keploy, đồng thời loại trừ các field phi xác định khỏi phép so sánh, sau khi xác nhận field đó thực sự không ảnh hưởng nghiệp vụ. Mock lỗi thời sau khi đổi schema sẽ gây fail hàng loạt hoặc pass giả; cách xử lý đáng tin là ghi lại traffic theo phiên bản schema mới và gắn mock với commit tương ứng. Test pass nhưng hành vi vẫn sai không phải lỗi công cụ, mà là bản chất của replay — nó chỉ chứng minh hành vi giống quá khứ, và quá khứ đó có thể đã chứa bug.

Đánh giá kỹ thuật: ưu điểm, nhược điểm, bảo mật và vận hành

Ưu điểm

Ưu điểm lớn nhất là tốc độ tạo regression test: không cần SDK, không sửa code, không phụ thuộc ngôn ngữ, và test sinh ra từ traffic thật thay vì từ trí tưởng tượng của người viết test. Ưu điểm thứ hai là mock đa tầng: cả database, Kafka, Postgres, MongoDB và API ngoài đều được thay bằng mock, nên test chạy offline và giảm chi phí dựng môi trường. Ưu điểm thứ ba là giá trị regression: sau mỗi lần sửa code, replay chỉ ra ngay response nào lệch khỏi quá khứ, trước khi thay đổi đó chạm tới người dùng.

Nhược điểm và chi phí ẩn

Nhược điểm lớn nhất: test bị khóa vào hành vi quá khứ. Nếu traffic ghi chứa response sai, dữ liệu bẩn hoặc logic đã lỗi thời, Keploy sẽ khóa lỗi đó thành “đúng” và báo fail khi có người sửa đúng. Vì vậy traffic ghi phải được tuyển chọn và duyệt như code, và mỗi ca fail cần phân loại trước: đây là bug mới, hay sửa đúng làm lệch quá khứ.

Chi phí ẩn thứ hai là bảo trì mock: schema đổi là phải ghi lại, kho mock phình to theo traffic, cần chính sách đặt tên, dọn dẹp và gắn phiên bản. Chi phí ẩn thứ ba là niềm tin giả: bộ test xanh 100% có thể khiến team chủ quan, trong khi nó chỉ bao phủ những đường đi đã từng xảy ra. Bài này không nêu số liệu hiệu năng hay khả năng mở rộng, vì không có số liệu nào được kiểm chứng độc lập — mọi đánh giá ở đây chỉ ở mức định tính.

Bảo mật: recording chính là bản sao dữ liệu thật

Testcase và mock có thể chứa token, thông tin cá nhân và dữ liệu production, vì chúng là bản sao của traffic thật. Trước khi commit, phải rà soát và tẩy dữ liệu nhạy cảm, kiểm soát quyền truy cập repo và log CI, quét secret trước commit. Repo chứa mock nên để riêng tư, và pipeline cần chính sách rõ về việc ai được xem file ghi.

Ngoài ra, cơ chế bắt gói ở tầng hệ thống và chế độ chạy container với quyền cao — nếu áp dụng — đều mở rộng bề mặt tấn công của host chạy test. Vì vậy chỉ chạy record trên môi trường staging hoặc CI biệt lập, không record trực tiếp production khi chưa có chính sách phê duyệt và tách dữ liệu nhạy cảm.

Khả năng vận hành cho DevOps và sysadmin

Với team nhỏ, vận hành Keploy khá nhẹ: CLI độc lập, tích hợp CI sẵn có, không cần cụm hạ tầng riêng cho test. Khi lên quy mô nhiều service, phần nặng nằm ở quản trị vòng đời mock và độ ổn định của replay: mock của service nào thuộc phiên bản schema nào, ghi lại khi nào, ai duyệt diff khi regenerate. Theo mình, đây là phần quyết định Keploy có trụ được lâu dài hay chỉ là thử nghiệm vài tuần rồi bị bỏ.

So sánh Keploy với các giải pháp cùng phạm vi

Tiêu chí so sánh gồm: phạm vi ghi, có cần sửa code hay gắn SDK không, chạy offline được không, tính xác định của replay, chi phí bảo trì khi schema đổi, và tích hợp CI/CD.

Kết luận so sánh khá rõ: Keploy thắng ở tốc độ tạo regression test từ hệ thống đang chạy, và thua ở khả năng chứng minh tính đúng đắn theo đặc tả. Hai việc đó bổ sung cho nhau, không thay thế nhau. Team làm đúng sẽ dùng Keploy làm lưới regression, và giữ test theo đặc tả cùng contract test cho những hành vi bắt buộc phải đúng.

Trường hợp sử dụng thực tế

Doanh nghiệp: khóa regression cho API legacy trước khi refactor. Ghi traffic staging của API legacy, rồi refactor, rồi replay để phát hiện response lệch trước khi release. Team không cần viết lại toàn bộ test trước khi dám chạm vào code cũ — bản ghi traffic chính là đặc tả thực tế của hệ thống, dù là đặc tả của quá khứ.

Homelab và sysadmin: test API tự host mà không dựng lại stack. Với service tự host có Postgres hay Kafka, duy trì cụm phụ thuộc riêng chỉ để test là tốn kém. Replay offline cho phép chạy test mà không cần cụm đó, miễn là bản ghi còn khớp phiên bản service đang chạy. Khi service đổi schema, ghi lại là xong.

Quy trình DevOps: kiểm thử API không cần SDK trong CI. Keploy là một bước CLI chạy song song trước, rồi chặn release sau khi đã ổn định. Vì không sửa code ứng dụng, bước này gắn vào pipeline hiện có mà không đụng tới codebase.

Quy trình AI và QA: mở rộng coverage từ recording và OpenAPI. QA dùng tính năng mở rộng coverage để sinh thêm ca biên, rồi duyệt tay từng ca trước khi đưa vào bộ test chính thức. Ca sinh ra giúp phát hiện field thiếu, sai kiểu hay sai thứ tự, nhưng quyết định ca nào hợp lệ về nghiệp vụ vẫn thuộc về QA.

Kết luận: ai nên dùng Keploy và bước tiếp theo

Keploy phù hợp với team có API đang chạy, phụ thuộc phức tạp, cần regression test nhanh mà không viết lại toàn bộ test từ đầu. Nó không phù hợp với dự án chưa có traffic, hệ thống cần kiểm chứng theo đặc tả, hoặc môi trường cấm ghi dữ liệu thật vì lý do bảo mật. Nếu bạn thuộc nhóm đầu, bước tiếp theo rất cụ thể: chọn một service, một luồng nghiệp vụ, ghi traffic trên staging, chạy replay cho ổn định, rồi mới mở rộng sang CI chặn release.

Để đối chiếu record/replay với một góc nhìn khác về kiểm thử API — một bên khóa regression, một bên tìm lỗ hổng — bạn có thể đọc thêm bài Shannon AI pentester cho web app và API trên cùng blog này.

Bài học rút ra

1. Replay chứng minh sự giống nhau, không chứng minh sự đúng đắn: test pass chỉ nghĩa là hành vi chưa đổi so với bản ghi, không nghĩa là hành vi đó đúng.
2. Chất lượng test bằng chất lượng traffic đã ghi: ghi traffic bẩn, chứa bug hoặc dữ liệu lỗi, là khóa bug đó thành chuẩn.
3. Mock là tài sản cần vòng đời: ghi lại khi schema đổi, đặt tên rõ ràng, dọn dẹp mock cũ và gắn mock với commit tương ứng.
4. Dữ liệu ghi là dữ liệu thật: xử lý testcase và mock như dữ liệu production — rà soát, tẩy nhạy cảm và kiểm soát quyền truy cập trước khi commit.
5. Chạy song song trước khi chặn pipeline: đo độ flaky thực tế qua nhiều lần chạy rồi mới để Keploy chặn release, nếu không CI sẽ mất tin cậy rất nhanh.

Phạm vi xác minh

Ngày kiểm tra: 2026-11-04. Đã xác minh repo github.com/keploy/keploy, giấy phép Apache-2.0, số stars và forks, bản phát hành v3.6.216 ngày 2026-11-03 và lệnh cài đặt, record, test theo tài liệu chính thức của dự án. Hỗ trợ nền tảng Linux, macOS, Windows và tích hợp CI là tài liệu của hãng, chưa kiểm chứng độc lập. Các con số về phiên bản kernel Linux và yêu cầu Docker privileged hay host-network đến từ nguồn thứ cấp, chưa đối chiếu với tài liệu platform-requirements chính thức nên không được nêu trong bài. Không có benchmark hiệu năng nào được trình bày, vì không có số liệu đo được. Tính năng AI mở rộng coverage và báo cáo coverage là hành vi theo tài liệu của dự án, còn dùng mock registry và chạy Keploy chặn release là cấu hình vận hành do team tự chọn. Phần này mình chưa cài đặt hay chạy thử thực tế.

Tài liệu tham khảo

• Keploy trên GitHub: https://github.com/keploy/keploy
• Hướng dẫn cài đặt: https://keploy.io/docs/server/installation/
• Keploy hoạt động như thế nào: https://keploy.io/docs/keploy-explained/how-keploy-works/
• Lệnh CLI của Keploy: https://keploy.io/docs/running-keploy/cli-commands/