db-test-isolation

Enforces isolation rules for database tests using template-database cloning and global truncation.

Updated Jan 12, 2026
One-click install
npx skills add https://github.com/brandonarbini/arbini.family --skill db-test-isolation-brandonarbini
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: db-test-isolation
Source: https://github.com/brandonarbini/arbini.family/tree/main/.agents/skills/db-test-isolation
Command: npx skills add https://github.com/brandonarbini/arbini.family --skill db-test-isolation-brandonarbini

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Database-touching test suites often suffer from order-dependent failures, leaked connections, and slow manual cleanup code. This Skill encodes the counter-intuitive rules of a template-database + per-worker-clone + global-truncate architecture so tests stay isolated without any hand-written teardown. ## Core Features & Use Cases - Cleanup elimination: Explains why deleteMany, DELETE FROM, ID tracking, and manual rollback in afterEach/afterAll are bugs under this harness, since a global truncate already wipes every table. - Concurrency and transaction guardrails: Prevents raw BEGIN statements on pooled clients, forbids test.concurrent in DB-touching files, and bans row creation in beforeAll that later tests depend on. - Failure diagnosis: Maps symptoms like "passes alone but fails in the suite", "row not found after the first test", and connection-pool exhaustion to their architectural root causes. - Use Case: When writing a Vitest suite for a repository layer against a Postgres test database, load this Skill before adding beforeEach hooks or teardown logic to avoid cleanup code that fights the harness. ## Quick Start Review my database test file and tell me whether the cleanup and setup hooks follow the test-isolation rules.

Frequently Asked Questions about db-test-isolation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I clean up database rows between tests?▼

Under this harness you write no cleanup code at all. A global afterEach truncates every table automatically, so deleteMany calls, ID tracking arrays, and manual rollbacks in tests are unnecessary and indicate a misunderstanding of the architecture.

Why do my database tests pass alone but fail in the full suite?▼

Order-dependent failures usually come from rows created in beforeAll that the global truncate wipes after the first test, or from concurrent tests sharing one database. Move setup into beforeEach and keep DB-touching tests sequential within a file.

Can I use test.concurrent with database tests in Vitest?▼

No, not within a file that touches the database. Tests in one file share a single cloned database, so one test's truncate wipes another's rows mid-flight. Concurrency between files is safe because each worker gets its own clone.

Why does my test suite report too many clients or pool exhaustion?▼

Issuing a raw BEGIN from a test on a pooled client checks out an arbitrary connection and leaves a transaction open on it, leaking one connection per occurrence until the pool deadlocks. Use the ORM's transaction API inside the code under test instead.

Should I mock the database to make tests faster?▼

No. The template-database plus per-worker-clone design makes real database tests cheap, since each worker gets a private clone and truncation handles reset. Code under test may freely commit real transactions, so mocking the ORM is unnecessary.