or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

formatters.mdindex.mdplugin-testing.mdpreset-testing.mdtest-configuration.mdutilities.md
tile.json

tessl/npm-babel-plugin-tester

Utilities for testing babel plugins

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/babel-plugin-tester@12.0.x

To install, run

npx @tessl/cli install tessl/npm-babel-plugin-tester@12.0.0

index.mddocs/

babel-plugin-tester

babel-plugin-tester provides comprehensive utilities for testing Babel plugins and presets, designed to work seamlessly with popular testing frameworks like Jest, Mocha, Jasmine, node:test, and Vitest. It offers a simple abstraction layer that streamlines the process of writing and executing tests for Babel transformations.

Package Information

  • Package Name: babel-plugin-tester
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev babel-plugin-tester

Core Imports

ESM (default import with automatic Jest setup):

import pluginTester from "babel-plugin-tester";

For more control without automatic Jest configuration:

import { pluginTester } from "babel-plugin-tester/pure";

CommonJS:

const pluginTester = require("babel-plugin-tester");

Named imports (with automatic Jest setup):

import { pluginTester as defaultPluginTester } from "babel-plugin-tester";

Additional utilities:

import {
  pluginTester,
  prettierFormatter,
  unstringSnapshotSerializer,
  runPluginUnderTestHere,
  runPresetUnderTestHere
} from "babel-plugin-tester";

Basic Usage

import pluginTester from "babel-plugin-tester";
import myBabelPlugin from "../my-babel-plugin";

pluginTester({
  plugin: myBabelPlugin,
  tests: [
    {
      code: `const hello = "world";`,
      output: `const hello = "WORLD";`,
    },
    {
      code: `
        function greet(name) {
          return "Hello " + name;
        }
      `,
      output: `
        function greet(name) {
          return "HELLO " + name;
        }
      `,
    },
  ],
});

Architecture

babel-plugin-tester is built around several key components:

  • Plugin Testing Engine: Core pluginTester function that orchestrates test execution
  • Test Configuration System: Flexible configuration supporting both simple arrays and complex test objects
  • Fixture Support: File-based testing with automatic discovery and loading
  • Result Formatting: Pluggable formatters like prettierFormatter for output normalization
  • Snapshot Integration: Automatic Jest snapshot serializer setup for cleaner test output
  • Multi-Framework Support: Compatible with Jest, Mocha, Jasmine, node:test, and Vitest

Capabilities

Plugin Testing

Core functionality for testing Babel plugins with various test configurations and execution modes.

function pluginTester(options?: PluginTesterOptions): void;

Plugin Testing

Preset Testing

Testing functionality specifically designed for Babel presets with preset-specific configuration options.

interface PluginTesterOptions {
  preset?: (...args: any[]) => Babel.TransformOptions;
  presetName?: string;
  presetOptions?: any;
}

Preset Testing

Test Configuration

Flexible test configuration supporting arrays, objects, and fixture-based testing approaches.

interface TestObject {
  code?: string;
  output?: string;
  fixture?: string;
  outputFixture?: string;
  /** @deprecated Use fixture instead */
  codeFixture?: string;
  throws?: ErrorExpectation;
  only?: boolean;
  skip?: boolean;
  setup?: SetupFunction;
  teardown?: TeardownFunction;
  outputRaw?: OutputTesterFunction;
  babelOptions?: Babel.TransformOptions;
  pluginOptions?: any;
  presetOptions?: any;
  filename?: string;
  snapshot?: boolean;
  formatResult?: ResultFormatter;
}

type ErrorExpectation = boolean | string | RegExp | Error | Class<Error> | ((error: unknown) => boolean);

Test Configuration

Result Formatting

Pluggable result formatters for normalizing and prettifying Babel transformation output.

type ResultFormatter<T = any> = (
  code: string,
  options?: {
    cwd?: string;
    filename?: string;
    filepath?: string;
  } & T
) => Promise<string>;

const prettierFormatter: ResultFormatter<{
  prettierOptions?: PrettierOptions | null;
  config?: PrettierOptions | null;
}>;

Formatters

Utilities

Helper functions and symbols for advanced testing scenarios and framework integration.

function restartTestTitleNumbering(): void;

const runPluginUnderTestHere: unique symbol;
const runPresetUnderTestHere: unique symbol;
const unstringSnapshotSerializer: SnapshotSerializer;

const validEndOfLineValues: readonly string[];
const validTitleNumberingValues: readonly (string | boolean)[];

Utilities

Core Types

interface PluginTesterOptions {
  plugin?: (...args: any[]) => Babel.PluginObj<any>;
  pluginName?: string;
  pluginOptions?: Babel.PluginOptions;
  preset?: (...args: any[]) => Babel.TransformOptions;
  presetName?: string;
  presetOptions?: any;
  babel?: {
    transform: BabelType['transform'];
    transformAsync?: BabelType['transformAsync'];
  };
  babelOptions?: Omit<Babel.TransformOptions, 'plugins' | 'presets'> & {
    plugins?: (NonNullable<Babel.TransformOptions['plugins']>[number] | typeof runPluginUnderTestHere)[] | null;
    presets?: (NonNullable<Babel.TransformOptions['presets']>[number] | typeof runPresetUnderTestHere)[] | null;
  };
  title?: string | false;
  filepath?: string;
  /** @deprecated Use filepath instead */
  filename?: string;
  endOfLine?: 'lf' | 'crlf' | 'auto' | 'preserve' | false;
  setup?: SetupFunction;
  teardown?: TeardownFunction;
  formatResult?: ResultFormatter;
  snapshot?: boolean;
  fixtureOutputName?: string;
  fixtureOutputExt?: string;
  titleNumbering?: 'all' | 'tests-only' | 'fixtures-only' | false;
  restartTitleNumbering?: boolean;
  fixtures?: string;
  tests?: (TestObject | string)[] | Record<string, TestObject | string>;
}

interface FixtureOptions {
  babelOptions?: Babel.TransformOptions;
  pluginOptions?: any;
  presetOptions?: any;
  output?: string;
  throws?: ErrorExpectation;
  only?: boolean;
  skip?: boolean;
  setup?: SetupFunction;
  teardown?: TeardownFunction;
  outputRaw?: OutputTesterFunction;
  fixtureOutputName?: string;
  fixtureOutputExt?: string;
  formatResult?: ResultFormatter;
  snapshot?: boolean;
}

type Promisable<T> = T | Promise<T>;
type BabelType = typeof import('@babel/core');

type SetupFunction = () => Promisable<void> | Promisable<TeardownFunction>;
type TeardownFunction = () => Promisable<void>;
type OutputTesterFunction = (output: Babel.BabelFileResult) => Promisable<void>;

type ResultFormatter<T = any> = (
  code: string,
  options?: {
    cwd?: string;
    filepath?: string;
    /** @deprecated Use filepath instead */
    filename?: string;
  } & T
) => Promise<string> | string;

type SnapshotSerializer = import('pretty-format').Plugin;