Helper functions and symbols for advanced testing scenarios and framework integration.
Control over test title numbering for better test organization and debugging.
/**
* Resets the internal test title numbering counter to 1
*/
function restartTestTitleNumbering(): void;
/** Valid values for the titleNumbering option */
const validTitleNumberingValues: readonly ('all' | 'tests-only' | 'fixtures-only' | false)[];Usage Examples:
import pluginTester, { restartTestTitleNumbering } from "babel-plugin-tester";
// Reset numbering between test suites
describe("Plugin Suite 1", () => {
pluginTester({
plugin: myPlugin,
titleNumbering: "all",
tests: [
{ code: "const a = 1;", output: "var a = 1;" }, // "1. transforms const"
{ code: "let b = 2;", output: "var b = 2;" }, // "2. transforms let"
],
});
});
describe("Plugin Suite 2", () => {
restartTestTitleNumbering(); // Reset to start from 1 again
pluginTester({
plugin: myPlugin,
titleNumbering: "tests-only",
tests: [
{ code: "const c = 3;", output: "var c = 3;" }, // "1. transforms const"
],
});
});
// Different numbering strategies
pluginTester({
plugin: myPlugin,
titleNumbering: "all", // Number all tests and fixtures
fixtures: "__fixtures__",
tests: [
"const a = 1;", // "1. unknown"
"let b = 2;", // "2. unknown"
],
});
pluginTester({
plugin: myPlugin,
titleNumbering: "fixtures-only", // Only number fixture tests
fixtures: "__fixtures__",
tests: [
"const a = 1;", // "unknown"
"let b = 2;", // "unknown"
],
});
pluginTester({
plugin: myPlugin,
titleNumbering: false, // No numbering
tests: [
"const a = 1;", // "unknown"
],
});Special symbols for controlling plugin and preset execution context.
/** Symbol to run plugin in the current test context */
const runPluginUnderTestHere: unique symbol;
/** Symbol to run preset in the current test context */
const runPresetUnderTestHere: unique symbol;Usage Examples:
import {
pluginTester,
runPluginUnderTestHere,
runPresetUnderTestHere
} from "babel-plugin-tester";
// Plugin execution control
pluginTester({
plugin: myPlugin,
tests: [
{
code: `
import { runPluginUnderTestHere } from "babel-plugin-tester";
runPluginUnderTestHere;
const foo = "bar";
`,
output: `
const foo = "BAR";
`,
},
],
});
// Preset execution control
pluginTester({
preset: myPreset,
tests: [
{
code: `
import { runPresetUnderTestHere } from "babel-plugin-tester";
runPresetUnderTestHere;
const Component = () => <div>Test</div>;
`,
output: `
const Component = () => React.createElement("div", null, "Test");
`,
},
],
});Jest snapshot serializer for cleaner snapshot output by removing string quotes.
/**
* Jest snapshot serializer that removes surrounding double quotes from string snapshots
*/
const unstringSnapshotSerializer: SnapshotSerializer;
/** Type alias for Jest snapshot serializer interface */
type SnapshotSerializer = import('pretty-format').Plugin;Usage Examples:
import { unstringSnapshotSerializer } from "babel-plugin-tester";
// Manual serializer setup (if not using default entry point)
if (typeof expect !== 'undefined' && expect.addSnapshotSerializer) {
expect.addSnapshotSerializer(unstringSnapshotSerializer);
}
// The serializer automatically cleans up snapshot output:
// Before: "const foo = \"bar\";"
// After: const foo = "bar";
pluginTester({
plugin: myPlugin,
tests: [
'const greeting = "hello world";', // Snapshot will be clean
],
});Control over line ending normalization in test output.
/** Valid values for the endOfLine option */
const validEndOfLineValues: readonly ('lf' | 'crlf' | 'auto' | 'preserve' | false)[];Usage Examples:
pluginTester({
plugin: myPlugin,
endOfLine: "lf", // Force Unix line endings
tests: [
{
code: "const a = 1;\r\nconst b = 2;",
output: "var a = 1;\nvar b = 2;", // Normalized to LF
},
],
});
pluginTester({
plugin: myPlugin,
endOfLine: "crlf", // Force Windows line endings
tests: [
{
code: "const a = 1;\nconst b = 2;",
output: "var a = 1;\r\nvar b = 2;", // Normalized to CRLF
},
],
});
pluginTester({
plugin: myPlugin,
endOfLine: "auto", // Auto-detect from input
tests: [
{
code: "const a = 1;\r\nconst b = 2;",
output: "var a = 1;\r\nvar b = 2;", // Preserves CRLF from input
},
],
});
pluginTester({
plugin: myPlugin,
endOfLine: "preserve", // Keep original line endings
tests: [
{
code: "const a = 1;\r\nconst b = 2;\n",
output: "var a = 1;\r\nvar b = 2;\n", // Mixed endings preserved
},
],
});
pluginTester({
plugin: myPlugin,
endOfLine: false, // No line ending normalization
tests: [
{
code: "const a = 1;\r\nconst b = 2;",
output: "var a = 1;\r\nvar b = 2;", // Must match exactly
},
],
});Built-in support for test filtering via environment variables.
Environment Variables:
TEST_ONLY / TEST_NUM_ONLY: Run only specific tests by name or numberTEST_SKIP / TEST_NUM_SKIP: Skip specific tests by name or numberUsage Examples:
# Run only test number 1
TEST_NUM_ONLY=1 npm test
# Run only tests 1-3
TEST_NUM_ONLY=1-3 npm test
# Skip test number 2
TEST_NUM_SKIP=2 npm test
# Run only tests containing "transform"
TEST_ONLY=transform npm test
# Skip tests containing "error"
TEST_SKIP=error npm testType representing the Babel API for type safety.
/** Type representing the Babel API interface */
type BabelType = typeof import('@babel/core');Usage Example:
import * as Babel from "@babel/core";
import pluginTester from "babel-plugin-tester";
pluginTester({
plugin: myPlugin,
babel: {
transform: Babel.transform,
transformAsync: Babel.transformAsync,
},
tests: [...],
});Collection of error message factory functions for various validation and runtime scenarios.
/** Error message factories for different validation scenarios */
const ErrorMessage: {
TestEnvironmentUndefinedDescribe(): string;
TestEnvironmentUndefinedIt(): string;
BadConfigPluginAndPreset(): string;
BadConfigNoPluginOrPreset(): string;
BadConfigBadTitle(): string;
BadConfigBadFilename(): string;
BadConfigBadEndOfLine(): string;
BadConfigBadTitleNumbering(): string;
BadConfigRestartBadTitleNumbering(): string;
BadConfigBadSetup(): string;
BadConfigBadTeardown(): string;
BadConfigBadFormatResult(): string;
BadConfigBadSnapshot(): string;
BadConfigBadBabelOptions(): string;
BadConfigBadTests(): string;
BadTestObjectUnknownType(): string;
BadTestObjectMixedWithFixtures(): string;
BadTestObjectBadName(): string;
BadTestObjectUnnamedMultiple(): string;
BadTestObjectBadCodeOrFixture(): string;
BadTestObjectBadCodeAndFixture(): string;
BadTestObjectBadCodeAndCodeFixture(): string;
BadTestObjectBadFixtureAndCodeFixture(): string;
BadTestObjectMissingMaybe(): string;
BadTestObjectBadOutput(): string;
BadTestObjectBadOutputAndOutputFixture(): string;
BadTestObjectBadSnapshot(): string;
ExpectedBabelToThrow(): string;
ExpectedBabelToNotThrow(): string;
// ... more error message functions
};Internal constants used by babel-plugin-tester for configuration and debugging.
/** Internal symbol for test configuration type marking */
const $type: unique symbol;
/** Global debugger namespace */
const globalDebuggerNamespace: 'bpt';
/** Global debug logger instance */
const globalDebugger: ExtendedDebugger;