or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-jest--pattern

Helper library for Jest that implements the logic for parsing and matching test path patterns

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@jest/pattern@30.0.x

To install, run

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

Jest Pattern

Jest Pattern is a helper library for the Jest testing framework that implements pattern parsing and matching logic for test path filtering. It provides cross-platform pattern matching capabilities that handle both absolute and relative file paths, with sophisticated regex-based matching and Windows/POSIX path separator normalization.

Package Information

Package Name: @jest/pattern
Package Type: npm
Language: TypeScript
Installation: npm install @jest/pattern

Core Imports

import { TestPathPatterns, TestPathPatternsExecutor, type TestPathPatternsExecutorOptions } from "@jest/pattern";

For CommonJS:

const { TestPathPatterns, TestPathPatternsExecutor } = require("@jest/pattern");

Basic Usage

import { TestPathPatterns } from "@jest/pattern";

// Create pattern collection
const patterns = new TestPathPatterns(["**/*.test.js", "./src/**/*"]);

// Validate patterns
if (patterns.isValid()) {
  // Create executor with root directory
  const executor = patterns.toExecutor({ rootDir: "/project" });
  
  // Test file paths against patterns
  const matches = executor.isMatch("/project/src/utils.test.js"); // true
  const noMatch = executor.isMatch("/project/docs/readme.md"); // false
}

Architecture

Jest Pattern is built around two primary components:

TestPathPatterns: Manages collections of pattern strings and provides validation/conversion methods
TestPathPatternsExecutor: Handles pattern execution with cross-platform path matching logic
Pattern Processing: Converts string patterns to case-insensitive regular expressions with path separator normalization
Cross-Platform Support: Handles both Windows backslash and POSIX forward slash path separators automatically

Capabilities

Pattern Collection Management

Manages collections of test path patterns with validation and conversion capabilities.

/**
 * Manages collections of test path patterns for Jest test discovery
 */
class TestPathPatterns {
  /** Array of pattern strings provided during construction */
  readonly patterns: Array<string>;
  
  /**
   * Creates a new TestPathPatterns instance
   * @param patterns - Array of pattern strings to manage
   */
  constructor(patterns: Array<string>);
  
  /**
   * Check if any patterns are configured
   * @returns true if patterns array is not empty
   */
  isSet(): boolean;
  
  /**
   * Validate that all patterns form valid regular expressions
   * @returns true if all patterns compile to valid regex
   */
  isValid(): boolean;
  
  /**
   * Get human-readable representation of patterns
   * @returns patterns joined with '|' separator
   */
  toPretty(): string;
  
  /**
   * Create executor for pattern matching operations
   * @param options - Configuration options including rootDir
   * @returns TestPathPatternsExecutor instance
   */
  toExecutor(options: TestPathPatternsExecutorOptions): TestPathPatternsExecutor;
  
  /**
   * Serialize patterns for Jest serializers
   * @returns serialization object with patterns and type
   */
  toJSON(): any;
}

Pattern Execution

Executes pattern matching operations against file paths with cross-platform support.

/**
 * Executes pattern matching operations with cross-platform path handling
 */
class TestPathPatternsExecutor {
  /** Reference to the pattern collection */
  readonly patterns: TestPathPatterns;
  
  /**
   * Creates a new TestPathPatternsExecutor
   * @param patterns - TestPathPatterns instance to execute
   * @param options - Configuration options for execution
   */
  constructor(patterns: TestPathPatterns, options: TestPathPatternsExecutorOptions);
  
  /**
   * Check if any patterns are configured
   * @returns true if patterns are set (delegates to patterns.isSet())
   */
  isSet(): boolean;
  
  /**
   * Validate that all patterns form valid regular expressions
   * @returns true if all patterns compile successfully
   */
  isValid(): boolean;
  
  /**
   * Test if absolute path matches any configured pattern
   * @param absPath - Absolute file path to test against patterns
   * @returns true if path matches any pattern
   * @throws Error if patterns form invalid regex
   */
  isMatch(absPath: string): boolean;
  
  /**
   * Get human-readable representation of patterns
   * @returns patterns joined with '|' separator (delegates to patterns.toPretty())
   */
  toPretty(): string;
}

Configuration Options

Configuration interface for TestPathPatternsExecutor behavior.

/**
 * Configuration options for TestPathPatternsExecutor
 */
interface TestPathPatternsExecutorOptions {
  /** Root directory for resolving relative patterns */
  rootDir: string;
}

Pattern Matching Behavior

Pattern Types

Relative patterns: ./src/**/*.test.js - matched against relative path from rootDir
Absolute patterns: /project/tests/**/* - matched against absolute path
Mixed patterns: Supports both types in the same pattern collection

Cross-Platform Support

Windows paths: Automatically handles backslash separators (\)
POSIX paths: Handles forward slash separators (/)
Pattern normalization: Converts path separators in patterns to work with target platform

Special Pattern Handling

Dot prefix patterns: ./foo.test.js converts to ^foo.test.js regex
Windows dot prefix: .\foo.test.js converts to ^foo.test.js regex
Case-insensitive matching: All pattern matching is case-insensitive
Empty patterns: Empty pattern array matches all paths (returns true)

Path Resolution

Dual testing: Tests patterns against both absolute and relative path versions
Relative path calculation: Uses path.relative(rootDir, absPath) for relative pattern matching
Pattern compilation: Converts string patterns to RegExp with case-insensitive flag

Error Handling

Invalid regex patterns: isValid() returns false for patterns that don't compile to valid regex
Runtime regex errors: isMatch() throws errors if patterns form invalid regex during execution
Path resolution: Uses Node.js path module for reliable cross-platform path operations

Usage Examples

Basic Pattern Matching

import { TestPathPatterns } from "@jest/pattern";

const patterns = new TestPathPatterns(["**/*.test.js", "!**/node_modules/**"]);
const executor = patterns.toExecutor({ rootDir: "/my-project" });

// Test various paths
console.log(executor.isMatch("/my-project/src/utils.test.js")); // true
console.log(executor.isMatch("/my-project/src/utils.js")); // false
console.log(executor.isMatch("/my-project/node_modules/lib/test.js")); // false

Validation and Error Handling

import { TestPathPatterns } from "@jest/pattern";

const patterns = new TestPathPatterns(["[invalid-regex"]);

if (!patterns.isValid()) {
  console.log("Invalid patterns detected");
  // Handle invalid patterns appropriately
} else {
  const executor = patterns.toExecutor({ rootDir: "/project" });
  // Safe to use executor
}

Pretty Printing for Debugging

import { TestPathPatterns } from "@jest/pattern";

const patterns = new TestPathPatterns(["src/**/*.test.js", "tests/**/*"]);
console.log("Patterns:", patterns.toPretty()); // "src/**/*.test.js|tests/**/*"

const executor = patterns.toExecutor({ rootDir: "/project" });
console.log("Executor patterns:", executor.toPretty()); // Same output