@vensofts-integration-testkit/scenario-core
v0.1.4
Published
Relational Scenario SDK core: schema IR, recipe DSL, deterministic generation, constraint planning, independent fixture validation.
Maintainers
Readme
@vensofts-integration-testkit/scenario-core
Deterministic, constraint-valid relational test data from a short recipe. Describe your tables and how many rows you need. The SDK proves the recipe is satisfiable, or explains exactly why not, then generates data that passes every key, foreign key, unique and CHECK constraint, identically on every machine. MIT. No database driver.
The open core of the NodeSDK Relational Scenario SDK. Node.js 22 or newer. For PostgreSQL loading see
@vensofts-integration-testkit/scenario-postgres;
for the command line see @vensofts-integration-testkit/scenario-cli.
Install
npm install --save-dev @vensofts-integration-testkit/scenario-coreWhat it does
- Schema IR (
defineSchema) and recipe DSL (defineRecipe): counts, per-parent cardinalities, generators, aliases, relationships, derived values, invariants and obligations. compileRecipereturnsok,unsatisfiable,budget-exhaustedorunsupported. Every non-okoutcome includes explanations, the constraint IDs involved and a dependency graph slice. It never fails late by writing half a dataset.- Deterministic generation: per-value xoshiro128** streams with SHA-256 stream keys. Results do
not depend on declaration order, chunk size or worker count. Frozen test vectors pin determinism
version
1. - Exact decimals for
numeric, derived values (x.mul,x.sum, …), and CHECK-aware generation. - Independent validator (
validateFixture): PK, unique, FK, NOT NULL, CHECK, derived values, invariants and scenario obligations. diffFixtures,recomputeDerived,compareSchemas+ recipe impact, t-wise covering arrays, boundary witnesses, andexportWitnessManifestfor the Authorization SDK.
import assert from 'node:assert/strict';
import {
compileRecipe,
defineRecipe,
defineSchema,
f,
fk,
t,
} from '@vensofts-integration-testkit/scenario-core';
const schema = defineSchema({
models: {
users: { fields: { id: f.required(t.uuid()) }, primaryKey: ['id'] },
seats: {
fields: { user_id: f.required(t.uuid()) },
primaryKey: ['user_id'],
foreignKeys: [fk('seats_user_fk', ['user_id'], 'users', ['id'])],
},
},
});
// 5 seats keyed by user_id need 5 distinct users; only 2 exist → proven unsatisfiable before any write.
const recipe = defineRecipe({
id: 'too-many-seats',
version: 1,
seed: 's',
clock: '2026-01-15T12:00:00.000Z',
models: { users: { count: 2 }, seats: { count: 5 } },
});
const r = compileRecipe({ schema, recipe });
assert.equal(r.status, 'unsatisfiable');
if (r.status === 'unsatisfiable') assert.ok(r.problems[0]!.explanation.length > 0);Use it in tests with withFixture / prepareFixture from @vensofts-integration-testkit/scenario-core/testing.
Pro features
Failure reduction, recipe packs and HTML reports are in
@vensofts-integration-testkit/scenario-pro under a
commercial license: a free 14-day trial, then USD 299 per year per organization; see the price table. Contact
[email protected].
