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 (DB safety → format+lint → lint-staged → risk:audit → unit → SBOM)

.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. risk:audit — security-risk scan (all adapters) + secret misuse + slop + bun audit + OSV (skipped if only docs changed).
5. Unit tests — vitest run (skipped if only docs changed).
6. SBOM sync — when bun.lock / package.json changed.

Pre-push (~5–8 min) — production build + verifiers + tenant + SQLite integration

.githooks/pre-push runs:

Full unit suite is not re-run on push. Multi-adapter DB matrix, E2E, and benchmarks are CI-only. Docs-only pushes skip build + integration.

bun run gate                               # pre-push gate (build + verifiers + tenant + SQLite)
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
bun run risk:audit                         # same scanners as pre-commit step 4

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–60 seconds (full unit suite + risk audit; 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 + E2E + benchmarks are CI-only.

Manual equivalent: bun run prepush / bun run gate (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