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

package/src/matchers/toSucceedAndMatchInlineSnapshot/index.ts

@@ -0,0 +1,44 @@
+/* eslint-disable @typescript-eslint/no-unused-vars,no-unused-vars */
+import { Result } from '@fgv/ts-utils';
+import { matcherHint } from 'jest-matcher-utils';
+import { Context, toMatchInlineSnapshot } from 'jest-snapshot';
+import { printReceivedResult } 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 .toSucceedAndMatchInlineSnapshot to verify that a Result<T> is a success
+       * and that the result value matches an inline snapshot
+       */
+      toSucceedAndMatchInlineSnapshot<T>(snapshot: string | undefined): R;
+    }
+  }
+}
+
+const matcherName: string = 'toSucceedAndMatchInlineSnapshot';
+
+export default {
+  toSucceedAndMatchInlineSnapshot: function <T>(
+    this: jest.MatcherContext,
+    received: Result<T>,
+    snapshot: string | undefined
+  ): jest.CustomMatcherResult {
+    const context = this as unknown as Context;
+    if (received.isFailure()) {
+      return {
+        pass: false,
+        message: (): string => {
+          return [
+            matcherHint(`${matcherName}`, 'callback'),
+            'Expected:\n  Callback to succeed with a result that matches the snapshot',
+            printReceivedResult(received)
+          ].join('\n');
+        }
+      };
+    }
+    return toMatchInlineSnapshot.call(context, received.value, {}, snapshot) as jest.CustomMatcherResult;
+  }
+};

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

@@ -0,0 +1,27 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.toSucceedAndMatchSnapshot logs details correctly for a failed result: toFailTestAndMatchSnapshot 1`] = `
+"expect(callback).toSucceedAndMatchSnapshot(expected)
+Expected:
+  Callback to succeed with a result that matches the snapshot
+Received:
+  Failure with \\"oopsy\\""
+`;
+
+exports[`.toSucceedAndMatchSnapshot logs details correctly for a failed result: toFailTestAndMatchSnapshot 2`] = `
+"expect(received).not.toMatchSnapshot(hint)
+
+Matcher error: Snapshot matchers cannot be used with not"
+`;
+
+exports[`.toSucceedAndMatchSnapshot passes for a success result that matches the snapshot: toSucceedAndMatchSnapshot 1`] = `
+Object {
+  "nestedObject": Object {
+    "anArray": Array [
+      "element 1",
+      "element 2",
+    ],
+  },
+  "someField": "this is a value",
+}
+`;

package/src/matchers/toSucceedAndMatchSnapshot/index.ts

@@ -0,0 +1,47 @@
+/* eslint-disable @typescript-eslint/no-unused-vars,no-unused-vars */
+import { Result } from '@fgv/ts-utils';
+import { matcherHint } from 'jest-matcher-utils';
+import { Context, toMatchSnapshot } from 'jest-snapshot';
+import { printReceivedResult } 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 .toSucceedAndMatchSnapshot to verify that a Result<T> is a success
+       * and that the result value matches a stored snapshot
+       */
+      toSucceedAndMatchSnapshot<T>(): R;
+    }
+  }
+}
+
+const matcherName: string = 'toSucceedAndMatchSnapshot';
+
+export default {
+  toSucceedAndMatchSnapshot: function <T>(
+    this: jest.MatcherContext,
+    received: Result<T>
+  ): jest.CustomMatcherResult {
+    const context = this as unknown as Context;
+    if (received.isFailure()) {
+      return {
+        pass: false,
+        message: (): string => {
+          return [
+            matcherHint(`${matcherName}`, 'callback'),
+            'Expected:\n  Callback to succeed with a result that matches the snapshot',
+            printReceivedResult(received)
+          ].join('\n');
+        }
+      };
+    }
+    return toMatchSnapshot.call(
+      context,
+      received.value,
+      'toSucceedAndMatchSnapshot'
+    ) as jest.CustomMatcherResult;
+  }
+};

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

@@ -0,0 +1,37 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.toSucceedAndSatisfy reports details when callback fails an expectation: toFailTestAndMatchSnapshot 1`] = `
+"expect(received).toBe(expected) // Object.is equality
+
+Expected: \\"goodbye\\"
+Received: \\"hello\\""
+`;
+
+exports[`.toSucceedAndSatisfy reports details when callback returns false: toFailTestAndMatchSnapshot 1`] = `
+"expect(result).toSucceedAndSatisfy(callback)
+Expected:
+  Success with \\"successful callback\\"
+Received:
+  Success with \\"hello\\"
+  Callback returned false"
+`;
+
+exports[`.toSucceedAndSatisfy reports details when callback throws an exception: toFailTestAndMatchSnapshot 1`] = `"UH OH AN ERROR"`;
+
+exports[`.toSucceedAndSatisfy reports details when received is a failure result: toFailTestAndMatchSnapshot 1`] = `
+"expect(result).toSucceedAndSatisfy(callback)
+Expected:
+  Success with \\"successful callback\\"
+Received:
+  Failure with \\"oops\\"
+  Callback was not invoked"
+`;
+
+exports[`.toSucceedAndSatisfy reports details with success and .not: toFailTestAndMatchSnapshot 1`] = `
+"expect(result).not.toSucceedAndSatisfy(callback)
+Expected:
+  Not success with \\"successful callback\\"
+Received:
+  Success with \\"hello\\"
+  Callback returned true"
+`;

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;
+    }
+  }
+}