diff --git a/README.md b/README.md index 49acd539..13b92d4a 100644 --- a/README.md +++ b/README.md @@ -363,6 +363,7 @@ jscodeshift comes with a simple utility to allow easy unit testing with [Jest](h - Test fixtures are located in a `__testfixtures__` directory This results in a directory structure like this: + ``` /MyTransform.js /__tests__/MyTransform-test.js @@ -370,26 +371,68 @@ This results in a directory structure like this: /__testfixtures__/MyTransform.output.js ``` -To define a test, use `defineTest` or `defineInlineTest` from the `testUtils` module. A simple example is bundled in the [sample directory](sample). +A simple example of unit tests is bundled in the [sample directory](sample). + +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 + ```js 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: +An alternate fixture filename can be provided as the fourth argument to `defineTest`. +This also means that multiple test fixtures can be provided: + ```js defineTest(__dirname, 'MyTransform', null, 'FirstFixture'); defineTest(__dirname, 'MyTransform', null, 'SecondFixture'); ``` -This will run two tests: One for `__testfixtures__/FirstFixture.input.js` and one for `__testfixtures__/SecondFixture.input.js` + +This will run two tests: +- `__testfixtures__/FirstFixture.input.js` +- `__testfixtures__/SecondFixture.input.js` #### `defineInlineTest` + +Defines a Jest/Jasmine test suite for a jscodeshift transform which accepts inline values + +This is a more flexible alternative to `defineTest`, as this allows to also provide options to your transform + +```js +const defineInlineTest = require('jscodeshift/dist/testUtils').defineInlineTest; +const transform = require('../myTransform'); +const transformOptions = {}; +defineInlineTest(transform, transformOptions, 'input', 'expected output', 'test name (optional)'); +``` + +#### `defineSnapshotTest` + +Similar to `defineInlineTest` but instead of requiring an output value, it uses Jest's `toMatchSnapshot()` + +```js +const defineSnapshotTest = require('jscodeshift/dist/testUtils').defineSnapshotTest; +const transform = require('../myTransform'); +const transformOptions = {}; +defineSnapshotTest(transform, transformOptions, 'input', 'test name (optional)'); +``` + +For more information on snapshots, check out [Jest's docs](https://jestjs.io/docs/en/snapshot-testing) + +#### `applyTransform` + +Executes your transform using the options and the input given and returns the result. +This function is used internally by the other helpers, but it can prove useful in other cases. + ```js +const applyTransform = require('jscodeshift/dist/testUtils').applyTransform; const transform = require('../myTransform'); -defineInlineTest(transform, {}, 'input', 'expected output', 'test name (optional)'); +const transformOptions = {}; +const output = applyTransform(transform, transformOptions, 'input'); ``` ### Example Codemods diff --git a/src/testUtils.js b/src/testUtils.js index 5fe24c42..3abee393 100644 --- a/src/testUtils.js +++ b/src/testUtils.js @@ -14,7 +14,7 @@ const fs = require('fs'); const path = require('path'); -function runInlineTest(module, options, input, expectedOutput) { +function applyTransform(module, options, input) { // Handle ES6 modules using default export for the transform const transform = module.default ? module.default : module; @@ -33,7 +33,22 @@ function runInlineTest(module, options, input, expectedOutput) { }, options || {} ); - expect((output || '').trim()).toEqual(expectedOutput.trim()); + + return (output || '').trim(); +} +exports.applyTransform = applyTransform; + +function runSnapshotTest(module, options, input) { + const output = applyTransform(module, options, input); + expect(output).toMatchSnapshot(); + return output; +} +exports.runSnapshotTest = runSnapshotTest; + +function runInlineTest(module, options, input, expectedOutput) { + const output = applyTransform(module, options, input); + expect(output).toEqual(expectedOutput.trim()); + return output; } exports.runInlineTest = runInlineTest; @@ -101,3 +116,12 @@ function defineInlineTest(module, options, input, expectedOutput, testName) { }); } exports.defineInlineTest = defineInlineTest; + +function defineSnapshotTest(module, options, input, testName) { + it(testName || 'transforms correctly', () => { + runSnapshotTest(module, options, { + source: input + }); + }); +} +exports.defineSnapshotTest = defineSnapshotTest;