SveltyCMS

Documentation

Database & Authentication Testing Guide

Comprehensive guide for testing the database layer, authentication system, and multi-database support in SveltyCMS.

Last updated: 3/6/2026

Database & Authentication Testing Guide

Overview

SveltyCMS uses a database-agnostic architecture via the IDBAdapter interface. In 2026, we standardized on a SQLite-First local testing strategy to ensure 100% deterministic results across all environments (Windows, SSH, CI).

This guide covers:

  • SQLite (Default): Primary driver for unit and integration tests.
  • MongoDB / Postgres / MariaDB: Verified via CI matrix testing.
  • Strict Isolation: How we protect production data.

The SQLite-First Strategy (2026)

Previously, local testing required a running MongoDB instance, which often led to authentication errors or “Server Busy” timeouts.

Why SQLite for Tests?

  1. Zero Latency: No network overhead; tests run in milliseconds.
  2. Zero Config: No Docker or local Mongo service required.
  3. Deterministic: Every test run starts with a fresh file-based database (sveltycms_test.db).

Test Architecture

Isolation Flow

SveltyCMS enforces a hard boundary between production and testing:

  1. TEST_MODE: Automatically enabled during bun run test:*.
  2. Config Redirect: The system is hard-coded to look for config/private.test.ts when testing.
  3. Safety Guard: src/databases/db.ts will throw a fatal error if it detects config/private.ts (Live) being loaded while in test mode.

Database Test Sequence

sequenceDiagram participant Runner as Bun Test Runner participant Server as Preview Server participant DB as SQLite (test.db) Runner->>Server: GET /api/testing/reset Server->>DB: Delete test.db file Runner->>Server: POST /api/testing/seed Server->>DB: Initialize schema & Insert Admin Note over Runner,DB: Execute Black-Box Tests

Authentication System Tests

File: tests/unit/auth/*.test.ts & tests/integration/api/user.test.ts

Key Test Areas:

1. Argon2id Password Security

  • ✅ Quantum-resistant hashing verification.
  • ✅ Timing attack resistance (constant-time comparisons).

2. Session & Rotation

  • ✅ Secure cookie handling.
  • ✅ Session rotation on privilege change.
  • ✅ Automatic cleanup of expired sessions.

3. SAML 2.0 / Enterprise SSO

  • ✅ Verified via BoxyHQ Jackson.
  • ✅ Tests mock connection strings and IdP redirects.

Running Database Tests

1. The Standard Suite (SQLite)

This is the recommended way to test locally:

bun run test:integration

The script will automatically set DB_TYPE=sqlite and run the suite.

2. Testing Other Adapters

To verify MongoDB or PostgreSQL locally:

DB_TYPE=mongodb DB_HOST=localhost bun run test:integration

Troubleshooting

“UNIQUE constraint failed: roles._id”

This usually happens if multiple Playwright workers try to seed the database at once. Fix: I updated playwright.config.ts to use workers: 1 for setup-related tests.

“Database connection failed”

Ensure your config/private.test.ts has the correct credentials. If using SQLite, ensure the process has write permissions to the project root.

Related Documentation

testingdatabaseauthenticationsqlitemongodb