Pretty Format

Common errors

• Snapshot mismatch

  cause Upgrading `pretty-format` (especially with Jest 30) or its dependencies can alter the serialized output of various JavaScript values, leading to failing snapshot tests.
  fix Review the snapshot differences and, if the changes are expected and correct, update your snapshots by running `jest --updateSnapshot`.

• TypeError: (0 , pretty_format__WEBPACK_IMPORTED_MODULE_0__.format) is not a function

  cause This error typically occurs in a mixed CommonJS/ESM environment or when a bundler incorrectly handles named exports, treating `format` as a default export, or when trying to destructure a CommonJS `require` directly with an ESM import syntax.
  fix Ensure you are using the correct import syntax for your module system. For ESM, use `import { format } from 'pretty-format';`. For CommonJS, use `const { format } = require('pretty-format');`. Verify your bundler/TypeScript configuration is set up to correctly handle module interop.

• Custom plugin not applied or applied incorrectly.

  cause The `test` method of a custom plugin might be returning `false` incorrectly, or the `serialize` method has a bug, or the plugin is not passed in the `options.plugins` array to `format`.
  fix Debug the `test` method to ensure it correctly identifies the target value. Check the `serialize` method for logic errors. Confirm the plugin is included in the `plugins` array passed to the `format` function. Ensure the `serialize` method uses `printer` for child values and `indenter` for new lines as expected.

Warnings

• breaking The React plugin for `pretty-format` no longer renders empty string children (`''`) in React elements. If your snapshots previously captured these empty strings, they will now be omitted, leading to snapshot mismatches.
  Fix: Update existing snapshots (`jest --updateSnapshot`) after upgrading to Jest 30 or `pretty-format` v30 to reflect the new rendering behavior. Review the changes to ensure they are intended.
• breaking The formatting of `ArrayBuffer` and `DataView` objects has been updated to be more correct and human-readable in version 30. This change will likely cause snapshot mismatches if your tests include these types.
  Fix: Run Jest with `--updateSnapshot` to accept the new, corrected formatting for `ArrayBuffer` and `DataView` instances in your snapshots. Verify the updated output is as expected.
• breaking As part of the Jest 30 upgrade, `pretty-format` introduces general improvements to object printing. While specific changes beyond React empty strings and ArrayBuffer/DataView are not individually listed as 'breaking' for `pretty-format`, the overall improvements may alter snapshot output for various JavaScript values.
  Fix: It is highly recommended to run `jest --updateSnapshot` after upgrading to Jest 30 to re-record any snapshots affected by these underlying formatting improvements. Always review snapshot diffs carefully.
• gotcha When developing custom plugins, ensure that the `test` method is highly performant as it is called frequently by `pretty-format` for all values. Inefficient `test` implementations can significantly degrade performance.
  Fix: Keep `test` methods simple, fast, and avoid expensive operations. Perform heavy logic only within the `serialize` or `print` methods once `test` has confirmed the plugin should handle the value.

Install

• npm install pretty-format npm
• yarn add pretty-format yarn
• pnpm add pretty-format pnpm

Imports

• format
  wrong:

  const format = require('pretty-format');

  correct:

  import { format } from 'pretty-format';

  While CommonJS `require` still works, ES Modules `import` is the recommended standard for modern Node.js environments (v18.14.0+), aligning with Jest 30's requirements. The `format` function is a named export.
• prettyFormat
  wrong:

  import prettyFormat from 'pretty-format';

  correct:

  import { format as prettyFormat } from 'pretty-format';

  The primary formatting function is a named export `format`. It's common practice to alias it to `prettyFormat` for clarity, as seen in Jest's own usage examples. There is no default export.
• plugins
  wrong:

  import { plugins } from 'pretty-format/plugins';

  correct:

  import { format, plugins } from 'pretty-format';
  // or specific plugins:
  import { ReactElement, ReactTestComponent } from 'pretty-format/build/plugins';

  Built-in plugins like `ReactElement` and `ReactTestComponent` are available for specialized formatting. They are typically imported directly from `pretty-format/build/plugins` when used outside of Jest's automatic configuration.

Quickstart

Demonstrates basic usage of `pretty-format` with a complex object, including circular references, various JavaScript types, and the use of built-in React plugins and a simple custom plugin.

import { format, plugins } from 'pretty-format';

const { ReactElement, ReactTestComponent } = plugins;

const val = {
  string: 'hello world',
  number: 123.45,
  boolean: true,
  array: [-0, Infinity, NaN, null, undefined],
  object: { key: 'value', nested: { id: 1 } },
  circularReference: null,
  map: new Map([['prop', 'value']]),
  set: new Set([1, 2, 3]),
  symbol: Symbol('description'),
  func: function myFunc() {},
  date: new Date('2023-01-01T12:00:00.000Z')
};

val.circularReference = val; // Create a circular reference

const options = {
  indent: 2,
  min: false,
  callToJSON: true,
  plugins: [ReactElement, ReactTestComponent]
};

console.log(format(val, options));

// Example with a custom plugin (simple)
const customPlugin = {
  test(value) {
    return value instanceof Error;
  },
  serialize(value, config, indentation, depth, refs, printer) {
    return `Custom Error: ${value.message}`;
  },
};

const error = new Error('Something went wrong');
console.log(format(error, { plugins: [customPlugin] }));