jest-util

What is jest-util?

The jest-util package provides utility functions for Jest, a popular JavaScript testing framework. It includes a variety of helpers and tools that are used internally by Jest but can also be useful for developers working with or extending Jest tests.

What are jest-util's main functionalities?

Console Replacement

This feature allows for the creation of a custom console that buffers all logs. This is useful for controlling and testing console output during test runs.

const { BufferedConsole } = require('jest-util');
const customConsole = new BufferedConsole();
customConsole.log('Hello, this is a buffered log.');

Error Formatting

This function formats execution errors for display in Jest's output, providing a standardized view of test errors, including stack traces.

const { formatExecError } = require('jest-util');
const error = new Error('Test error');
const config = {rootDir: '/path/to/project', testMatch: []};
console.log(formatExecError(error, config, {noStackTrace: false}, undefined, true));

Test Path Normalization

This utility normalizes file paths for glob matching, which is particularly useful on Windows where path separators differ.

const { replacePathSepForGlob } = require('jest-util');
const path = 'path\to\test\file.js';
console.log(replacePathSepForGlob(path));

Other packages similar to jest-util

chai

Chai is an assertion library similar to jest-util in that it is used to help with testing JavaScript applications. Unlike jest-util, Chai focuses more on providing a rich set of assertions rather than utilities for managing Jest environments or outputs.

mocha

Mocha is a test framework that, like Jest, can utilize utility packages for enhanced testing capabilities. While jest-util specifically supports Jest, Mocha has its own set of utilities and plugins that serve a similar purpose but are tailored to Mocha's ecosystem.

sinon

Sinon provides standalone test spies, stubs, and mocks for JavaScript. It complements jest-util by offering more focused functionalities for creating and managing test doubles, which can be used alongside or independently of Jest.

README

@jest/utils

This packages is a collection of utilities and helper functions

ErrorWithStack

This custom error class can be useful when you need to capture the stack trace of an error and provide additional context to the error message. By default, JavaScript errors only capture the stack trace when they are thrown, but this class allows you to capture the stack trace at any point in your code by calling its constructor.

clearLine

It ensures that the clearing operation is only performed when running in a terminal environment, and not when the output is redirected to a file or another non-terminal destination.

convertDescriptorToString

It defines a function named convertDescriptorToString that takes a descriptor as input and converts it to a string based on its type. It handles various types such as functions, numbers, strings, and undefined values. If the input doesn't match any of these types, it throws an error with a descriptive message.

createDirectory

It creates new directory and also allows creation of nested directories.

deepCyclicCopy

The deepCyclicCopy function provides deep copying of JavaScript objects and arrays, including handling circular references. It offers optional customization through a DeepCyclicCopyOptions parameter, allowing users to blacklist properties and preserve object prototypes. The function returns a completely independent deep copy of the input data structure.

formatTime

This function is useful for formatting time values with appropriate SI unit prefixes for readability. It expresses time in various units (e.g., milliseconds, microseconds, nanoseconds) while ensuring the formatting is consistent and human-readable.

globsToMatcher

The code efficiently converts a list of glob patterns into a reusable function for matching paths against those patterns, considering negated patterns and optimizing for performance.

installCommonGlobals

Sets up various global variables and functions needed by the Jest testing framework. It ensures that these globals are properly set up for testing scenarios while maintaining compatibility with the environment's global object.

interopRequireDefault

Provides a way to ensure compatibility between ES modules and CommonJS modules by handling the default export behavior appropriately.

invariant

It is a utility used for asserting that a given condition is true. It's often used as a debugging aid during development to catch situations where an expected condition is not met.

isInteractive

Checks whether the current environment is suitable for interactive terminal interactions.

isNonNullable

Used to narrow down the type of a variable within a TypeScript code block, ensuring that it is safe to assume that the value is non-nullable. This can help avoid runtime errors related to null or undefined values.

isPromise

It helps in order to determine whether a given value conforms to the structure of a Promise-like object, which typically has a then method. This can be useful when working with asynchronous code to ensure dealing with promises correctly.

pluralize

This function is used to easily generate grammatically correct phrases in text output that depend on the count of items. It ensures that the word is correctly pluralized when needed.

preRunMessage

These functions are intended for use in interactive command-line tools or scripts which provide informative messages to the user while ensuring a clean and responsive interface.

replacePathSepForGlob

The function takes a string path as input and replaces backslashes ('\') with forward slashes ('/') in the path. Used to normalize file paths to be compatible with glob patterns, ensuring consistency in path representation for different operating systems.

requireOrImportModule

This function provides a unified way to load modules regardless of whether they use CommonJS or ESM syntax. It ensures that the default export is applied consistently when needed, allowing users to work with modules that might use different module systems.

setGlobal

Used to set properties with specified values within a global object. It is designed to work in both browser-like and Node.js environments by accepting different types of global objects as input.

specialChars

It defines constants and conditional values for handling platform-specific behaviors in a terminal environment. It determines if the current platform is Windows ('win32') and sets up constants for various symbols and terminal screen clearing escape sequences accordingly, ensuring proper display and behavior on both Windows and non-Windows operating systems.

testPathPatternToRegExp

This function is used for consistency when serializing/deserializing global configurations and ensures that consistent regular expressions are produced for matching test paths.

tryRealpath

Used to resolve the real path of a given path, but if the path doesn't exist or is a directory, it doesn't throw an error and returns the original path string. This can be useful for gracefully handling path resolution in scenarios where some paths might not exist or might be directories.

Changelog

29.7.0

Features

• [create-jest] Add npm init / yarn create initialiser for Jest projects (#14465)
• [jest-validate] Allow deprecation warnings for unknown options (#14499)

Fixes

• [jest-resolver] Replace unmatched capture groups in moduleNameMapper with empty string instead of undefined (#14507)
• [jest-snapshot] Allow for strings as well as template literals in inline snapshots (#14465)
• [@jest/test-sequencer] Calculate test runtime if perStats.duration is missing (#14473)

Performance

• [@jest/create-cache-key-function] Cache access of NODE_ENV and BABEL_ENV (#14455)

Chore & Maintenance

• [jest-cli] Move internal config initialisation logic to the create-jest package (#14465)