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

package/src/matchers/toSucceedAndSatisfy/index.ts

@@ -1,78 +0,0 @@
-import { Result, ResultValueType } from '@fgv/ts-utils';
-import { printExpectedResult, printReceivedResult } from '../../utils/matcherHelpers';
-import { matcherName, predicate } from './predicate';
-
-import { matcherHint } from 'jest-matcher-utils';
-
-declare global {
-  // eslint-disable-next-line @typescript-eslint/no-namespace
-  namespace jest {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars, no-unused-vars,  @typescript-eslint/naming-convention
-    interface Matchers<R, T> {
-      /**
-       * Use .toSucceedAndSatisfy to verify that a Result<T> is a success
-       * and that the supplied test function returns true (or void)
-       * for the resulting value
-       * @param test -
-       */
-      toSucceedAndSatisfy(test: (value: ResultValueType<T>) => boolean | void): R;
-    }
-  }
-}
-
-function passMessage<T>(received: Result<T>): () => string {
-  const expected = 'successful callback';
-  const got = [printReceivedResult(received)];
-  got.push('  Callback returned true');
-
-  return () =>
-    [
-      matcherHint(`.not.${matcherName}`, 'result', 'callback'),
-      printExpectedResult('success', false, expected),
-      ...got
-    ].join('\n');
-}
-
-function failMessage<T>(received: Result<T>, cbResult: Result<boolean | void>): () => string {
-  const expected = 'successful callback';
-  const got = [printReceivedResult(received)];
-
-  /* c8 ignore else */
-  if (cbResult.isFailure()) {
-    got.push(cbResult.message);
-  } else if (cbResult.value === false) {
-    got.push('  Callback returned false');
-  } else if (cbResult.value === undefined) {
-    got.push('  Callback was not invoked');
-  } else {
-    throw new Error('Internal error: toSucceedAndSatisfy.failMessage passed success with true');
-  }
-
-  return () =>
-    [
-      matcherHint(`${matcherName}`, 'result', 'callback'),
-      printExpectedResult('success', true, expected),
-      ...got
-    ].join('\n');
-}
-
-export default {
-  toSucceedAndSatisfy: function <T>(
-    this: jest.MatcherContext,
-    received: Result<T>,
-    test: (value: T) => boolean | void
-  ): jest.CustomMatcherResult {
-    // For the normal (not '.not') case, we do not want to capture exceptions
-    // so that the IDE can display exactly the line on which the failure case.
-    // For the .not case, we want to swallow exceptions or expect failures since
-    // we're just testing failure and not the reason.
-    const capture = this.isNot;
-    const cbResult = predicate(received, test, !!capture);
-    const pass = cbResult.isSuccess() && cbResult.value === true;
-    if (pass) {
-      return { pass: true, message: passMessage(received) };
-    }
-
-    return { pass: false, message: failMessage(received, cbResult) };
-  }
-};

package/src/matchers/toSucceedAndSatisfy/predicate.ts

@@ -1,22 +0,0 @@
-import { Result, captureResult, fail, succeed } from '../../ts-utils';
-
-export const matcherName: string = 'toSucceedAndSatisfy';
-
-// If the result is successful and callback does not throw, returns Success with the callback return value, or
-//    true if the callback returns undefined
-// If the result is successful but the callback throws, returns Failure with the thrown error
-// If the result is failure, returns Success with undefined
-export function predicate<T>(
-  received: Result<T>,
-  cb: (value: T) => boolean | void,
-  capture: boolean
-): Result<boolean | undefined> {
-  if (received.isSuccess()) {
-    const cbResult = capture ? captureResult(() => cb(received.value)) : succeed(cb(received.value));
-    if (cbResult.isSuccess()) {
-      return succeed(cbResult.value === true || cbResult.value === undefined);
-    }
-    return fail(`  Callback failed with:\n    ${cbResult.message}`);
-  }
-  return succeed(undefined);
-}

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

@@ -1,25 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`.toSucceedWith reports details when it fails due to a failure result: toFailTestAndMatchSnapshot 1`] = `
-"expect(received).toSucceedWith(expected)
-Expected:
-  Success with \\"oops\\"
-Received:
-  Failure with \\"oops\\""
-`;
-
-exports[`.toSucceedWith reports details when it fails due to a success result with .not: toFailTestAndMatchSnapshot 1`] = `
-"expect(received).not.toSucceedWith(expected)
-Expected:
-  Not success with \\"hello\\"
-Received:
-  Success with \\"hello\\""
-`;
-
-exports[`.toSucceedWith reports details when it fails due to success with a non-matching value: toFailTestAndMatchSnapshot 1`] = `
-"expect(received).toSucceedWith(expected)
-Expected:
-  Success with \\"goodbye\\"
-Received:
-  Success with \\"hello\\""
-`;

package/src/matchers/toSucceedWith/index.ts

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

package/src/matchers/toSucceedWith/predicate.ts

@@ -1,14 +0,0 @@
-import { equals } from '@jest/expect-utils';
-import { Result } from '../../ts-utils';
-
-export const matcherName: string = 'toSucceedWith';
-
-export function predicate<T>(received: Result<T>, expected: unknown): boolean {
-  if (received.isSuccess()) {
-    if (typeof received.value === 'string' && expected instanceof RegExp) {
-      return expected.test(received.value);
-    }
-    return equals(received.value, expected);
-  }
-  return false;
-}

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

@@ -1,41 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`.toSucceedWithDetail reports details when it fails due to a failure result: toFailTestAndMatchSnapshot 1`] = `
-"expect(received).toSucceedWithDetail(expected)
-Expected:
-  Success with \\"oops\\"
-  Detail: \\"\\"detail\\"\\"
-Received:
-  Failure with \\"oops\\"
-  Detail: \\"\\"detail\\"\\""
-`;
-
-exports[`.toSucceedWithDetail reports details when it fails due to a success result with .not: toFailTestAndMatchSnapshot 1`] = `
-"expect(received).not.toSucceedWithDetail(expected)
-Expected:
-  Not success with \\"hello\\"
-  Detail: \\"\\"detail\\"\\"
-Received:
-  Success with \\"\\"hello\\"\\"
-  Detail: \\"\\"detail\\"\\""
-`;
-
-exports[`.toSucceedWithDetail reports details when it fails due to success with a non-matching detail: toFailTestAndMatchSnapshot 1`] = `
-"expect(received).toSucceedWithDetail(expected)
-Expected:
-  Success with \\"hello\\"
-  Detail: \\"\\"other detail\\"\\"
-Received:
-  Success with \\"\\"hello\\"\\"
-  Detail: \\"\\"detail\\"\\""
-`;
-
-exports[`.toSucceedWithDetail reports details when it fails due to success with a non-matching value: toFailTestAndMatchSnapshot 1`] = `
-"expect(received).toSucceedWithDetail(expected)
-Expected:
-  Success with \\"goodbye\\"
-  Detail: \\"\\"detail\\"\\"
-Received:
-  Success with \\"\\"hello\\"\\"
-  Detail: \\"\\"detail\\"\\""
-`;

package/src/matchers/toSucceedWithDetail/index.ts

@@ -1,62 +0,0 @@
-import { DetailedResult, ResultDetailType, ResultValueType } from '@fgv/ts-utils';
-import { printExpectedDetailedResult, printReceivedDetailedResult } from '../../utils/matcherHelpers';
-import { matcherName, predicate } from './predicate';
-
-import { matcherHint } from 'jest-matcher-utils';
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars, no-unused-vars
-declare global {
-  // eslint-disable-next-line @typescript-eslint/no-namespace
-  namespace jest {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars, no-unused-vars,  @typescript-eslint/naming-convention
-    interface Matchers<R, T> {
-      /**
-       * Use .toSucceedWithDetail to verify that a DetailedResult\<T, TD\> is
-       * a success and that the result value and detail matches the supplied
-       * values
-       */
-      toSucceedWithDetail(expected: ResultValueType<T> | RegExp, detail: ResultDetailType<T> | undefined): R;
-    }
-  }
-}
-
-function passMessage<T extends DetailedResult<unknown, unknown>>(
-  received: T,
-  expected: ResultValueType<T> | RegExp,
-  expectedDetail: ResultDetailType<T> | undefined
-): () => string {
-  return () =>
-    [
-      matcherHint(`.not.${matcherName}`),
-      printExpectedDetailedResult('success', false, expected, expectedDetail),
-      printReceivedDetailedResult(received)
-    ].join('\n');
-}
-
-function failMessage<T extends DetailedResult<unknown, unknown>>(
-  received: T,
-  expected: ResultValueType<T> | RegExp,
-  expectedDetail: ResultDetailType<T> | undefined
-): () => string {
-  return () =>
-    [
-      matcherHint(`${matcherName}`),
-      printExpectedDetailedResult('success', true, expected, expectedDetail),
-      printReceivedDetailedResult(received)
-    ].join('\n');
-}
-
-export default {
-  toSucceedWithDetail: function <T extends DetailedResult<unknown, unknown>>(
-    received: T,
-    expected: ResultValueType<T> | RegExp,
-    detail: ResultDetailType<T> | undefined
-  ): jest.CustomMatcherResult {
-    const pass = predicate(received, expected, detail);
-    if (pass) {
-      return { pass: true, message: passMessage(received, expected, detail) };
-    }
-
-    return { pass: false, message: failMessage(received, expected, detail) };
-  }
-};

package/src/matchers/toSucceedWithDetail/predicate.ts

@@ -1,23 +0,0 @@
-import { equals } from '@jest/expect-utils';
-import { DetailedResult } from '../../ts-utils';
-
-export const matcherName: string = 'toSucceedWithDetail';
-
-export function predicate<T, TD>(
-  received: DetailedResult<T, TD>,
-  expected: unknown,
-  detail: TD | undefined
-): boolean {
-  if (received.isSuccess()) {
-    let pass = false;
-    if (typeof received.value === 'string' && expected instanceof RegExp) {
-      pass = expected.test(received.value);
-    } else {
-      pass = equals(received.value, expected);
-    }
-
-    pass = pass && equals(received.detail, detail);
-    return pass;
-  }
-  return false;
-}

package/src/resolvers/cli.ts

@@ -1,21 +0,0 @@
-import * as Resolver from '../utils/snapshotResolver';
-
-const CLI_SNAPSHOT_FOLDER: string = '__cli__';
-
-function resolveSnapshotPath(testPath: string, ext: string): string {
-  return Resolver.resolveSnapshotPath(testPath, ext, CLI_SNAPSHOT_FOLDER);
-}
-
-function resolveTestPath(snapshotPath: string, ext: string): string {
-  return Resolver.resolveTestPath(snapshotPath, ext);
-}
-
-const testPathForConsistencyCheck: string = Resolver.testPathForConsistencyCheck;
-
-module.exports = {
-  resolveSnapshotPath,
-  resolveTestPath,
-  testPathForConsistencyCheck
-};
-
-export default module.exports;

package/src/resolvers/ide.ts

@@ -1,21 +0,0 @@
-import * as Resolver from '../utils/snapshotResolver';
-
-const CLI_SNAPSHOT_FOLDER: string = '__ide__';
-
-function resolveSnapshotPath(testPath: string, ext: string): string {
-  return Resolver.resolveSnapshotPath(testPath, ext, CLI_SNAPSHOT_FOLDER);
-}
-
-function resolveTestPath(snapshotPath: string, ext: string): string {
-  return Resolver.resolveTestPath(snapshotPath, ext);
-}
-
-const testPathForConsistencyCheck: string = Resolver.testPathForConsistencyCheck;
-
-module.exports = {
-  resolveSnapshotPath,
-  resolveTestPath,
-  testPathForConsistencyCheck
-};
-
-export default module.exports;

package/src/ts-utils.ts

@@ -1 +0,0 @@
-export * from '@fgv/ts-utils';

package/src/types/index.ts

@@ -1,107 +0,0 @@
-/// <reference types="jest"/>
-
-// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-explicit-any
-export type Function = (...args: any[]) => any;
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars,no-unused-vars
-import { ResultDetailType, ResultValueType } from '@fgv/ts-utils';
-
-/* eslint-disable @typescript-eslint/no-unused-vars,no-unused-vars */
-declare global {
-  // eslint-disable-next-line @typescript-eslint/no-namespace
-  namespace jest {
-    // eslint-disable-next-line @typescript-eslint/naming-convention
-    interface Matchers<R, T> {
-      /**
-       * Use .toSucceed to verify that a Result\<T\> is a success
-       */
-      toSucceed(): R;
-
-      /**
-       * Use .toSucceedWith to verify that a Result\<T\> is a success
-       * and that the result value matches the supplied value
-       * @param expected -
-       */
-      toSucceedWith(expected: ResultValueType<T> | RegExp): R;
-
-      /**
-       * Use .toSucceedWithDetail to verify that a DetailedResult\<T, TD\> is
-       * a success and that the result value and detail matches the supplied
-       * values
-       * @param expected -
-       * @param detail -
-       */
-      toSucceedWithDetail(expected: ResultValueType<T>, detail: ResultDetailType<T> | undefined): R;
-
-      /**
-       * Use .toSucceedAndSatisfy to verify that a Result\<T\> is a success
-       * and that the supplied test function returns true (or void)
-       * for the resulting value
-       * @param test -
-       */
-      toSucceedAndSatisfy(test: (value: ResultValueType<T>) => boolean | void): R;
-
-      /**
-       * Use .toSucceedAndMatchInlineSnapshot to verify that a Result\<T\> is a success
-       * and that the result value matches an inline snapshot
-       */
-      toSucceedAndMatchInlineSnapshot(snapshot: string | undefined): R;
-
-      /**
-       * Use .toSucceedAndMatchSnapshot to verify that a Result\<T\> is a success
-       * and that the result value matches a stored snapshot
-       */
-      toSucceedAndMatchSnapshot(): R;
-
-      /**
-       * Use .toFail to verify that a Result\<T\> is a failure
-       */
-      toFail(): R;
-
-      /**
-       * Use .toFailWith to verify that a Result\<T\> is a failure
-       * that matches a supplied string, RegExp or undefined value
-       * @param message -
-       */
-      toFailWith(expected: string | RegExp | undefined): R;
-
-      /**
-       * Use .toFailWithDetail to verify that a DetailedResult\<T\> is
-       * a failure that matches both a supplied expected failure value
-       * (string, RegExp or undefined) and a supplied failure detail.
-       * @param message -
-       * @param detail -
-       */
-      toFailWithDetail<TDetail>(message: string | RegExp, detail: TDetail): R;
-      toFailWithDetail(message: string | RegExp | undefined, detail: ResultDetailType<T>): R;
-
-      /**
-       * Use .toFailTest to test a custom matcher by
-       * verifying that a test case fails.
-       */
-      toFailTest(): R;
-
-      /**
-       * 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(): R;
-
-      /**
-       * Use .toFailTestWith to test a custom matcher by
-       * verifying that a test case fails as expected and
-       * reports an error matching a supplied value.
-       * @param expected -
-       */
-      toFailTestWith(expected: string | string[] | RegExp): R;
-
-      /**
-       * Use .toSucceedWith to verify that a Result\<T\> is a success
-       * and that the result value matches the supplied value
-       * @param expected -
-       */
-      toHaveBeenCalledWithArgumentsMatching(expected: unknown): R;
-    }
-  }
-}

package/src/utils/colorHelpers.ts

@@ -1,82 +0,0 @@
-/**
- * Utility functions for handling ANSI color codes in test output.
- *
- * @packageDocumentation
- */
-
-/**
- * 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: RegExp = /\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
- */
-export function stripAnsiColors(text: string): string {
-  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
- */
-export function createColorStripWrapper<T extends (...args: unknown[]) => string>(fn: T): T {
-  return ((...args: Parameters<T>) => {
-    const result = fn(...args);
-    return stripAnsiColors(result);
-  }) as T;
-}

package/src/utils/matcherHelpers.ts

@@ -1,64 +0,0 @@
-import { printExpected, printReceived } from 'jest-matcher-utils';
-import { DetailedResult, Result } from '../ts-utils';
-import { createColorStripWrapper } from './colorHelpers';
-
-// Create color-stripped versions of Jest matcher utilities
-const printExpectedClean: typeof printExpected = createColorStripWrapper(printExpected);
-const printReceivedClean: typeof printReceived = createColorStripWrapper(printReceived);
-
-function printExpectedValue<T>(outcome: string, expected?: T): string {
-  return expected !== undefined ? `  ${outcome} with ${printExpectedClean(expected)}` : `  ${outcome}`;
-}
-
-export function printExpectedResult<T>(expect: 'success' | 'failure', isNot: boolean, expected?: T): string {
-  return [
-    'Expected:',
-    isNot
-      ? expect === 'success'
-        ? printExpectedValue('Success', expected)
-        : printExpectedValue('Failure', expected)
-      : expect === 'success'
-      ? printExpectedValue('Not success', expected)
-      : printExpectedValue('Not failure', expected)
-  ].join('\n');
-}
-
-export function printExpectedDetailedResult<T, TD>(
-  expect: 'success' | 'failure',
-  isNot: boolean,
-  expectedMessage?: T,
-  expectedDetail?: TD
-): string {
-  /* c8 ignore next */
-  return [
-    'Expected:',
-    isNot
-      ? expect === 'success'
-        ? printExpectedValue('Success', expectedMessage)
-        : printExpectedValue('Failure', expectedMessage)
-      : expect === 'success'
-      ? printExpectedValue('Not success', expectedMessage)
-      : printExpectedValue('Not failure', expectedMessage),
-    `  Detail: "${printExpectedClean(expectedDetail)}"`
-  ].join('\n');
-}
-
-export function printReceivedResult<T>(received: Result<T>): string {
-  return [
-    'Received:',
-    received.isSuccess()
-      ? `  Success with ${printReceivedClean(received.value)}`
-      : `  Failure with "${received.message}"`
-  ].join('\n');
-}
-
-export function printReceivedDetailedResult<T, TD>(received: DetailedResult<T, TD>): string {
-  return [
-    'Received:',
-    received.isSuccess()
-      ? `  Success with "${printReceivedClean(received.value)}"\n  Detail: "${printReceivedClean(
-          received.detail
-        )}"`
-      : `  Failure with "${received.message}"\n  Detail: "${printReceivedClean(received.detail)}"`
-  ].join('\n');
-}

package/src/utils/snapshotResolver.ts

@@ -1,28 +0,0 @@
-import path from 'path';
-
-export function resolveSnapshotPath(
-  testPath: string,
-  snapshotExtension: string,
-  snapshotFolderName: string
-): string {
-  const snapshotPath = path.join(
-    path.join(path.dirname(testPath), '__snapshots__', snapshotFolderName),
-    path.basename(testPath) + snapshotExtension
-  );
-  return snapshotPath;
-}
-
-export function resolveTestPath(snapshotFilePath: string, snapshotExtension: string): string {
-  const testPath = path.join(
-    path.dirname(path.dirname(path.dirname(snapshotFilePath))),
-    path.basename(snapshotFilePath, snapshotExtension)
-  );
-  return testPath;
-}
-
-export const testPathForConsistencyCheck: string = path.posix.join(
-  'consistency_check',
-  '__tests__',
-  'subdir',
-  'example.test.js'
-);