Socket
Socket
Sign inDemoInstall

pretty-format

Package Overview
Dependencies
4
Maintainers
6
Versions
234
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

pretty-format

Stringify any JavaScript value.


Version published
Maintainers
6
Weekly downloads
78,459,445
decreased by-6.97%

Weekly downloads

Package description

What is pretty-format?

The pretty-format npm package is a JavaScript library that allows you to serialize any JavaScript value into a string with a human-readable format. It is particularly useful for snapshot testing, where you want to compare the expected and actual output of your test cases.

What are pretty-format's main functionalities?

Pretty-printing of basic JavaScript types

This feature allows you to convert basic JavaScript types like objects, arrays, strings, numbers, etc., into a nicely formatted string.

const prettyFormat = require('pretty-format');
const value = { foo: 'bar', baz: 42 };
console.log(prettyFormat(value));

Customizing output with plugins

pretty-format supports plugins that can be used to customize the output for specific types of values, such as React elements.

const prettyFormat = require('pretty-format');
const ReactElementPlugin = require('pretty-format/plugins/ReactElement');
const reactElement = <div>Hello World</div>;
console.log(prettyFormat(reactElement, { plugins: [ReactElementPlugin] }));

Minimizing diff output

By using pretty-format in combination with a diffing library like jest-diff, you can minimize the output of diffs to make them easier to read and understand.

const prettyFormat = require('pretty-format');
const diff = require('jest-diff');
const oldValue = { a: 'old', b: 'values' };
const newValue = { a: 'new', b: 'values' };
const difference = diff(prettyFormat(oldValue), prettyFormat(newValue));
console.log(difference);

Other packages similar to pretty-format

Readme

Source

pretty-format

Stringify any JavaScript value.

  • Serialize built-in JavaScript types.
  • Serialize application-specific data types with built-in or user-defined plugins.

Installation

$ yarn add pretty-format

Usage

const {format: prettyFormat} = require('pretty-format'); // CommonJS
import {format as prettyFormat} from 'pretty-format'; // ES2015 modules
const val = {object: {}};
val.circularReference = val;
val[Symbol('foo')] = 'foo';
val.map = new Map([['prop', 'value']]);
val.array = [-0, Infinity, NaN];

console.log(prettyFormat(val));
/*
Object {
  "array": Array [
    -0,
    Infinity,
    NaN,
  ],
  "circularReference": [Circular],
  "map": Map {
    "prop" => "value",
  },
  "object": Object {},
  Symbol(foo): "foo",
}
*/

Usage with options

function onClick() {}

console.log(prettyFormat(onClick));
/*
[Function onClick]
*/

const options = {
  printFunctionName: false,
};
console.log(prettyFormat(onClick, options));
/*
[Function]
*/
keytypedefaultdescription
callToJSONbooleantruecall toJSON method (if it exists) on objects
escapeRegexbooleanfalseescape special characters in regular expressions
escapeStringbooleantrueescape special characters in strings
highlightbooleanfalsehighlight syntax with colors in terminal (some plugins)
indentnumber2spaces in each level of indentation
maxDepthnumberInfinitylevels to print in arrays, objects, elements, and so on
minbooleanfalseminimize added space: no indentation nor line breaks
pluginsarray[]plugins to serialize application-specific data types
printBasicPrototypebooleanfalseprint the prototype for plain objects and arrays
printFunctionNamebooleantrueinclude or omit the name of a function
themeobjectcolors to highlight syntax in terminal

Property values of theme are from ansi-styles colors

const DEFAULT_THEME = {
  comment: 'gray',
  content: 'reset',
  prop: 'yellow',
  tag: 'cyan',
  value: 'green',
};

Usage with plugins

The pretty-format package provides some built-in plugins, including:

  • ReactElement for elements from react
  • ReactTestComponent for test objects from react-test-renderer
// CommonJS
const React = require('react');
const renderer = require('react-test-renderer');
const {format: prettyFormat, plugins} = require('pretty-format');

const {ReactElement, ReactTestComponent} = plugins;
// ES2015 modules and destructuring assignment
import React from 'react';
import renderer from 'react-test-renderer';
import {plugins, format as prettyFormat} from 'pretty-format';

const {ReactElement, ReactTestComponent} = plugins;
const onClick = () => {};
const element = React.createElement('button', {onClick}, 'Hello World');

const formatted1 = prettyFormat(element, {
  plugins: [ReactElement],
  printFunctionName: false,
});
const formatted2 = prettyFormat(renderer.create(element).toJSON(), {
  plugins: [ReactTestComponent],
  printFunctionName: false,
});
/*
<button
  onClick=[Function]
>
  Hello World
</button>
*/

Usage in Jest

For snapshot tests, Jest uses pretty-format with options that include some of its built-in plugins. For this purpose, plugins are also known as snapshot serializers.

To serialize application-specific data types, you can add modules to devDependencies of a project, and then:

In an individual test file, you can add a module as follows. It precedes any modules from Jest configuration.

import serializer from 'my-serializer-module';
expect.addSnapshotSerializer(serializer);

// tests which have `expect(value).toMatchSnapshot()` assertions

For all test files, you can specify modules in Jest configuration. They precede built-in plugins for React, HTML, and Immutable.js data types. For example, in a package.json file:

{
  "jest": {
    "snapshotSerializers": ["my-serializer-module"]
  }
}

Writing plugins

A plugin is a JavaScript object.

If options has a plugins array: for the first plugin whose test(val) method returns a truthy value, then prettyFormat(val, options) returns the result from either:

  • serialize(val, …) method of the improved interface (available in version 21 or later)
  • print(val, …) method of the original interface (if plugin does not have serialize method)

test

Write test so it can receive val argument of any type. To serialize objects which have certain properties, then a guarded expression like val != null && … or more concise val && … prevents the following errors:

  • TypeError: Cannot read property 'whatever' of null
  • TypeError: Cannot read property 'whatever' of undefined

For example, test method of built-in ReactElement plugin:

const elementSymbol = Symbol.for('react.element');
const test = val => val && val.$$typeof === elementSymbol;

Pay attention to efficiency in test because pretty-format calls it often.

serialize

The improved interface is available in version 21 or later.

Write serialize to return a string, given the arguments:

  • val which “passed the test”
  • unchanging config object: derived from options
  • current indentation string: concatenate to indent from config
  • current depth number: compare to maxDepth from config
  • current refs array: find circular references in objects
  • printer callback function: serialize children

config

keytypedescription
callToJSONbooleancall toJSON method (if it exists) on objects
colorsObjectescape codes for colors to highlight syntax
escapeRegexbooleanescape special characters in regular expressions
escapeStringbooleanescape special characters in strings
indentstringspaces in each level of indentation
maxDepthnumberlevels to print in arrays, objects, elements, and so on
minbooleanminimize added space: no indentation nor line breaks
pluginsarrayplugins to serialize application-specific data types
printFunctionNamebooleaninclude or omit the name of a function
spacingInnerstrongspacing to separate items in a list
spacingOuterstrongspacing to enclose a list of items

Each property of colors in config corresponds to a property of theme in options:

  • the key is the same (for example, tag)
  • the value in colors is a object with open and close properties whose values are escape codes from ansi-styles for the color value in theme (for example, 'cyan')

Some properties in config are derived from min in options:

  • spacingInner and spacingOuter are newline if min is false
  • spacingInner is space and spacingOuter is empty string if min is true

Example of serialize and test

This plugin is a pattern you can apply to serialize composite data types. Side note: pretty-format does not need a plugin to serialize arrays.

// We reused more code when we factored out a function for child items
// that is independent of depth, name, and enclosing punctuation (see below).
const SEPARATOR = ',';
function serializeItems(items, config, indentation, depth, refs, printer) {
  if (items.length === 0) {
    return '';
  }
  const indentationItems = indentation + config.indent;
  return (
    config.spacingOuter +
    items
      .map(
        item =>
          indentationItems +
          printer(item, config, indentationItems, depth, refs), // callback
      )
      .join(SEPARATOR + config.spacingInner) +
    (config.min ? '' : SEPARATOR) + // following the last item
    config.spacingOuter +
    indentation
  );
}

const plugin = {
  test(val) {
    return Array.isArray(val);
  },
  serialize(array, config, indentation, depth, refs, printer) {
    const name = array.constructor.name;
    return ++depth > config.maxDepth
      ? '[' + name + ']'
      : (config.min ? '' : name + ' ') +
          '[' +
          serializeItems(array, config, indentation, depth, refs, printer) +
          ']';
  },
};
const val = {
  filter: 'completed',
  items: [
    {
      text: 'Write test',
      completed: true,
    },
    {
      text: 'Write serialize',
      completed: true,
    },
  ],
};
console.log(
  prettyFormat(val, {
    plugins: [plugin],
  }),
);
/*
Object {
  "filter": "completed",
  "items": Array [
    Object {
      "completed": true,
      "text": "Write test",
    },
    Object {
      "completed": true,
      "text": "Write serialize",
    },
  ],
}
*/
console.log(
  prettyFormat(val, {
    indent: 4,
    plugins: [plugin],
  }),
);
/*
Object {
    "filter": "completed",
    "items": Array [
        Object {
            "completed": true,
            "text": "Write test",
        },
        Object {
            "completed": true,
            "text": "Write serialize",
        },
    ],
}
*/
console.log(
  prettyFormat(val, {
    maxDepth: 1,
    plugins: [plugin],
  }),
);
/*
Object {
  "filter": "completed",
  "items": [Array],
}
*/
console.log(
  prettyFormat(val, {
    min: true,
    plugins: [plugin],
  }),
);
/*
{"filter": "completed", "items": [{"completed": true, "text": "Write test"}, {"completed": true, "text": "Write serialize"}]}
*/

print

The original interface is adequate for plugins:

  • that do not depend on options other than highlight or min
  • that do not depend on depth or refs in recursive traversal, and
  • if values either
    • do not require indentation, or
    • do not occur as children of JavaScript data structures (for example, array)

Write print to return a string, given the arguments:

  • val which “passed the test”
  • current printer(valChild) callback function: serialize children
  • current indenter(lines) callback function: indent lines at the next level
  • unchanging config object: derived from options
  • unchanging colors object: derived from options

The 3 properties of config are min in options and:

  • spacing and edgeSpacing are newline if min is false
  • spacing is space and edgeSpacing is empty string if min is true

Each property of colors corresponds to a property of theme in options:

  • the key is the same (for example, tag)
  • the value in colors is a object with open and close properties whose values are escape codes from ansi-styles for the color value in theme (for example, 'cyan')

Example of print and test

This plugin prints functions with the number of named arguments excluding rest argument.

const plugin = {
  print(val) {
    return `[Function ${val.name || 'anonymous'} ${val.length}]`;
  },
  test(val) {
    return typeof val === 'function';
  },
};
const val = {
  onClick(event) {},
  render() {},
};

prettyFormat(val, {
  plugins: [plugin],
});
/*
Object {
  "onClick": [Function onClick 1],
  "render": [Function render 0],
}
*/

prettyFormat(val);
/*
Object {
  "onClick": [Function onClick],
  "render": [Function render],
}
*/

This plugin ignores the printFunctionName option. That limitation of the original print interface is a reason to use the improved serialize interface, described above.

prettyFormat(val, {
  plugins: [pluginOld],
  printFunctionName: false,
});
/*
Object {
  "onClick": [Function onClick 1],
  "render": [Function render 0],
}
*/

prettyFormat(val, {
  printFunctionName: false,
});
/*
Object {
  "onClick": [Function],
  "render": [Function],
}
*/

FAQs

Last updated on 13 Sep 2021

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc