dangkhoa2016's picture
docs: add Vietnamese translation for the testing guide
6ebdbe8
|
Raw History Blame Contribute Delete
7.37 kB
# 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.