Commit 3746eee
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 6cadc71 commit 3746eee
1 file changed
Lines changed: 55 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -209,6 +209,35 @@ const assert = require('assert'); | |||
| 209 | 209 | const freelist = require('internal/freelist'); | |
| 210 | 210 | ``` | |
| 211 | 211 | ||
| 212 | + ### Assertions | ||
| 213 | + | ||
| 214 | + When writing assertions, prefer the strict versions: | ||
| 215 | + | ||
| 216 | + * `assert.strictEqual()` over `assert.equal()` | ||
| 217 | + * `assert.deepStrictEqual()` over `assert.deepEqual()` | ||
| 218 | + | ||
| 219 | + When using `assert.throws()`, if possible, provide the full error message: | ||
| 220 | + | ||
| 221 | + ```js | ||
| 222 | + assert.throws( | ||
| 223 | + () => { | ||
| 224 | + throw new Error('Wrong value'); | ||
| 225 | + }, | ||
| 226 | + /^Error: Wrong value$/ // Instead of something like /Wrong value/ | ||
| 227 | + ); | ||
| 228 | + ``` | ||
| 229 | + | ||
| 230 | + ### ES.Next features | ||
| 231 | + | ||
| 232 | + For performance considerations, we only use a selected subset of ES.Next | ||
| 233 | + features in JavaScript code in the `lib` directory. However, when writing | ||
| 234 | + tests, it is encouraged to use ES.Next features that have already landed | ||
| 235 | + in the ECMAScript specification. For example: | ||
| 236 | + | ||
| 237 | + * `let` and `const` over `var` | ||
| 238 | + * Template literals over string concatenation | ||
| 239 | + * Arrow functions when appropriate | ||
| 240 | + | ||
| 212 | 241 | ## Naming Test Files | |
| 213 | 242 | ||
| 214 | 243 | 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 | |||
| 220 | 249 | named `test-process-before-exit.js`. If the test specifically checked that arrow | |
| 221 | 250 | functions worked correctly with the `beforeExit` event, then it might be named | |
| 222 | 251 | `test-process-before-exit-arrow-functions.js`. | |
| 252 | + | ||
| 253 | + ## Imported Tests | ||
| 254 | + | ||
| 255 | + ### Web Platform Tests | ||
| 256 | + | ||
| 257 | + Some of the tests for the WHATWG URL implementation (named | ||
| 258 | + `test-whatwg-url-*.js`) are imported from the | ||
| 259 | + [Web Platform Tests Project](https://github.com/w3c/web-platform-tests/tree/master/url). | ||
| 260 | + These imported tests will be wrapped like this: | ||
| 261 | + | ||
| 262 | + ```js | ||
| 263 | + /* eslint-disable */ | ||
| 264 | + /* WPT Refs: | ||
| 265 | + https://github.com/w3c/web-platform-tests/blob/8791bed/url/urlsearchparams-stringifier.html | ||
| 266 | + License: http://www.w3.org/Consortium/Legal/2008/04-testsuite-copyright.html | ||
| 267 | + */ | ||
| 268 | + | ||
| 269 | + // Test code | ||
| 270 | + | ||
| 271 | + /* eslint-enable */ | ||
| 272 | + ``` | ||
| 273 | + | ||
| 274 | + If you want to improve tests that have been imported this way, please send | ||
| 275 | + a PR to the upstream project first. When your proposed change is merged in | ||
| 276 | + the upstream project, send another PR here to update Node.js accordingly. | ||
| 277 | + Be sure to update the hash in the URL following `WPT Refs:`. | ||
0 commit comments