@fgv/ts-utils-jest 5.0.0-11 → 5.0.0-14

package/src/matchers/toSucceedAndSatisfy/index.ts

@@ -0,0 +1,78 @@
+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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,25 @@
+// 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

@@ -0,0 +1,58 @@
+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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,41 @@
+// 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

@@ -0,0 +1,62 @@
+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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,21 @@
+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

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

package/src/types/index.ts

@@ -0,0 +1,107 @@
+/// <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/matcherHelpers.ts

@@ -0,0 +1,57 @@
+import { printExpected, printReceived } from 'jest-matcher-utils';
+import { DetailedResult, Result } from '../ts-utils';
+
+function printExpectedValue<T>(outcome: string, expected?: T): string {
+  return expected !== undefined ? `  ${outcome} with ${printExpected(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: "${printExpected(expectedDetail)}"`
+  ].join('\n');
+}
+
+export function printReceivedResult<T>(received: Result<T>): string {
+  return [
+    'Received:',
+    received.isSuccess()
+      ? `  Success with ${printReceived(received.value)}`
+      : `  Failure with "${received.message}"`
+  ].join('\n');
+}
+
+export function printReceivedDetailedResult<T, TD>(received: DetailedResult<T, TD>): string {
+  return [
+    'Received:',
+    received.isSuccess()
+      ? `  Success with "${printReceived(received.value)}"\n  Detail: "${printReceived(received.detail)}"`
+      : `  Failure with "${received.message}"\n  Detail: "${printReceived(received.detail)}"`
+  ].join('\n');
+}

package/src/utils/snapshotResolver.ts

@@ -0,0 +1,28 @@
+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'
+);

package/test/data/testData.json

@@ -0,0 +1,4 @@
+{
+  "filename": "testData.json",
+  "fromBackingFile": true
+}

package/CHANGELOG.md

@@ -1,105 +0,0 @@
-# Change Log - @fgv/ts-utils-jest
-
-This log was last generated on Thu, 17 Jul 2025 00:13:24 GMT and should not be manually modified.
-
-## 5.0.0
-Thu, 17 Jul 2025 00:13:24 GMT
-
-### Updates
-
-- minor fixes
-- bump version
-
-## 4.6.0
-Wed, 02 Jul 2025 05:48:16 GMT
-
-_Version update only_
-
-## 4.5.1
-Wed, 02 Jul 2025 05:47:11 GMT
-
-### Updates
-
-- update rushstack
-
-## 4.5.0
-Tue, 01 Jul 2025 03:26:11 GMT
-
-_Version update only_
-
-## 4.4.0
-Sat, 01 Feb 2025 17:13:10 GMT
-
-_Version update only_
-
-## 4.3.0
-Thu, 30 Jan 2025 00:35:17 GMT
-
-_Version update only_
-
-## 4.2.2
-Thu, 23 Jan 2025 06:19:32 GMT
-
-_Version update only_
-
-## 4.2.1
-Tue, 21 Jan 2025 04:19:21 GMT
-
-_Version update only_
-
-## 4.2.0
-Mon, 20 Jan 2025 09:46:53 GMT
-
-_Version update only_
-
-## 4.1.0
-Thu, 09 Jan 2025 05:33:39 GMT
-
-### Updates
-
-- update dependencies
-
-## 4.0.2
-Tue, 14 May 2024 14:45:53 GMT
-
-_Version update only_
-
-## 4.0.1
-Tue, 14 May 2024 05:02:20 GMT
-
-### Updates
-
-- publish
-
-## 4.0.0
-Tue, 14 May 2024 03:09:27 GMT
-
-### Updates
-
-- update dependencies
-
-## 3.0.0
-Mon, 22 Jan 2024 07:00:18 GMT
-
-### Updates
-
-- gitignore tweaks
-- fix types for ts-utils-jest
-- fix peers
-- bump versions
-- cleanup
-- Update dependencies
-- bump dependencies, fix tests
-- version upgrades
-- update dependencies
-- update peer dependencies
-- bump version
-
-## 2.0.0
-Mon, 10 Apr 2023 03:33:11 GMT
-
-### Breaking changes
-
-- initial checking
-- refactor
-