dangkhoa2016 commited on
Commit
6ebdbe8
·
1 Parent(s): f7cdd52

docs: add Vietnamese translation for the testing guide

Browse files
Files changed (3) hide show
  1. README.md +2 -1
  2. tests/README.md +4 -0
  3. tests/README.vi.md +108 -0
README.md CHANGED
@@ -371,7 +371,8 @@ json-api-server/
371
  │ │ ├── index.test.js # Server request handler, admin auth, graceful shutdown (13)
372
  │ │ ├── integration.test.js # API integration tests — real HTTP + SQLite, runtime PATCH (81)
373
  │ │ └── route.test.js # Route parsing, favicon, health, admin auth cache, runtime config (18)
374
- │ ├── README.md # Testing documentation
 
375
  │ └── helpers/
376
  │ ├── coverage.js # Test-coverage utilities (save/restore/setEnv/clearCjs/configMockFactory)
377
  │ ├── index.js # startServer / stopServer / request utilities
 
371
  │ │ ├── index.test.js # Server request handler, admin auth, graceful shutdown (13)
372
  │ │ ├── integration.test.js # API integration tests — real HTTP + SQLite, runtime PATCH (81)
373
  │ │ └── route.test.js # Route parsing, favicon, health, admin auth cache, runtime config (18)
374
+ │ ├── README.md # Testing documentation (English)
375
+ │ ├── README.vi.md # Testing documentation (Vietnamese)
376
  │ └── helpers/
377
  │ ├── coverage.js # Test-coverage utilities (save/restore/setEnv/clearCjs/configMockFactory)
378
  │ ├── index.js # startServer / stopServer / request utilities
tests/README.md CHANGED
@@ -1,5 +1,7 @@
1
  # Testing
2
 
 
 
3
  ## Stack
4
 
5
  - **vitest** — test runner
@@ -35,6 +37,8 @@ tests/
35
  integration.test.js # API integration tests — real HTTP + SQLite, runtime PATCH settings (81 tests)
36
  index.test.js # Server request handler, admin auth, graceful shutdown (13 tests)
37
  route.test.js # Route parsing, favicon, health, admin auth cache, runtime config updates (18 tests)
 
 
38
  helpers/
39
  coverage.js # Shared test utilities (save/restore/setEnv/clearCjs/configMockFactory)
40
  mock-factory.js # Mock factory helpers (mkDb/mkReq/mkRes/mkRedis/mkSettingsTable)
 
1
  # Testing
2
 
3
+ > 🌐 Language / Ngôn ngữ: **English** | [Tiếng Việt](README.vi.md)
4
+
5
  ## Stack
6
 
7
  - **vitest** — test runner
 
37
  integration.test.js # API integration tests — real HTTP + SQLite, runtime PATCH settings (81 tests)
38
  index.test.js # Server request handler, admin auth, graceful shutdown (13 tests)
39
  route.test.js # Route parsing, favicon, health, admin auth cache, runtime config updates (18 tests)
40
+ README.md # Testing documentation (English)
41
+ README.vi.md # Testing documentation (Vietnamese)
42
  helpers/
43
  coverage.js # Shared test utilities (save/restore/setEnv/clearCjs/configMockFactory)
44
  mock-factory.js # Mock factory helpers (mkDb/mkReq/mkRes/mkRedis/mkSettingsTable)
tests/README.vi.md ADDED
@@ -0,0 +1,108 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Kiểm thử
2
+
3
+ > 🌐 Language / Ngôn ngữ: [English](README.md) | **Tiếng Việt**
4
+
5
+ ## Stack
6
+
7
+ - **vitest** — trình chạy kiểm thử
8
+ - **@vitest/coverage-v8** — vùng phủ mã V8 gốc
9
+
10
+ ## Lệnh
11
+
12
+ ```sh
13
+ npm test # Chạy tất cả kiểm thử một lần
14
+ npm run test:watch # Chế độ watch
15
+ npm run test:coverage # Chạy với báo cáo vùng phủ
16
+ ```
17
+
18
+ ## Cấu trúc
19
+
20
+ ```
21
+ tests/
22
+ config/
23
+ config.test.js # Config mặc định và nhánh biến môi trường (9 kiểm thử)
24
+ load-env.test.js # Tải chuỗi, override:false, bỏ qua production, fallback (7 kiểm thử)
25
+ db/
26
+ database.test.js # CRUD database, phân trang, tìm kiếm, sắp xếp, SQL injection, cascade delete (11 kiểm thử)
27
+ migrate.test.js # Đường dẫn migration thành công và thất bại (2 kiểm thử)
28
+ seed.test.js # Seed với DB thật + mock dependencies, JSONPlaceholder fetch (5 kiểm thử)
29
+ sql-logger.test.js # Kiểm thử bọc SQL query logger (5 kiểm thử)
30
+ middleware/
31
+ rate-limiter.test.js # Đường dẫn rate limiter in-memory và Redis, circuit breaker, proxy IPs, hot-swap updateConfig (57 kiểm thử)
32
+ redis/
33
+ redis.test.js # Mã hóa/giải mã giao thức RESP, tùy chọn constructor, phương thức eval, reconnect (33 kiểm thử)
34
+ server/
35
+ coverage-printlog.test.js # Vùng phủ V8 printlog và xuất server (4 kiểm thử)
36
+ graceful-shutdown.test.js # Vùng phủ handler SIGINT/SIGTERM (1 kiểm thử)
37
+ index.test.js # Handler request server, admin auth, tắt máy an toàn (13 kiểm thử)
38
+ integration.test.js # Kiểm thử tích hợp API — HTTP thật + SQLite, PATCH settings runtime (81 kiểm thử)
39
+ route.test.js # Phân tích route, favicon, health, cache xác thực admin, cập nhật cấu hình runtime (18 kiểm thử)
40
+ README.md # Tài liệu kiểm thử (tiếng Anh)
41
+ README.vi.md # Tài liệu kiểm thử (tiếng Việt)
42
+ helpers/
43
+ coverage.js # Tiện ích kiểm thử dùng chung (save/restore/setEnv/clearCjs/configMockFactory)
44
+ mock-factory.js # Hàm factory mock (mkDb/mkReq/mkRes/mkRedis/mkSettingsTable)
45
+ index.js # Tiện ích startServer / stopServer / request
46
+ seed.js # Script độc lập để tạo và seed DB tạm thời
47
+ seed-settings-coverage.test.js # Vùng phủ V8 seed-settings.js (4 kiểm thử)
48
+ ```
49
+
50
+ **Tổng: 250 kiểm thử trên 14 file.**
51
+
52
+ ## Thiết kế kiểm thử
53
+
54
+ ### Kiểm thử tích hợp (`tests/server/integration.test.js`)
55
+
56
+ Mỗi lần chạy tạo một database SQLite tạm thời riêng biệt, seed dữ liệu kiểm thử qua một tiến trình con (`helpers/seed.js`), sau đó khởi động server trên cổng 3199. Kiểm thử thực hiện request HTTP thật và xác thực toàn bộ vòng đời request — bao gồm phân trang (`_page`/`_limit`/`_start`/`_end`), tìm kiếm (`q`), sắp xếp (`_sort`/`_order`), và thao tác CRUD. Giới hạn tốc độ bị tắt qua `RATE_LIMIT_ENABLED=false` trong helper kiểm thử. Thư mục tạm được dọn dẹp sau khi tất cả kiểm thử hoàn tất.
57
+
58
+ ### Kiểm thử đơn vị (`tests/config/`, `tests/db/`, `tests/middleware/`, `tests/redis/`, `tests/server/`)
59
+
60
+ Kiểm thử đơn vị bao phủ từng module nguồn riêng lẻ. Mỗi module có file kiểm thử riêng:
61
+
62
+ | Module | File kiểm thử | Cách tiếp cận |
63
+ |--------------------------------|------------------------------|----------|
64
+ | `config/index.js` | `tests/config/config.test.js` | Module được import lại với các giá trị `process.env` khác nhau |
65
+ | `config/runtime-config.js` | _(được bao phủ qua route.test.js & integration.test.js)_ | Ghi đè cấu hình trong bộ nhớ cho cập nhật runtime |
66
+ | `config/load-env.js` | `tests/config/load-env.test.js` | Thư mục env tạm thời, mock dotenv; kiểm thử chain, override:false, ENOENT, lỗi phân tích |
67
+ | `db/index.js` | `tests/db/database.test.js` | Database `node:sqlite` thật; kiểm thử phân trang, tìm kiếm, sắp xếp, SQL injection |
68
+ | `middleware/rate-limiter.js` | `tests/middleware/rate-limiter.test.js` | Module được import một lần; mock Redis, in-memory store; kiểm thử circuit breaker, proxy IPs, escalating blocks |
69
+ | `redis/index.js` | `tests/redis/redis.test.js` | Mã hóa/giải mã RESP trực tiếp; tùy chọn constructor |
70
+ | `server/index.js` | `tests/server/index.test.js` | `requestHandler()` với mock req/res; inject CJS cache cho mock DB; kiểm thử auth caching và tắt máy an toàn (13 kiểm thử) |
71
+ | `server/route.js` | `tests/server/route.test.js` | Phân tích route, favicon, null body, health endpoint, xác thực admin, cache auth, reset-database, route không xác định, cập nhật cấu hình runtime (rate-limit + Redis) |
72
+ | `server/index.js` (ESM) | `tests/server/coverage-printlog.test.js` | `import()` động cho printLog, startServer, catch 500 được vùng phủ V8 |
73
+ | `server/index.js` (tiến trình con)| `tests/server/graceful-shutdown.test.js` | SIGINT/SIGTERM qua tiến trình con (vùng phủ V8) |
74
+ | `db/migrate.js` | `tests/db/migrate.test.js` | Migration thật + đường dẫn thất bại do DB hỏng |
75
+ | `db/seed.js` | `tests/db/seed.test.js` | Dependency injection — `database` và `fetch` được inject |
76
+ | `db/seed-settings.js` | `tests/seed-settings-coverage.test.js` | DB thật + đường dẫn mock DB (vùng phủ V8) |
77
+ | `db/sql-logger.js` | `tests/db/sql-logger.test.js`| Hành vi Proxy wrapper trên exec/prepare/run/get/all |
78
+
79
+ ### Mẫu kiểm thử chính
80
+
81
+ - **Inject CJS cache**: Kiểm thử server inject mock `db/index.js` vào `require.cache` của CJS trước khi tải `server/index.js`, đảm bảo mock được `require()` của CommonJS sử dụng.
82
+ - **Kiểm thử rate limiter**: `middleware/rate-limiter.js` nhận tùy chọn qua `createRateLimiter({enabled, max, windowMs})`, giúp dễ dàng kiểm thử với các cấu hình khác nhau, mock Redis, và mô phỏng trạng thái circuit breaker mà không cần import lại. Kiểm thử bao gồm fallback in-memory, chế độ Redis, trích xuất IP proxy CIDR, và thời gian chặn tăng dần.
83
+ - **Dependency injection cho seed**: `db/seed.js` chấp nhận tham số `database` và `fetch`, tránh phải mock `require('https')` và `require('../db')`.
84
+ - **Kiểm thử cấu hình runtime**: Cập nhật cấu hình runtime được kiểm thử qua cả kiểm thử đơn vị (`route.test.js` với CJS cache injection) và kiểm thử tích hợp (`integration.test.js` với request HTTP thật). Phương thức `updateConfig()` trên middleware rate limiter được kiểm thử trực tiếp trong `rate-limiter.test.js`, trong khi kết nối lại Redis được kiểm thử trong `redis.test.js` với TCP server thật.
85
+ - **Chỉ thị vùng phủ V8**: Comment `/* v8 ignore */` loại trừ các đường dẫn mã mà V8 không thể theo dõi qua chuỗi module CJS (ví dụ: điểm vào CLI, handler tín hiệu, khoảng trống vùng phủ cross-worker).
86
+
87
+ ## Cấu hình
88
+
89
+ `vitest.config.js` đặt `NODE_ENV=test` và `PORT=3199`. Giới hạn tốc độ bị tắt trong helper kiểm thử tích hợp (`tests/helpers/index.js`) nhưng được bật mặc định trong kiểm thử đơn vị, cho phép thực thi đầy đủ rate limiter bao gồm circuit breaker và escalating blocks.
90
+
91
+ ## CI/CD
92
+
93
+ GitHub Actions (`.github/workflows/test.yml`) chạy kiểm thử trên Node.js 22, 23, và 26. Vùng phủ chỉ được tạo trên Node 26 và được tải lên dưới dạng artifact.
94
+
95
+ ## Vùng phủ
96
+
97
+ ```sh
98
+ npm run test:coverage
99
+ ```
100
+
101
+ | Chỉ số | Vùng phủ |
102
+ |-------------|----------|
103
+ | Statements | 100% |
104
+ | Branches | 100% |
105
+ | Functions | 100% |
106
+ | Lines | 100% |
107
+
108
+ Tất cả file nguồn đạt 100% vùng phủ V8 trên mọi chỉ số.