doc: improve testing guide

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

PR-URL: #11150
Ref: #11142
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Santiago Gimeno <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Timothy Gu <[email protected]>

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