bupkis 0.18.3 → 1.0.0

package/dist/snapshot/adapters/fallback.cjs

@@ -0,0 +1,452 @@
+"use strict";
+/**
+ * Fallback adapter for frameworks without native snapshot support.
+ *
+ * This adapter provides custom snapshot storage for test frameworks that don't
+ * have built-in snapshot functionality (e.g., Mocha, Tap, custom test
+ * runners).
+ *
+ * **Storage Format:** Snapshots are stored as CommonJS modules in
+ * `__snapshots__/` directories:
+ *
+ * ```javascript
+ * // __snapshots__/my-test.test.js.snap.cjs
+ * module.exports = {
+ *   'test name': '{\n  "value": 42\n}',
+ *   'test name 2': '"another snapshot"',
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fallbackAdapter = exports.FallbackAdapter = void 0;
+const json_stable_stringify_1 = __importDefault(require("json-stable-stringify"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const serializer_js_1 = require("../serializer.cjs");
+const { entries } = Object;
+/**
+ * Extract snapshot context from Mocha's `this` context.
+ *
+ * Mocha provides test information through `this.test` in test callbacks. This
+ * function attempts to extract the test name and file path from that
+ * structure.
+ *
+ * @example
+ *
+ * ```typescript
+ * describe('suite', function () {
+ *   it('test', function () {
+ *     const ctx = extractMochaContext(this);
+ *     // ctx = {
+ *     //   testPath: 'suite test',
+ *     //   filePath: '/path/to/test.js',
+ *     //   isUpdateMode: false
+ *     // }
+ *   });
+ * });
+ * ```
+ *
+ * @function
+ * @param context - Potential Mocha context object
+ * @returns Snapshot context if Mocha context detected, null otherwise
+ */
+const extractMochaContext = (context) => {
+    const mochaCtx = context;
+    if (mochaCtx?.test?.fullTitle) {
+        return {
+            filePath: mochaCtx.test.file || getTestFilePathFromStack(),
+            isUpdateMode: process.env.BUPKIS_UPDATE_SNAPSHOTS === '1',
+            testPath: mochaCtx.test.fullTitle(),
+        };
+    }
+    return null;
+};
+/**
+ * Get snapshot file path for a test file.
+ *
+ * Snapshots are stored in a `__snapshots__/` directory next to the test file.
+ * The snapshot filename is based on the test file path, with slashes replaced
+ * by dashes to create a flat structure.
+ *
+ * Uses `.cjs` extension for CommonJS compatibility in both CJS and ESM
+ * projects.
+ *
+ * @example
+ *
+ * ```typescript
+ * getSnapshotFilePath('/project/test/unit/foo.test.ts');
+ * // Returns: '/project/test/unit/__snapshots__/test-unit-foo.test.ts.snap.cjs'
+ * ```
+ *
+ * @function
+ * @param testFilePath - Absolute path to the test file
+ * @returns Absolute path to the snapshot file
+ */
+const getSnapshotFilePath = (testFilePath) => {
+    const dir = (0, node_path_1.dirname)(testFilePath);
+    const snapshotDir = (0, node_path_1.join)(dir, '__snapshots__');
+    const filename = (0, node_path_1.relative)(process.cwd(), testFilePath).replace(/\//g, '-');
+    return (0, node_path_1.join)(snapshotDir, `${filename}.snap.cjs`);
+};
+/**
+ * Get test file path from stack trace.
+ *
+ * Searches the stack trace for lines containing test file paths. Looks for
+ * files matching patterns like `*.test.js`, `*.spec.ts`, etc.
+ *
+ * @function
+ * @returns Absolute path to test file, or 'unknown.test.js' if not found
+ */
+const getTestFilePathFromStack = () => {
+    const stack = new Error().stack || '';
+    const lines = stack.split('\n');
+    for (const line of lines) {
+        // Match file paths in stack traces
+        const match = line.match(/\((.+\.(?:test|spec)\.[jt]s):\d+:\d+\)/);
+        if (match && match[1]) {
+            return (0, node_path_1.resolve)(match[1]);
+        }
+    }
+    return (0, node_path_1.resolve)('unknown.test.js');
+};
+/**
+ * Load snapshots from a snapshot file.
+ *
+ * Reads and parses the CommonJS format snapshot file. If the file doesn't exist
+ * or can't be parsed, returns an empty store.
+ *
+ * **Expected format:**
+ *
+ * ```javascript
+ * module.exports = {
+ *   'test name': '{"value": 42}',
+ *   'another test': '"string"',
+ * };
+ * ```
+ *
+ * @example
+ *
+ * ```typescript
+ * const store = loadSnapshots('/path/to/__snapshots__/test.snap.cjs');
+ * console.log(store['my test']); // '{"foo": "bar"}'
+ * ```
+ *
+ * @function
+ * @param snapshotPath - Path to the snapshot file
+ * @returns Snapshot store (test name → serialized value)
+ */
+const loadSnapshots = (snapshotPath) => {
+    if (!(0, node_fs_1.existsSync)(snapshotPath)) {
+        return {};
+    }
+    try {
+        // Read as CommonJS module
+        const content = (0, node_fs_1.readFileSync)(snapshotPath, 'utf-8');
+        // Parse the module.exports = { ... } format
+        const match = content.match(/module\.exports\s*=\s*(\{[\s\S]*\});?\s*$/);
+        if (match) {
+            // Use Function constructor to safely eval the object literal
+            // This is safe because we're only parsing the object structure,
+            // not executing arbitrary code
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval, @typescript-eslint/no-unsafe-call
+            const store = new Function(`return ${match[1]}`)();
+            return store;
+        }
+    }
+    catch {
+        // If parsing fails, return empty store
+        // This allows for snapshot regeneration
+    }
+    return {};
+};
+/**
+ * Save snapshots to a snapshot file.
+ *
+ * Writes the snapshot store to disk in CommonJS format. Creates the
+ * `__snapshots__/` directory if it doesn't exist. Entries are sorted
+ * alphabetically by test name for consistency.
+ *
+ * **Output format:**
+ *
+ * ```javascript
+ * module.exports = {
+ *   'test 1': '{"value": 1}',
+ *   'test 2': '{"value": 2}',
+ * };
+ * ```
+ *
+ * @example
+ *
+ * ```typescript
+ * const store = {
+ *   'my test': '{"foo": "bar"}',
+ *   'another test': '"string"',
+ * };
+ * saveSnapshots('/path/to/__snapshots__/test.snap.cjs', store);
+ * ```
+ *
+ * @function
+ * @param snapshotPath - Path to the snapshot file
+ * @param store - Snapshot store to save
+ */
+const saveSnapshots = (snapshotPath, store) => {
+    const dir = (0, node_path_1.dirname)(snapshotPath);
+    // Ensure directory exists
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    // Generate CommonJS module format with sorted entries
+    const snapshotEntries = entries(store)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `  ${(0, json_stable_stringify_1.default)(key)}: ${(0, json_stable_stringify_1.default)(value)}`)
+        .join(',\n');
+    const content = `module.exports = {\n${snapshotEntries}\n};\n`;
+    (0, node_fs_1.writeFileSync)(snapshotPath, content, 'utf-8');
+};
+/**
+ * Snapshot counters for multiple snapshots per test.
+ *
+ * Tracks how many snapshots have been taken for each test path to generate
+ * unique snapshot names when a test has multiple snapshots.
+ */
+const snapshotCounters = new Map();
+/**
+ * Fallback adapter for frameworks without native snapshot support.
+ *
+ * This adapter provides custom snapshot storage and management for test
+ * frameworks that don't have built-in snapshot functionality.
+ *
+ * **Supported Contexts:**
+ *
+ * - **Mocha**: Pass `this` from test callback
+ * - **Explicit names**: Pass a string snapshot name
+ *
+ * **Storage:**
+ *
+ * - Snapshots stored in `__snapshots__/*.snap.cjs` files
+ * - CommonJS format for compatibility with both CJS and ESM projects
+ * - Sorted entries for consistent diffs
+ *
+ * **Update Mode:**
+ *
+ * - Controlled by `BUPKIS_UPDATE_SNAPSHOTS=1` environment variable
+ *
+ * **Features:**
+ *
+ * - Multiple snapshots per test (automatic counters)
+ * - Named snapshots via `hint` option
+ * - Circular reference detection
+ * - Non-JSON type handling
+ *
+ * @example
+ *
+ * ```typescript
+ * // Mocha usage
+ * describe('MyComponent', function() {
+ *   it('renders', function() {
+ *     const output = render(<MyComponent />);
+ *     expect(output, 'to match snapshot', this);
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ *
+ * ```typescript
+ * // Explicit name (any framework)
+ * test('renders component', () => {
+ *   const output = render(<MyComponent />);
+ *   expect(output, 'to match snapshot', 'component-default-state');
+ * });
+ * ```
+ *
+ * @example
+ *
+ * ```typescript
+ * // Multiple snapshots with hints
+ * test('multi-step process', () => {
+ *   expect(step1(), 'to match snapshot', 'step-1', { hint: 'initial' });
+ *   expect(step2(), 'to match snapshot', 'step-2', { hint: 'processing' });
+ *   expect(step3(), 'to match snapshot', 'step-3', { hint: 'complete' });
+ * });
+ * ```
+ *
+ * @example
+ *
+ * ```sh
+ * # Update snapshots
+ * BUPKIS_UPDATE_SNAPSHOTS=1 npm test
+ * ```
+ */
+class FallbackAdapter {
+    /**
+     * Adapter name for identification and debugging.
+     */
+    name = 'fallback';
+    /**
+     * Check if this adapter can handle the given context.
+     *
+     * The fallback adapter accepts both strings (explicit snapshot names) and
+     * objects (potential Mocha contexts). It's designed to be the last adapter in
+     * the selection chain and will accept most inputs.
+     *
+     * @param context - Test context or snapshot name
+     * @returns `true` for strings or objects
+     */
+    canHandle = (context) => 
+    // Fallback handles strings (explicit names) and objects (Mocha)
+    typeof context === 'string' || typeof context === 'object';
+    /**
+     * Extract snapshot context from Mocha context or string name.
+     *
+     * **For Mocha contexts:**
+     *
+     * - Extracts test name from `this.test.fullTitle()`
+     * - Gets file path from `this.test.file` or stack trace
+     *
+     * **For string contexts:**
+     *
+     * - Uses the string as the test name
+     * - Extracts file path from stack trace
+     *
+     * **Update mode:**
+     *
+     * - Checks `process.env.BUPKIS_UPDATE_SNAPSHOTS === '1'`
+     *
+     * @param context - Mocha context or string snapshot name
+     * @returns Normalized snapshot context
+     * @throws {TypeError} If context is neither a valid Mocha context nor a
+     *   string
+     */
+    getContext(context) {
+        // Try Mocha first
+        const mochaContext = extractMochaContext(context);
+        if (mochaContext) {
+            return mochaContext;
+        }
+        // String context (explicit snapshot name)
+        if (typeof context === 'string') {
+            return {
+                filePath: getTestFilePathFromStack(),
+                isUpdateMode: process.env.BUPKIS_UPDATE_SNAPSHOTS === '1',
+                testPath: context,
+            };
+        }
+        throw new TypeError('Fallback adapter requires either a string snapshot name or Mocha context. ' +
+            'Pass test name as string: expect(value, "to match snapshot", "my-test-name")');
+    }
+    /**
+     * Perform snapshot assertion using custom storage.
+     *
+     * **Behavior:**
+     *
+     * - **Update mode**: Creates or updates the snapshot
+     * - **Comparison mode**: Loads existing snapshot and compares
+     *
+     * **Process:**
+     *
+     * 1. Serialize the value using provided serializer or default
+     * 2. Generate unique snapshot name (with counter if needed)
+     * 3. Load existing snapshot store from disk
+     * 4. Either update snapshot or compare and throw on mismatch
+     *
+     * @example
+     *
+     * ```typescript
+     * const adapter = new FallbackAdapter();
+     *
+     * // With Mocha context
+     * adapter.assertSnapshot({ foo: 'bar' }, mochaThis);
+     *
+     * // With explicit name
+     * adapter.assertSnapshot({ foo: 'bar' }, 'my-snapshot');
+     *
+     * // With custom serializer
+     * adapter.assertSnapshot(data, 'test', {
+     *   serializer: (v) => JSON.stringify(v, null, 2),
+     * });
+     * ```
+     *
+     * @param value - Value to snapshot
+     * @param context - Mocha context or string name
+     * @param options - Optional serializer and hint
+     * @throws {TypeError} If context is invalid
+     * @throws {AssertionError} If snapshot doesn't match (in comparison mode)
+     */
+    validateSnapshot(value, context, options) {
+        const ctx = this.getContext(context);
+        const serializer = options?.serializer || serializer_js_1.defaultSerializer;
+        const snapshotName = getSnapshotName(ctx.testPath, options?.hint);
+        const snapshotPath = getSnapshotFilePath(ctx.filePath);
+        const store = loadSnapshots(snapshotPath);
+        const actual = serializer(value);
+        const expected = store[snapshotName];
+        if (ctx.isUpdateMode || expected === undefined) {
+            // Update/create snapshot
+            store[snapshotName] = actual;
+            saveSnapshots(snapshotPath, store);
+            return;
+        }
+        // Compare snapshots
+        if (actual !== expected) {
+            return {
+                actual,
+                expected,
+                message: `Snapshot mismatch for "${snapshotName}"\n\nExpected:\n${expected}\n\nActual:\n${actual}`,
+            };
+        }
+    }
+}
+exports.FallbackAdapter = FallbackAdapter;
+/**
+ * Get the next snapshot name for a test.
+ *
+ * For the first snapshot in a test, uses the test path as-is. For subsequent
+ * snapshots, appends a counter: `"test name 2"`, `"test name 3"`, etc.
+ *
+ * If a hint is provided, it's appended in brackets: `"test name [hint]"`.
+ *
+ * @example
+ *
+ * ```typescript
+ * getSnapshotName('MyComponent renders'); // 'MyComponent renders'
+ * getSnapshotName('MyComponent renders'); // 'MyComponent renders 2'
+ * getSnapshotName('MyComponent renders'); // 'MyComponent renders 3'
+ *
+ * getSnapshotName('test', 'initial state'); // 'test [initial state]'
+ * ```
+ *
+ * @function
+ * @param testPath - Full test path/name
+ * @param hint - Optional descriptive hint
+ * @returns Unique snapshot name
+ */
+const getSnapshotName = (testPath, hint) => {
+    if (hint) {
+        return `${testPath} [${hint}]`;
+    }
+    const counter = snapshotCounters.get(testPath) || 0;
+    snapshotCounters.set(testPath, counter + 1);
+    return counter === 0 ? testPath : `${testPath} ${counter + 1}`;
+};
+/**
+ * Singleton instance of the fallback adapter.
+ *
+ * This is the primary export and should be used for adapter registration.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { fallbackAdapter } from 'bupkis/snapshot';
+ * import { registerAdapter } from 'bupkis/snapshot';
+ *
+ * registerAdapter(fallbackAdapter);
+ * ```
+ */
+exports.fallbackAdapter = new FallbackAdapter();
+//# sourceMappingURL=fallback.js.map

package/dist/snapshot/adapters/fallback.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../../../src/snapshot/adapters/fallback.ts"],"names":[],"mappings":"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"}

package/dist/snapshot/adapters/fallback.d.cts

@@ -0,0 +1,185 @@
+/**
+ * Fallback adapter for frameworks without native snapshot support.
+ *
+ * This adapter provides custom snapshot storage for test frameworks that don't
+ * have built-in snapshot functionality (e.g., Mocha, Tap, custom test
+ * runners).
+ *
+ * **Storage Format:** Snapshots are stored as CommonJS modules in
+ * `__snapshots__/` directories:
+ *
+ * ```javascript
+ * // __snapshots__/my-test.test.js.snap.cjs
+ * module.exports = {
+ *   'test name': '{\n  "value": 42\n}',
+ *   'test name 2': '"another snapshot"',
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { AssertionFailure } from "../../types.cjs";
+import type { SnapshotAdapter, SnapshotContext, SnapshotOptions } from "../adapter.cjs";
+/**
+ * Fallback adapter for frameworks without native snapshot support.
+ *
+ * This adapter provides custom snapshot storage and management for test
+ * frameworks that don't have built-in snapshot functionality.
+ *
+ * **Supported Contexts:**
+ *
+ * - **Mocha**: Pass `this` from test callback
+ * - **Explicit names**: Pass a string snapshot name
+ *
+ * **Storage:**
+ *
+ * - Snapshots stored in `__snapshots__/*.snap.cjs` files
+ * - CommonJS format for compatibility with both CJS and ESM projects
+ * - Sorted entries for consistent diffs
+ *
+ * **Update Mode:**
+ *
+ * - Controlled by `BUPKIS_UPDATE_SNAPSHOTS=1` environment variable
+ *
+ * **Features:**
+ *
+ * - Multiple snapshots per test (automatic counters)
+ * - Named snapshots via `hint` option
+ * - Circular reference detection
+ * - Non-JSON type handling
+ *
+ * @example
+ *
+ * ```typescript
+ * // Mocha usage
+ * describe('MyComponent', function() {
+ *   it('renders', function() {
+ *     const output = render(<MyComponent />);
+ *     expect(output, 'to match snapshot', this);
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ *
+ * ```typescript
+ * // Explicit name (any framework)
+ * test('renders component', () => {
+ *   const output = render(<MyComponent />);
+ *   expect(output, 'to match snapshot', 'component-default-state');
+ * });
+ * ```
+ *
+ * @example
+ *
+ * ```typescript
+ * // Multiple snapshots with hints
+ * test('multi-step process', () => {
+ *   expect(step1(), 'to match snapshot', 'step-1', { hint: 'initial' });
+ *   expect(step2(), 'to match snapshot', 'step-2', { hint: 'processing' });
+ *   expect(step3(), 'to match snapshot', 'step-3', { hint: 'complete' });
+ * });
+ * ```
+ *
+ * @example
+ *
+ * ```sh
+ * # Update snapshots
+ * BUPKIS_UPDATE_SNAPSHOTS=1 npm test
+ * ```
+ */
+export declare class FallbackAdapter implements SnapshotAdapter {
+    /**
+     * Adapter name for identification and debugging.
+     */
+    readonly name = "fallback";
+    /**
+     * Check if this adapter can handle the given context.
+     *
+     * The fallback adapter accepts both strings (explicit snapshot names) and
+     * objects (potential Mocha contexts). It's designed to be the last adapter in
+     * the selection chain and will accept most inputs.
+     *
+     * @param context - Test context or snapshot name
+     * @returns `true` for strings or objects
+     */
+    canHandle: (context: unknown) => boolean;
+    /**
+     * Extract snapshot context from Mocha context or string name.
+     *
+     * **For Mocha contexts:**
+     *
+     * - Extracts test name from `this.test.fullTitle()`
+     * - Gets file path from `this.test.file` or stack trace
+     *
+     * **For string contexts:**
+     *
+     * - Uses the string as the test name
+     * - Extracts file path from stack trace
+     *
+     * **Update mode:**
+     *
+     * - Checks `process.env.BUPKIS_UPDATE_SNAPSHOTS === '1'`
+     *
+     * @param context - Mocha context or string snapshot name
+     * @returns Normalized snapshot context
+     * @throws {TypeError} If context is neither a valid Mocha context nor a
+     *   string
+     */
+    getContext(context: unknown): SnapshotContext;
+    /**
+     * Perform snapshot assertion using custom storage.
+     *
+     * **Behavior:**
+     *
+     * - **Update mode**: Creates or updates the snapshot
+     * - **Comparison mode**: Loads existing snapshot and compares
+     *
+     * **Process:**
+     *
+     * 1. Serialize the value using provided serializer or default
+     * 2. Generate unique snapshot name (with counter if needed)
+     * 3. Load existing snapshot store from disk
+     * 4. Either update snapshot or compare and throw on mismatch
+     *
+     * @example
+     *
+     * ```typescript
+     * const adapter = new FallbackAdapter();
+     *
+     * // With Mocha context
+     * adapter.assertSnapshot({ foo: 'bar' }, mochaThis);
+     *
+     * // With explicit name
+     * adapter.assertSnapshot({ foo: 'bar' }, 'my-snapshot');
+     *
+     * // With custom serializer
+     * adapter.assertSnapshot(data, 'test', {
+     *   serializer: (v) => JSON.stringify(v, null, 2),
+     * });
+     * ```
+     *
+     * @param value - Value to snapshot
+     * @param context - Mocha context or string name
+     * @param options - Optional serializer and hint
+     * @throws {TypeError} If context is invalid
+     * @throws {AssertionError} If snapshot doesn't match (in comparison mode)
+     */
+    validateSnapshot(value: unknown, context: unknown, options?: SnapshotOptions): AssertionFailure | void;
+}
+/**
+ * Singleton instance of the fallback adapter.
+ *
+ * This is the primary export and should be used for adapter registration.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { fallbackAdapter } from 'bupkis/snapshot';
+ * import { registerAdapter } from 'bupkis/snapshot';
+ *
+ * registerAdapter(fallbackAdapter);
+ * ```
+ */
+export declare const fallbackAdapter: FallbackAdapter;
+//# sourceMappingURL=fallback.d.ts.map

package/dist/snapshot/adapters/fallback.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../../../src/snapshot/adapters/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAuB;AACvD,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,eAAe,EAChB,uBAAsB;AAwPvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,qBAAa,eAAgB,YAAW,eAAe;IACrD;;OAEG;IACH,QAAQ,CAAC,IAAI,cAAc;IAE3B;;;;;;;;;OASG;IACH,SAAS,GAAI,SAAS,OAAO,KAAG,OAAO,CAEsB;IAE7D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe;IAsB7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,gBAAgB,CACd,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,eAAe,GACxB,gBAAgB,GAAG,IAAI;CA2B3B;AAoCD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,iBAAwB,CAAC"}