Plugin Testing

/**
 * Main function for testing Babel plugins and presets
 * @param options - Configuration options for plugin testing
 */
function pluginTester(options?: PluginTesterOptions): void;

interface PluginTesterOptions {
  /** The babel plugin under test */
  plugin?: (...args: any[]) => Babel.PluginObj<any>;
  /** Name for the plugin (used in test descriptions) */
  pluginName?: string;
  /** Options passed to the plugin at transform time */
  pluginOptions?: Babel.PluginOptions;
  /** Babel instance to use for transformations */
  babel?: {
    transform: BabelType['transform'];
    transformAsync?: BabelType['transformAsync'];
  };
  /** Babel transformation options */
  babelOptions?: Omit<Babel.TransformOptions, 'plugins' | 'presets'> & {
    plugins?: (NonNullable<Babel.TransformOptions['plugins']>[number] | typeof runPluginUnderTestHere)[] | null;
    presets?: (NonNullable<Babel.TransformOptions['presets']>[number] | typeof runPresetUnderTestHere)[] | null;
  };
  /** Custom title for describe block (or false to disable) */
  title?: string | false;
  /** File path for resolving relative paths */
  filepath?: string;
  /** @deprecated Use filepath instead */
  filename?: string;
  /** Line ending normalization strategy */
  endOfLine?: 'lf' | 'crlf' | 'auto' | 'preserve' | false;
  /** Setup function run before each test */
  setup?: SetupFunction;
  /** Teardown function run after each test */
  teardown?: TeardownFunction;
  /** Result formatter for output normalization */
  formatResult?: ResultFormatter;
  /** Enable snapshot testing for all tests */
  snapshot?: boolean;
  /** Default output filename for fixtures */
  fixtureOutputName?: string;
  /** Default output file extension for fixtures */
  fixtureOutputExt?: string;
  /** Test title numbering strategy */
  titleNumbering?: 'all' | 'tests-only' | 'fixtures-only' | false;
  /** Restart title numbering at 1 */
  restartTitleNumbering?: boolean;
  /** Directory containing fixture files */
  fixtures?: string;
  /** Test cases or test configuration */
  tests?: (TestObject | string)[] | Record<string, TestObject | string>;
}

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

// Basic plugin testing
pluginTester({
  plugin: myPlugin,
  tests: [
    {
      code: `const foo = "bar";`,
      output: `const foo = "BAR";`,
    },
  ],
});

// Plugin with options
pluginTester({
  plugin: myPlugin,
  pluginName: "my-awesome-plugin",
  pluginOptions: {
    uppercase: true,
    prefix: "transformed_",
  },
  tests: [
    {
      code: `const hello = "world";`,
      output: `const transformed_hello = "WORLD";`,
    },
  ],
});

// Using fixtures
pluginTester({
  plugin: myPlugin,
  fixtures: "__fixtures__/my-plugin",
});

// Advanced configuration
pluginTester({
  plugin: myPlugin,
  babel: require("@babel/core"),
  filename: "test.js",
  babelOptions: {
    parserOpts: {
      plugins: ["jsx", "typescript"],
    },
  },
  formatResult: prettierFormatter,
  titleNumbering: "tests-only",
  endOfLine: "lf",
  tests: {
    "transforms variables": {
      code: `let x = 1;`,
      output: `var x = 1;`,
    },
    "handles arrow functions": {
      code: `const fn = () => {};`,
      output: `const fn = function() {};`,
    },
  },
});

// Plugin name automatically inferred as "myTransformPlugin"
function myTransformPlugin() {
  return {
    visitor: {
      // plugin implementation
    }
  };
}

pluginTester({
  plugin: myTransformPlugin,
  // pluginName not needed - will be inferred
  tests: [...]
});

/** Symbol to run plugin in the current test context */
const runPluginUnderTestHere: unique symbol;

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

pluginTester({
  plugin: myPlugin,
  tests: [
    {
      code: `
        import { runPluginUnderTestHere } from "babel-plugin-tester";
        runPluginUnderTestHere;
        const foo = "bar";
      `,
      output: `
        const foo = "BAR";
      `,
    },
  ],
});