Kiểm thử agent

Tài liệu này là chiến lược kiểm thử của agent. Kiểm thử tải nhiều agent (agentsim) và đa tenant thuộc phía Collector và nền tảng, agent cung cấp internal/mockcollector để kiểm thử độc lập.

7 phút đọcCập nhật 02/10/2026access-hub-agent, docs/08-testing.md

Nguyên tắc

1. Logic chung (chuẩn hóa, WAL, sender, cấu hình) kiểm thử được trên mọi hệ điều hành mà không cần máy thật.
2. Mã đặc thù nền tảng (đọc /proc, PDH) kiểm thử bằng fixture ghi sẵn ở tầng đơn vị, và bằng máy thật ở tầng tích hợp.
3. Không kiểm thử phụ thuộc mạng ngoài, dùng mockcollector cục bộ.
4. Mọi lỗi đã gặp ngoài thực tế thành một ca kiểm thử hồi quy.

Các tầng

Tầng	Nội dung	Công cụ
Đơn vị	Phân tích /proc/stat, /proc/meminfo, /proc/net/dev, mountinfo, tính tốc độ từ bộ đếm (quay vòng, mẫu đầu bị bỏ), lọc fstype và giao diện, chuẩn hóa nhãn, giới hạn series, phân tích cấu hình, backoff, WAL	go test, bảng ca kiểm thử (table driven)
Fixture Linux	Bộ test/fixtures/proc/<distro>-<kernel>/ ghi từ máy thật (Ubuntu 18.04, 22.04, Debian 10, RHEL 7, 9, Amazon Linux 2)	Lấy bằng collect-fixture (công cụ dev)
Windows	Logic bộ thu kiểm thử bằng windows.API giả trên mọi máy (CPU, RAM, đĩa, mạng, bảng cổng, tên hệ điều hành). Lớp gọi hệ thống chỉ biên dịch chéo (GOOS=windows, amd64 và arm64) kèm kiểm tra kích thước cấu trúc lúc biên dịch. Dịch vụ Windows: SID dịch vụ (so với giá trị TrustedInstaller đã công bố), SDDL, thứ tự cài đặt (khóa thư mục trước khi ghi tệp, đóng an toàn khi khóa lỗi), gỡ giữ dữ liệu, ánh xạ mã thoát sang SCM, cờ --windows-service đều kiểm thử bằng SCM giả. Còn thiếu: chạy trên máy thật hoặc runner Windows của CI, kiểm tra giá trị hợp lý, không rò rỉ handle, ngôn ngữ không phải tiếng Anh	GitHub Actions windows-latest hoặc runner tự dựng, máy ảo đa ngôn ngữ
Tích hợp với mock	Enroll, gửi, nhận lỗi, backoff, Retry-After, 401 dừng, 403 dừng, 413 tách, thay đổi config_etag	mockcollector (một chương trình Go nhỏ, kịch bản cấu hình được)
Độ bền	Kill -9 giữa lúc ghi WAL, đầy đĩa, quyền tệp sai, đồng hồ nhảy, đổi giờ	Kịch bản, fault injection ở tầng tệp
Fuzz	Phân tích cấu hình, phân tích WAL, phân tích phản hồi collector	go test -fuzz (giới hạn thời gian trong CI)
Đua dữ liệu	Toàn bộ	go test -race
Rò rỉ	Goroutine, handle, RSS trong 24 giờ thu thập tăng tốc	Kiểm thử soak (interval: 1s) với pprof
Hiệu năng	Benchmark thu thập, chuẩn hóa, mã hóa protobuf. So với ngân sách	go test -bench, ngưỡng trong CI (cảnh báo khi tăng quá 20%)
Gói	Cài, nâng cấp N-1, gỡ, purge, cài lại, khởi động lại máy, quyền, dịch vụ	Máy ảo (Vagrant hoặc cloud), kịch bản trong test/packaging/
Bảo mật	Che bí mật trong log, quyền tệp thông tin đăng nhập, cấu hình từ xa độc hại, chặn link-local, xác minh chữ ký cập nhật	Kiểm thử đơn vị và tích hợp

Ma trận kiểm thử phát hành

Nền tảng	Phiên bản	Bắt buộc mỗi bản phát hành
Ubuntu	20.04, 22.04, 24.04 (18.04 mỗi quý)	Cài, nâng cấp, gỡ, chạy 1 giờ
Debian	11, 12 (10 mỗi quý)	như trên
RHEL family	Rocky 8, 9, CentOS 7 (mỗi quý), Amazon Linux 2, 2023	như trên
Windows	10 22H2, 11, Server 2016, 2019, 2022	Cài im lặng, nâng cấp, gỡ, chạy 1 giờ, thêm 1 máy ngôn ngữ không phải tiếng Anh
Kiến trúc	amd64 (bắt buộc), arm64 (GĐ 3)

Ca kiểm thử quan trọng (danh sách tối thiểu)

Thu thập

• CPU: hai mẫu /proc/stat cho kết quả đúng, bộ đếm quay vòng không cho số âm, mẫu đầu không phát ra.
• Bộ nhớ: dùng MemAvailable, hỗ trợ kernel cũ không có MemAvailable (ước tính từ Free + Buffers + Cached).
• Đĩa: bỏ mount ảo, bỏ mount dưới /var/lib/docker, xử lý mount treo NFS (thời gian chờ mỗi mount, không làm treo agent).
• Mạng: giao diện xuất hiện và biến mất giữa các chu kỳ, bộ đếm reset.
• Windows: bộ đếm mạng cần hai mẫu, giao diện có ký tự đặc biệt hoặc trùng tên, ổ đĩa quang bị bỏ, ổ tháo rời rỗng không được hiện hộp thoại (SetErrorMode), bộ đếm 64 bit giảm là reset.

Truyền

• Bảng mã lỗi 400, 401, 403, 409, 413, 422, 426, 429, 5xx đúng hành vi.
• Retry-After cả dạng giây và ngày HTTP.
• Backoff không vượt trần, có jitter.
• Gửi bù đúng thứ tự cũ trước, không dồn tải (giới hạn tốc độ).
• Lô rỗng vẫn được gửi làm heartbeat.
• Độ lệch đồng hồ 10 phút: agent bù, không bị collector từ chối.

Độ bền

• Ngắt giữa lúc ghi bản ghi WAL: khởi động lại bỏ bản ghi dở, giữ phần còn lại.
• Hết dung lượng đĩa: agent không sập, bỏ mẫu và đếm.
• Thông tin đăng nhập hỏng hoặc rỗng: trạng thái rõ ràng, không lặp vô hạn.
• Ghi thông tin đăng nhập nguyên tử: mất điện giữa xoay token vẫn giữ token cũ hợp lệ. Xoay token: TestRenewsWhenDueSavesBeforeUsing, TestSaveFailureKeepsOldTokenAndRetriesWithIt, TestFailuresKeepTheOldTokenAndRetry, TestOldTokenIsRenewedAndUsedAfterwards (mock collector có chồng 24 giờ), TestFirstFailureWarnsRepeatsAreDebug.

Bảo mật

• Log không chứa chuỗi ahat_ hay ahet_ ở mọi cấp log, kể cả debug.
• diag không chứa bí mật (TestDiagBundleHasNoSecrets, TestDiagRefusesABundleThatWouldLeakAToken).
• Cấu hình từ xa có khóa lạ, regex khổng lồ, 1.000 check, đích 169.254.169.254: bị từ chối hoặc cắt (TestMergeRefusesUnsafeValues, TestMergeHonoursAllowRemoteConfigFalse).
• Manifest cập nhật chữ ký sai, phiên bản thấp hơn: bị từ chối.
• machine_id đổi: dừng gửi.

CI

Chạy mỗi PR:

1. gofmt, golangci-lint, go vet.
2. go test -race ./... trên linux amd64, windows amd64.
3. Dựng chéo (linux arm64, windows arm64) để bắt lỗi biên dịch.
4. govulncheck.
5. Kiểm tra kích thước binary (không vượt 20 MB) và không có CGO (go version -m hoặc kiểm ldd).
6. Fuzz ngắn (30 giây mỗi mục tiêu).

Chạy hằng đêm: soak ngắn, benchmark, fuzz dài, kiểm thử gói trên máy ảo.

Chạy khi phát hành: ma trận đầy đủ, ký, SBOM.

Tiêu chí chất lượng

• Độ phủ dòng của logic chung từ 80%, gói wal và sender từ 90%.
• Không có TODO không có mã việc tham chiếu.
• Mọi khóa cấu hình mới có kiểm thử và cập nhật 04-config-and-cli.md.
• Mọi chỉ số mới cập nhật 03-metrics-catalog.md và collector.

Chạy cục bộ và CI

Lệnh	Việc
make all	go vet, go test, dựng binary vào bin/
make test-race	go test -race (cần cgo và trình biên dịch C, CI bật sẵn)
make lint	golangci-lint theo .golangci.yml (bản v2.14.0)
make vuln	govulncheck (bản v1.8.0)
make cross	Dựng tĩnh (CGO_ENABLED=0) cho linux và windows, amd64 và arm64 vào dist/, ghi kích thước vào dist/sizes.txt, lỗi nếu quá 20 MB (ANFR-03)
make proto-check	So agent.proto.ref với tệp .proto do nhóm Collector cung cấp (truyền đường dẫn hoặc đặt COLLECTOR_PROTO, xem 10-wire-contract.md)
make fuzz	Fuzz bộ phân tích cấu hình 30 giây

Pipeline .gitlab-ci.yml có ba giai đoạn: check (gofmt, vet, lint, govulncheck), test (go test -race, fuzz theo lịch), build (dựng chéo bốn tổ hợp, giữ artifact 2 tuần). Job proto-drift chạy thủ công vì cần lấy tệp .proto từ nhóm Collector (CI hiện kéo bằng CI_JOB_TOKEN), cho phép thất bại. Khi hợp đồng đổi: nhận tệp .proto mới từ nhóm Collector, chép sang internal/wire/accesshub/agent/v1/agent.proto.ref, sinh lại agent.pb.go, chạy make proto-check.