From 3ce763fff492085c02b13eeecaaeb23665d818be Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Sat, 4 Feb 2017 02:14:32 +0800
Subject: [PATCH] doc: improve testing guide

Add guide on choice of assertions, use of ES.Next features,
and the WPT upstream.

PR-URL: https://github.com/nodejs/node/pull/11150
Ref: https://github.com/nodejs/node/pull/11142
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
---
 doc/guides/writing-tests.md | 55 +++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

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:`.