feat: allow testing entire babel transform result via outputRaw

Xunnamius · Xunnamius · commit e9d5aa1569dd · 2024-03-13T05:20:52.000-07:00
closes #186
diff --git a/README.md b/README.md
diff --git a/babel.config.js b/babel.config.js
@@ -54,7 +54,7 @@ module.exports = {
             modules: 'cjs',
             targets: NODE_LTS,
             useBuiltIns: 'usage',
-            corejs: '3.35',
+            corejs: '3.36',
             shippedProposals: true,
             exclude: ['proposal-dynamic-import']
           }
diff --git a/src/errors.ts b/src/errors.ts
@@ -67,7 +67,7 @@ export const ErrorMessage = {
   ExpectedErrorToMatchRegExp: (resultString: string, expectedError: RegExp) =>
     `expected "${resultString}" to match ${expectedError}`,
   BabelOutputTypeIsNotString: (rawBabelOutput: unknown) =>
-    `unexpected babel output type "${typeof rawBabelOutput}" (expected string)`,
+    `unexpected babel output of type "${typeof rawBabelOutput}" (expected 'code' property to be of type "string")`,
   BabelOutputUnexpectedlyEmpty: () =>
     'attempted to execute babel output but it was empty. An empty string cannot be evaluated',
   AttemptedToSnapshotUnmodifiedBabelOutput: () =>
@@ -107,6 +107,8 @@ export const ErrorMessage = {
       ? 'neither `output` nor `outputFixture` can be provided with `throws` or `error`'
       : 'a fixture cannot be provided with `throws` or `error` and also contain an output file';
   },
+  InvalidHasThrowsAndOutputRaw: () =>
+    '`outputRaw` cannot be provided with `throws` or `error`',
   InvalidHasThrowsAndExec: (
     testConfig: Pick<MaybePluginTesterTestConfig, typeof $type>
   ) => {
diff --git a/src/plugin-tester.ts b/src/plugin-tester.ts
@@ -726,6 +726,7 @@ function pluginTester(options: PluginTesterOptions = {}) {
             setup,
             teardown,
             formatResult,
+            outputRaw,
             fixtureOutputName,
             fixtureOutputExt
           } = localOptions;
@@ -799,6 +800,7 @@ function pluginTester(options: PluginTesterOptions = {}) {
               code,
               codeFixture: codePath,
               output,
+              outputRaw,
               outputFixture: outputPath,
               exec,
               execFixture: execPath
@@ -868,13 +870,14 @@ function pluginTester(options: PluginTesterOptions = {}) {
         teardown,
         formatResult,
         snapshot,
-        code: rawCode,
-        output: rawOutput,
-        exec: rawExec,
+        code: originalCode,
+        output: originalOutput,
+        outputRaw,
+        exec: originalExec,
         fixture,
-        codeFixture: rawCodeFixture,
+        codeFixture: originalCodeFixture,
         outputFixture,
-        execFixture: rawExecFixture
+        execFixture: originalExecFixture
       } = mergeWith(
         {
           setup: noop,
@@ -886,19 +889,23 @@ function pluginTester(options: PluginTesterOptions = {}) {
 
       const codeFixture = getAbsolutePathUsingFilepathDirname(
         filepath,
-        rawCodeFixture ?? fixture
+        originalCodeFixture ?? fixture
       );
 
-      const execFixture = getAbsolutePathUsingFilepathDirname(filepath, rawExecFixture);
+      const execFixture = getAbsolutePathUsingFilepathDirname(
+        filepath,
+        originalExecFixture
+      );
 
-      const code = rawCode !== undefined ? stripIndent(rawCode) : readCode(codeFixture);
+      const code =
+        originalCode !== undefined ? stripIndent(originalCode) : readCode(codeFixture);
 
       const output =
-        rawOutput !== undefined
-          ? stripIndent(rawOutput)
+        originalOutput !== undefined
+          ? stripIndent(originalOutput)
           : readCode(filepath, outputFixture);
 
-      const exec = rawExec ?? readCode(execFixture);
+      const exec = originalExec ?? readCode(execFixture);
 
       const testConfig: MaybePluginTesterTestObjectConfig = mergeWith(
         { [$type]: 'test-object' } as const,
@@ -945,6 +952,7 @@ function pluginTester(options: PluginTesterOptions = {}) {
             output !== undefined
               ? trimAndFixLineEndings(output, endOfLine, code)
               : undefined,
+          outputRaw,
           outputFixture,
           exec,
           execFixture:
@@ -973,9 +981,9 @@ function pluginTester(options: PluginTesterOptions = {}) {
       verbose3('finalized test object: %O', testConfig);
 
       validateTestConfig(testConfig, {
-        hasCodeAndCodeFixture: !!(rawCode && codeFixture),
-        hasOutputAndOutputFixture: !!(rawOutput && outputFixture),
-        hasExecAndExecFixture: !!(rawExec && execFixture)
+        hasCodeAndCodeFixture: !!(originalCode && codeFixture),
+        hasOutputAndOutputFixture: !!(originalOutput && outputFixture),
+        hasExecAndExecFixture: !!(originalExec && execFixture)
       });
 
       hasTests = true;
@@ -1124,6 +1132,7 @@ function pluginTester(options: PluginTesterOptions = {}) {
       code,
       codeFixture,
       output,
+      outputRaw,
       outputFixture,
       exec,
       execFixture
@@ -1141,7 +1150,7 @@ function pluginTester(options: PluginTesterOptions = {}) {
           `calling babel transform function (${transformer.name}) with parameters: %O`,
           parameters
         );
-        return (await transformer(...parameters))?.code;
+        return await transformer(...parameters);
       } catch (error) {
         verbose2(`babel transformation failed with error: ${error}`);
         if (expectedError) {
@@ -1188,18 +1197,37 @@ function pluginTester(options: PluginTesterOptions = {}) {
             );
           } // ? Else condition is handled by the typeof === 'function' branch
         }
-      } else if (typeof rawBabelOutput !== 'string') {
-        throw new TypeError(ErrorMessage.BabelOutputTypeIsNotString(rawBabelOutput));
       } else {
         debug2('expecting babel transform function to succeed');
+
+        // ? Since expectedError is not truthy, we know that rawBabelOutput must
+        // ? be the return type of the babel transformer function
+        const isRawBabelOutput = !!rawBabelOutput && typeof rawBabelOutput === 'object';
+        const hasRawBabelOutputCode = isRawBabelOutput && 'code' in rawBabelOutput;
+
+        if (isRawBabelOutput && outputRaw) {
+          debug2('executing provided outputRaw function before final comparison');
+          await outputRaw(rawBabelOutput);
+        }
+
+        if (!hasRawBabelOutputCode || typeof rawBabelOutput.code !== 'string') {
+          throw new TypeError(
+            ErrorMessage.BabelOutputTypeIsNotString(
+              hasRawBabelOutputCode ? rawBabelOutput.code : rawBabelOutput
+            )
+          );
+        }
+
+        debug2('performing final comparison');
+
         const formatResultFilepath = codeFixture || execFixture || filepath;
 
         // ? We split rawBabelOutput and result into two steps to ensure
         // ? exceptions thrown by trimAndFixLineEndings and formatResult are not
         // ? erroneously captured when we only really care about errors thrown by
         // ? babel
         const result = trimAndFixLineEndings(
-          await formatResult(rawBabelOutput || '', {
+          await formatResult(rawBabelOutput.code || '', {
             cwd: formatResultFilepath ? path.dirname(formatResultFilepath) : undefined,
             filepath: formatResultFilepath,
             filename: formatResultFilepath
@@ -1294,7 +1322,8 @@ function pluginTester(options: PluginTesterOptions = {}) {
       exec,
       output,
       babelOptions,
-      expectedError
+      expectedError,
+      outputRaw
     } = testConfig;
 
     if (knownViolations) {
@@ -1348,6 +1377,10 @@ function pluginTester(options: PluginTesterOptions = {}) {
       throwTypeErrorWithDebugOutput(ErrorMessage.InvalidHasThrowsAndOutput(testConfig));
     }
 
+    if (outputRaw !== undefined && expectedError !== undefined) {
+      throwTypeErrorWithDebugOutput(ErrorMessage.InvalidHasThrowsAndOutputRaw());
+    }
+
     if (exec !== undefined && expectedError !== undefined) {
       throwTypeErrorWithDebugOutput(ErrorMessage.InvalidHasThrowsAndExec(testConfig));
     }
diff --git a/src/types.ts b/src/types.ts
@@ -43,6 +43,13 @@ export type SetupFunction = () => Promisable<void | TeardownFunction>;
  */
 export type TeardownFunction = () => Promisable<void>;
 
+/**
+ * The shape of an `outputRaw` test object or fixture option.
+ *
+ * @see https://npm.im/babel-plugin-tester#outputraw
+ */
+export type OutputTesterFunction = (output: Babel.BabelFileResult) => Promisable<void>;
+
 /**
  * Options passed as parameters to the `pluginTester` function.
  *
@@ -418,6 +425,18 @@ export interface FixtureOptions {
    * @see https://npm.im/babel-plugin-tester#formatResult-1
    */
   formatResult?: ResultFormatter;
+  /**
+   * This is a `fixtures` option similar in intent to `output.js` except it
+   * tests against the entire `BabelFileResult` object returned by babel's
+   * `transform` function instead of only the `code` property of
+   * `BabelFileResult`.
+   *
+   * As it requires a function value, this option must be used in `options.js`
+   * instead of `options.json`.
+   *
+   * @see https://npm.im/babel-plugin-tester#outputRaw
+   */
+  outputRaw?: OutputTesterFunction;
   /**
    * This is a `fixtures` option used to provide your own fixture output file
    * name. Defaults to `"output"`.
@@ -599,6 +618,15 @@ export interface TestObject {
    * @see https://npm.im/babel-plugin-tester#output
    */
   output?: string;
+  /**
+   * This is a `tests` object option similar in intent to the `output` option
+   * except it tests against the entire `BabelFileResult` object returned by
+   * babel's `transform` function instead of only the `code` property of
+   * `BabelFileResult`.
+   *
+   * @see https://npm.im/babel-plugin-tester#outputRaw-1
+   */
+  outputRaw?: OutputTesterFunction;
   /**
    * This is a `tests` object option that will be transformed just like the
    * `code` property, except the output will be _evaluated_ in the same context
@@ -768,6 +796,7 @@ type PluginTesterSharedTestConfigProperties = {
   only?: TestObject['only'] | FixtureOptions['only'];
   skip?: TestObject['skip'] | FixtureOptions['skip'];
   expectedError?: TestObject['throws'] | FixtureOptions['throws'];
+  outputRaw?: TestObject['outputRaw'] | FixtureOptions['outputRaw'];
   testSetup: NonNullable<PluginTesterOptions['setup']>;
   testTeardown: NonNullable<PluginTesterOptions['teardown']>;
   formatResult: NonNullable<PluginTesterOptions['formatResult']>;
diff --git a/test/fixtures/creates-output-file-outputRaw/fixture/code.js b/test/fixtures/creates-output-file-outputRaw/fixture/code.js
@@ -0,0 +1 @@
+console.log('hello');
diff --git a/test/fixtures/creates-output-file-outputRaw/fixture/options.js b/test/fixtures/creates-output-file-outputRaw/fixture/options.js
@@ -0,0 +1,3 @@
+module.exports = {
+  outputRaw: () => undefined
+};
diff --git a/test/fixtures/option-throws-and-outputRaw/fixture/code.js b/test/fixtures/option-throws-and-outputRaw/fixture/code.js
@@ -0,0 +1 @@
+console.log('hello');
diff --git a/test/fixtures/option-throws-and-outputRaw/fixture/options.js b/test/fixtures/option-throws-and-outputRaw/fixture/options.js
@@ -0,0 +1,4 @@
+module.exports = {
+  throws: true,
+  outputRaw: () => undefined
+};
diff --git a/test/fixtures/simple-outputRaw/fixture/code.js b/test/fixtures/simple-outputRaw/fixture/code.js
@@ -0,0 +1 @@
+const hello = 'hey';
diff --git a/test/fixtures/simple-outputRaw/fixture/options.js b/test/fixtures/simple-outputRaw/fixture/options.js
@@ -0,0 +1,5 @@
+module.exports = {
+  outputRaw: (output) => {
+    expect(output?.metadata).toStrictEqual({ seen: true });
+  }
+};
diff --git a/test/fixtures/simple-outputRaw/fixture/output.js b/test/fixtures/simple-outputRaw/fixture/output.js
@@ -0,0 +1 @@
+const hello = 'hey';
diff --git a/test/helpers/plugins.ts b/test/helpers/plugins.ts
@@ -17,6 +17,20 @@ export const deleteVariablesPlugin: () => PluginObj<State> = require('./plugin-d
  */
 export const addLinePlugin: () => PluginObj<State> = require('./plugin-add-line');
 
+/**
+ * Dummy plugin that mutates global metadata.
+ */
+export const metadataMutationPlugin: () => PluginObj<State> = () => {
+  return {
+    visitor: {
+      Identifier(_, state) {
+        // @ts-expect-error: we don't care
+        state.file.metadata.seen = true;
+      }
+    }
+  };
+};
+
 /**
  * When called, returns a no-op babel plugin that tracks invocation order.
  */
diff --git a/test/unit-plugin-tester.test.ts b/test/unit-plugin-tester.test.ts

Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ module.exports = {`
`54`	`54`	`modules: 'cjs',`
`55`	`55`	`targets: NODE_LTS,`
`56`	`56`	`useBuiltIns: 'usage',`
`57`		`- corejs: '3.35',`
	`57`	`+ corejs: '3.36',`
`58`	`58`	`shippedProposals: true,`
`59`	`59`	`exclude: ['proposal-dynamic-import']`
`60`	`60`	`}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+module.exports = {`
	`2`	`+ outputRaw: () => undefined`
	`3`	`+};`