goodgo-platform/docs/load-testing/K6_README.md

Tài Liệu K6 Load Testing cho GoodGo Platform

Hướng dẫn đầy đủ để hiểu và triển khai K6 load tests cho GoodGo Platform API.

---

📚 Các File Tài Liệu

Thư mục này chứa ba hướng dẫn toàn diện về K6 load testing:

1. K6_LOAD_TESTING_GUIDE.md (Tham Khảo Chính)

Khám phá toàn diện cấu trúc GoodGo Platform API cho load testing.

Nội dung:

• Cấu trúc module API (auth, listings, payments, search)
• Tài liệu endpoint chi tiết với HTTP method, rate limit và yêu cầu auth
• Đặc tả DTO đầy đủ với hình dạng request/response body
• Tham khảo cấu hình database và environment
• Thiết lập test hiện có (Playwright, Vitest, CI/CD)
• Mẫu kiến trúc (CQRS, DDD)
• Tham khảo nhanh vị trí file
• Khuyến nghị triển khai K6

Khi nào sử dụng: Khi cần đào sâu vào các endpoint cụ thể, hiểu luồng xác thực, kiểm tra biến môi trường

2. K6_ENDPOINTS_SUMMARY.md (Tham Khảo Nhanh)

Tham khảo endpoint cô đọng với hình dạng dữ liệu để tra cứu ngay lập tức.

Nội dung:

• Tất cả endpoint dưới dạng bảng (method, path, auth, rate limit)
• Module Authentication (register, login, refresh, profile)
• Module Listings (CRUD, kiểm duyệt, upload media)
• Module Payments (create, list, callback, refund)
• Module Search (full-text, geo)
• Ví dụ request/response body (JSON)
• Các kịch bản test K6 (search, auth, listings, payments, webhook)
• Tóm tắt rate limit
• Ví dụ luồng xác thực (cookies vs tokens)

Khi nào sử dụng: Tra cứu nhanh chi tiết endpoint, sao chép payload mẫu, hiểu rate limit

3. K6_QUICK_START.md (Ví Dụ Chạy Được)

Hướng dẫn từng bước với script K6 sẵn sàng chạy và hướng dẫn thiết lập.

Nội dung:

• Hướng dẫn cài đặt (macOS, Linux, Docker)
• Thiết lập môi trường (khởi động API, seed database)
• Năm script K6 chạy được:
  • Search load test (công khai, lưu lượng cao)
  • Auth load test (đăng ký bị giới hạn rate)
  • Tạo listing (đã xác thực, giới hạn quota)
  • Xử lý payment (đã xác thực)
  • Tất cả kịch bản kết hợp
• Tích hợp CI với GitHub Actions
• Tùy chọn tạo báo cáo (JSON, Grafana Cloud, CSV)
• Các check K6 và mẫu phổ biến
• Debug và xử lý sự cố

Khi nào sử dụng: Bắt đầu nhanh, chạy test ngay, thiết lập CI/CD

---

🚀 Bắt Đầu Nhanh (3 Phút)

1. Cài Đặt K6

brew install k6  # macOS
# or
apt-get install k6  # Linux

2. Khởi Động API & Database

pnpm install
pnpm db:generate
pnpm db:migrate:dev
pnpm db:seed
pnpm dev

3. Chạy Load Test

# Copy this from K6_QUICK_START.md Step 3
k6 run load-tests/search.k6.js

4. Xem Kết Quả

K6 in tóm tắt ra console. Để xem báo cáo chi tiết hơn, xem mục tạo báo cáo trong K6_QUICK_START.md.

---

📊 Các Kịch Bản Test Đã Triển Khai

Kịch Bản	File	Trọng Tâm	VUs	Thời Lượng	Endpoint Chính
Search Load	load-tests/search.k6.js	Hiệu suất tìm kiếm công khai	50	4m	GET /search, GET /search/geo
Authentication	load-tests/auth.k6.js	Throughput auth & rate limit	10	2m	POST /auth/register, POST /auth/login
Tạo Listing	load-tests/listings.k6.js	CRUD listing đã xác thực	5	2m	POST /listings, GET /listings/:id
Payments	load-tests/payments.k6.js	Khởi tạo & trạng thái thanh toán	10	2m	POST /payments, GET /payments/:id
Combined	load-tests/all-scenarios.k6.js	Tải hỗn hợp thực tế	50	5m	Nhiều endpoint

---

🔐 Phương Thức Xác Thực

Tùy Chọn 1: Dựa Trên Cookie (Khuyến nghị cho test giống trình duyệt)

const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password });
// Cookies automatically managed by K6
const profileRes = http.get(`${BASE_URL}/auth/profile`);

Tùy Chọn 2: Bearer Token (Khuyến nghị cho test chỉ API)

const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password });
const { accessToken } = loginRes.json();
const headers = { Authorization: `Bearer ${accessToken}` };
const profileRes = http.get(`${BASE_URL}/auth/profile`, { headers });

Xem K6_ENDPOINTS_SUMMARY.md để xem ví dụ đầy đủ.

---

🎯 Endpoint Chính Theo Mức Ưu Tiên

Ưu Tiên Cao (Chức Năng Cốt Lõi)

Endpoint	Ưu Tiên	Tại sao
GET /search	⭐⭐⭐	Công khai, truy vấn lưu lượng cao
GET /search/geo	⭐⭐⭐	Địa không gian, dùng thường xuyên
GET /listings	⭐⭐⭐	Tìm/lọc công khai
GET /listings/:id	⭐⭐⭐	Tải trang chi tiết
POST /auth/login	⭐⭐	Tạo phiên người dùng
POST /auth/register	⭐⭐	Bị giới hạn rate, quan trọng

Ưu Tiên Trung Bình (Tính Năng Cụ Thể)

Endpoint	Ưu Tiên	Tại sao
POST /listings	⭐⭐	Bị giới hạn quota, đã xác thực
POST /payments	⭐⭐	Tích hợp bên ngoài
GET /payments	⭐⭐	Lịch sử giao dịch người dùng
POST /payments/callback/:provider	⭐⭐	Webhook handler, then chốt

Ưu Tiên Thấp (Admin/Chuyên Biệt)

Endpoint	Ưu Tiên	Tại sao
PATCH /listings/:id/moderate	⭐	Chỉ admin
GET /listings/pending	⭐	Chỉ admin
POST /search/reindex	⭐	Chỉ admin, có lịch

---

📍 Tổng Quan Cấu Trúc API

API Base: http://localhost:3001/api/v1

Modules:
├── /auth               # User authentication & profiles
├── /listings           # Property CRUD & moderation
├── /search             # Full-text & geo search
├── /payments           # Payment processing & webhooks
├── /subscriptions      # Plans & quotas (not focused for load tests)
├── /admin              # Admin operations (low priority for load tests)
└── /analytics          # Market data (low priority for load tests)

---

🗄️ Cấu Hình Database

Phát Triển Cục Bộ

DATABASE_URL=postgresql://goodgo:password@localhost:5432/goodgo
REDIS_URL=redis://localhost:6379
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108

Môi Trường Test (CI)

DATABASE_URL=postgresql://goodgo:goodgo_test_secret@localhost:5432/goodgo_test
REDIS_URL=redis://localhost:6379
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108

Xem K6_LOAD_TESTING_GUIDE.md để biết đầy đủ biến môi trường.

---

⚡ Rate Limit

Tôn trọng các giới hạn này trong load test của bạn:

Endpoint	Limit	Cửa Sổ	Hành Động Khi Vượt
/auth/register	5	mỗi giờ	Trả về 429
/auth/login	5	mỗi giờ	Trả về 429
/auth/refresh	5	mỗi giờ	Trả về 429
/payments/callback/*	20	mỗi phút	Trả về 429
Tất cả khác	Không có	N/A	Quota gate áp dụng cho thao tác ghi

Xử Lý K6:

check(res, {
  'status not rate limited': (r) => r.status !== 429,
  'status success or expected': (r) => [200, 201, 400, 404].includes(r.status),
});

---

🏗️ Cấu Trúc Test Đề Xuất

load-tests/
├── search.k6.js              # High-volume public search
├── auth.k6.js                # Authentication flow with rate limit handling
├── listings.k6.js            # Authenticated listing creation
├── payments.k6.js            # Payment processing
├── all-scenarios.k6.js       # Combined realistic mix
├── helpers/
│   ├── data-generators.js    # Generate test data (users, listings)
│   ├── auth-flows.js         # Reusable login/register functions
│   └── assertions.js         # Custom check functions
└── config.js                 # Base URL, env, thresholds

Cấu trúc helper mẫu được cung cấp trong K6_QUICK_START.md.

---

🧪 Tích Hợp Với Các Test Hiện Có

Bổ Sung, Không Thay Thế

K6 dành cho load testing (hiệu suất dưới tải đồng thời). Các test hiện có phục vụ các mục đích khác:

Loại Test	Công Cụ	Mục Đích	Khi Nào
Unit Tests	Vitest	Xác minh logic hàm	Trong quá trình phát triển
E2E Tests	Playwright	Xác minh luồng người dùng hoạt động	Trước khi triển khai
Load Tests	K6	Xác minh hiệu suất ở quy mô lớn	Theo lịch, theo yêu cầu

Chạy Tất Cả Test

# Unit tests (API only)
pnpm test

# E2E tests (API + Web)
pnpm test:e2e

# Load tests (new)
k6 run load-tests/search.k6.js

# All in sequence
pnpm test && pnpm test:e2e && k6 run load-tests/all-scenarios.k6.js

---

📈 Tích Hợp CI/CD

Workflow GitHub Actions

Tạo .github/workflows/load-test.yml (mẫu trong K6_QUICK_START.md mục 🔟):

# Runs on schedule (daily at 2 AM)
# Or manually via workflow_dispatch
# Reports results as artifacts

Báo Cáo Thủ Công

# Export JSON
k6 run load-tests/search.k6.js --summary-export=results.json

# View CSV (with extension)
k6 run load-tests/search.k6.js --out csv=results.csv

# Upload to Grafana Cloud
K6_CLOUD_TOKEN=xxx k6 run load-tests/search.k6.js --out cloud

---

🔗 Hướng Dẫn Tham Chiếu Chéo

Đang tìm kiếm...?

Cần	Tìm trong
Tất cả URL & method endpoint	K6_ENDPOINTS_SUMMARY.md
Hình dạng JSON request/response	K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes)
DTO & quy tắc validation	K6_LOAD_TESTING_GUIDE.md (Controllers & DTOs)
Chi tiết rate limit	K6_ENDPOINTS_SUMMARY.md (📌 Important Rate Limits)
Luồng xác thực	K6_ENDPOINTS_SUMMARY.md (🔗 Authentication Flow for K6)
Biến database	K6_LOAD_TESTING_GUIDE.md (🗄️ Database & Environment)
Script sẵn sàng chạy	K6_QUICK_START.md (Steps 3-8️⃣)
Thiết lập CI/CD	K6_QUICK_START.md (Step 🔟)
Xử lý sự cố	K6_QUICK_START.md (✅ Troubleshooting)
Chi tiết kiến trúc	K6_LOAD_TESTING_GUIDE.md (📊 Architecture Patterns)
Vị trí file	K6_LOAD_TESTING_GUIDE.md (📁 File Locations Quick Reference)

---

🛠️ Công Việc Phổ Biến

Công Việc: Load Test Endpoint Search

1. Đọc: K6_ENDPOINTS_SUMMARY.md (mục 🔍 Search)
2. Sử dụng: K6_QUICK_START.md (Bước 3️⃣ - Search Load Test)
3. Chạy: k6 run load-tests/search.k6.js

Công Việc: Hiểu Luồng Payment

1. Đọc: K6_LOAD_TESTING_GUIDE.md (💳 PAYMENTS MODULE)
2. Kiểm tra: K6_ENDPOINTS_SUMMARY.md (mục 💳 Payments)
3. Sử dụng: K6_QUICK_START.md (Bước 7️⃣ - Payment Test)

Công Việc: Thêm Endpoint Mới Vào Load Tests

1. Tìm endpoint trong: K6_LOAD_TESTING_GUIDE.md hoặc K6_ENDPOINTS_SUMMARY.md
2. Lấy hình dạng dữ liệu từ: K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes)
3. Kiểm tra auth từ: K6_LOAD_TESTING_GUIDE.md (mỗi mục module)
4. Triển khai sử dụng ví dụ trong: K6_QUICK_START.md

---

✅ Danh Sách Kiểm Tra Xác Minh

Trước khi chạy load test, hãy xác minh:

• API đang chạy: pnpm dev (port 3001)
• Database đã seed: pnpm db:seed
• K6 đã cài đặt: k6 version
• Có thể truy cập API: curl http://localhost:3001/api/v1/docs
• Biến ENV đã set: JWT_SECRET, CORS_ORIGINS, v.v.
• File load test tồn tại: load-tests/*.k6.js
• Có sẵn dữ liệu test: Kiểm tra seed trong prisma/seed.ts

---

📞 Hỗ Trợ & Tham Khảo

Tài Liệu Nội Bộ

• Kiến Trúc Đầy Đủ: K6_LOAD_TESTING_GUIDE.md
• Tham Khảo Endpoint: K6_ENDPOINTS_SUMMARY.md
• Bắt Đầu: K6_QUICK_START.md

Tài Nguyên Bên Ngoài

• Tài Liệu Chính Thức K6: https://k6.io/docs
• Tham Khảo K6 API: https://k6.io/docs/javascript-api
• Cộng Đồng K6: https://community.k6.io
• Ví Dụ K6: https://github.com/grafana/k6-templates

File Dự Án

• API Controllers: apps/api/src/modules/*/presentation/controllers/
• DTOs: apps/api/src/modules/*/presentation/dto/
• E2E Tests: e2e/api/
• Seed Data: prisma/seed.ts

---

🎓 Lộ Trình Học

Người Mới Bắt Đầu (30 phút)

1. Đọc K6_QUICK_START.md (Bước 1-4)
2. Cài đặt K6
3. Chạy: k6 run load-tests/search.k6.js

Trung Cấp (1-2 giờ)

1. Đọc K6_ENDPOINTS_SUMMARY.md
2. Hiểu luồng auth
3. Chạy test auth: k6 run load-tests/auth.k6.js
4. Chạy test listing: k6 run load-tests/listings.k6.js

Nâng Cao (2-4 giờ)

1. Đọc K6_LOAD_TESTING_GUIDE.md đầy đủ
2. Xem xét triển khai controller trong source
3. Tạo script load test tùy chỉnh
4. Thiết lập CI/CD với GitHub Actions (K6_QUICK_START.md Bước 🔟)
5. Tạo và phân tích báo cáo

---

📝 Ghi Chú

• Chưa có thiết lập K6 nào — Tài liệu này cung cấp hướng dẫn đầy đủ
• Ba tài liệu bổ sung cho nhau — Khám phá các tài liệu khác nhau cho các nhu cầu khác nhau
• Ví dụ chạy được — Script K6_QUICK_START.md hoạt động ngay
• Rate limit quan trọng — Hãy xem xét chúng trong thiết kế test
• Quota gate — Một số thao tác (listings, payments) bị giới hạn theo subscription
• Dữ liệu test — Sử dụng dữ liệu seed hoặc tạo người dùng test duy nhất cho mỗi VU
• Sẵn sàng cho production — Hướng dẫn tuân theo các thực hành tốt nhất của K6

---

Đã tạo: 2026-04-09 Cập nhật lần cuối: K6_QUICK_START.md mới nhất