Skip to content

Design lineage ​

db-test-kit-js is a TypeScript composition of mature database-testing practices. Its strongest lineage is Rails: a small committed fixture baseline, human-readable labels, deterministic identifiers, factories for variation, and a transaction rolled back after each test. Django and Laravel provide independent evidence that transaction-backed isolation is a durable framework pattern rather than a Rails peculiarity.

The labels below keep the attribution precise:

  • Direct lineage means an API or design in this kit was consciously adapted from that source.
  • Parallel precedent means another ecosystem arrived at a similar practice independently.
  • Kit-specific adaptation means integration work needed to make the practice explicit and safe in a Vitest, TypeScript, ORM, and application-module environment.

Idea map ​

Idea in this kitLineageWhere it appears hereMaterial difference
One rollback transaction per testRails direct lineage; Django and Laravel parallel precedenttest/db/harness.ts, test/db/setup.tsA private thrown sentinel guarantees the ORM callback rolls back instead of committing
A small committed baselineRails fixtures direct lineagetest/fixtures/, global setupFixtures are typed TypeScript rows rather than YAML interpreted by the ORM
Stable IDs derived from labelsRails FixtureSet.identify direct lineagetest/fixtures/identify.tsUUIDv5 incorporates fixture-set identity as well as the label
Relationships written as label referencesRails fixture labels direct lineageidOf(fixtureSet, "label")TypeScript checks that the label belongs to that fixture set
Factories, traits, and lazy associationsfactory_bot direct lineage, via Fisherytest/factories/Persistence is isolated in onCreate; build() remains pure
Explicit non-transactional testsRails opt-out direct lineageuseCommittedDb() and committed-mode suitesThe escape hatch is restricted to disposable Postgres and owns cleanup
Database reset alternativesDjango and Laravel parallel precedentCaveat guidance and committed-mode cleanupThe kit does not hide truncation or migration behind its default path
Current-transaction application seamKit-specific adaptationmocked application db module and transaction contextProduction imports keep working while tests fail closed outside a transaction
Real authorization queries in testsKit-specific compositionsession helper plus real membership queryOnly identity lookup is replaceable; database authorization remains real
Executable caveats and update headersKit-specific maintenance designcaveat tests, managed headers, RECREATE.mdThe copied implementation carries its own boundaries and provenance

Why Rails is the primary reference ​

Rails joins the relevant ideas into one established workflow. Transactional tests preserve a known database state; fixture labels describe shared records; identify turns a label into a stable ID; and the factory_bot ecosystem covers data that should vary per test. That combination is closer to this kit than any single JavaScript package.

This is a port of the testing model, not of Rails syntax or global conventions. The kit keeps the useful division of responsibilities while exposing the database seam, transaction lifetime, opt-out path, and copy/update boundary as ordinary project code.

Continue with Rails testing ecosystem, then compare Django and Laravel and the available TypeScript prior art.

Copy-ready research prompt ​

text
Read the Design lineage section of the db-test-kit-js documentation, beginning at
https://danielrose7.github.io/db-test-kit-js/reference/lineage/. Follow only its primary-source links.
Produce a table with one row per db-test-kit-js feature and columns for classification (direct lineage,
parallel precedent, or kit-specific adaptation), upstream source, local implementation file, and important
semantic difference. Treat the repository's executable tests as the authority for current implementation
behavior. Do not claim that db-test-kit-js invented transactional tests, fixtures, deterministic fixture
IDs, or factories. Do not make numerical performance claims unless you also provide a reproducible
benchmark and environment details.

A reference implementation to copy from, not a dependency.