@fgv/ts-utils-jest 5.0.0-2 → 5.0.0-21

package/lib/utils/colorHelpers.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Utility functions for handling ANSI color codes in test output.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripAnsiColors = stripAnsiColors;
+exports.createColorStripWrapper = createColorStripWrapper;
+/**
+ * Regular expression to match ANSI color/style escape sequences.
+ *
+ * This matches:
+ * - ESC character (ASCII 27) followed by `[`
+ * - `[0-9;]*` - Zero or more digits and semicolons (parameters)
+ * - `[a-zA-Z]` - Single letter command (m for SGR, K for erase, etc.)
+ *
+ * Examples of what this matches:
+ * - `\u001b[31m` - Red foreground
+ * - `\u001b[39m` - Default foreground
+ * - `\u001b[2m` - Dim/faint
+ * - `\u001b[22m` - Normal intensity
+ *
+ * Using a pre-compiled regex literal to satisfy ESLint security requirements.
+ * We use the unicode escape sequence \\u001b instead of \\x1b to avoid control-regex warnings.
+ */
+// eslint-disable-next-line @rushstack/security/no-unsafe-regexp, no-control-regex
+const ANSI_COLOR_REGEX = /\u001b\[[0-9;]*[a-zA-Z]/g;
+/**
+ * Strips ANSI color/style escape sequences from a string.
+ *
+ * This function removes all ANSI escape sequences commonly used for
+ * terminal colors and text styling, making the output suitable for
+ * color-agnostic snapshot testing.
+ *
+ * @param text - The text that may contain ANSI escape sequences
+ * @returns The text with all ANSI escape sequences removed
+ *
+ * @example
+ * ```typescript
+ * const coloredText = '\u001b[31mError:\u001b[39m Something failed';
+ * const plainText = stripAnsiColors(coloredText);
+ * console.log(plainText); // "Error: Something failed"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Common usage in Jest matchers
+ * const formattedOutput = matcherUtils.printReceived(value);
+ * const cleanOutput = stripAnsiColors(formattedOutput);
+ * expect(cleanOutput).toMatchSnapshot();
+ * ```
+ *
+ * @public
+ */
+function stripAnsiColors(text) {
+    return text.replace(ANSI_COLOR_REGEX, '');
+}
+/**
+ * Creates a wrapper function that strips ANSI colors from any string-returning function.
+ *
+ * This is useful for wrapping Jest matcher utility functions to make them
+ * color-agnostic for snapshot testing.
+ *
+ * @param fn - A function that returns a string (potentially with ANSI colors)
+ * @returns A wrapped function that returns the same string with colors stripped
+ *
+ * @example
+ * ```typescript
+ * import { printReceived } from 'jest-matcher-utils';
+ *
+ * const printReceivedClean = createColorStripWrapper(printReceived);
+ * const output = printReceivedClean(someValue); // No colors
+ * ```
+ *
+ * @public
+ */
+function createColorStripWrapper(fn) {
+    return ((...args) => {
+        const result = fn(...args);
+        return stripAnsiColors(result);
+    });
+}
+//# sourceMappingURL=colorHelpers.js.map

package/lib/utils/matcherHelpers.js

@@ -5,8 +5,12 @@ exports.printExpectedDetailedResult = printExpectedDetailedResult;
 exports.printReceivedResult = printReceivedResult;
 exports.printReceivedDetailedResult = printReceivedDetailedResult;
 const jest_matcher_utils_1 = require("jest-matcher-utils");
+const colorHelpers_1 = require("./colorHelpers");
+// Create color-stripped versions of Jest matcher utilities
+const printExpectedClean = (0, colorHelpers_1.createColorStripWrapper)(jest_matcher_utils_1.printExpected);
+const printReceivedClean = (0, colorHelpers_1.createColorStripWrapper)(jest_matcher_utils_1.printReceived);
 function printExpectedValue(outcome, expected) {
-    return expected !== undefined ? `  ${outcome} with ${(0, jest_matcher_utils_1.printExpected)(expected)}` : `  ${outcome}`;
+    return expected !== undefined ? `  ${outcome} with ${printExpectedClean(expected)}` : `  ${outcome}`;
 }
 function printExpectedResult(expect, isNot, expected) {
     return [
@@ -31,14 +35,14 @@ function printExpectedDetailedResult(expect, isNot, expectedMessage, expectedDet
             : expect === 'success'
                 ? printExpectedValue('Not success', expectedMessage)
                 : printExpectedValue('Not failure', expectedMessage),
-        `  Detail: "${(0, jest_matcher_utils_1.printExpected)(expectedDetail)}"`
+        `  Detail: "${printExpectedClean(expectedDetail)}"`
     ].join('\n');
 }
 function printReceivedResult(received) {
     return [
         'Received:',
         received.isSuccess()
-            ? `  Success with ${(0, jest_matcher_utils_1.printReceived)(received.value)}`
+            ? `  Success with ${printReceivedClean(received.value)}`
             : `  Failure with "${received.message}"`
     ].join('\n');
 }
@@ -46,8 +50,8 @@ function printReceivedDetailedResult(received) {
     return [
         'Received:',
         received.isSuccess()
-            ? `  Success with "${(0, jest_matcher_utils_1.printReceived)(received.value)}"\n  Detail: "${(0, jest_matcher_utils_1.printReceived)(received.detail)}"`
-            : `  Failure with "${received.message}"\n  Detail: "${(0, jest_matcher_utils_1.printReceived)(received.detail)}"`
+            ? `  Success with "${printReceivedClean(received.value)}"\n  Detail: "${printReceivedClean(received.detail)}"`
+            : `  Failure with "${received.message}"\n  Detail: "${printReceivedClean(received.detail)}"`
     ].join('\n');
 }
 //# sourceMappingURL=matcherHelpers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-utils-jest",
-  "version": "5.0.0-2",
+  "version": "5.0.0-21",
   "description": "Custom matchers for ts-utils result class",
   "main": "lib/index.js",
   "keywords": [
@@ -32,20 +32,20 @@
     "jest": "^29.7.0",
     "prettier": "^3.6.2",
     "rimraf": "^5.0.7",
-    "ts-jest": "^29.4.0",
+    "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.7.3",
-    "@rushstack/heft": "~0.74.0",
+    "typescript": "^5.8.3",
+    "@rushstack/heft": "~0.74.2",
     "@rushstack/eslint-config": "~4.4.0",
-    "@rushstack/heft-jest-plugin": "~0.16.9",
-    "@rushstack/heft-node-rig": "~2.9.0",
+    "@rushstack/heft-jest-plugin": "~0.16.11",
+    "@rushstack/heft-node-rig": "~2.9.3",
     "@types/heft-jest": "1.0.6",
     "eslint-plugin-n": "^16.6.2",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-2"
+    "@fgv/ts-utils": "5.0.0-21"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-2"
+    "@fgv/ts-utils": "5.0.0-21"
   },
   "scripts": {
     "build": "heft build --clean",

package/src/__snapshots__/index.test.ts.snap

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`verify matchers accessibility toFailTestAndMatchSnapshot exists and works: toFailTestAndMatchSnapshot 1`] = `
+"expect(received).toBe(expected) // Object.is equality
+
+Expected: false
+Received: true"
+`;
+
+exports[`verify matchers accessibility toSucceedAndMatchSnapshot exists and works: toSucceedAndMatchSnapshot 1`] = `
+Object {
+  "child": Object {
+    "values": Array [
+      Object {
+        "number": 1,
+      },
+      Object {
+        "number": 2,
+      },
+    ],
+  },
+  "field": "field",
+}
+`;

package/src/helpers/fsHelpers.ts

@@ -0,0 +1,184 @@
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import fs from 'fs';
+import * as path from 'path';
+
+/**
+ * @public
+ */
+export interface IMockFileConfig {
+  path: string;
+  backingFile?: string;
+  payload?: string;
+  writable?: boolean;
+}
+
+/**
+ * @public
+ */
+export class ReadWriteSpies {
+  public readonly read: jest.SpyInstance;
+  public readonly write: jest.SpyInstance;
+
+  public constructor(read: jest.SpyInstance, write: jest.SpyInstance) {
+    this.read = read;
+    this.write = write;
+  }
+
+  public clear(): void {
+    this.read.mockClear();
+    this.write.mockClear();
+  }
+
+  public restore(): void {
+    this.read.mockRestore();
+    this.write.mockRestore();
+  }
+}
+
+/**
+ * @public
+ */
+export interface IMockFileSystemOptions {
+  mockWriteOnly?: boolean;
+  allowUnknownMockWrite?: boolean;
+}
+
+/**
+ * @public
+ */
+// eslint-disable-next-line @rushstack/no-new-null
+type ReadFunc = (
+  path: string | number | Buffer | URL,
+  // eslint-disable-next-line @rushstack/no-new-null
+  options?: { encoding?: null; flag?: string } | null
+) => Buffer;
+
+/**
+ * @public
+ */
+export class MockFileSystem {
+  protected readonly _options?: IMockFileSystemOptions;
+  protected readonly _config: Map<string, IMockFileConfig>;
+  protected readonly _data: Map<string, string>;
+  protected readonly _realReadFileSync: ReadFunc;
+  protected readonly _extraWrites: string[] = [];
+
+  public constructor(configs: Iterable<IMockFileConfig>, options?: IMockFileSystemOptions) {
+    this._config = new Map<string, IMockFileConfig>();
+    this._data = new Map<string, string>();
+    this._options = options;
+    this._realReadFileSync = fs.readFileSync;
+
+    for (const config of configs) {
+      const fullPath = path.resolve(config.path);
+      this._config.set(fullPath, config);
+      if (config.backingFile) {
+        this.readMockFileSync(fullPath);
+      } else if (config.payload) {
+        this._data.set(fullPath, config.payload);
+      }
+    }
+  }
+
+  public readMockFileSync(wanted: string): string {
+    const fullPathWanted = path.resolve(wanted);
+    if (!this._data.has(fullPathWanted)) {
+      const config = this._config.get(fullPathWanted);
+      if (config?.backingFile === undefined) {
+        if (this._options?.mockWriteOnly !== true) {
+          throw new Error(`Mock file not found: ${wanted}`);
+        }
+        const body = this._realReadFileSync(fullPathWanted).toString();
+        this._data.set(fullPathWanted, body);
+      } else {
+        const fullBackingPath = path.resolve(config.backingFile);
+        const body = this._realReadFileSync(fullBackingPath).toString();
+        this._data.set(fullPathWanted, body);
+      }
+    }
+
+    const payload = this._data.get(fullPathWanted);
+    // not actually reproducible right now
+    /* c8 ignore next 3 */
+    if (payload === undefined) {
+      throw new Error(`Mock file ${wanted} payload is undefined.`);
+    }
+    return payload;
+  }
+
+  public writeMockFileSync(wanted: string, body: string): void {
+    const fullPathWanted = path.resolve(wanted);
+    const config = this._config.get(fullPathWanted);
+    if (config === undefined) {
+      if (this._options?.allowUnknownMockWrite !== true) {
+        throw new Error(`Mock path not found: ${wanted}`);
+      }
+      this._extraWrites.push(fullPathWanted);
+    } else if (config.writable !== true) {
+      throw new Error(`Mock permission denied: ${wanted}`);
+    }
+    this._data.set(fullPathWanted, body);
+  }
+
+  public getExtraFilesWritten(): string[] {
+    return Array.from(this._extraWrites);
+  }
+  public tryGetPayload(want: string): string | undefined {
+    return this._data.get(path.resolve(want));
+  }
+
+  public reset(): void {
+    const writable = Array.from(this._config.values()).filter((c) => c.writable === true);
+    for (const config of writable) {
+      this._data.delete(path.resolve(config.path));
+      if (config.backingFile) {
+        this.readMockFileSync(path.resolve(config.path));
+      } else if (config.payload) {
+        this._data.set(path.resolve(config.path), config.payload);
+      }
+    }
+
+    for (const path of this._extraWrites) {
+      this._data.delete(path);
+    }
+    this._extraWrites.splice(0, this._extraWrites.length);
+  }
+
+  public startSpies(): ReadWriteSpies {
+    return new ReadWriteSpies(
+      jest.spyOn(fs, 'readFileSync').mockImplementation((wanted: unknown) => {
+        if (typeof wanted !== 'string') {
+          throw new Error('readFileSync mock supports only string parameters');
+        }
+        return this.readMockFileSync(wanted);
+      }),
+      jest.spyOn(fs, 'writeFileSync').mockImplementation((wanted: unknown, payload: unknown) => {
+        if (typeof wanted !== 'string' || typeof payload !== 'string') {
+          throw new Error('writeFileSync mock supports only string parameters');
+        }
+        return this.writeMockFileSync(wanted, payload);
+      })
+    );
+  }
+}

package/src/helpers/index.ts

@@ -0,0 +1 @@
+export * from './fsHelpers';

package/src/index.ts

@@ -0,0 +1,27 @@
+import matchers from './matchers';
+import './types';
+
+import * as MockFs from './helpers/fsHelpers';
+export { MockFs };
+
+// eslint-disable-next-line no-undef
+type JestGlobal = typeof global & { expect: jest.Expect };
+
+// eslint-disable-next-line no-undef
+function isJestGlobal(g: typeof global): g is JestGlobal {
+  return g.hasOwnProperty('expect');
+}
+
+/* c8 ignore else */
+if (isJestGlobal(global)) {
+  global.expect.extend(matchers);
+} else {
+  /* eslint-disable no-console */
+  console.error(
+    [
+      "Unable to find Jest's global expect",
+      'Please check that you have added ts-utils-jest correctly to your jest configuration.'
+    ].join('\n')
+  );
+  /* eslint-enable no-console */
+}

package/src/matchers/index.ts

@@ -0,0 +1,29 @@
+import ToFail from './toFail';
+import ToFailTest from './toFailTest';
+import ToFailTestAndMatchSnapshot from './toFailTestAndMatchSnapshot';
+import ToFailTestWith from './toFailTestWith';
+import ToFailWith from './toFailWith';
+import ToFailWithDetail from './toFailWithDetail';
+import ToHaveBeenCalledWithArgumentsMatching from './toHaveBeenCalledWithArgumentsMatching';
+import ToSucceed from './toSucceed';
+import ToSucceedAndMatchInlineSnapshot from './toSucceedAndMatchInlineSnapshot';
+import ToSucceedAndMatchSnapshot from './toSucceedAndMatchSnapshot';
+import ToSucceedAndSatisfy from './toSucceedAndSatisfy';
+import ToSucceedWith from './toSucceedWith';
+import toSucceedWithDetail from './toSucceedWithDetail';
+
+export default {
+  ...ToFail,
+  ...ToFailTest,
+  ...ToFailTestAndMatchSnapshot,
+  ...ToFailTestWith,
+  ...ToFailWith,
+  ...ToFailWithDetail,
+  ...ToHaveBeenCalledWithArgumentsMatching,
+  ...ToSucceed,
+  ...ToSucceedAndMatchInlineSnapshot,
+  ...ToSucceedAndMatchSnapshot,
+  ...ToSucceedAndSatisfy,
+  ...ToSucceedWith,
+  ...toSucceedWithDetail
+};

package/src/matchers/toFail/__snapshots__/index.test.ts.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.toFail reports details for a failed test with .not: toFailTestAndMatchSnapshot 1`] = `
+"expect(received).not.toFail(expected)
+Expected:
+  Not failure
+Received:
+  Failure with \\"oops\\""
+`;
+
+exports[`.toFail reports details for a failed test: toFailTestAndMatchSnapshot 1`] = `
+"expect(received).toFail(expected)
+Expected:
+  Failure
+Received:
+  Success with \\"hello\\""
+`;

package/src/matchers/toFail/index.ts

@@ -0,0 +1,45 @@
+import { printExpectedResult, printReceivedResult } from '../../utils/matcherHelpers';
+import { matcherName, predicate } from './predicate';
+
+import { Result } from '@fgv/ts-utils';
+import { matcherHint } from 'jest-matcher-utils';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace jest {
+    // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars,  @typescript-eslint/naming-convention
+    interface Matchers<R, T> {
+      /**
+       * Use .toFail to verify that a Result<T> is a failure
+       */
+      toFail(): R;
+    }
+  }
+}
+
+function passMessage<T extends Result<unknown>>(received: T): () => string {
+  return () =>
+    [
+      matcherHint(`.not.${matcherName}`),
+      printExpectedResult('failure', false),
+      printReceivedResult(received)
+    ].join('\n');
+}
+
+function failMessage<T extends Result<unknown>>(received: T): () => string {
+  return () =>
+    [matcherHint(`${matcherName}`), printExpectedResult('failure', true), printReceivedResult(received)].join(
+      '\n'
+    );
+}
+
+export default {
+  toFail: function <T extends Result<unknown>>(received: T): jest.CustomMatcherResult {
+    const pass = predicate(received);
+    if (pass) {
+      return { pass: true, message: passMessage(received) };
+    }
+
+    return { pass: false, message: failMessage(received) };
+  }
+};

package/src/matchers/toFail/predicate.ts

@@ -0,0 +1,7 @@
+import { Result } from '../../ts-utils';
+
+export const matcherName: string = 'toFail';
+
+export function predicate<T>(received: Result<T>): boolean {
+  return received.isFailure();
+}

package/src/matchers/toFailTest/__snapshots__/index.test.ts.snap

@@ -0,0 +1,15 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.toFailTest logs details correctly for a failed .not result: toFailTestAndMatchSnapshot 1`] = `
+"expect(callback).not.toFailTest(expected)
+Expected:
+  Not failure
+  Received: Test failed"
+`;
+
+exports[`.toFailTest logs details correctly for a failed result: toFailTestAndMatchSnapshot 1`] = `
+"expect(callback).toFailTest(expected)
+Expected:
+  Failure
+  Received: Test passed"
+`;

package/src/matchers/toFailTest/index.ts

@@ -0,0 +1,48 @@
+/* eslint-disable @typescript-eslint/no-unused-vars,no-unused-vars */
+import { matcherName, predicate } from './predicate';
+
+import { matcherHint } from 'jest-matcher-utils';
+import { printExpectedResult } from '../../utils/matcherHelpers';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace jest {
+    // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars,  @typescript-eslint/naming-convention
+    interface Matchers<R, T> {
+      /**
+       * Use .toFailTest to test a custom matcher by
+       * verifying that a test case fails.
+       */
+      toFailTest<T>(): R;
+    }
+  }
+}
+
+function passMessage<T>(): () => string {
+  return () =>
+    [
+      matcherHint(`.not.${matcherName}`, 'callback'),
+      printExpectedResult('failure', false),
+      '  Received: Test failed'
+    ].join('\n');
+}
+
+function failMessage<T>(): () => string {
+  return () =>
+    [
+      matcherHint(`${matcherName}`, 'callback'),
+      printExpectedResult('failure', true),
+      '  Received: Test passed'
+    ].join('\n');
+}
+
+export default {
+  toFailTest: function <T>(cb: () => void): jest.CustomMatcherResult {
+    const pass = predicate(cb);
+    if (pass) {
+      return { pass: true, message: passMessage() };
+    }
+
+    return { pass: false, message: failMessage() };
+  }
+};

package/src/matchers/toFailTest/predicate.ts

@@ -0,0 +1,8 @@
+/* eslint-disable @typescript-eslint/no-unused-vars,no-unused-vars */
+import { captureResult } from '../../ts-utils';
+export const matcherName: string = 'toFailTest';
+
+export function predicate<T>(cb: () => void): boolean {
+  const cbResult = captureResult(() => cb());
+  return cbResult.isFailure();
+}

package/src/matchers/toFailTestAndMatchSnapshot/__snapshots__/index.test.ts.snap

@@ -0,0 +1,14 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.toFailTestAndMatchSnapshot logs details correctly for a failed result: toFailTestAndMatchSnapshot 1`] = `
+"expect(callback).toFailTestAndMatchSnapshot(expected)
+  Expected: Callback to fail with an error that matches snapshot
+  Received: Callback succeeded"
+`;
+
+exports[`.toFailTestAndMatchSnapshot passes for a test that fails with a result matching the snapshot: toFailTestAndMatchSnapshot 1`] = `
+"expect(received).toBe(expected) // Object.is equality
+
+Expected: false
+Received: true"
+`;

package/src/matchers/toFailTestAndMatchSnapshot/index.ts

@@ -0,0 +1,48 @@
+/* eslint-disable @typescript-eslint/no-unused-vars,no-unused-vars */
+import { Context, toMatchSnapshot } from 'jest-snapshot';
+import { matcherName, predicate } from './predicate';
+
+import { matcherHint } from 'jest-matcher-utils';
+import { stripAnsiColors } from '../../utils/colorHelpers';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace jest {
+    // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars,  @typescript-eslint/naming-convention
+    interface Matchers<R, T> {
+      /**
+       * Use .toFailTestWith to test a custom matcher by
+       * verifying that a test case fails as expected and
+       * reports an error matching a stored snapshot.
+       */
+      toFailTestAndMatchSnapshot<T>(): R;
+    }
+  }
+}
+
+export default {
+  toFailTestAndMatchSnapshot: function <T>(
+    this: jest.MatcherContext,
+    cb: () => void
+  ): jest.CustomMatcherResult {
+    const context = this as unknown as Context;
+    const cbResult = predicate(cb);
+    if (cbResult.isFailure()) {
+      return {
+        pass: false,
+        message: (): string => {
+          return [
+            matcherHint(`${matcherName}`, 'callback'),
+            '  Expected: Callback to fail with an error that matches snapshot',
+            '  Received: Callback succeeded'
+          ].join('\n');
+        }
+      };
+    }
+    return toMatchSnapshot.call(
+      context,
+      stripAnsiColors(cbResult.value),
+      'toFailTestAndMatchSnapshot'
+    ) as jest.CustomMatcherResult;
+  }
+};

package/src/matchers/toFailTestAndMatchSnapshot/predicate.ts

@@ -0,0 +1,12 @@
+/* eslint-disable @typescript-eslint/no-unused-vars,no-unused-vars */
+import { Result, captureResult, fail, succeed } from '../../ts-utils';
+
+export const matcherName: string = 'toFailTestAndMatchSnapshot';
+
+export function predicate<T>(cb: () => void): Result<string> {
+  const cbResult = captureResult(() => cb());
+  if (cbResult.isFailure()) {
+    return succeed(cbResult.message);
+  }
+  return fail('Callback did not fail');
+}