From fb7b132b7230dac3fca30d79fcc57c98ecffbc81 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Mon, 26 Aug 2019 11:04:04 -0400 Subject: [PATCH] jest-diff: Export as ECMAScript module (#8873) * jest-diff: Export Diff constructor as value instead of type * Rewrite as ECMAScript-TypeScript module * Delete or TypeScript in README * Add .default to example of CommonJS default export in README * Rename and add as BREAKING to CHANGELOG * Rewrite re-export as explicit import and export statements * Edit description in CHANGELOG.md --- CHANGELOG.md | 1 + packages/jest-diff/README.md | 84 ++++++++++++------- .../src/__tests__/diffStringsRaw.test.ts | 34 ++++++++ packages/jest-diff/src/index.ts | 30 ++----- packages/jest-matcher-utils/src/index.ts | 22 ++--- packages/jest-snapshot/src/print.ts | 4 +- 6 files changed, 110 insertions(+), 65 deletions(-) create mode 100644 packages/jest-diff/src/__tests__/diffStringsRaw.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index ce698c98f80e..4d622017f4ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ - `[babel-plugin-jest-hoist]` Show codeframe on static hoisting issues ([#8865](https://github.com/facebook/jest/pull/8865)) - `[jest-config]` [**BREAKING**] Set default display name color based on runner ([#8689](https://github.com/facebook/jest/pull/8689)) - `[jest-diff]` Add options for colors and symbols ([#8841](https://github.com/facebook/jest/pull/8841)) +- `[jest-diff]` [**BREAKING**] Export as ECMAScript module ([#8873](https://github.com/facebook/jest/pull/8873)) - `[jest-runner]` Warn if a worker had to be force exited ([#8206](https://github.com/facebook/jest/pull/8206)) - `[@jest/test-result]` Create method to create empty `TestResult` ([#8867](https://github.com/facebook/jest/pull/8867)) - `[jest-worker]` [**BREAKING**] Return a promise from `end()`, resolving with the information whether workers exited gracefully ([#8206](https://github.com/facebook/jest/pull/8206)) diff --git a/packages/jest-diff/README.md b/packages/jest-diff/README.md index d60e630be761..822e6c2d619b 100644 --- a/packages/jest-diff/README.md +++ b/packages/jest-diff/README.md @@ -26,8 +26,8 @@ Given values and optional options, `diffLinesUnified(a, b, options?)` does the f To use this function, write either of the following: -- `const diffLinesUnified = require('jest-diff');` in a CommonJS module -- `import diffLinesUnified from 'jest-diff';` in an ECMAScript module +- `const diffLinesUnified = require('jest-diff').default;` in CommonJS modules +- `import diffLinesUnified from 'jest-diff';` in ECMAScript modules ### Example of default export @@ -40,8 +40,7 @@ const difference = diffLinesUnified(a, b); The returned **string** consists of: -- annotation lines which describe the change symbols with labels -- blank line +- annotation lines: describe the two change symbols with labels, and a blank line - comparison lines: similar to “unified” view on GitHub, but `Expected` lines are green, `Received` lines are red, and common lines are dim (by default, see Options) ```diff @@ -77,8 +76,8 @@ Although the function is mainly for **multiline** strings, it compares any strin Write either of the following: -- `const {diffStringsUnified} = require('jest-diff');` in a CommonJS module -- `import {diffStringsUnified} from 'jest-diff';` in an ECMAScript module +- `const {diffStringsUnified} = require('jest-diff');` in CommonJS modules +- `import {diffStringsUnified} from 'jest-diff';` in ECMAScript modules ### Example of diffStringsUnified @@ -91,9 +90,8 @@ const difference = diffStringsUnified(a, b); The returned **string** consists of: -- annotation lines which describe the change symbols with labels -- blank line -- comparison lines: similar to “unified” view on GitHub, and **changed substrings** have **inverted** foreground and background colors +- annotation lines: describe the two change symbols with labels, and a blank line +- comparison lines: similar to “unified” view on GitHub, and **changed substrings** have **inverted** foreground and background colors (which the following example does not show) ```diff - Expected @@ -121,18 +119,21 @@ If the input strings can have **arbitrary length**, we recommend that the callin ## Usage of diffStringsRaw -Given strings, `diffStringsRaw(a, b, cleanup)` does the following: +Given strings and boolean, `diffStringsRaw(a, b, cleanup)` does the following: - **compare** the strings character-by-character using the `diff-sequences` package - optionally **clean up** small (often coincidental) common substrings, also known as chaff Write one of the following: -- `const {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, diffStringsRaw} = require('jest-diff');` in a CommonJS module -- `import {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, diffStringsRaw} from 'jest-diff';` in an ECMAScript module -- `import {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff, diffStringsRaw} from 'jest-diff';` in a TypeScript module +- `const {diffStringsRaw} = require('jest-diff');` in CommonJS modules +- `import {diffStringsRaw} from 'jest-diff';` in ECMAScript modules -The returned **array** describes substrings as instances of the `Diff` class (which calling code can access like array tuples). +Because `diffStringsRaw` returns the difference as **data** instead of a string, you can format it as your application requires (for example, enclosed in HTML markup for browser instead of escape sequences for console). + +The returned **array** describes substrings as instances of the `Diff` class, which calling code can access like array tuples: + +The value at index `0` is one of the following: | value | named export | description | | ----: | :------------ | :-------------------- | @@ -140,21 +141,23 @@ The returned **array** describes substrings as instances of the `Diff` class (wh | `-1` | `DIFF_DELETE` | in `a` but not in `b` | | `1` | `DIFF_INSERT` | in `b` but not in `a` | -Because `diffStringsRaw` returns the difference as **data** instead of a string, you are free to format it as your application requires (for example, enclosed in HTML markup for browser instead of escape sequences for console). +The value at index `1` is a substring of `a` or `b` or both. ### Example of diffStringsRaw with cleanup ```js const diffs = diffStringsRaw('change from', 'change to', true); -// diffs[0][0] === DIFF_EQUAL -// diffs[0][1] === 'change ' +/* +diffs[0][0] === 0 // DIFF_EQUAL +diffs[0][1] === 'change ' -// diffs[1][0] === DIFF_DELETE -// diffs[1][1] === 'from' +diffs[1][0] === -1 // DIFF_DELETE +diffs[1][1] === 'from' -// diffs[2][0] === DIFF_INSERT -// diffs[2][1] === 'to' +diffs[2][0] === 1 // DIFF_INSERT +diffs[2][1] === 'to' +*/ ``` ### Example of diffStringsRaw without cleanup @@ -162,21 +165,40 @@ const diffs = diffStringsRaw('change from', 'change to', true); ```js const diffs = diffStringsRaw('change from', 'change to', false); -// diffs[0][0] === DIFF_EQUAL -// diffs[0][1] === 'change ' +/* +diffs[0][0] === 0 // DIFF_EQUAL +diffs[0][1] === 'change ' -// diffs[1][0] === DIFF_DELETE -// diffs[1][1] === 'fr' +diffs[1][0] === -1 // DIFF_DELETE +diffs[1][1] === 'fr' -// diffs[2][0] === DIFF_INSERT -// diffs[2][1] === 't' +diffs[2][0] === 1 // DIFF_INSERT +diffs[2][1] === 't' // Here is a small coincidental common substring: -// diffs[3][0] === DIFF_EQUAL -// diffs[3][1] === 'o' +diffs[3][0] === 0 // DIFF_EQUAL +diffs[3][1] === 'o' + +diffs[4][0] === -1 // DIFF_DELETE +diffs[4][1] === 'm' +*/ +``` + +## Advanced import for diffStringsRaw -// diffs[4][0] === DIFF_DELETE -// diffs[4][1] === 'm' +Here are all the named imports for the `diffStringsRaw` function: + +- `const {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff, diffStringsRaw} = require('jest-diff');` in CommonJS modules +- `import {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff, diffStringsRaw} from 'jest-diff';` in ECMAScript modules + +To write a **formatting** function, you might need the named constants (and `Diff` in TypeScript annotations). + +If you write an application-specific **cleanup** algorithm, then you might need to call the `Diff` constructor: + +```js +const diffCommon = new Diff(DIFF_EQUAL, 'change '); +const diffDelete = new Diff(DIFF_DELETE, 'from'); +const diffInsert = new Diff(DIFF_INSERT, 'to'); ``` ## Options diff --git a/packages/jest-diff/src/__tests__/diffStringsRaw.test.ts b/packages/jest-diff/src/__tests__/diffStringsRaw.test.ts new file mode 100644 index 000000000000..330310b58f7d --- /dev/null +++ b/packages/jest-diff/src/__tests__/diffStringsRaw.test.ts @@ -0,0 +1,34 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +import {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff, diffStringsRaw} from '../'; + +describe('diffStringsRaw', () => { + test('one-line with cleanup', () => { + const expected: Array = [ + new Diff(DIFF_EQUAL, 'change '), + new Diff(DIFF_DELETE, 'from'), + new Diff(DIFF_INSERT, 'to'), + ]; + const received = diffStringsRaw('change from', 'change to', true); + + expect(received).toEqual(expected); + }); + + test('one-line without cleanup', () => { + const expected: Array = [ + new Diff(DIFF_EQUAL, 'change '), + new Diff(DIFF_DELETE, 'fr'), + new Diff(DIFF_INSERT, 't'), + new Diff(DIFF_EQUAL, 'o'), + new Diff(DIFF_DELETE, 'm'), + ]; + const received = diffStringsRaw('change from', 'change to', false); + + expect(received).toEqual(expected); + }); +}); diff --git a/packages/jest-diff/src/index.ts b/packages/jest-diff/src/index.ts index df6cd5a140a9..76cbb7c34dae 100644 --- a/packages/jest-diff/src/index.ts +++ b/packages/jest-diff/src/index.ts @@ -8,17 +8,17 @@ import prettyFormat = require('pretty-format'); import chalk from 'chalk'; import getType = require('jest-get-type'); -import { - DIFF_DELETE, - DIFF_EQUAL, - DIFF_INSERT, - Diff as DiffClass, -} from './cleanupSemantic'; +import {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff} from './cleanupSemantic'; import diffLines from './diffLines'; import {normalizeDiffOptions} from './normalizeDiffOptions'; import {diffStringsRaw, diffStringsUnified} from './printDiffs'; import {NO_DIFF_MESSAGE, SIMILAR_MESSAGE} from './constants'; -import {DiffOptionsNormalized, DiffOptions as JestDiffOptions} from './types'; +import {DiffOptionsNormalized, DiffOptions as ImportDiffOptions} from './types'; + +export type DiffOptions = ImportDiffOptions; + +export {diffStringsRaw, diffStringsUnified}; +export {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff}; const { AsymmetricMatcher, @@ -50,7 +50,7 @@ const FALLBACK_FORMAT_OPTIONS_0 = {...FALLBACK_FORMAT_OPTIONS, indent: 0}; // Generate a string that will highlight the difference between two values // with green and red. (similar to how github does code diffing) -function diff(a: any, b: any, options?: JestDiffOptions): string | null { +function diff(a: any, b: any, options?: DiffOptions): string | null { if (Object.is(a, b)) { return NO_DIFF_MESSAGE; } @@ -163,16 +163,4 @@ function compareObjects( return diffMessage; } -// eslint-disable-next-line no-redeclare -namespace diff { - export type Diff = DiffClass; - export type DiffOptions = JestDiffOptions; -} - -diff.diffStringsUnified = diffStringsUnified; -diff.diffStringsRaw = diffStringsRaw; -diff.DIFF_DELETE = DIFF_DELETE; -diff.DIFF_EQUAL = DIFF_EQUAL; -diff.DIFF_INSERT = DIFF_INSERT; - -export = diff; +export default diff; diff --git a/packages/jest-matcher-utils/src/index.ts b/packages/jest-matcher-utils/src/index.ts index aba7ff29812e..2d03613e4a6a 100644 --- a/packages/jest-matcher-utils/src/index.ts +++ b/packages/jest-matcher-utils/src/index.ts @@ -6,17 +6,17 @@ */ import chalk from 'chalk'; -import jestDiff = require('jest-diff'); -import getType = require('jest-get-type'); -import prettyFormat = require('pretty-format'); - -const { +import diffLinesUnified, { DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, + Diff, + DiffOptions as ImportDiffOptions, diffStringsRaw, diffStringsUnified, -} = jestDiff; +} from 'jest-diff'; +import getType = require('jest-get-type'); +import prettyFormat = require('pretty-format'); const { AsymmetricMatcher, @@ -49,7 +49,7 @@ export type MatcherHintOptions = { secondArgumentColor?: MatcherHintColor; }; -export type DiffOptions = jestDiff.DiffOptions; +export type DiffOptions = ImportDiffOptions; export const EXPECTED_COLOR = chalk.green; export const RECEIVED_COLOR = chalk.red; @@ -226,12 +226,12 @@ export const ensureExpectedIsNonNegativeInteger = ( // * include change substrings which have argument op // with inverse highlight only if there is a common substring const getCommonAndChangedSubstrings = ( - diffs: Array, + diffs: Array, op: number, hasCommonDiff: boolean, ): string => diffs.reduce( - (reduced: string, diff: jestDiff.Diff): string => + (reduced: string, diff: Diff): string => reduced + (diff[0] === DIFF_EQUAL ? diff[1] @@ -338,7 +338,7 @@ export const printDiffOrStringify = ( } if (isLineDiffable(expected, received)) { - const difference = jestDiff(expected, received, { + const difference = diffLinesUnified(expected, received, { aAnnotation: expectedLabel, bAnnotation: receivedLabel, expand, @@ -378,7 +378,7 @@ const shouldPrintDiff = (actual: unknown, expected: unknown) => { }; export const diff = (a: any, b: any, options?: DiffOptions): string | null => - shouldPrintDiff(a, b) ? jestDiff(a, b, options) : null; + shouldPrintDiff(a, b) ? diffLinesUnified(a, b, options) : null; export const pluralize = (word: string, count: number) => (NUMBERS[count] || count) + ' ' + word + (count === 1 ? '' : 's'); diff --git a/packages/jest-snapshot/src/print.ts b/packages/jest-snapshot/src/print.ts index 4f0516f91bf2..c59df18106f5 100644 --- a/packages/jest-snapshot/src/print.ts +++ b/packages/jest-snapshot/src/print.ts @@ -5,7 +5,7 @@ * LICENSE file in the root directory of this source tree. */ -import diff = require('jest-diff'); +import diff, {diffStringsUnified} from 'jest-diff'; import getType = require('jest-get-type'); import { EXPECTED_COLOR, @@ -86,7 +86,7 @@ export const printDiffOrStringified = ( receivedSerializedTrimmed.length <= MAX_DIFF_STRING_LENGTH && expectedSerializedTrimmed !== receivedSerializedTrimmed ) { - return diff.diffStringsUnified( + return diffStringsUnified( expectedSerializedTrimmed, receivedSerializedTrimmed, {