jest-diff: Rename some new options and change their default values (#…

…9077)

* jest-diff: Rename some new options and change their default values

* Edit noColor in README.md

* Copy edit prose in README.md

* Swap args consistent with destructuring in printDiffs

* Update CHANGELOG.md

* Fix prettier lint error in README.md

* Modify yellowish test for common but not change

* Replace example of hex with rgb in README.md

* Replace arg with string in identify function in README

CHANGELOG.md

@@ -34,6 +34,7 @@
 - `[jest-console]` Add missing `console.group` calls to `NullConsole` ([#9024](https://github.com/facebook/jest/pull/9024))
 - `[jest-core]` Don't include unref'd timers in --detectOpenHandles results ([#8941](https://github.com/facebook/jest/pull/8941))
 - `[jest-diff]` Do not inverse format if line consists of one change ([#8903](https://github.com/facebook/jest/pull/8903))
+- `[jest-diff]` Rename some new options and change their default values ([#9077](https://github.com/facebook/jest/pull/9077))
 - `[jest-fake-timers]` `getTimerCount` will not include cancelled immediates ([#8764](https://github.com/facebook/jest/pull/8764))
 - `[jest-leak-detector]` [**BREAKING**] Use `weak-napi` instead of `weak` package ([#8686](https://github.com/facebook/jest/pull/8686))
 - `[jest-mock]` Fix for mockReturnValue overriding mockImplementationOnce ([#8398](https://github.com/facebook/jest/pull/8398))

packages/jest-diff/README.md

@@ -361,24 +361,25 @@ For other applications, you can provide an options object as a third argument:
 
 ### 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`           |
-| `firstOrLastEmptyLineReplacement` | `'↵'`            |
-| `includeChangeCounts`             | `false`          |
-| `omitAnnotationLines`             | `false`          |
-| `patchColor`                      | `chalk.yellow`   |
-| `trailingSpaceFormatter`          | `chalk.bgYellow` |
+| name                              | default            |
+| :-------------------------------- | :----------------- |
+| `aAnnotation`                     | `'Expected'`       |
+| `aColor`                          | `chalk.green`      |
+| `aIndicator`                      | `'-'`              |
+| `bAnnotation`                     | `'Received'`       |
+| `bColor`                          | `chalk.red`        |
+| `bIndicator`                      | `'+'`              |
+| `changeColor`                     | `chalk.inverse`    |
+| `changeLineTrailingSpaceColor`    | `string => string` |
+| `commonColor`                     | `chalk.dim`        |
+| `commonIndicator`                 | `' '`              |
+| `commonLineTrailingSpaceColor`    | `string => string` |
+| `contextLines`                    | `5`                |
+| `emptyFirstOrLastLinePlaceholder` | `''`               |
+| `expand`                          | `true`             |
+| `includeChangeCounts`             | `false`            |
+| `omitAnnotationLines`             | `false`            |
+| `patchColor`                      | `chalk.yellow`     |
 
 For more information about the options, see the following examples.
 
@@ -425,27 +426,45 @@ Although the default inverse of foreground and background colors is hard to beat
 import chalk from 'chalk';
 
 const options = {
-  changeColor: chalk.bold.bgAnsi256(226), // #ffff00
+  changeColor: chalk.bold.bgYellowBright,
 };
 ```
 
 ### 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 change lines have a background color, then you can see trailing spaces.
+- If common lines have default dim color, then you cannot see trailing spaces. You might want yellowish background color to see them.
 
-If instead of yellowish background color, you want to replace trailing spaces with middle dot characters:
+```js
+const options = {
+  aColor: chalk.rgb(128, 0, 128).bgRgb(255, 215, 255), // magenta
+  bColor: chalk.rgb(0, 95, 0).bgRgb(215, 255, 215), // green
+  commonLineTrailingSpaceColor: chalk.bgYellow,
+};
+```
+
+The value of a Color option is a function, which given a string, returns a string.
+
+If you want to replace trailing spaces with middle dot characters:
 
 ```js
+const replaceSpacesWithMiddleDot = string => '·'.repeat(string.length);
+
 const options = {
-  trailingSpaceFormatter: string => '·'.repeat(string.length),
+  changeLineTrailingSpaceColor: replaceSpacesWithMiddleDot,
+  commonLineTrailingSpaceColor: replaceSpacesWithMiddleDot,
 };
 ```
 
-### Example of options for no colors
+If you need the TypeScript type of a Color option:
 
-The value of a color or formatter option is a function, which given a string, returns a string.
+```ts
+import {DiffOptionsColor} from 'jest-diff';
+```
+
+### Example of options for no colors
 
 To store the difference in a file without escape codes for colors, provide an identity function:
 
@@ -458,7 +477,6 @@ const options = {
   changeColor: noColor,
   commonColor: noColor,
   patchColor: noColor,
-  trailingSpaceFormatter: noColor,
 };
 ```
 
@@ -551,19 +569,19 @@ const difference = diffStringsUnified(a, b, options);
 + changed to
 ```
 
-### Example of option not to replace first or last empty lines
+### Example of option for empty first or last lines
 
 If the **first** or **last** comparison line is **empty**, because the content is empty and the indicator is a space, you might not notice it.
 
-Also, because Jest trims the report when a matcher fails, it deletes an empty last line.
+The replacement option is a string whose default value is `''` empty string.
 
-The replacement is a string whose default value is `'↵'` U+21B5 downwards arrow with corner leftwards.
+Because Jest trims the report when a matcher fails, it deletes an empty last line.
 
-To store the difference in a file without a replacement, because it could be ambiguous with the content of the arguments, provide an empty string:
+Therefore, Jest uses as placeholder the downwards arrow with corner leftwards:
 
 ```js
 const options = {
-  firstOrLastEmptyLineReplacement: '',
+  emptyFirstOrLastLinePlaceholder: '↵', // U+21B5
 };
 ```
 

packages/jest-diff/src/__tests__/__snapshots__/diff.test.ts.snap

@@ -363,15 +363,15 @@ exports[`options omitAnnotationLines true diffStringsUnified and includeChangeCo
 
 exports[`options omitAnnotationLines true diffStringsUnified empty strings 1`] = ``;
 
-exports[`options trailingSpaceFormatter diffDefault default yellowish 1`] = `
+exports[`options trailingSpaceFormatter diffDefault default no color 1`] = `
 <g>- Expected</>
 <r>+ Received</>
 
-<g>- delete 1 trailing space:<Y> </></>
+<g>- delete 1 trailing space: </>
 <r>+ delete 1 trailing space:</>
-<d>  common 2 trailing spaces:<Y>  </></>
+<d>  common 2 trailing spaces:  </>
 <g>- insert 1 trailing space:</>
-<r>+ insert 1 trailing space:<Y> </></>
+<r>+ insert 1 trailing space: </>
 `;
 
 exports[`options trailingSpaceFormatter diffDefault middle dot 1`] = `
@@ -384,3 +384,14 @@ exports[`options trailingSpaceFormatter diffDefault middle dot 1`] = `
 <g>- insert 1 trailing space:</>
 <r>+ insert 1 trailing space:·</>
 `;
+
+exports[`options trailingSpaceFormatter diffDefault yellowish common 1`] = `
+<g>- Expected</>
+<r>+ Received</>
+
+<g>- delete 1 trailing space: </>
+<r>+ delete 1 trailing space:</>
+<d>  common 2 trailing spaces:<Y>  </></>
+<g>- insert 1 trailing space:</>
+<r>+ insert 1 trailing space: </>
+`;

packages/jest-diff/src/__tests__/diff.test.ts

@@ -10,6 +10,7 @@ import stripAnsi from 'strip-ansi';
 import {alignedAnsiStyleSerializer} from '@jest/test-utils';
 
 import diff from '../';
+import {noColor} from '../normalizeDiffOptions';
 import {diffStringsUnified} from '../printDiffs';
 import {DiffOptions} from '../types';
 
@@ -23,7 +24,6 @@ const NO_DIFF_MESSAGE = 'Compared values have no visual difference.';
 const stripped = (a: unknown, b: unknown) => stripAnsi(diff(a, b) || '');
 
 // Use in toBe assertions for comparison lines.
-const noColor = (string: string) => string;
 const optionsBe: DiffOptions = {
   aColor: noColor,
   bColor: noColor,
@@ -905,13 +905,23 @@ describe('options', () => {
       'insert 1 trailing space: ',
     ].join('\n');
 
-    test('diffDefault default yellowish', () => {
+    test('diffDefault default no color', () => {
       expect(diff(aTrailingSpaces, bTrailingSpaces)).toMatchSnapshot();
     });
 
     test('diffDefault middle dot', () => {
+      const replaceSpacesWithMiddleDot = string => '·'.repeat(string.length);
       const options = {
-        trailingSpaceFormatter: string => '·'.repeat(string.length),
+        changeLineTrailingSpaceColor: replaceSpacesWithMiddleDot,
+        commonLineTrailingSpaceColor: replaceSpacesWithMiddleDot,
+      };
+
+      expect(diff(aTrailingSpaces, bTrailingSpaces, options)).toMatchSnapshot();
+    });
+
+    test('diffDefault yellowish common', () => {
+      const options = {
+        commonLineTrailingSpaceColor: chalk.bgYellow,
       };
 
       expect(diff(aTrailingSpaces, bTrailingSpaces, options)).toMatchSnapshot();

packages/jest-diff/src/__tests__/joinAlignedDiffs.test.ts

@@ -10,19 +10,19 @@ import {
   joinAlignedDiffsExpand,
   joinAlignedDiffsNoExpand,
 } from '../joinAlignedDiffs';
-import {normalizeDiffOptions} from '../normalizeDiffOptions';
+import {noColor, normalizeDiffOptions} from '../normalizeDiffOptions';
 
 // To align columns so people can review snapshots confidently:
 
 // 1. Use options to omit line colors.
-const identity = (string: string) => string;
 const changeColor = (string: string) => '<i>' + string + '</i>';
 const optionsNoColor = {
-  aColor: identity,
-  bColor: identity,
+  aColor: noColor,
+  bColor: noColor,
   changeColor,
-  commonColor: identity,
-  patchColor: identity,
+  commonColor: noColor,
+  emptyFirstOrLastLinePlaceholder: '↵', // U+21B5
+  patchColor: noColor,
 };
 
 // 2. Add string serializer to omit double quote marks.

packages/jest-diff/src/index.ts

@@ -12,9 +12,13 @@ import {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff} from './cleanupSemantic';
 import {diffLinesRaw, diffLinesUnified, diffLinesUnified2} from './diffLines';
 import {diffStringsRaw, diffStringsUnified, splitLines0} from './printDiffs';
 import {NO_DIFF_MESSAGE, SIMILAR_MESSAGE} from './constants';
-import {DiffOptions as ImportDiffOptions} from './types';
+import {
+  DiffOptions as ImportDiffOptions,
+  DiffOptionsColor as ImportDiffOptionsColor,
+} from './types';
 
 export type DiffOptions = ImportDiffOptions;
+export type DiffOptionsColor = ImportDiffOptionsColor;
 
 export {diffLinesRaw, diffLinesUnified, diffLinesUnified2};
 export {diffStringsRaw, diffStringsUnified, splitLines0};

packages/jest-diff/src/normalizeDiffOptions.ts

@@ -9,6 +9,8 @@ import chalk from 'chalk';
 
 import {DiffOptions, DiffOptionsNormalized} from './types';
 
+export const noColor = (string: string) => string;
+
 const DIFF_CONTEXT_DEFAULT = 5;
 
 const OPTIONS_DEFAULT: DiffOptionsNormalized = {
@@ -19,15 +21,16 @@ const OPTIONS_DEFAULT: DiffOptionsNormalized = {
   bColor: chalk.red,
   bIndicator: '+',
   changeColor: chalk.inverse,
+  changeLineTrailingSpaceColor: noColor,
   commonColor: chalk.dim,
   commonIndicator: ' ',
+  commonLineTrailingSpaceColor: noColor,
   contextLines: DIFF_CONTEXT_DEFAULT,
+  emptyFirstOrLastLinePlaceholder: '',
   expand: true,
-  firstOrLastEmptyLineReplacement: '\u{21B5}', // downwards arrow with corner leftwards
   includeChangeCounts: false,
   omitAnnotationLines: false,
   patchColor: chalk.yellow,
-  trailingSpaceFormatter: chalk.bgYellow,
 };
 
 const getContextLines = (contextLines?: number): number =>

packages/jest-diff/src/printDiffs.ts

@@ -32,17 +32,17 @@ const printDiffLine = (
   isFirstOrLast: boolean,
   color: DiffOptionsColor,
   indicator: string,
-  firstOrLastEmptyLineReplacement: string,
   trailingSpaceFormatter: DiffOptionsColor,
+  emptyFirstOrLastLinePlaceholder: string,
 ): string =>
   line.length !== 0
     ? color(
         indicator + ' ' + formatTrailingSpaces(line, trailingSpaceFormatter),
       )
     : indicator !== ' '
     ? color(indicator)
-    : isFirstOrLast && firstOrLastEmptyLineReplacement.length !== 0
-    ? color(indicator + ' ' + firstOrLastEmptyLineReplacement)
+    : isFirstOrLast && emptyFirstOrLastLinePlaceholder.length !== 0
+    ? color(indicator + ' ' + emptyFirstOrLastLinePlaceholder)
     : '';
 
 export const printDeleteLine = (
@@ -51,17 +51,17 @@ export const printDeleteLine = (
   {
     aColor,
     aIndicator,
-    firstOrLastEmptyLineReplacement,
-    trailingSpaceFormatter,
+    changeLineTrailingSpaceColor,
+    emptyFirstOrLastLinePlaceholder,
   }: DiffOptionsNormalized,
 ): string =>
   printDiffLine(
     line,
     isFirstOrLast,
     aColor,
     aIndicator,
-    firstOrLastEmptyLineReplacement,
-    trailingSpaceFormatter,
+    changeLineTrailingSpaceColor,
+    emptyFirstOrLastLinePlaceholder,
   );
 
 export const printInsertLine = (
@@ -70,17 +70,17 @@ export const printInsertLine = (
   {
     bColor,
     bIndicator,
-    firstOrLastEmptyLineReplacement,
-    trailingSpaceFormatter,
+    changeLineTrailingSpaceColor,
+    emptyFirstOrLastLinePlaceholder,
   }: DiffOptionsNormalized,
 ): string =>
   printDiffLine(
     line,
     isFirstOrLast,
     bColor,
     bIndicator,
-    firstOrLastEmptyLineReplacement,
-    trailingSpaceFormatter,
+    changeLineTrailingSpaceColor,
+    emptyFirstOrLastLinePlaceholder,
   );
 
 export const printCommonLine = (
@@ -89,17 +89,17 @@ export const printCommonLine = (
   {
     commonColor,
     commonIndicator,
-    firstOrLastEmptyLineReplacement,
-    trailingSpaceFormatter,
+    commonLineTrailingSpaceColor,
+    emptyFirstOrLastLinePlaceholder,
   }: DiffOptionsNormalized,
 ): string =>
   printDiffLine(
     line,
     isFirstOrLast,
     commonColor,
     commonIndicator,
-    firstOrLastEmptyLineReplacement,
-    trailingSpaceFormatter,
+    commonLineTrailingSpaceColor,
+    emptyFirstOrLastLinePlaceholder,
   );
 
 export const hasCommonDiff = (diffs: Array<Diff>, isMultiline: boolean) => {