Files
DataStack/docs/dev/testing.md
Team Dark Devil 40a6855724 feat(sdk): refactor Python SDK documentation
- Standardize Python SDK (`datastack`) documentation with a new multi-file suite.
- Update `datastack-sdk` to serve as a backward-compatible shim for the canonical `datastack` package.
- Update project manifest and memory map to reflect current SDK structure and v2.2.0 features.
2026-11-18 10:03:40 +06:00

84 lines
4.2 KiB
Markdown

# Automated Testing Guide
This guide details the automated test suites, execution commands, coverage domains, and verification standards for DataStack.
---
## 1. Test Architecture
DataStack utilizes a lightweight, native test architecture built upon the Node.js native test runner (`node:test`) and Python's `unittest` framework:
- **Zero Heavy Test Framework Bloat**: Tests run using `npx tsx --test`, executing directly against TypeScript source modules without requiring Jest or Mocha.
- **Fast Execution**: The complete TypeScript suite executes in under 2 seconds.
- **Isolation**: Each test suite initializes mock stores or clean temporary directories, guaranteeing zero side effects on production data.
---
## 2. Running TypeScript Test Suites
To run all TypeScript test suites in sequence:
```bash
npx --yes tsx --test tests/phase01-auth.test.ts \
tests/phase02-sync.test.ts \
tests/phase03-storage-buffer.test.ts \
tests/phase06-pwa-landing.test.ts \
tests/phase07-deployment.test.ts
```
### Test Suite Coverage Breakdown
#### 1. `tests/phase01-auth.test.ts` (Security & Authentication)
- **Production Secret Fail-Closed**: Verifies that empty, short (<32 chars), or placeholder secrets halt execution.
- **Session Cookie Invalidation**: Asserts that incrementing `tokenVersion` immediately causes session rejection.
- **Brute-Force Rate Limiting**: Validates that 5 failed login attempts lock out the composite IP + Email key for 15 minutes.
- **Client Token Redaction**: Ensures client secrets and raw tokens are omitted from public audit responses.
- **CSRF Origin Verification**: Tests that mismatched Origin/Referer headers return `403 Forbidden`.
#### 2. `tests/phase02-sync.test.ts` (Dual-Runtime Synchronization)
- **Internal Secret Security**: Tests timing-safe header validation on `/internal/*` routes.
- **Settings Synchronization**: Validates that updating settings in Port 3000 propagates instantly to Port 4000.
- **Client Revocation**: Confirms that revoking a client immediately severs active WebSocket connections.
- **JWT Secret Rotation**: Asserts that all client tokens are re-signed and old tokens are rejected.
#### 3. `tests/phase03-storage-buffer.test.ts` (Storage & Durability)
- **Redis Queue Durability**: Tests RAM queue fallback and Redis list buffering.
- **Batch Threshold & Interval**: Verifies that threshold count (500) and interval time (2000ms) trigger flushes.
- **Cooperative Locking**: Proves that `.lock` files prevent concurrent write collisions and that stale locks (>30s) are safely reclaimed.
- **Streaming Export**: Verifies non-blocking streaming CSV and JSON exports with client and date filtering.
#### 4. `tests/phase06-pwa-landing.test.ts` (PWA & Client Shell)
- **Web App Manifest**: Validates manifest schema, icons, and display modes.
- **Service Worker Lifecycle**: Tests cache strategies and offline shell handling.
#### 5. `tests/phase07-deployment.test.ts` (Containerization & Deployment Health)
- **Docker Compose Configuration**: Audits volume mounts (`datastack-data`, `pgdata`, `redisdata`).
- **Nginx Reverse Proxy**: Verifies routing rules for `/`, `/socket.io/`, and `/health`.
- **Unhydrated DB Auto-Pruning Guard**: Confirms that partition pruning is deferred until database settings are fully hydrated.
---
## 3. Running Python SDK Test Suites
The Python SDK includes a dedicated integration test suite verifying WebSocket streaming, heartbeat pings, HTTP fallbacks, and offline disk spooling:
```bash
python3 -m unittest tests/phase05_sdk_test.py
```
### Verified Behaviors:
- WebSocket connection and JWT handshake authentication.
- Offline spooling to local disk directory (`.datastack_spool/`) during network disruption.
- Automatic drain and delivery of spooled events when connectivity is restored.
- Streaming large `.csv` and `.json` files in chunks.
---
## 4. Continuous Integration Checklist
Before opening a pull request:
1. `npm run lint` must exit with `0` errors and `0` warnings.
2. `npm run build` must compile the Next.js standalone bundle successfully.
3. All 5 TypeScript test suites must pass (`23/23 tests passing`).
4. Python SDK test suite must pass (`3/3 tests passing`).