@lssm/lib.testing 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,48 @@
+# @lssm/lib.testing
+
+**Safe regeneration verification** — Capture production traffic and generate golden tests automatically.
+
+Golden-test utilities that record real requests/responses and generate runnable test suites. Prove that regenerated code behaves identically to the original.
+
+- **TrafficRecorder** captures production requests/responses with sampling + sanitization.
+- **GoldenTestGenerator** converts snapshots into runnable suites.
+- **Adapters** output Vitest or Jest files and helper runners.
+
+### Usage
+
+```ts
+import {
+  TrafficRecorder,
+  InMemoryTrafficStore,
+} from '@lssm/lib.testing/recorder';
+
+const recorder = new TrafficRecorder({
+  store: new InMemoryTrafficStore(),
+  sampleRate: 0.01,
+});
+
+await recorder.record({
+  operation: { name: 'orders.create', version: 3 },
+  input: payload,
+  output,
+  success: true,
+  timestamp: new Date(),
+});
+```
+
+See `GoldenTestGenerator` for generating suites and CLI in `@lssm/app.contracts-cli`.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/adapters/jest-adapter.d.ts

@@ -0,0 +1,12 @@
+import { GoldenTestCase } from "../types.js";
+
+//#region src/adapters/jest-adapter.d.ts
+interface JestAdapterOptions {
+  suiteName: string;
+  cases: GoldenTestCase[];
+  runnerImport: string;
+  runnerFunction: string;
+}
+declare function generateJestSuite(options: JestAdapterOptions): string;
+//#endregion
+export { JestAdapterOptions, generateJestSuite };

package/dist/adapters/jest-adapter.js

@@ -0,0 +1,13 @@
+import{serialize as e}from"../generator/assertion-builder.js";function t(t){let n=t.cases.map(n=>{let r=e(n.input),i=e(n.metadata??{}),a=`const result = await ${t.runnerFunction}(input${n.id}, metadata${n.id});
+    expect(result).toEqual(${e(n.expectedOutput??null)});`,o=`await expect(${t.runnerFunction}(input${n.id}, metadata${n.id})).rejects.toMatchObject(${e(n.expectedError??{message:`expected failure`})});`;return`
+  test('${n.name}', async () => {
+    const input${n.id} = ${r};
+    const metadata${n.id} = ${i};
+    ${n.success?a:o}
+  });`}).join(`
+`);return`
+import { ${t.runnerFunction} } from '${t.runnerImport}';
+
+describe('${t.suiteName}', () => {${n}
+});
+`.trim()}export{t as generateJestSuite};

package/dist/adapters/vitest-adapter.d.ts

@@ -0,0 +1,12 @@
+import { GoldenTestCase } from "../types.js";
+
+//#region src/adapters/vitest-adapter.d.ts
+interface VitestAdapterOptions {
+  suiteName: string;
+  cases: GoldenTestCase[];
+  runnerImport: string;
+  runnerFunction: string;
+}
+declare function generateVitestSuite(options: VitestAdapterOptions): string;
+//#endregion
+export { VitestAdapterOptions, generateVitestSuite };

package/dist/adapters/vitest-adapter.js

@@ -0,0 +1,14 @@
+import{serialize as e}from"../generator/assertion-builder.js";function t(t){let n=t.cases.map(n=>{let r=e(n.input),i=e(n.metadata??{}),a=n.success?[`const result = await ${t.runnerFunction}(input${n.id}, metadata${n.id});`,`expect(result).toEqual(${e(n.expectedOutput??null)});`]:[`await expect(${t.runnerFunction}(input${n.id}, metadata${n.id})).rejects.toMatchObject(${e(n.expectedError??{message:`expected failure`})});`];return`
+  it('${n.name}', async () => {
+    const input${n.id} = ${r};
+    const metadata${n.id} = ${i};
+    ${a.join(`
+    `)}
+  });`}).join(`
+`);return`
+import { describe, it, expect } from 'bun:test';
+import { ${t.runnerFunction} } from '${t.runnerImport}';
+
+describe('${t.suiteName}', () => {${n}
+});
+`.trim()}export{t as generateVitestSuite};

package/dist/generator/assertion-builder.d.ts

@@ -0,0 +1,11 @@
+import { GoldenTestCase } from "../types.js";
+
+//#region src/generator/assertion-builder.d.ts
+interface AssertionContext {
+  runnerCall: string;
+  caseRef: string;
+}
+declare function buildAssertions(testCase: GoldenTestCase, ctx: AssertionContext): string;
+declare function serialize(value: unknown): string;
+//#endregion
+export { AssertionContext, buildAssertions, serialize };

package/dist/generator/assertion-builder.js

@@ -0,0 +1,2 @@
+function e(e,n){return e.success?[`const result = await ${n.runnerCall};`,`expect(result).toEqual(${t(e.expectedOutput??null)});`].join(`
+      `):`await expect(${n.runnerCall}).rejects.toMatchObject(${t(e.expectedError??{message:`expected failure`})});`}function t(e){return JSON.stringify(e,(e,t)=>t instanceof Date?t.toISOString():t===void 0?null:t,2)}export{e as buildAssertions,t as serialize};

package/dist/generator/golden-test-generator.d.ts

@@ -0,0 +1,26 @@
+import { GoldenTestCase, TrafficSnapshot } from "../types.js";
+
+//#region src/generator/golden-test-generator.d.ts
+interface GoldenTestGeneratorOptions {
+  suiteName: string;
+  runnerImport: string;
+  runnerFunction: string;
+  framework?: 'vitest' | 'jest';
+  serializeMetadata?: (snapshot: TrafficSnapshot) => Record<string, unknown>;
+}
+declare class GoldenTestGenerator {
+  private readonly serializeMetadata;
+  constructor(serializeMetadata?: GoldenTestGeneratorOptions['serializeMetadata']);
+  createCases(snapshots: TrafficSnapshot[]): GoldenTestCase[];
+  generate(snapshots: TrafficSnapshot[], options: GoldenTestGeneratorOptions): string;
+}
+type GoldenTestRunner = (input: unknown, metadata?: Record<string, unknown>) => Promise<unknown>;
+interface GoldenTestRunResult {
+  caseId: string;
+  passed: boolean;
+  durationMs: number;
+  error?: unknown;
+}
+declare function runGoldenTests(cases: GoldenTestCase[], runner: GoldenTestRunner): Promise<GoldenTestRunResult[]>;
+//#endregion
+export { GoldenTestGenerator, GoldenTestGeneratorOptions, GoldenTestRunResult, GoldenTestRunner, runGoldenTests };

package/dist/generator/golden-test-generator.js

@@ -0,0 +1 @@
+import{generateVitestSuite as e}from"../adapters/vitest-adapter.js";import{generateJestSuite as t}from"../adapters/jest-adapter.js";import{randomUUID as n}from"node:crypto";import{performance as r}from"node:perf_hooks";var i=class{constructor(e=e=>({tenantId:e.tenantId,userId:e.userId,channel:e.channel})){this.serializeMetadata=e}createCases(e){return e.map((e,t)=>({id:e.id??n(),name:e.success?`case-${t+1}-success`:`case-${t+1}-failure`,input:e.input,expectedOutput:e.output,expectedError:e.error,success:e.success,metadata:this.serializeMetadata?.(e)}))}generate(n,r){let i=this.createCases(n);return r.framework===`jest`?t({suiteName:r.suiteName,cases:i,runnerImport:r.runnerImport,runnerFunction:r.runnerFunction}):e({suiteName:r.suiteName,cases:i,runnerImport:r.runnerImport,runnerFunction:r.runnerFunction})}};async function a(e,t){let n=[];for(let i of e){let e=r.now();try{let a=await t(i.input,i.metadata);if(!i.success){n.push({caseId:i.id,passed:!1,durationMs:r.now()-e,error:Error(`Expected failure but runner resolved`)});continue}let o=JSON.stringify(a)===JSON.stringify(i.expectedOutput??null);n.push({caseId:i.id,passed:o,durationMs:r.now()-e,error:o?void 0:{expected:i.expectedOutput,received:a}})}catch(t){let a=r.now()-e;i.success?n.push({caseId:i.id,passed:!1,durationMs:a,error:t}):n.push({caseId:i.id,passed:!0,durationMs:a})}}return n}export{i as GoldenTestGenerator,a as runGoldenTests};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { GoldenTestCase, RuntimeContract, TrafficSnapshot } from "./types.js";
+import { InMemoryTrafficStore, RecordOperationInput, TrafficRecorder, TrafficRecorderOptions, TrafficStore } from "./recorder/traffic-recorder.js";
+import { GoldenTestGenerator, GoldenTestGeneratorOptions, GoldenTestRunResult, GoldenTestRunner, runGoldenTests } from "./generator/golden-test-generator.js";
+import { AssertionContext, buildAssertions, serialize } from "./generator/assertion-builder.js";
+import { VitestAdapterOptions, generateVitestSuite } from "./adapters/vitest-adapter.js";
+import { JestAdapterOptions, generateJestSuite } from "./adapters/jest-adapter.js";
+export { AssertionContext, GoldenTestCase, GoldenTestGenerator, GoldenTestGeneratorOptions, GoldenTestRunResult, GoldenTestRunner, InMemoryTrafficStore, JestAdapterOptions, RecordOperationInput, RuntimeContract, TrafficRecorder, TrafficRecorderOptions, TrafficSnapshot, TrafficStore, VitestAdapterOptions, buildAssertions, generateJestSuite, generateVitestSuite, runGoldenTests, serialize };

package/dist/index.js

@@ -0,0 +1 @@
+import{InMemoryTrafficStore as e,TrafficRecorder as t}from"./recorder/traffic-recorder.js";import{buildAssertions as n,serialize as r}from"./generator/assertion-builder.js";import{generateVitestSuite as i}from"./adapters/vitest-adapter.js";import{generateJestSuite as a}from"./adapters/jest-adapter.js";import{GoldenTestGenerator as o,runGoldenTests as s}from"./generator/golden-test-generator.js";export{o as GoldenTestGenerator,e as InMemoryTrafficStore,t as TrafficRecorder,n as buildAssertions,a as generateJestSuite,i as generateVitestSuite,s as runGoldenTests,r as serialize};

package/dist/recorder/traffic-recorder.d.ts

@@ -0,0 +1,39 @@
+import { TrafficSnapshot } from "../types.js";
+
+//#region src/recorder/traffic-recorder.d.ts
+interface TrafficStore {
+  save(snapshot: TrafficSnapshot): Promise<void>;
+  list(operation?: TrafficSnapshot['operation']['name']): Promise<TrafficSnapshot[]>;
+}
+declare class InMemoryTrafficStore implements TrafficStore {
+  private readonly items;
+  save(snapshot: TrafficSnapshot): Promise<void>;
+  list(operation?: string): Promise<TrafficSnapshot[]>;
+}
+interface TrafficRecorderOptions {
+  store: TrafficStore;
+  sampleRate?: number;
+  sanitize?: (snapshot: TrafficSnapshot) => TrafficSnapshot;
+}
+interface RecordOperationInput {
+  operation: TrafficSnapshot['operation'];
+  input: unknown;
+  output?: unknown;
+  error?: TrafficSnapshot['error'];
+  success: boolean;
+  durationMs?: number;
+  tenantId?: string;
+  userId?: string;
+  channel?: string;
+  metadata?: Record<string, unknown>;
+}
+declare class TrafficRecorder {
+  private readonly store;
+  private readonly sampleRate;
+  private readonly sanitize?;
+  constructor(options: TrafficRecorderOptions);
+  record(input: RecordOperationInput): Promise<void>;
+  private shouldSample;
+}
+//#endregion
+export { InMemoryTrafficStore, RecordOperationInput, TrafficRecorder, TrafficRecorderOptions, TrafficStore };

package/dist/recorder/traffic-recorder.js

@@ -0,0 +1 @@
+import{randomUUID as e}from"node:crypto";var t=class{items=[];async save(e){this.items.push(e)}async list(e){return e?this.items.filter(t=>t.operation.name===e):[...this.items]}},n=class{store;sampleRate;sanitize;constructor(e){this.store=e.store,this.sampleRate=e.sampleRate??1,this.sanitize=e.sanitize}async record(t){if(!this.shouldSample())return;let n={id:e(),operation:t.operation,input:r(t.input),output:r(t.output),error:t.error?r(t.error):void 0,success:t.success,timestamp:new Date,durationMs:t.durationMs,tenantId:t.tenantId,userId:t.userId,channel:t.channel,metadata:t.metadata},i=this.sanitize?this.sanitize(n):n;await this.store.save(i)}shouldSample(){return this.sampleRate>=1?!0:Math.random()<=this.sampleRate}};function r(e){if(e==null)return e??void 0;try{let t=globalThis.structuredClone;return typeof t==`function`?t(e):JSON.parse(JSON.stringify(e))}catch{return}}export{t as InMemoryTrafficStore,n as TrafficRecorder};

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+import { ContractSpec, ResourceRefDescriptor } from "@lssm/lib.contracts";
+import { AnySchemaModel } from "@lssm/lib.schema";
+
+//#region src/types.d.ts
+interface TrafficSnapshot {
+  id: string;
+  operation: {
+    name: string;
+    version: number;
+  };
+  input: unknown;
+  output?: unknown;
+  error?: {
+    name?: string;
+    message?: string;
+    stack?: string;
+    code?: string;
+  };
+  success: boolean;
+  timestamp: Date;
+  durationMs?: number;
+  tenantId?: string;
+  userId?: string;
+  channel?: string;
+  metadata?: Record<string, unknown>;
+}
+interface GoldenTestCase {
+  id: string;
+  name: string;
+  input: unknown;
+  expectedOutput?: unknown;
+  expectedError?: {
+    name?: string;
+    message?: string;
+    code?: string;
+  };
+  success: boolean;
+  metadata?: Record<string, unknown>;
+}
+type RuntimeContract = ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+//#endregion
+export { GoldenTestCase, RuntimeContract, TrafficSnapshot };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@lssm/lib.testing",
+  "version": "0.0.0-canary-20251206160926",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun run"
+  },
+  "dependencies": {
+    "@lssm/lib.contracts": "workspace:*"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}