diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index f27c076590e513..36cf04fc546825 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -209,6 +209,35 @@ const assert = require('assert'); const freelist = require('internal/freelist'); ``` +### Assertions + +When writing assertions, prefer the strict versions: + +* `assert.strictEqual()` over `assert.equal()` +* `assert.deepStrictEqual()` over `assert.deepEqual()` + +When using `assert.throws()`, if possible, provide the full error message: + +```js +assert.throws( + () => { + throw new Error('Wrong value'); + }, + /^Error: Wrong value$/ // Instead of something like /Wrong value/ +); +``` + +### ES.Next features + +For performance considerations, we only use a selected subset of ES.Next +features in JavaScript code in the `lib` directory. However, when writing +tests, it is encouraged to use ES.Next features that have already landed +in the ECMAScript specification. For example: + +* `let` and `const` over `var` +* Template literals over string concatenation +* Arrow functions when appropriate + ## Naming Test Files Test files are named using kebab casing. The first component of the name is @@ -220,3 +249,29 @@ For example, a test for the `beforeExit` event on the `process` object might be named `test-process-before-exit.js`. If the test specifically checked that arrow functions worked correctly with the `beforeExit` event, then it might be named `test-process-before-exit-arrow-functions.js`. + +## Imported Tests + +### Web Platform Tests + +Some of the tests for the WHATWG URL implementation (named +`test-whatwg-url-*.js`) are imported from the +[Web Platform Tests Project](https://github.com/w3c/web-platform-tests/tree/master/url). +These imported tests will be wrapped like this: + +```js +/* eslint-disable */ +/* WPT Refs: + https://github.com/w3c/web-platform-tests/blob/8791bed/url/urlsearchparams-stringifier.html + License: http://www.w3.org/Consortium/Legal/2008/04-testsuite-copyright.html +*/ + +// Test code + +/* eslint-enable */ +``` + +If you want to improve tests that have been imported this way, please send +a PR to the upstream project first. When your proposed change is merged in +the upstream project, send another PR here to update Node.js accordingly. +Be sure to update the hash in the URL following `WPT Refs:`.