Introduction

SveltyCMS uses a comprehensive Git workflow with automated testing and semantic versioning to ensure code quality and streamline the release process. A mandatory Local Quality Gate is enforced via native Git hooks to ensure that only verified code reaches the repository.

Our CI/CD and Local pipeline uses:

• Native Git Hooks: Zero-dependency quality gate (.githooks/pre-commit).
• Vitest (jsdom): Unified unit testing for components, stores, services, and API handlers.
• Unified Formatting: oxfmt-powered bun run format for lightning-fast cleanup.
• Vitest Unit Suite: Fast unit testing (1,100+ tests in under 10 seconds for the full suite).
• Playwright: Comprehensive E2E testing across multiple database backends.
• Tag-Driven Releases: Push a v* tag to main to trigger npm publish + GitHub Release.
• Standardized Network: Always use 127.0.0.1 for local consistency.

🛡️ Mandatory Local Quality Gate

Before any commit or push, SveltyCMS runs automated checks via native Git hooks. Activate them once per clone:

git config core.hooksPath .githooks

Git Hook Overview

SveltyCMS uses native Git hooks for local quality gates — no external precheck orchestrator script required.

Pre-commit (check-test-db-safety.ts → format+lint → lint-staged → unit tests)

.githooks/pre-commit runs:

1. Database safety — scripts/check-test-db-safety.ts blocks unsafe private.test.ts, live private.ts pointing at test DBs, and matching live/test DB names (user data protection).
2. Format + lint — bun run check (oxfmt + oxlint).
3. Lint-staged — bun run gate:fast.
4. Unit tests — vitest run (skipped if only docs changed).

Pre-push (~5 min) — production build + SQLite integration tests

.githooks/pre-push runs:

Security regression is not re-run on push. DB integration (multi-adapter matrix) and benchmarks are CI-only.

bun run gate                               # pre-push gate (build + SQLite integration)
bun run prepush                            # same as gate
bun test --timeout 300000 tests/integration/   # Integration only (needs build/)
bun run test:doctor                        # unit + SQLite integration + gate map

Branching Strategy

We have two primary, long-lived branches: main and next.

main Branch (Production)

• Purpose: Production-ready, stable code. This branch represents the latest official release.
• Protection: Protected branch requiring pull request reviews.
• Automated Actions:
  • Runs full Playwright + Vitest test suite.
  • Tag-driven releases: pushing a v* tag triggers npm publish + GitHub Release with auto-generated notes from commits.
• Version source: Git tags, not package.json.

next Branch (Development)

• Purpose: Development and staging. This is the primary branch for all new features.
• Automated Actions:
  • ✅ Runs full test suite on every push.
  • ✅ Tests across multiple databases (MongoDB, PostgreSQL, MariaDB).
  • ✅ No automatic releases (tests only).

Commit Message Convention

Our automated release process depends on a strict commit message format. We use the Conventional Commits specification.

Commit Message Model (Conventional Commits + TQA)

We follow an enhanced Conventional Commits specification to maintain a clear Technical Ledger.

Format:

<type>(<scope>): <subject> [TQA-Verified]

Types:

• tqa - Resilience & Integrity: Adding chaos tests, state-machine audits, or GDPR verification.
• perf - Throughput & Latency: Memory leak fixes, JIT optimizations, and benchmark improvements.
• feat - Feature: New functionality.
• fix - Stability: Bug fixes.
• refactor - Clean Code: Internal restructuring without behavior changes.

Mandatory Scopes:

• resilience: For any changes to circuit breakers or failover logic.
• temporal: For timezone/date normalization changes.
• concurrency: For locking and atomic transaction changes.
• ledger: For documentation and benchmark result updates.

Automated Testing Architecture

🧪 Vitest Unit Tests

• Speed: ⚡ Fast feedback on every commit (full suite via pre-commit).
• Location: tests/unit/
• Runner: Vitest with jsdom for components, stores, services, and API logic.
• Command: bun run test:unit · focused security: bun run test:security

🔗 Contract Tests (Adapter Parity)

• Purpose: Identical assertions run against all 4 databases (SQLite, MongoDB, PostgreSQL, MariaDB).
• Location: tests/integration/databases/contract.test.ts
• Contracts: Adapter, Auth, Permission, Setup Gating, Resilience.
• Command: bun run test:integration

🎭 Playwright Tests (E2E)

• Purpose: Browser automation for critical user journeys.
• Standard: Always point to 127.0.0.1:4173 via TEST_MODE=true.
• Location: tests/e2e/

🧠 Smart Test Orchestrator

• Purpose: Reads git diff and selects required test suites. Unknown changes fail closed.
• Command: bun run test:smart

🔍 AI Slop Scanner

• Purpose: Detects unsafe {@html}, legacy Svelte 4 patterns, missing ARIA, RTL violations, dead exports.
• Command: bun run slop

Tiered Local Testing Strategy

SveltyCMS uses a three-tier testing strategy that balances developer velocity with full CI parity. Each tier corresponds to a different Git lifecycle event:

Tier 1: Pre-Commit (.githooks/pre-commit) — Fast Feedback

Runs automatically on every git commit. Target: ~40 seconds (full unit suite; skipped if only docs changed).

Tier 2: Pre-Push (.githooks/pre-push) — Production Build + Integration

Runs automatically on every git push. Catches build and integration failures before they reach CI.

Multi-adapter DB integration + benchmarks are CI-only.

Manual equivalent: bun run prepush (alias for pre-push hook via hardened git wrapper).

Tier 3: Full CI Parity — CI Pipeline

CI runs the complete matrix automatically on every PR/push to next. Covers what local hooks skip:

• Whitebox: format + lint + type check + secret scan + deploy backdoor probe
• Build: COMPILE_ALL_ADAPTERS=true production build
• DB tests: Full multi-adapter matrix (MongoDB, PostgreSQL, MariaDB, SQLite)
• E2E: Playwright prep + 6 shards (chromium)
• Benchmarks: Performance regression detection

All local test commands must use config/private.test.ts only — they must not rename, overwrite, or connect through the developer’s config/private.ts (live user data). Isolation is env + policy (private-config-policy.ts), not backup/restore of live config.

Prerequisites for local integration tests: Docker Desktop with MongoDB (27017), MariaDB (3306), and PostgreSQL (5432) on 127.0.0.1.

Scripts Audit

All scripts in scripts/ and their role in the testing pipeline:

Core Scripts (Testing Pipeline)

Utility Scripts

Best Practices

Commit Workflow

1. Stage changes: git add .
2. Commit: git commit -m "feat(auth): add OAuth2 support" — pre-commit hook runs (DB safety → format+lint → lint-staged → unit tests).
3. Push: bun run git push origin feat/my-feature — pre-push hook runs (production build → bun test tests/integration/).
4. Before PR: Ensure CI passes — local hooks already guarantee the same gate.

Manual Verification

If you want to run checks outside the hook lifecycle:

# Pre-commit gate manually
bun run precommit

# Pre-push gate manually
bun run gate
# or: bun run prepush

# Unit + SQLite integration + gate map
bun run test:doctor

# Integration tests (SQLite; needs build/)
bun test --timeout 300000 tests/integration/

# Smart Test Orchestrator — auto-detects what to test from git diff
bun run test:smart

# AI Slop Scanner — detect code smells
bun run slop

Security & Slop Regression Check

For changes touching auth, middleware, or API routes, also run:

bun run test:security
bun run slop

Troubleshooting

“Permission Denied” on Git Hook

If you are on Linux/macOS and the hook fails to execute:

chmod +x .githooks/pre-commit .githooks/pre-push

“Database connection failed” in Tests

Ensure you are using 127.0.0.1 in your config/private.test.ts and that the test database is accessible.

Bypassing Hooks

bun run git commit and bun run git push block --no-verify. Bypassing requires invoking the system Git binary directly — a deliberate act, not muscle memory. CI will reject the same failures the hooks catch.

Docker DB Not Reachable During Pre-Push

If the pre-push hook or local CI reports postgresql is not reachable at 127.0.0.1:5432:

docker compose -f tests/docker-compose.yml --profile postgresql up -d
docker compose -f tests/docker-compose.yml --profile mariadb up -d
docker compose -f tests/docker-compose.yml --profile mongodb up -d

Credentials must match src/utils/test-db-credentials.ts (image defaults: postgres/postgres, root/mariadb, mongo no-auth).

Related Documentation

• Test Status Report
• API Testing
• Testing Strategy