concordance

What is concordance?

Concordance is a powerful assertion library for JavaScript that provides detailed and human-readable diffs for objects, arrays, and other data structures. It is particularly useful for testing and debugging, as it helps developers quickly identify differences between expected and actual values.

What are concordance's main functionalities?

Detailed Object Comparison

This feature allows you to compare two objects and get a detailed diff of their differences. The output is human-readable and helps in quickly identifying discrepancies.

const concordance = require('concordance');
const actual = { a: 1, b: 2 };
const expected = { a: 1, b: 3 };
const result = concordance.diff(actual, expected);
console.log(result);

Array Comparison

This feature allows you to compare two arrays and get a detailed diff of their differences. It is useful for testing and debugging array data structures.

const concordance = require('concordance');
const actual = [1, 2, 3];
const expected = [1, 2, 4];
const result = concordance.diff(actual, expected);
console.log(result);

Custom Serializers

This feature allows you to create custom serializers to handle specific data types in your comparisons. It provides flexibility in how data is represented in the diffs.

const concordance = require('concordance');
const customSerializer = {
  describe(value) {
    return { text: `Custom: ${value}` };
  },
  test(value) {
    return typeof value === 'string';
  }
};
const actual = 'hello';
const expected = 'world';
const result = concordance.diff(actual, expected, { serializers: [customSerializer] });
console.log(result);

Other packages similar to concordance

jest-diff

jest-diff is a part of the Jest testing framework and provides similar functionality for comparing objects and arrays. It is integrated into Jest, making it a convenient choice for users of that framework. However, it may not be as flexible as Concordance in terms of custom serializers.

deep-diff

deep-diff is another library for comparing objects and arrays. It provides a detailed diff of the differences between two data structures. While it is powerful, it may not offer the same level of human-readable output as Concordance.

diff

diff is a general-purpose library for comparing text and data structures. It provides a variety of diff algorithms and output formats. While versatile, it may require more configuration to achieve the same level of readability as Concordance.

README

concordance

Compare, format, diff and serialize any JavaScript value. Built for Node.js 10 and above.

Behavior

Concordance recursively describes JavaScript values, whether they're booleans or complex object structures. It recurses through all enumerable properties, list items (e.g. arrays) and iterator entries.

The same algorithm is used when comparing, formatting or diffing values. This means Concordance's behavior is consistent, no matter how you use it.

Comparison details

• Object wrappers are compared both as objects and unwrapped values. Thus Concordance always treats Object(1) as different from 1.
• -0 is distinct from 0.
• NaN equals NaN.
• The Argument values can be compared to a regular array.
• Error names and messages are always compared, even if these are not enumerable properties.
• Function values are compared by identity only. Names are always formatted and serialized.
• Global objects are considered equal.
• Map keys and Set items are compared in-order.
• Object string properties are compared according to the traversal order. Symbol properties are compared by identity.
• Promise values are compared by identity only.
• Symbol values are compared by identity only.
• Recursion stops whenever a circular reference is encountered. If the same cycle is present in the actual and expected values they're considered equal, but they're unequal otherwise.

Formatting details

Concordance strives to format every aspect of a value that is used for comparisons. Formatting is optimized for human legibility.

Strings enjoy special formatting:

• When used as keys, line break characters are escaped
• Otherwise, multi-line strings are formatted using backticks, and line break characters are replaced by control pictures.

Similarly, line breaks in symbol descriptions are escaped.

Diffing details

Concordance tries to minimize diff lines. This is difficult with object values, which may have similar properties but a different constructor. Multi-line strings are compared line-by-line.

Serialization details

Concordance can serialize any value for later use. Deserialized values can be compared to each other or to regular JavaScript values. The deserialized value should be passed as the actual value to the comparison and diffing methods. Certain value comparisons behave differently when the actual value is deserialized:

• Argument values can only be compared to other Argument values.
• Function values are compared by name.
• Promise values are compared by their constructor and additional enumerable properties, but not by identity.
• Symbol values are compared by their string serialization. Registered and well-known symbols will never equal symbols with similar descriptions.