Flexible test configuration supporting arrays, objects, and fixture-based testing approaches.
The main interface for defining individual test cases.
interface TestObject {
/** Input code to transform */
code?: string;
/** Expected output after transformation */
output?: string;
/** Path to fixture file containing input code */
fixture?: string;
/** Path to fixture file containing expected output */
outputFixture?: string;
/** @deprecated Use fixture instead */
codeFixture?: string;
/** Expected error or error validation */
throws?: ErrorExpectation;
/** Function to run before this test */
setup?: SetupFunction;
/** Function to run after this test */
teardown?: TeardownFunction;
/** Function to test raw Babel output */
outputRaw?: OutputTesterFunction;
/** Mark this test to run exclusively (test.only) */
only?: boolean;
/** Skip this test (test.skip) */
skip?: boolean;
/** Babel options specific to this test */
babelOptions?: Babel.TransformOptions;
/** Plugin options specific to this test */
pluginOptions?: any;
/** Preset options specific to this test */
presetOptions?: any;
/** Filename for this test transformation */
filename?: string;
/** Enable snapshot testing for this test */
snapshot?: boolean;
/** Custom formatter for this test output */
formatResult?: ResultFormatter;
}Different ways to structure test configurations.
/** Union type for all possible test configuration formats */
type PluginTesterTestConfig =
| PluginTesterTestObjectConfig
| PluginTesterTestFixtureConfig
| MaybePluginTesterTestConfig[];
/** Object-based test configuration */
type PluginTesterTestObjectConfig = {
[testName: string]: string | TestObject | null | undefined;
};
/** Array-based test configuration */
type MaybePluginTesterTestConfig = string | TestObject | null | undefined;Usage Examples:
import pluginTester from "babel-plugin-tester";
// Array of test objects
pluginTester({
plugin: myPlugin,
tests: [
{
code: `const a = 1;`,
output: `var a = 1;`,
},
{
code: `let b = 2;`,
output: `var b = 2;`,
},
],
});
// Object with named tests
pluginTester({
plugin: myPlugin,
tests: {
"transforms const to var": {
code: `const a = 1;`,
output: `var a = 1;`,
},
"transforms let to var": {
code: `let b = 2;`,
output: `var b = 2;`,
},
},
});
// String-only tests (for snapshot testing)
pluginTester({
plugin: myPlugin,
tests: [
`const a = 1;`,
`let b = 2;`,
`var c = 3;`,
],
});
// Mixed configuration
pluginTester({
plugin: myPlugin,
tests: {
"simple transform": `const x = 1;`,
"complex transform": {
code: `
const fn = (a, b) => a + b;
`,
output: `
const fn = function(a, b) {
return a + b;
};
`,
},
"should be skipped": {
skip: true,
code: `const skip = true;`,
},
},
});Testing expected errors and exceptions.
/** Union type for different ways to specify expected errors */
type ErrorExpectation =
| boolean
| string
| RegExp
| Error
| Class<Error>
| ((error: unknown) => boolean);Usage Examples:
pluginTester({
plugin: myPlugin,
tests: [
// Expect any error
{
code: `invalid syntax here`,
throws: true,
},
// Expect specific error message
{
code: `const a = 1;`,
throws: "Cannot transform const declarations",
},
// Expect error matching regex
{
code: `const a = 1;`,
throws: /Cannot transform/,
},
// Expect specific error instance
{
code: `const a = 1;`,
throws: new SyntaxError("Unexpected token"),
},
// Expect error of specific type
{
code: `const a = 1;`,
throws: SyntaxError,
},
// Custom error validation
{
code: `const a = 1;`,
throws: (error) => {
return error instanceof SyntaxError &&
error.message.includes("const");
},
},
],
});Functions that run before and after tests for initialization and cleanup.
type Promisable<T> = T | Promise<T>;
/** Function that runs before a test, optionally returning a teardown function */
type SetupFunction = () => Promisable<void> | Promisable<TeardownFunction>;
/** Function that runs after a test for cleanup */
type TeardownFunction = () => Promisable<void>;Usage Examples:
pluginTester({
plugin: myPlugin,
tests: [
{
setup: () => {
// Set up test environment
process.env.NODE_ENV = "test";
// Return teardown function
return () => {
delete process.env.NODE_ENV;
};
},
code: `const a = process.env.NODE_ENV;`,
output: `const a = "test";`,
},
{
setup: async () => {
await setupDatabase();
},
teardown: async () => {
await cleanupDatabase();
},
code: `const data = getFromDB();`,
output: `const data = mockData;`,
},
],
});Testing using external files for input and expected output.
interface FixtureOptions {
/** Babel options for fixture transformations */
babelOptions?: Babel.TransformOptions;
/** Plugin options for fixture transformations */
pluginOptions?: any;
/** Preset options for fixture transformations */
presetOptions?: any;
/** Expected output (overrides output fixture file) */
output?: string;
/** Expected error */
throws?: ErrorExpectation;
/** Run this fixture exclusively */
only?: boolean;
/** Skip this fixture */
skip?: boolean;
/** Setup function for this fixture */
setup?: SetupFunction;
/** Teardown function for this fixture */
teardown?: TeardownFunction;
/** Function to test raw Babel output */
outputRaw?: OutputTesterFunction;
/** Custom output filename for fixtures */
fixtureOutputName?: string;
/** Custom output file extension for fixtures */
fixtureOutputExt?: string;
/** Custom formatter for fixture output */
formatResult?: ResultFormatter;
/** Enable snapshot testing for fixtures */
snapshot?: boolean;
}Usage Examples:
// Fixture directory structure:
// __fixtures__/
// my-plugin/
// basic-transform/
// code.js
// output.js
// error-case/
// code.js
// options.json
pluginTester({
plugin: myPlugin,
fixtures: "__fixtures__/my-plugin",
});
// With fixture options
pluginTester({
plugin: myPlugin,
fixtures: "__fixtures__/my-plugin",
// Fixture options applied to all fixtures
setup: () => {
console.log("Setting up fixture test");
},
});Testing the raw Babel transformation result for advanced validation.
/** Function for testing raw Babel output */
type OutputTesterFunction = (output: Babel.BabelFileResult) => Promisable<void>;Usage Example:
pluginTester({
plugin: myPlugin,
tests: [
{
code: `const a = 1;`,
outputRaw: (output) => {
expect(output.code).toContain("var");
expect(output.map).toBeDefined();
expect(output.ast.body).toHaveLength(1);
},
},
],
});