Merge pull request #3328 from babel/tests-docs

Docs: update CONTRIBUTING to include some information on how tests wo…

CONTRIBUTING.md

@@ -80,9 +80,52 @@ $ make test-cov
 
 #### Writing tests
 
-When writing tests in `babylon`, you can easily generate an `expected.json` automatically by just providing the `actual.js` and running `make test-only` like normal.
+Most packages in [`/packages`](/packages) have a `test` folder.
+Some tests might be in different packages or in [`/packages/babel-core`](/packages/babel-core/test/fixtures).
+
+##### `babel-plugin-x`
+
+All the babel plugins (and other packages) that have a `/test/fixtures` are written in a similar way.
+
+For example in [`babel-plugin-transform-exponentiation-operator/test`](/packages/babel-plugin-transform-exponentiation-operator/test)
+
+- There is an `index.js` file. It imports our [test helper](/packages/babel-helper-plugin-test-runner). (You don't have to worry about this).
+- There can be multiple folders under [`/fixtures`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures)
+   - There is an [`options.json`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/options.json) is basically a `.babelrc` file to pass in the plugins and setttings you need for your tests.
+   - For this test, we only need the relevant plugin, so it's just `{ "plugins": ["transform-exponentiation-operator"] }`.
+   - If necessary, you can specify a different `options.json` for each sub folder if you need different options.
+
+- In each sub-folder, you can actually write out your different categories of tests. (You can name this by the feature you are testing, or you can reference the issue number)
+- There are mainly two kinds of tests for plugins.
+   - One is a simple test of input/output by Babel. We do this by creating an [`actual.js`](packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/binary/actual.js) (the code before transformation) and [`expected.js`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/binary/expected.js).
+   - The other type is a test to actually evaluate code an assert certain properties are true or not (this is usually better). We do this by creating an [`exec.js`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/comprehensive/exec.js).
+
+In an actual/expected test, you simply write out the code you want transformed in `actual.js`.
 
 ```js
+// actual.js
+2 ** 2;
+```
+
+and the expected output after transforming it with your `options.json` in `expected.js`.
+
+```js
+// expected.js
+Math.pow(2, 2);
+```
+In an `exec.js` test, we might want to actually run/check the code does what it's supposed to do rather than just check output.
+
+```js
+// exec.js
+assert.equal(8, 2 ** 3);
+assert.equal(24, 3 * 2 ** 3);
+```
+   
+##### `babylon`
+
+For `babylon` specifically, you can easily generate an `expected.json` automatically by just providing the `actual.js` and running `make test-only` like normal.
+
+```
 // Example
 - babylon
   - test
@@ -94,7 +137,6 @@ When writing tests in `babylon`, you can easily generate an `expected.json` auto
             - expected.json (will be generated if not created)
 ```
 
-
 #### Internals
 
 Please see [`/doc`](/doc) for internals documentation relevant to developing babel.