or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-manipulation.mderror-handling.mdfile-system.mdgarbage-collection.mdglobal-environment.mdindex.mdmodule-loading.mdstring-path.mdterminal.mdtype-checking.md
tile.json

tessl/npm-jest-util

Collection of utility functions for Jest testing framework

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jest-util@30.0.x

To install, run

npx @tessl/cli install tessl/npm-jest-util@30.0.0

index.mddocs/

Jest Util

Jest Util is a comprehensive collection of utility functions specifically designed for the Jest testing framework ecosystem. It provides essential utilities for error handling, file system operations, terminal interactions, module loading compatibility, data manipulation, path and glob pattern matching, assertions and type checking, formatting utilities, global environment setup, and performance optimization through garbage collection utilities.

Package Information

  • Package Name: jest-util
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install jest-util
  • Version: 30.0.5

Core Imports

import { 
  clearLine, 
  createDirectory, 
  ErrorWithStack, 
  isInteractive, 
  isPromise,
  deepCyclicCopy,
  formatTime,
  pluralize
} from "jest-util";

For CommonJS:

const { 
  clearLine, 
  createDirectory, 
  ErrorWithStack, 
  isInteractive, 
  isPromise,
  deepCyclicCopy,
  formatTime,
  pluralize
} = require("jest-util");

Namespace imports:

import { specialChars, preRunMessage } from "jest-util";

Basic Usage

import { 
  createDirectory, 
  isPromise, 
  formatTime, 
  deepCyclicCopy,
  ErrorWithStack 
} from "jest-util";

// File system operations
createDirectory("/path/to/test/directory");

// Type checking
const maybePromise = someFunction();
if (isPromise(maybePromise)) {
  await maybePromise;
}

// Data utilities
const original = { nested: { data: [1, 2, 3] } };
const copy = deepCyclicCopy(original);

// Time formatting for test results
const executionTime = 1250; // milliseconds
console.log(`Test completed in ${formatTime(executionTime)}`); // "1.25 s"

// Error handling with stack traces
throw new ErrorWithStack("Test failed", testFunction);

Architecture

Jest Util is organized around several key functional areas:

  • File System Utilities: Safe directory creation and path resolution for test environments
  • Module Loading: Cross-platform module loading with CommonJS/ES6 interoperability
  • Global Environment: Jest test environment setup and global object management
  • Type Checking: Runtime type validation and assertions for test data
  • Data Manipulation: Deep copying and object utilities for test fixtures
  • String & Path Utilities: Text formatting and path manipulation for test output
  • Terminal Interaction: TTY detection and terminal output control
  • Garbage Collection: Memory management and cleanup for test isolation

Capabilities

File System Utilities

Core file system operations designed for Jest's testing needs, including safe directory creation and path resolution.

function createDirectory(path: string): void;
function tryRealpath(path: string): string;

File System Utilities

Module Loading Utilities

Cross-platform module loading utilities that handle CommonJS/ES6 interoperability and dynamic imports for Jest's module system.

function interopRequireDefault(obj: any): any;
function requireOrImportModule<T>(
  filePath: string, 
  applyInteropRequireDefault?: boolean
): Promise<T>;

Module Loading Utilities

Global Environment Management

Utilities for setting up and managing Jest's global test environment, including process object creation and global property management.

function installCommonGlobals(
  globalObject: typeof globalThis,
  globals: Config.ConfigGlobals,
  garbageCollectionDeletionMode?: DeletionMode
): typeof globalThis & Config.ConfigGlobals;

function setGlobal(
  globalToMutate: typeof globalThis | Global.Global,
  key: string | symbol,
  value: unknown,
  afterTeardown: 'clean' | 'retain' = 'clean'
): void;

Global Environment Management

Type Checking & Validation

Runtime type checking and validation utilities for test data and assertions.

function isPromise<T = unknown>(candidate: unknown): candidate is PromiseLike<T>;
function isNonNullable<T>(value: T): value is NonNullable<T>;
function invariant(condition: unknown, message = ''): asserts condition;

Type Checking & Validation

Data Manipulation

Utilities for copying, transforming, and manipulating data structures commonly used in test scenarios.

function deepCyclicCopy<T>(
  value: T, 
  options?: DeepCyclicCopyOptions, 
  cycles?: WeakMap<any, any>
): T;

function convertDescriptorToString(
  descriptor: Global.BlockNameLike | undefined
): string;

Data Manipulation

String & Path Utilities

Text formatting and path manipulation utilities for test output and file system operations.

function pluralize(word: string, count: number, ending = 's'): string;
function formatTime(time: number, prefixPower = -3, padLeftLength = 0): string;
function replacePathSepForGlob(path: string): string;
function globsToMatcher(globs: Array<string>): Matcher;

String & Path Utilities

Terminal Interaction

Terminal and TTY interaction utilities for Jest's interactive features and output control.

function clearLine(stream: WriteStream): void;
const isInteractive: boolean;
const specialChars: {
  ARROW: string;
  ICONS: {
    failed: string;
    pending: string;
    success: string;
    todo: string;
  };
  CLEAR: string;
};
const preRunMessage: {
  print(stream: WriteStream): void;
  remove(stream: WriteStream): void;
};

Terminal Interaction

Error Handling

Enhanced error handling with custom stack trace management for better test debugging.

class ErrorWithStack extends Error {
  constructor(
    message: string | undefined,
    callsite: (...args: Array<any>) => unknown,
    stackLimit?: number
  );
}

Error Handling

Garbage Collection Utilities

Memory management and cleanup utilities for test isolation and performance optimization.

type DeletionMode = 'soft' | 'off' | 'on';

function initializeGarbageCollectionUtils(
  globalObject: typeof globalThis,
  deletionMode: DeletionMode
): void;

function canDeleteProperties(value: unknown): value is object;
function protectProperties<T>(
  value: T,
  properties?: Array<keyof T>,
  depth?: number
): boolean;
function deleteProperties(value: unknown): void;

Garbage Collection Utilities

Core Types

interface DeepCyclicCopyOptions {
  blacklist?: Set<string>;
  keepPrototype?: boolean;
}

type Matcher = (str: string) => boolean;

type DeletionMode = 'soft' | 'off' | 'on';