File size: 7,374 Bytes
75a60d6
 
6ebdbe8
 
75a60d6
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
25059bd
13def79
2e6d0d7
25059bd
5533459
25059bd
 
62e3094
25059bd
e9d5bbe
25059bd
e9d5bbe
25059bd
2e6d0d7
cfbebe0
e9d5bbe
ad871c9
e9d5bbe
6ebdbe8
 
75a60d6
a3bf2e3
7db7c77
25059bd
 
e9d5bbe
75a60d6
 
e9d5bbe
75a60d6
 
 
62e3094
25059bd
eab7289
25059bd
 
 
 
 
1f0f638
 
 
e9d5bbe
2e6d0d7
 
7b6e647
1f0f638
ad871c9
e9d5bbe
9c74555
2e6d0d7
1f0f638
 
7f0d072
1f0f638
25059bd
 
 
1f0f638
7b6e647
1f0f638
e9d5bbe
25059bd
 
 
 
7b6e647
75a60d6
 
 
 
 
 
 
 
 
 
 
25059bd
 
2e6d0d7
 
 
 
25059bd
2e6d0d7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
# Testing

> 🌐 Language / Ngôn ngữ: **English** | [Tiếng Việt](README.vi.md)

## Stack

- **vitest** — test runner
- **@vitest/coverage-v8** — V8 native code coverage

## Commands

```sh
npm test                 # Run all tests once
npm run test:watch       # Watch mode
npm run test:coverage    # Run with coverage report
```

## Structure

```
tests/
  config/
    config.test.js                   # Config defaults and env var branches (9 tests)
    load-env.test.js                 # Chain-loading, override:false, production skip, fallback (7 tests)
  db/
    database.test.js                 # Database CRUD, pagination, search, sort, SQL injection, cascade delete (11 tests)
    migrate.test.js                  # Migration success and failure paths (2 tests)
    seed.test.js                     # Seed with real DB + mocked deps, JSONPlaceholder fetch (5 tests)
    sql-logger.test.js               # SQL query logger wrapping tests (5 tests)
  middleware/
    rate-limiter.test.js             # In-memory, Redis, circuit breaker, proxy IPs, updateConfig hot-swap (57 tests)
  redis/
    redis.test.js                    # RESP protocol encoding/parsing, constructor options, eval method, reconnect (33 tests)
  server/
    coverage-printlog.test.js        # Printlog and server export V8 coverage (4 tests)
    graceful-shutdown.test.js        # SIGINT/SIGTERM handler coverage (1 test)
    integration.test.js              # API integration tests — real HTTP + SQLite, runtime PATCH settings (81 tests)
    index.test.js                    # Server request handler, admin auth, graceful shutdown (13 tests)
    route.test.js                    # Route parsing, favicon, health, admin auth cache, runtime config updates (18 tests)
  README.md                          # Testing documentation (English)
  README.vi.md                       # Testing documentation (Vietnamese)
  helpers/
    coverage.js                      # Shared test utilities (save/restore/setEnv/clearCjs/configMockFactory)
    mock-factory.js                  # Mock factory helpers (mkDb/mkReq/mkRes/mkRedis/mkSettingsTable)
    index.js                         # startServer / stopServer / request utilities
    seed.js                          # Standalone script to create & seed temp DB
  seed-settings-coverage.test.js     # Seed-settings.js V8 coverage (4 tests)
```

**Total: 250 tests across 14 test files.**

## Test design

### Integration tests (`tests/server/integration.test.js`)

Each run creates an isolated temp SQLite database, seeds it with test data via a child process (`helpers/seed.js`), then starts the server on port 3199. Tests make real HTTP requests and validate the full request lifecycle — including pagination (`_page`/`_limit`/`_start`/`_end`), search (`q`), sorting (`_sort`/`_order`), and CRUD operations. Rate limiting is disabled via `RATE_LIMIT_ENABLED=false` in the test helper. The temp directory is cleaned up after all tests finish.

### Unit tests (`tests/config/`, `tests/db/`, `tests/middleware/`, `tests/redis/`, `tests/server/`)

Unit tests cover every source module individually. Each module has its own test file:

| Module                         | Test file                    | Approach |
|--------------------------------|------------------------------|----------|
| `config/index.js`              | `tests/config/config.test.js` | Module re-imported with different `process.env` values |
| `config/runtime-config.js`     | _(covered via route.test.js & integration.test.js)_ | In-memory config overrides for runtime setting updates |
| `config/load-env.js`           | `tests/config/load-env.test.js` | Temp env dirs, mocked dotenv; tests chain, override:false, ENOENT, parse errors |
| `db/index.js`                  | `tests/db/database.test.js`   | Real `node:sqlite` databases; tests pagination, search, sort, SQL injection |
| `middleware/rate-limiter.js`   | `tests/middleware/rate-limiter.test.js` | Module imported once; mocks Redis, in-memory store; tests circuit breaker, proxy IPs, escalating blocks |
| `redis/index.js`               | `tests/redis/redis.test.js`  | RESP encoding/parsing directly; constructor options |
| `server/index.js`              | `tests/server/index.test.js`  | `requestHandler()` with mock req/res; CJS cache injection for DB mock; tests auth caching and graceful shutdown (13 tests) |
| `server/route.js`              | `tests/server/route.test.js`  | Route parsing, favicon, null body, health endpoint, admin auth, auth cache eviction, reset-database, unknown routes, runtime config updates (rate-limit + Redis) |
| `server/index.js` (ESM)        | `tests/server/coverage-printlog.test.js` | Dynamic `import()` for V8-covered printLog, startServer, 500 catch |
| `server/index.js` (child)      | `tests/server/graceful-shutdown.test.js` | SIGINT/SIGTERM via child process (V8 coverage) |
| `db/migrate.js`                | `tests/db/migrate.test.js`   | Real migration + corrupt DB failure path |
| `db/seed.js`                   | `tests/db/seed.test.js`      | Dependency injection — `database` and `fetch` injected |
| `db/seed-settings.js`          | `tests/seed-settings-coverage.test.js` | Real DB + mock DB paths (V8 coverage) |
| `db/sql-logger.js`             | `tests/db/sql-logger.test.js`| Proxy wrapper behavior on exec/prepare/run/get/all |

### Key testing patterns

- **CJS cache injection**: Server tests inject mock `db/index.js` into the CJS `require.cache` before loading `server/index.js`, ensuring the mock is picked up by CommonJS `require()` calls.
- **Rate limiter testing**: `middleware/rate-limiter.js` accepts options via `createRateLimiter({enabled, max, windowMs})`, making it easy to test with different configurations, mock Redis, and simulate circuit breaker states without re-importing. Tests cover in-memory fallback, Redis mode, CIDR proxy IP extraction, and escalating block durations.
- **Seed dependency injection**: `db/seed.js` accepts `database` and `fetch` parameters, bypassing the need to mock `require('https')` and `require('../db')`.
- **Runtime config testing**: Runtime configuration updates are tested through both unit tests (`route.test.js` with CJS cache injection) and integration tests (`integration.test.js` with real HTTP requests). The `updateConfig()` method on the rate limiter middleware is tested directly in `rate-limiter.test.js`, while Redis reconnection is tested in `redis.test.js` with real TCP servers.
- **V8 coverage pragmas**: `/* v8 ignore */` comments exclude code paths that V8 cannot track through CJS module chains (e.g., CLI entry points, signal handlers, cross-worker coverage gaps).

## Configuration

`vitest.config.js` sets `NODE_ENV=test` and `PORT=3199`. Rate limiting is disabled in the integration test helper (`tests/helpers/index.js`) but enabled by default in unit tests, which exercise the full rate limiter including circuit breaker and escalating blocks.

## CI/CD

GitHub Actions (`.github/workflows/test.yml`) runs tests on Node.js 22, 23, and 26. Coverage is generated only on Node 26 and uploaded as an artifact.

## Coverage

```sh
npm run test:coverage
```

| Metric      | Coverage |
|-------------|----------|
| Statements  | 100%    |
| Branches    | 100%    |
| Functions   | 100%    |
| Lines       | 100%    |

All source files reach 100% V8 coverage across all metrics.