Testing And Verification¶

BillTracker combines automated Node tests, syntax checking, a production Vite build, targeted smoke scripts, and runtime validation.

Standard Commands¶

npm test
npm run check

npm run check performs:

npm run check:server
npm run build

check:server runs node --check over backend CommonJS files in:

server.js
db/
middleware/
routes/
services/
utils/

The Vite build validates frontend imports, JSX, bundling, and production asset generation.

Node Test Suite¶

Test file	Coverage focus
`tests/statusService.test.js`	Cycle resolution, due dates, status calculation, and tracker row behavior
`tests/csvTransactionImportService.test.js`	CSV preview, mapping, normalization, dedupe, and commit
`tests/transactionMatchService.test.js`	Match, unmatch, ignore, linked payments, and ownership
`tests/backupAndCleanup.test.js`	Backup retention, checksum validation, and cleanup tasks

Run one file while iterating:

node --test tests/statusService.test.js

Smoke Scripts¶

Script	Purpose
`scripts/test-cookie-options.js`	Verifies session cookie Secure inference and overrides
`scripts/test-oidc-smoke.js`	Exercises OIDC configuration resolution and lockout behavior
`scripts/test-import.js`	Exercises spreadsheet import behavior with fixture workbooks
`scripts/migrate-db.js`	Opens the database and applies migrations
`scripts/docker-test.sh`	Container-oriented validation helper

Import Fixtures¶

Fixture	Purpose
`scripts/test-import-fixture.xlsx`	Standard spreadsheet import
`scripts/test-import-multi-fixture.xlsx`	Multi-header and dual-column spreadsheet cases

Documentation Verification¶

MkDocs is validated with the same container image used by the docs service:

docker run --rm \
  -v "$PWD/mkdocs:/docs" \
  squidfunk/mkdocs-material:latest \
  build --strict

Strict mode fails on missing nav pages and warnings that would otherwise leave the published site partially broken.

After deploy, test:

curl -fsSI http://<docs-host>:8055/
curl -fsSI http://<docs-host>:8055/technical/engineering-log/
curl -fsSI http://<docs-host>:8055/assets/screenshots/live-login.png
curl -fsS  http://<docs-host>:8055/search/search_index.json >/dev/null

Verification Matrix¶

Use this matrix for non-trivial releases:

Change area	Minimum verification
React UI	`npm run build`, affected-page walkthrough
Backend route	`node --check`, related tests, API request
SQLite migration	Backup, migration script, schema inspection, app restart
Auth or CSRF	Cookie smoke script, login walkthrough, mutation request
SimpleFIN	Unit checks where available, manual sync, source status review
Backup and restore	Backup creation, checksum, managed-list review, restore only on test copy unless required
Docs	Strict MkDocs build, relative-link audit, live URL checks

Test Data Policy¶

Prefer synthetic fixtures and demo users. Never add production SQLite files, backup files, access URLs, session IDs, or screenshots containing household financial data to the documentation tree.