Skip to content

Latest commit

 

History

History
159 lines (113 loc) · 5.79 KB

CONTRIBUTING.md

File metadata and controls

159 lines (113 loc) · 5.79 KB
Raw

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

Setup | Running tests | Writing tests | Internals

Contributing

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

Not sure where to start?

  • If you aren't just making a documentation change, you'll probably want to learn a bit about a few topics.
  • ASTs (Abstract Syntax Tree): Our current spec is a bit different from ESTree.
  • This repository's /doc directory for notes on Babel's internals
  • Check out the Babel Plugin Handbook - core plugins are written the same way as any other plugin!
  • Check out AST Explorer to learn more about ASTs or make your own plugin in the browser

If you're stuck, feel free to check out the #development channel on our slack.

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 and incrementally build files on change.

You can access the built files for individual packages from packages/<package-name>/lib.

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

$ make build-dist

Running tests

You can run tests for all packages via:

$ make test

To run tests for a specific package, you can use 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, however some tests might be in other 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 file whose function is similar to a .babelrc file, allowing you 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 have an options.json with different options in each subfolder.

  • In each subfolder, you can organize your directory structure by categories of tests. (Example: these folders can be named after the feature you are testing or can reference the issue number they fix)

  • Generally, there are two kinds of tests for plugins

    • The first is a simple test of the input and output produced by running Babel on some code. We do this by creating an actual.js file and an expected.js file.
    • If you need to expect an error, you can ignore creating the expected.js file and pass a new throws key to the options.json that contains the error string that is created.
    • The second and preferred type is a test that actually evaluates the produced code and asserts that certain properties are true or false. We do this by creating an exec.js file.

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 run or check that the code actually does what it's supposed to do rather than just check the static output.

// exec.js
assert.equal(8, 2 ** 3);
assert.equal(24, 3 * 2 ** 3);

If you need to check for an error that is thrown you can add to the options.json

// options.json example
{
  "plugins": [["transform-object-rest-spread", { "useBuiltIns": "invalidOption" }]],
  "throws": "transform-object-rest-spread currently only accepts a boolean option for useBuiltIns (defaults to false)"
}
babylon

For babylon specifically, you can easily generate an expected.json automatically by just providing the actual.js and running make test-only as you usually would.

// Example
- babylon
  - test
    - fixtures
      - comments
        - basic
          - block-trailing-comment
            - actual.js
            - expected.json (will be generated if not created)