babel/CONTRIBUTING.md

NOTE: DO NOT OPEN ISSUES FOR QUESTIONS AND SUPPORT. SEE THE README FOR MORE INFO.

---

Setup | Running tests | Internals

---

Contributing

Contributions are always welcome, no matter how large or small. Before contributing, please read the code of conduct.

Developing

Note: Versions < 5.1.10 can't be built. Make sure you are on npm 3.

Setup

$ git clone https://github.com/babel/babel
$ cd babel
$ make bootstrap

Then you can either run:

$ make build

to build Babel once or:

$ make watch

to have Babel build itself then incrementally build files on change.

If you wish to build a copy of Babel for distribution then run:

$ make build-dist

and access the files from packages/babel-core/dist.

Running tests

You can run tests for all packages via:

$ make test

This is mostly overkill and you can limit the package to a select by using the TEST_ONLY environment variable:

$ TEST_ONLY=babel-cli make test

Use the TEST_GREP variable to run a subset of tests by name:

$ TEST_GREP=transformation make test

To test the code coverage, use:

$ make test-cov

Writing tests

Most packages in /packages have a test folder. Some tests might be in different packages or in /packages/babel-core.

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

• There is an index.js file. It imports our test helper. (You don't have to worry about this).

• There can be multiple folders under /fixtures

  • There is an options.json is basically a .babelrc file to pass in the plugins and settings 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 (the code before transformation) and 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.

In an actual/expected test, you simply write out the code you want transformed in actual.js.

// actual.js
2 ** 2;

and the expected output after transforming it with your options.json in expected.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.

// 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
    - fixtures
      - comments
        - basic
          - block-trailing-comment
            - actual.js
            - expected.json (will be generated if not created)

Internals

Please see /doc for internals documentation relevant to developing babel.