Babel Helper Plugin Test Runner

The @babel/helper-plugin-test-runner package provides a helper function to support fixture-based test runners for Babel plugins. It simplifies the process of running fixture-based tests for Babel transformations by providing a standardized interface to @babel/helper-transform-fixture-test-runner, handling file system operations, path resolution, and cross-platform compatibility.

Package Information

• Package Name: @babel/helper-plugin-test-runner
• Package Type: npm
• Language: TypeScript
• Installation: npm install @babel/helper-plugin-test-runner

Core Imports

import testRunner from "@babel/helper-plugin-test-runner";

For CommonJS:

const testRunner = require("@babel/helper-plugin-test-runner");

Basic Usage

import testRunner from "@babel/helper-plugin-test-runner";

// Run tests for fixtures in a directory
testRunner("file:///path/to/plugin/test/");

// Legacy path format also supported
testRunner("/path/to/plugin/test/");

Capabilities

Test Runner Function

The main export is a function that processes fixture-based tests for Babel plugins, providing cross-platform compatibility and automatic fixture discovery.

/**
 * Run fixture-based tests for Babel plugins
 * @param loc - Location path (file:// URL or regular path) pointing to directory containing test fixtures
 */
function testRunner(loc: string): void;

Parameters:

• loc (string): Location path that can be either:
  • A file:// URL pointing to the test directory
  • A regular file system path to the test directory
  • The function automatically looks for a fixtures subdirectory within the provided location

Behavior:

• Cross-platform compatibility: Handles Windows path separators and URL formatting differences
• Automatic fixture discovery: Looks for fixtures subdirectory and determines test names from directory structure
• Path resolution: Supports both modern file:// URLs and legacy file system paths
• Integration: Delegates to @babel/helper-transform-fixture-test-runner for actual test execution
• Environment compatibility: Handles BABEL_8_BREAKING environment variable for version compatibility

Usage Examples:

import testRunner from "@babel/helper-plugin-test-runner";

// Using file:// URL (modern approach)
testRunner("file:///path/to/my-babel-plugin/test/");

// Using regular path (legacy support)
testRunner("/path/to/my-babel-plugin/test/");

// The function will automatically:
// 1. Look for a "fixtures" subdirectory
// 2. Extract the plugin name from the parent directory 
// 3. Call the underlying test runner with proper configuration

Types

/**
 * Main test runner function signature
 */
type TestRunnerFunction = (loc: string) => void;

Platform Support

• Node.js: >=6.9.0 (>=20.19.0 || >=22.12.0 for Babel 8)
• Platforms: Cross-platform with Windows-specific path handling
• Module Systems: Supports both CommonJS and ESM imports
• Environment Variables: Respects BABEL_8_BREAKING for version compatibility

Dependencies

This package requires:

• @babel/helper-transform-fixture-test-runner: Core test runner functionality
• node:path: Path manipulation utilities
• node:url: URL handling for file:// URLs

Error Handling

The function will throw errors in the following cases:

• Invalid path or URL formats
• Missing fixtures directory
• File system access issues
• Underlying test runner failures

Common error scenarios:

// This will work
testRunner("file:///Users/dev/my-plugin/test/");

// This will also work (legacy format)  
testRunner("/Users/dev/my-plugin/test/");

// This may fail if fixtures directory doesn't exist
testRunner("/path/without/fixtures/");