jest-diff: Add trailingSpaceFormatter option and replace cyan with commonColor (#8927)

* jest-diff: Add trailingSpaceFormatter option and replace cyan with commonColor

* Update CHANGELOG.md

Author: pedrottimark

CHANGELOG.md

@@ -12,6 +12,7 @@
 - `[jest-diff]` [**BREAKING**] Export as ECMAScript module ([#8873](https://github.com/facebook/jest/pull/8873))
 - `[jest-diff]` Add `includeChangeCounts` and rename `Indicator` options ([#8881](https://github.com/facebook/jest/pull/8881))
 - `[jest-diff]` Add `changeColor` and `patchColor` options ([#8911](https://github.com/facebook/jest/pull/8911))
+- `[jest-diff]` Add `trailingSpaceFormatter` option and replace cyan with `commonColor` ([#8927](https://github.com/facebook/jest/pull/8927))
 - `[jest-environment-jsdom]` Add `fakeTimersLolex` ([#8925](https://github.com/facebook/jest/pull/8925))
 - `[jest-environment-node]` Add `fakeTimersLolex` ([#8925](https://github.com/facebook/jest/pull/8925))
 - `[@jest/fake-timers]` Add Lolex as implementation of fake timers ([#8897](https://github.com/facebook/jest/pull/8897))

packages/expect/src/__tests__/__snapshots__/matchers.test.js.snap

@@ -325,7 +325,7 @@ trailing space" and "without trailing space" 1`] = `
 <red>+ Received</>
 
 <green>- with<inverse>out</> trailing space</>
-<red>+ with·</>
+<red>+ with<bgYellow> </></>
 <red>+ trailing space</>"
 `;
 
@@ -3603,8 +3603,8 @@ exports[`.toStrictEqual() displays substring diff for multiple lines 1`] = `
 <green>- Expected</>
 <red>+ Received</>
 
-<green>-     6<inverse>9</> |·</>
-<red>+     6<inverse>8</> |·</>
+<green>-     6<inverse>9</> |<bgYellow> </></>
+<red>+     6<inverse>8</> |<bgYellow> </></>
 <green>-     <inverse>70</> | test('assert.doesNotThrow', () => {</>
 <red>+     <inverse>69</> | test('assert.doesNotThrow', () => {</>
 <green>-   > 7<inverse>1</> |   assert.doesNotThrow(() => {</>

packages/jest-diff/README.md

@@ -18,24 +18,24 @@ To add this package as a dependency of a project, run either of the following co
 
 ## Usage of default export
 
-Given values and optional options, `diffLinesUnified(a, b, options?)` does the following:
+Given values and optional options, `diffDefault(a, b, options?)` does the following:
 
 - **serialize** the values as strings using the `pretty-format` package
 - **compare** the strings line-by-line using the `diff-sequences` package
 - **format** the changed or common lines using the `chalk` package
 
 To use this function, write either of the following:
 
-- `const diffLinesUnified = require('jest-diff').default;` in CommonJS modules
-- `import diffLinesUnified from 'jest-diff';` in ECMAScript modules
+- `const diffDefault = require('jest-diff').default;` in CommonJS modules
+- `import diffDefault from 'jest-diff';` in ECMAScript modules
 
 ### Example of default export
 
 ```js
-const a = ['delete', 'change from', 'common'];
-const b = ['change to', 'insert', 'common'];
+const a = ['delete', 'changed from', 'common'];
+const b = ['changed to', 'insert', 'common'];
 
-const difference = diffLinesUnified(a, b);
+const difference = diffDefault(a, b);
 ```
 
 The returned **string** consists of:
@@ -49,8 +49,8 @@ The returned **string** consists of:
 
   Array [
 -   "delete",
--   "change from",
-+   "change to",
+-   "changed from",
++   "changed to",
 +   "insert",
     "common",
   ]
@@ -82,8 +82,8 @@ Write either of the following:
 ### Example of diffStringsUnified
 
 ```js
-const a = 'change from\ncommon';
-const b = 'change to\ncommon';
+const a = 'changed from\ncommon';
+const b = 'changed to\ncommon';
 
 const difference = diffStringsUnified(a, b);
 ```
@@ -97,8 +97,8 @@ The returned **string** consists of:
 - Expected
 + Received
 
-- change from
-+ change to
+- changed from
++ changed to
   common
 ```
 
@@ -146,11 +146,11 @@ 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);
+const diffs = diffStringsRaw('changed from', 'changed to', true);
 
 /*
 diffs[0][0] === 0 // DIFF_EQUAL
-diffs[0][1] === 'change '
+diffs[0][1] === 'changed '
 
 diffs[1][0] === -1 // DIFF_DELETE
 diffs[1][1] === 'from'
@@ -163,11 +163,11 @@ diffs[2][1] === 'to'
 ### Example of diffStringsRaw without cleanup
 
 ```js
-const diffs = diffStringsRaw('change from', 'change to', false);
+const diffs = diffStringsRaw('changed from', 'changed to', false);
 
 /*
 diffs[0][0] === 0 // DIFF_EQUAL
-diffs[0][1] === 'change '
+diffs[0][1] === 'changed '
 
 diffs[1][0] === -1 // DIFF_DELETE
 diffs[1][1] === 'fr'
@@ -196,7 +196,7 @@ To write a **formatting** function, you might need the named constants (and `Dif
 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 diffCommon = new Diff(DIFF_EQUAL, 'changed ');
 const diffDelete = new Diff(DIFF_DELETE, 'from');
 const diffInsert = new Diff(DIFF_INSERT, 'to');
 ```
@@ -207,27 +207,30 @@ The default options are for the report when an assertion fails from the `expect`
 
 For other applications, you can provide an options object as a third argument:
 
-- `diffLinesUnified(a, b, options)`
+- `diffDefault(a, b, options)`
 - `diffStringsUnified(a, b, options)`
 
 ### Properties of options object
 
-| name                  | default         |
-| :-------------------- | :-------------- |
-| `aAnnotation`         | `'Expected'`    |
-| `aColor`              | `chalk.green`   |
-| `aIndicator`          | `'-'`           |
-| `bAnnotation`         | `'Received'`    |
-| `bColor`              | `chalk.red`     |
-| `bIndicator`          | `'+'`           |
-| `changeColor`         | `chalk.inverse` |
-| `commonColor`         | `chalk.dim`     |
-| `commonIndicator`     | `' '`           |
-| `contextLines`        | `5`             |
-| `expand`              | `true`          |
-| `includeChangeCounts` | `false`         |
-| `omitAnnotationLines` | `false`         |
-| `patchColor`          | `chalk.yellow`  |
+| name                     | default          |
+| :----------------------- | :--------------- |
+| `aAnnotation`            | `'Expected'`     |
+| `aColor`                 | `chalk.green`    |
+| `aIndicator`             | `'-'`            |
+| `bAnnotation`            | `'Received'`     |
+| `bColor`                 | `chalk.red`      |
+| `bIndicator`             | `'+'`            |
+| `changeColor`            | `chalk.inverse`  |
+| `commonColor`            | `chalk.dim`      |
+| `commonIndicator`        | `' '`            |
+| `contextLines`           | `5`              |
+| `expand`                 | `true`           |
+| `includeChangeCounts`    | `false`          |
+| `omitAnnotationLines`    | `false`          |
+| `patchColor`             | `chalk.yellow`   |
+| `trailingSpaceFormatter` | `chalk.bgYellow` |
+
+For more information about the options, see the following examples.
 
 ### Example of options for labels
 
@@ -240,6 +243,15 @@ const options = {
 };
 ```
 
+```diff
+- Original
++ Modified
+
+- changed from
++ changed to
+  common
+```
+
 The `jest-diff` package does not assume that the 2 labels have equal length.
 
 ### Example of options for colors of changed lines
@@ -257,29 +269,46 @@ const options = {
 
 ### Example of option for color of changed substrings
 
-Although the default inverse of foreground and background colors is hard to beat for changed substrings **within lines**, especially because it highlights spaces, if you want bold font weight on yellow background:
+Although the default inverse of foreground and background colors is hard to beat for changed substrings **within lines**, especially because it highlights spaces, if you want bold font weight on yellow background color:
 
 ```js
+import chalk from 'chalk';
+
 const options = {
   changeColor: chalk.bold.bgAnsi256(226), // #ffff00
 };
 ```
 
+### Example of option to format trailing spaces
+
+Because the default export does not display substring differences within lines, formatting can help you see when lines differ by the presence or absence of trailing spaces found by `/\s+$/` regular expression.
+
+The formatter is a function, which given a string, returns a string.
+
+If instead of yellowish background color, you want to replace trailing spaces with middle dot characters:
+
+```js
+const options = {
+  trailingSpaceFormatter: string => '·'.repeat(string.length),
+};
+```
+
 ### Example of options for no colors
 
-The value of a color option is a function, which given a string, returns a string.
+The value of a color or formatter option is a function, which given a string, returns a string.
 
 To store the difference in a file without escape codes for colors, provide an identity function:
 
 ```js
-const identity = string => string;
+const noColor = string => string;
 
 const options = {
-  aColor: identity,
-  bColor: identity,
-  changeColor: identity,
-  commonColor: identity,
-  patchColor: identity,
+  aColor: noColor,
+  bColor: noColor,
+  changeColor: noColor,
+  commonColor: noColor,
+  patchColor: noColor,
+  trailingSpaceFormatter: noColor,
 };
 ```
 
@@ -316,6 +345,8 @@ A patch mark like `@@ -12,7 +12,9 @@` accounts for omitted common lines.
 If you want patch marks to have the same dim color as common lines:
 
 ```js
+import chalk from 'chalk';
+
 const options = {
   expand: false,
   patchColor: chalk.dim,
@@ -327,22 +358,23 @@ const options = {
 To display the number of changed lines at the right of annotation lines:
 
 ```js
-const a = ['change from', 'common'];
-const b = ['change to', 'insert', 'common'];
+const a = ['changed from', 'common'];
+const b = ['changed to', 'insert', 'common'];
+
 const options = {
   includeChangeCounts: true,
 };
 
-const difference = diffLinesUnified(a, b, options);
+const difference = diffDefault(a, b, options);
 ```
 
 ```diff
 - Expected  1 -
 + Received  2 +
 
   Array [
--   "change from",
-+   "change to",
+-   "changed from",
++   "changed to",
 +   "insert",
     "common",
   ]
@@ -353,8 +385,9 @@ const difference = diffLinesUnified(a, b, options);
 To display only the comparison lines:
 
 ```js
-const a = 'change from\ncommon';
-const b = 'change to\ncommon';
+const a = 'changed from\ncommon';
+const b = 'changed to\ncommon';
+
 const options = {
   omitAnnotationLines: true,
 };
@@ -363,7 +396,7 @@ const difference = diffStringsUnified(a, b, options);
 ```
 
 ```diff
-- change from
-+ change to
+- changed from
++ changed to
   common
 ```