jscodeshift に付随するテストツールである defineTest の規則を調べてみた

## Unit Testing

jscodeshift comes with a simple utility to allow easy unit testing with Jest, without having to write a lot of boilerplate code. This utility makes some assumptions in order to reduce the amount of configuration required:

- The test is located in a subdirectory under the directory the transform itself is located in (eg. \_\_tests\_\_)
- Test fixtures are located in a \_\_testfixtures\_\_ directory

This results in a directory structure like this:

/MyTransform.js
/\_\_tests\_\_/MyTransform-test.js
/\_\_testfixtures\_\_/MyTransform.input.js
/\_\_testfixtures\_\_/MyTransform.output.js
A simple example of unit tests is bundled in the sample directory.

The testUtils module exposes a number of useful helpers for unit testing.

#### `defineTest`

Defines a Jest/Jasmine test for a jscodeshift transform which depends on fixtures

jest.autoMockOff();
const defineTest = require("jscodeshift/dist/testUtils").defineTest;
defineTest(\_\_dirname, "MyTransform");

An alternate fixture filename can be provided as the fourth argument to `defineTest`.
This also means that multiple test fixtures can be provided:

defineTest(\_\_dirname, "MyTransform", null, "FirstFixture");
defineTest(\_\_dirname, "MyTransform", null, "SecondFixture");

This will run two tests:

- `__testfixtures__/FirstFixture.input.js`
- `__testfixtures__/SecondFixture.input.js`

/**
 * Handles some boilerplate around defining a simple jest/Jasmine test for a
 * jscodeshift transform.
 */
function defineTest(
  dirName,
  transformName,
  options,
  testFilePrefix,
  testOptions
) {
  const testName = testFilePrefix
    ? `transforms correctly using "${testFilePrefix}" data`
    : "transforms correctly";
  describe(transformName, () => {
    it(testName, () => {
      runTest(dirName, transformName, options, testFilePrefix, testOptions);
    });
  });
}

// vitest.config.ts

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
  },
});

/**
 * Utility function to run a jscodeshift script within a unit test. This makes
 * several assumptions about the environment:
 *
 * - `dirName` contains the name of the directory the test is located in. This
 *   should normally be passed via __dirname.
 * - The test should be located in a subdirectory next to the transform itself.
 *   Commonly tests are located in a directory called __tests__.
 * - `transformName` contains the filename of the transform being tested,
 *   excluding the .js extension.
 * - `testFilePrefix` optionally contains the name of the file with the test
 *   data. If not specified, it defaults to the same value as `transformName`.
 *   This will be suffixed with ".input.js" for the input file and ".output.js"
 *   for the expected output. For example, if set to "foo", we will read the
 *   "foo.input.js" file, pass this to the transform, and expect its output to
 *   be equal to the contents of "foo.output.js".
 * - Test data should be located in a directory called __testfixtures__
 *   alongside the transform and __tests__ directory.
 */
function runTest(
  dirName,
  transformName,
  options,
  testFilePrefix,
  testOptions = {}
) {
  if (!testFilePrefix) {
    testFilePrefix = transformName;
  }

  const extension = extensionForParser(testOptions.parser);
  const fixtureDir = path.join(dirName, "..", "__testfixtures__");
  const inputPath = path.join(
    fixtureDir,
    testFilePrefix + `.input.${extension}`
  );
  const source = fs.readFileSync(inputPath, "utf8");
  const expectedOutput = fs.readFileSync(
    path.join(fixtureDir, testFilePrefix + `.output.${extension}`),
    "utf8"
  );
  // Assumes transform is one level up from __tests__ directory
  const module = require(path.join(dirName, "..", transformName));
  runInlineTest(
    module,
    options,
    {
      path: inputPath,
      source,
    },
    expectedOutput,
    testOptions
  );
}

const extension = extensionForParser(testOptions.parser);

function extensionForParser(parser) {
  switch (parser) {
    case "ts":
    case "tsx":
      return parser;
    default:
      return "js";
  }
}

const inputPath = path.join(fixtureDir, testFilePrefix + `.input.${extension}`);

const expectedOutput = fs.readFileSync(
  path.join(fixtureDir, testFilePrefix + `.output.${extension}`),
  "utf8"
);

// Assumes transform is one level up from __tests__ directory
const module = require(path.join(dirName, "..", transformName));

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    include: ["src/__tests__/**/*.ts", "**/*.test.ts"],
  },
});

function runInlineTest(module, options, input, expectedOutput, testOptions) {
  const output = applyTransform(module, options, input, testOptions);
  expect(output).toEqual(expectedOutput.trim());
  return output;
}

function applyTransform(module, options, input, testOptions = {}) {
  // Handle ES6 modules using default export for the transform
  const transform = module.default ? module.default : module;

  // Jest resets the module registry after each test, so we need to always get
  // a fresh copy of jscodeshift on every test run.
  let jscodeshift = require("./core");
  if (testOptions.parser || module.parser) {
    jscodeshift = jscodeshift.withParser(testOptions.parser || module.parser);
  }

  const output = transform(
    input,
    {
      jscodeshift,
      j: jscodeshift,
      stats: () => {},
    },
    options || {}
  );

  return (output || "").trim();
}