@decohere/testing 0.0.1-dev.119

package/README.md

@@ -0,0 +1,34 @@
+# Testing
+
+Vitest helpers for testing Decohere code ([ADR 0015](../../docs/adr/0015-core-devkit-testing.md)). Only for tests, never imported by library or app code.
+
+| Export | What it does |
+|---|---|
+| `resetMemfs`, `seedMemfs`, `createTestFile`, `readFile`, `fileExists` | An in-memory file system ([memfs](https://github.com/streamich/memfs)) for tests that mock `node:fs` |
+| `withMemfsFsForGlob` | Wraps the real `glob` module so its file access goes through memfs: real matching, in-memory files |
+| `createMockLogger` | A scribe-shaped logger whose methods are `vi.fn()` spies |
+| `spyOnConstructor` | Spies on a class constructor without losing `design:paramtypes`, so crucible can still inject it ([how-to](../../docs/testing/how-tos/vitest-constructor-spy-with-di.md)) |
+| `flushPromises` | Waits until pending promise callbacks have run |
+
+This repo routes file access to memfs in a Vitest setup file ([`test/fs.setup.ts`](../../test/fs.setup.ts)), with `__mocks__/fs.ts` re-exporting memfs:
+
+```ts
+// vitest setup file
+vi.mock("node:fs");
+vi.mock("node:fs/promises");
+vi.mock("glob", async () => {
+	const actual = await vi.importActual<typeof import("glob")>("glob");
+	const { withMemfsFsForGlob } = await import("@decohere/testing");
+	return withMemfsFsForGlob(actual);
+});
+
+// a test
+import { resetMemfs, seedMemfs } from "@decohere/testing";
+
+beforeEach(() => {
+	resetMemfs();
+	seedMemfs({ "/app/config/config.yaml": "name: api\n" });
+});
+```
+
+`vitest` and `memfs` should be peer dependencies; the dependency sync can't declare peers yet ([#683](https://github.com/typesmiths/decohere/issues/683)).

package/commonjs/src/flush-promises.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "flushPromises", {
+    enumerable: true,
+    get: function() {
+        return flushPromises;
+    }
+});
+var scheduler = typeof setImmediate === "function" ? setImmediate : setTimeout;
+function flushPromises() {
+    return new Promise((resolve)=>{
+        scheduler(resolve);
+    });
+}

package/commonjs/src/glob-with-memfs.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "withMemfsFsForGlob", {
+    enumerable: true,
+    get: function() {
+        return withMemfsFsForGlob;
+    }
+});
+const _memfs = require("memfs");
+function withMemfsFsForGlob(actual) {
+    // Preserve all module exports, overriding only `glob` to force `{ fs: memfs }`.
+    const glob = (pattern, options)=>actual.glob(pattern, {
+            ...options,
+            fs: _memfs.fs
+        });
+    return {
+        ...actual,
+        glob
+    };
+}

package/commonjs/src/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./flush-promises.js"), exports);
+_export_star(require("./glob-with-memfs.js"), exports);
+_export_star(require("./memfs.js"), exports);
+_export_star(require("./mock-logger.js"), exports);
+_export_star(require("./spy-on-constructor.js"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/commonjs/src/memfs.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get createTestFile () {
+        return createTestFile;
+    },
+    get fileExists () {
+        return fileExists;
+    },
+    get readFile () {
+        return readFile;
+    },
+    get resetMemfs () {
+        return resetMemfs;
+    },
+    get seedMemfs () {
+        return seedMemfs;
+    }
+});
+const _memfs = require("memfs");
+function resetMemfs() {
+    _memfs.vol.reset();
+}
+function seedMemfs(files) {
+    _memfs.vol.fromJSON(files);
+}
+function createTestFile(filePath, content) {
+    _memfs.fs.mkdirSync(filePath.substring(0, filePath.lastIndexOf("/")), {
+        recursive: true
+    });
+    _memfs.fs.writeFileSync(filePath, content);
+}
+async function readFile(filePath) {
+    const response = await _memfs.fs.promises.readFile(filePath, "utf8");
+    return response;
+}
+function fileExists(filePath) {
+    try {
+        _memfs.vol.statSync(filePath);
+        return true;
+    } catch  {
+        return false;
+    }
+}

package/commonjs/src/mock-logger.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "createMockLogger", {
+    enumerable: true,
+    get: function() {
+        return createMockLogger;
+    }
+});
+const _vitest = require("vitest");
+const DefaultLogLevels = {
+    fatal: 60,
+    error: 50,
+    warn: 40,
+    info: 30,
+    debug: 20,
+    trace: 10
+};
+function createMockLogger() {
+    return {
+        error: _vitest.vi.fn(),
+        info: _vitest.vi.fn(),
+        warn: _vitest.vi.fn(),
+        debug: _vitest.vi.fn(),
+        trace: _vitest.vi.fn(),
+        fatal: _vitest.vi.fn(),
+        isLevelEnabled: _vitest.vi.fn().mockReturnValue(true),
+        get currentLevel () {
+            return "info";
+        },
+        get logLevels () {
+            return DefaultLogLevels;
+        }
+    };
+}

package/commonjs/src/spy-on-constructor.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "spyOnConstructor", {
+    enumerable: true,
+    get: function() {
+        return spyOnConstructor;
+    }
+});
+const _vitest = require("vitest");
+function spyOnConstructor(Target) {
+    const spy = _vitest.vi.fn();
+    const ProxiedTarget = new Proxy(Target, {
+        construct (Ctor, args) {
+            spy(...args);
+            return Reflect.construct(Ctor, args);
+        }
+    });
+    for (const key of Reflect.getMetadataKeys(Target)){
+        Reflect.defineMetadata(key, Reflect.getMetadata(key, Target), ProxiedTarget);
+    }
+    return {
+        spy,
+        Proxy: ProxiedTarget
+    };
+}

package/es6/src/flush-promises.js

@@ -0,0 +1,6 @@
+var scheduler = typeof setImmediate === "function" ? setImmediate : setTimeout;
+export function flushPromises() {
+    return new Promise((resolve)=>{
+        scheduler(resolve);
+    });
+}

package/es6/src/glob-with-memfs.js

@@ -0,0 +1,20 @@
+import { fs } from "memfs";
+// Wraps a real `glob` module so all file-system access is routed through memfs.
+//
+// Why this exists:
+// - Integration tests often need real glob matching semantics.
+// - Vitest `vi.mock` factories are hoisted, so directly importing and patching
+//   `glob` inside helper modules can trigger initialization-order issues.
+// - Passing the already-loaded `actual` module keeps the helper pure and
+//   hoist-safe while still allowing us to inject memfs.
+export function withMemfsFsForGlob(actual) {
+    // Preserve all module exports, overriding only `glob` to force `{ fs: memfs }`.
+    const glob = (pattern, options)=>actual.glob(pattern, {
+            ...options,
+            fs
+        });
+    return {
+        ...actual,
+        glob
+    };
+}

package/es6/src/index.js

@@ -0,0 +1,5 @@
+export * from "./flush-promises.js";
+export * from "./glob-with-memfs.js";
+export * from "./memfs.js";
+export * from "./mock-logger.js";
+export * from "./spy-on-constructor.js";

package/es6/src/memfs.js

@@ -0,0 +1,25 @@
+import { fs, vol } from "memfs";
+export function resetMemfs() {
+    vol.reset();
+}
+export function seedMemfs(files) {
+    vol.fromJSON(files);
+}
+export function createTestFile(filePath, content) {
+    fs.mkdirSync(filePath.substring(0, filePath.lastIndexOf("/")), {
+        recursive: true
+    });
+    fs.writeFileSync(filePath, content);
+}
+export async function readFile(filePath) {
+    const response = await fs.promises.readFile(filePath, "utf8");
+    return response;
+}
+export function fileExists(filePath) {
+    try {
+        vol.statSync(filePath);
+        return true;
+    } catch  {
+        return false;
+    }
+}

package/es6/src/mock-logger.js

@@ -0,0 +1,26 @@
+import { vi } from "vitest";
+const DefaultLogLevels = {
+    fatal: 60,
+    error: 50,
+    warn: 40,
+    info: 30,
+    debug: 20,
+    trace: 10
+};
+export function createMockLogger() {
+    return {
+        error: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        debug: vi.fn(),
+        trace: vi.fn(),
+        fatal: vi.fn(),
+        isLevelEnabled: vi.fn().mockReturnValue(true),
+        get currentLevel () {
+            return "info";
+        },
+        get logLevels () {
+            return DefaultLogLevels;
+        }
+    };
+}

package/es6/src/spy-on-constructor.js

@@ -0,0 +1,31 @@
+import { vi } from "vitest";
+/**
+ * Creates a Proxy around a class constructor that intercepts `new` calls,
+ * records arguments via a spy, and delegates to the real constructor.
+ *
+ * Use this to assert what was injected into a class by a DI container
+ * (e.g. Container) without changing actual behavior.
+ *
+ * The proxy copies all `reflect-metadata` entries from the original class
+ * so that DI metadata (`design:paramtypes`) remains intact.
+ *
+ * @example
+ * const { spy, Proxy: SpiedService } = spyOnConstructor(MyService);
+ * // use SpiedService in place of MyService when wiring the container
+ * expect(spy).toHaveBeenCalledWith(expect.any(ExpectedDependency));
+ */ export function spyOnConstructor(Target) {
+    const spy = vi.fn();
+    const ProxiedTarget = new Proxy(Target, {
+        construct (Ctor, args) {
+            spy(...args);
+            return Reflect.construct(Ctor, args);
+        }
+    });
+    for (const key of Reflect.getMetadataKeys(Target)){
+        Reflect.defineMetadata(key, Reflect.getMetadata(key, Target), ProxiedTarget);
+    }
+    return {
+        spy,
+        Proxy: ProxiedTarget
+    };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@decohere/testing",
+  "version": "0.0.1-dev.119",
+  "description": "Test helpers for Decohere code under Vitest: memfs file systems, a mock logger, constructor spies that keep DI metadata.",
+  "keywords": [
+    "typescript",
+    "testing",
+    "vitest",
+    "memfs",
+    "decohere"
+  ],
+  "license": "ISC",
+  "author": "Typesmiths",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "types": "./types/src/index.d.ts",
+      "import": "./es6/src/index.js",
+      "require": "./commonjs/src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@decohere/core": "0.0.1-dev.119"
+  },
+  "devDependencies": {
+    "memfs": "^4.17.0",
+    "vitest": "^3.2.6"
+  }
+}

package/types/src/flush-promises.d.ts

@@ -0,0 +1 @@
+export declare function flushPromises(): Promise<unknown>;

package/types/src/glob-with-memfs.d.ts

@@ -0,0 +1,3 @@
+export declare function withMemfsFsForGlob<TGlobModule extends {
+    glob: (...args: unknown[]) => unknown;
+}>(actual: TGlobModule): TGlobModule;

package/types/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./flush-promises.js";
+export * from "./glob-with-memfs.js";
+export * from "./memfs.js";
+export * from "./mock-logger.js";
+export * from "./spy-on-constructor.js";

package/types/src/memfs.d.ts

@@ -0,0 +1,5 @@
+export declare function resetMemfs(): void;
+export declare function seedMemfs(files: Record<string, string>): void;
+export declare function createTestFile(filePath: string, content: string | Buffer): void;
+export declare function readFile(filePath: string): Promise<string>;
+export declare function fileExists(filePath: string): boolean;

package/types/src/mock-logger.d.ts

@@ -0,0 +1,13 @@
+export type LoggerMethod = (msg: string | number | object, ...args: unknown[]) => void;
+export type TestLogger = {
+    fatal: LoggerMethod;
+    error: LoggerMethod;
+    warn: LoggerMethod;
+    info: LoggerMethod;
+    debug: LoggerMethod;
+    trace: LoggerMethod;
+    isLevelEnabled(level: string): boolean;
+    readonly currentLevel: string;
+    readonly logLevels: Record<string, number>;
+};
+export declare function createMockLogger(): TestLogger;

package/types/src/spy-on-constructor.d.ts

@@ -0,0 +1,21 @@
+import { vi } from "vitest";
+import type { Constructable } from "@decohere/core/reflection";
+/**
+ * Creates a Proxy around a class constructor that intercepts `new` calls,
+ * records arguments via a spy, and delegates to the real constructor.
+ *
+ * Use this to assert what was injected into a class by a DI container
+ * (e.g. Container) without changing actual behavior.
+ *
+ * The proxy copies all `reflect-metadata` entries from the original class
+ * so that DI metadata (`design:paramtypes`) remains intact.
+ *
+ * @example
+ * const { spy, Proxy: SpiedService } = spyOnConstructor(MyService);
+ * // use SpiedService in place of MyService when wiring the container
+ * expect(spy).toHaveBeenCalledWith(expect.any(ExpectedDependency));
+ */
+export declare function spyOnConstructor<T extends Constructable>(Target: T): {
+    spy: ReturnType<typeof vi.fn>;
+    Proxy: T;
+};