Introduce jest snapshot testing utils (fixes #135)

README.md

@@ -363,33 +363,76 @@ 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
 /__testfixtures__/MyTransform.input.js
 /__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

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;