Commit 2b6ee39
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 <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>1 parent aae768c commit 2b6ee39
1 file changed
Lines changed: 55 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -189,6 +189,35 @@ const assert = require('assert'); | |||
| 189 | 189 | const freelist = require('internal/freelist'); | |
| 190 | 190 | ``` | |
| 191 | 191 | ||
| 192 | + ### Assertions | ||
| 193 | + | ||
| 194 | + When writing assertions, prefer the strict versions: | ||
| 195 | + | ||
| 196 | + * `assert.strictEqual()` over `assert.equal()` | ||
| 197 | + * `assert.deepStrictEqual()` over `assert.deepEqual()` | ||
| 198 | + | ||
| 199 | + When using `assert.throws()`, if possible, provide the full error message: | ||
| 200 | + | ||
| 201 | + ```js | ||
| 202 | + assert.throws( | ||
| 203 | + () => { | ||
| 204 | + throw new Error('Wrong value'); | ||
| 205 | + }, | ||
| 206 | + /^Error: Wrong value$/ // Instead of something like /Wrong value/ | ||
| 207 | + ); | ||
| 208 | + ``` | ||
| 209 | + | ||
| 210 | + ### ES.Next features | ||
| 211 | + | ||
| 212 | + For performance considerations, we only use a selected subset of ES.Next | ||
| 213 | + features in JavaScript code in the `lib` directory. However, when writing | ||
| 214 | + tests, it is encouraged to use ES.Next features that have already landed | ||
| 215 | + in the ECMAScript specification. For example: | ||
| 216 | + | ||
| 217 | + * `let` and `const` over `var` | ||
| 218 | + * Template literals over string concatenation | ||
| 219 | + * Arrow functions when appropriate | ||
| 220 | + | ||
| 192 | 221 | ## Naming Test Files | |
| 193 | 222 | ||
| 194 | 223 | Test files are named using kebab casing. The first component of the name is | |
@@ -200,3 +229,29 @@ For example, a test for the `beforeExit` event on the `process` object might be | |||
| 200 | 229 | named `test-process-before-exit.js`. If the test specifically checked that arrow | |
| 201 | 230 | functions worked correctly with the `beforeExit` event, then it might be named | |
| 202 | 231 | `test-process-before-exit-arrow-functions.js`. | |
| 232 | + | ||
| 233 | + ## Imported Tests | ||
| 234 | + | ||
| 235 | + ### Web Platform Tests | ||
| 236 | + | ||
| 237 | + Some of the tests for the WHATWG URL implementation (named | ||
| 238 | + `test-whatwg-url-*.js`) are imported from the | ||
| 239 | + [Web Platform Tests Project](https://github.com/w3c/web-platform-tests/tree/master/url). | ||
| 240 | + These imported tests will be wrapped like this: | ||
| 241 | + | ||
| 242 | + ```js | ||
| 243 | + /* eslint-disable */ | ||
| 244 | + /* WPT Refs: | ||
| 245 | + https://github.com/w3c/web-platform-tests/blob/8791bed/url/urlsearchparams-stringifier.html | ||
| 246 | + License: http://www.w3.org/Consortium/Legal/2008/04-testsuite-copyright.html | ||
| 247 | + */ | ||
| 248 | + | ||
| 249 | + // Test code | ||
| 250 | + | ||
| 251 | + /* eslint-enable */ | ||
| 252 | + ``` | ||
| 253 | + | ||
| 254 | + If you want to improve tests that have been imported this way, please send | ||
| 255 | + a PR to the upstream project first. When your proposed change is merged in | ||
| 256 | + the upstream project, send another PR here to update Node.js accordingly. | ||
| 257 | + Be sure to update the hash in the URL following `WPT Refs:`. | ||
0 commit comments