Improve Babel recipe #1290

florianb · 2017-02-28T13:18:12Z

Fixes Document how to use babel-polyfill to polyfill the test environment #727 by describing usage of babel-polyfill

novemberborn

Thanks for working on this @florianb. Some comments below.

novemberborn · 2017-03-02T10:30:52Z

docs/recipes/babelrc.md

+{
+  "ava": {
+    "require": [
+      "babel-register",


This isn't necessary for babel-polyfill, so let's leave it out.

Absolutely, thanks!

Remove the polyfill-snippet

novemberborn · 2017-03-02T10:31:56Z

docs/recipes/babelrc.md

 }
 ```

+## Provide ES2015 Polyfills to your tests


Perhaps Polyfill tests? I'm trying to avoid ES2015 mentions since the standard is continuously evolving. AVA tries to support stage-4 syntax which means currently we're supporting more than ES2016, but not ES2017 since it isn't official yet.

Thank you @novemberborn - that's a absolute valid point. I will change that.

Remove ES2015-reference

novemberborn · 2017-03-02T10:41:06Z

docs/recipes/babelrc.md


+## Provide ES2015 Polyfills to your tests
+
+You might run into issues when relying on ES2015-features your current environment do not support. Since Ava isn't providing any polyfills per default you might want to enable them by adding `babel-polyfill` manually to the `require` section:


This is a good start. I think it could be clearer on what AVA does out of the box, and what kind of features end up being missing. There's also a big downside to using babel-polyfill, which is that it impacts how your program behaves (not just the tests!)

What do you think about this:

AVA lets you write tests using new JavaScript syntax, even on Node.js version that do not support it otherwise. However it doesn't add or modify built-ins. For example Array.prototype.includes() is not available in Node.js 4 even when you use AVA.

You can opt in to these features by loading Babel's Polyfill module. Note that this modifies the environment, which impacts how your program itself behaves.

You can load babel-polyfill by adding it to AVA's require options:

Thank you very much @novemberborn - i somehow assumed it could be wanted to write not too much. 🤔 I guess that assumption was just a bit stupid. 😄

Elaborate the description

@novemberborn I rewrote the description. I think it reads better now (even though my mother-tongue is German, so don't expect too much) but i have still a note on it:

The documentation should probably elaborate on the distinction between the execution environment of tests and the execution environment of the tested code. The current wording may leave that as a question to the beginner.

novemberborn

I rewrote the description. I think it reads better now (even though my mother-tongue is German, so don't expect too much)

No worries, English isn't my first language either. Writing is hard!

The documentation should probably elaborate on the distinction between the execution environment of tests and the execution environment of the tested code. The current wording may leave that as a question to the beginner.

The point is that there is no distinction. Whether it impacts your program depends on how it's written. You take on the responsibility of figuring that out when you use polyfills. That said, my intent was to say that your program, when it actually runs, without the polyfills present, may malfunction. We could indeed make that more explicit.

novemberborn · 2017-03-09T09:48:17Z

docs/recipes/babelrc.md

+## Use Babel Polyfills

-You might run into issues when relying on ES2015-features your current environment do not support. Since Ava isn't providing any polyfills per default you might want to enable them by adding `babel-polyfill` manually to the `require` section:
+AVA lets you write your tests using new JavaScript syntax, even on Node.js versions that otherwise wouldn't support it. However, it doesn't add or modify built-ins of your current environment. Using AVA would, for example, not provide modern features such as `Array.prototype.includes()` to an underlying NodeJ.js 4 environment.


There's a typo in NodeJ.js.

Sorry for that..

Fix typo

novemberborn · 2017-03-09T09:48:46Z

docs/recipes/babelrc.md

-You might run into issues when relying on ES2015-features your current environment do not support. Since Ava isn't providing any polyfills per default you might want to enable them by adding `babel-polyfill` manually to the `require` section:
+AVA lets you write your tests using new JavaScript syntax, even on Node.js versions that otherwise wouldn't support it. However, it doesn't add or modify built-ins of your current environment. Using AVA would, for example, not provide modern features such as `Array.prototype.includes()` to an underlying NodeJ.js 4 environment.
+
+By loading [Babel's Polyfill module](https://babeljs.io/docs/usage/polyfill/) you're able to opt these features in. Note that this will modify the environment, which may influence how your program itself behaves.


able to opt in to these features.

Let's get rid of itself in how your program itself behaves.

Remove itself

novemberborn · 2017-03-09T09:50:01Z

docs/recipes/babelrc.md

+
+By loading [Babel's Polyfill module](https://babeljs.io/docs/usage/polyfill/) you're able to opt these features in. Note that this will modify the environment, which may influence how your program itself behaves.
+
+You can enable `babel-polyfill` by adding it to AVA's require options:


Perhaps:

… require option:

(Marking require as code, and singular "option".)

make require-option more explicit

florianb · 2017-03-09T10:23:11Z

Thanks for your understanding. 😄

So what we would need to say is that the user must ensure he provides the same "polyfilled" environment for AVA as he does to the execution environment of his program (in the case he uses more features than defined in AVA's stage-4)?
In my opinion this is a more general topic and would better be pointed out at the beginning of the whole file, probably in addition to the default's transpiler behavior section?

novemberborn · 2017-03-10T10:05:15Z

So what we would need to say is that the user must ensure he provides the same "polyfilled" environment for AVA as he does to the execution environment of his program (in the case he uses more features than defined in AVA's stage-4)

Yes.

In my opinion this is a more general topic and would better be pointed out at the beginning of the whole file, probably in addition to the default's transpiler behavior section?

AVA's test transpilation doesn't impact the user's program. I agree it's a general topic which is why I was trying to get away with just hinting at it.

florianb · 2017-03-10T11:16:18Z

Okay, i guess i'd like to try to clarify this a bit more on the default's transpiler behavior section. If you don't mind, of course. 😄

novemberborn · 2017-03-10T12:40:34Z

@florianb by all means.

florianb · 2017-03-27T09:54:10Z

Okay @novemberborn, i hope i could make the description of the default transpilation behavior a little bit more clear. I tried to become a little bit more explicit, even though i am not sure i got the meaning of

This is a great option for small modules where you do not desire a build step to transpile your source before deploying to npm

I think that former sentence implies that AVA allows you using ES-features even in projects you otherwise don't do any transpilation.

novemberborn

Thanks for getting back to this. I think we're getting there!

I think that former sentence implies that AVA allows you using ES-features even in projects you otherwise don't do any transpilation.

Yes.

novemberborn · 2017-04-01T13:39:21Z

docs/recipes/babelrc.md

+
+AVA lets you write your tests using new JavaScript syntax, even on Node.js versions that otherwise wouldn't support it. However, it doesn't add or modify built-ins of your current environment. Using AVA would, for example, not provide modern features such as `Array.prototype.includes()` to an underlying Node.js 4 environment.
+
+By loading [Babel's Polyfill module](https://babeljs.io/docs/usage/polyfill/) you're able to opt these features in. Note that this will modify the environment, which may influence how your program behaves.


By loading Babel's Polyfill module you can opt in to these features. …

Thanks! 😄

fix style

novemberborn · 2017-04-01T13:45:24Z

docs/recipes/babelrc.md

 ## AVA's default transpiler behavior

-By default, AVA transpiles your tests and helper files using the [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) Babel preset. This is a great option for small modules where you do not desire a build step to transpile your source before deploying to `npm`.
+AVA by default provides some nifty ECMAScript features, like [`async`](https://github.com/avajs/ava#async-function-support), to your test-environment. To make this possible AVA transpiles the tests and helper files using the [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) Babel preset.


Let's just call it JavaScript.

How about:

AVA lets you use some nifty JavaScript features in your tests, like async functions. To make this work on older Node.js versions AVA transpiles the tests and helper files using the @ava/stage-4 Babel preset. This is great for projects where you don't otherwise use Babel for your source, but do want to use the newest JavaScript features in your tests.

I am somehow torn between using JS over ECMAScript for these reasons:

JavaScript sounds just slight and handy

This paragraph is about the differences between good old vanilla JS and the new (not backward compatible) language features introduced by ES.

I think this topic is read by people who already know the term "ECMAScript" and i think in this case it supports understanding (and avoids confusion for less experienced programmers ["Isn't that feature an ES-feature?"]).

But i am really not insisting on that - so if you'd prefer using JS, i am fine with that.

Our main page talks about JavaScript, so I don't see why we should start using a different term here.

Okay - i just thought about the use of "ES2017" to explicitly spot on ES-features.

But as i said, i'm not insisting on it.

Replace ES by JS

novemberborn · 2017-04-03T12:21:02Z

docs/recipes/babelrc.md

+
+AVA lets you write your tests using new JavaScript syntax, even on Node.js versions that otherwise wouldn't support it. However, it doesn't add or modify built-ins of your current environment. Using AVA would, for example, not provide modern features such as `Array.prototype.includes()` to an underlying Node.js 4 environment.
+
+By loading [Babel's Polyfill module](https://babeljs.io/docs/usage/polyfill/) you can opt in to these features in. Note that this will modify the environment, which may influence how your program behaves.


Remove the "in" after "features".

novemberborn · 2017-04-03T12:23:57Z

docs/recipes/babelrc.md

-By default, AVA transpiles your tests and helper files using the [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) Babel preset. This is a great option for small modules where you do not desire a build step to transpile your source before deploying to `npm`.
+AVA by default provides some nifty JavaScript features, like [`async`](https://github.com/avajs/ava#async-function-support), to your test-environment. To make this possible AVA transpiles the tests and helper files using the [`@ava/stage-4`](https://github.com/avajs/babel-preset-stage-4) Babel preset.
+
+This is a great feature for projects where you desire to not transpile your source before deploying but enjoy using ECMAScript for writing tests.


Thanks for changing this to JavaScript (though it says ECMAScript in the second paragraph). I still think this reads better though:

AVA lets you use some nifty JavaScript features in your tests, like async functions. To make this work on older Node.js versions AVA transpiles the tests and helper files using the @ava/stage-4 Babel preset. This is great for projects where you don't otherwise use Babel for your source, but do want to use the newest JavaScript features in your tests.

The latest Node.js version support most of ES2017, so it helps to explain why AVA still needs to do transpilation. I feel the sentences read a bit better as well.

You're right, it reads better. However, i rewrote "...where you don't otherwise use..." to be a little slighter, i hope you don't mind.

novemberborn · 2017-04-04T08:47:50Z

Thanks @florianb!

florianb · 2017-04-04T10:43:34Z

Your are welcome @novemberborn - thanks for your help!

Florian Breisch added 2 commits February 28, 2017 14:13

Draft fix for avajs#727 by describing usage of babel-polyfill

83a33df

Fix indentation

2803ec3

novemberborn requested changes Mar 2, 2017

View reviewed changes

sindresorhus changed the title ~~WIP: Improve Docs~~ WIP: Improve docs Mar 6, 2017

sindresorhus changed the title ~~WIP: Improve docs~~ WIP: Improve Babel recipe Mar 6, 2017

Remove ES2015 reference, elaborate description, remove babel-register

161b61e

novemberborn requested changes Mar 9, 2017

View reviewed changes

Fix Typo, reformat require option, strip "itself"

866476b

Draft new default transpilation behavior section

3dfa5f7

novemberborn requested changes Apr 1, 2017

View reviewed changes

Fix style, use JavaScript over ECMAScript

35c992c

novemberborn requested changes Apr 3, 2017

View reviewed changes

Rewrite the default transpiler behavior paragraph; Fix mistake

8da9894

novemberborn changed the title ~~WIP: Improve Babel recipe~~ WIP:Improve Babel recipe Apr 4, 2017

novemberborn changed the title ~~WIP:Improve Babel recipe~~ Improve Babel recipe Apr 4, 2017

novemberborn approved these changes Apr 4, 2017

View reviewed changes

novemberborn merged commit ecdadfa into avajs:master Apr 4, 2017

florianb deleted the improve-docs branch April 4, 2017 10:42


		## Provide ES2015 Polyfills to your tests

		You might run into issues when relying on ES2015-features your current environment do not support. Since Ava isn't providing any polyfills per default you might want to enable them by adding `babel-polyfill` manually to the `require` section:


		By loading [Babel's Polyfill module](https://babeljs.io/docs/usage/polyfill/) you're able to opt these features in. Note that this will modify the environment, which may influence how your program itself behaves.

		You can enable `babel-polyfill` by adding it to AVA's require options:


		AVA lets you write your tests using new JavaScript syntax, even on Node.js versions that otherwise wouldn't support it. However, it doesn't add or modify built-ins of your current environment. Using AVA would, for example, not provide modern features such as `Array.prototype.includes()` to an underlying Node.js 4 environment.

		By loading [Babel's Polyfill module](https://babeljs.io/docs/usage/polyfill/) you're able to opt these features in. Note that this will modify the environment, which may influence how your program behaves.

Improve Babel recipe #1290

Improve Babel recipe #1290

Uh oh!

Conversation

florianb commented Feb 28, 2017

Uh oh!

novemberborn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Mar 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Mar 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Mar 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Mar 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

novemberborn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Mar 9, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Mar 9, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Mar 9, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb commented Mar 9, 2017

Uh oh!

novemberborn commented Mar 10, 2017

Uh oh!

florianb commented Mar 10, 2017

Uh oh!

novemberborn commented Mar 10, 2017

Uh oh!

florianb commented Mar 27, 2017

Uh oh!

novemberborn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Apr 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florianb Apr 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

florianb Mar 8, 2017 •

edited

Loading

florianb Mar 8, 2017 •

edited

Loading

florianb Mar 8, 2017 •

edited

Loading

florianb Mar 8, 2017 •

edited

Loading

florianb Mar 9, 2017 •

edited

Loading

florianb Mar 9, 2017 •

edited

Loading

florianb Mar 9, 2017 •

edited

Loading

florianb Apr 3, 2017 •

edited

Loading

florianb Apr 3, 2017 •

edited

Loading