1<!DOCTYPE html> 2<html lang="en"> 3<head> 4 <meta charset="utf-8"> 5 <meta name="viewport" content="width=device-width"> 6 <meta name="nodejs.org:node-version" content="v18.18.2"> 7 <title>Test runner | Node.js v18.18.2 Documentation</title> 8 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 9 <link rel="stylesheet" href="assets/style.css"> 10 <link rel="stylesheet" href="assets/hljs.css"> 11 <link rel="canonical" href="https://nodejs.org/api/test.html"> 12 <script async defer src="assets/api.js" type="text/javascript"></script> 13 <style>@media(max-width:494px){.with-34-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:454px){.with-29-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:590px){.with-46-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:534px){.with-39-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:686px){.with-58-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:582px){.with-45-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:598px){.with-47-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}</style> 14</head> 15<body class="alt apidoc" id="api-section-test"> 16 <div id="content" class="clearfix"> 17 <div id="column2" class="interior"> 18 <div id="intro" class="interior"> 19 <a href="/" title="Go back to the home page"> 20 Node.js 21 </a> 22 </div> 23 <ul> 24<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 25<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 26</ul> 27<hr class="line"> 28<ul> 29<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 30<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 31<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 32<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 33<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 34<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 35<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 36<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 37<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 38<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 39<li><a href="console.html" class="nav-console">Console</a></li> 40<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 41<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 42<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 43<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 44<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 45<li><a href="dns.html" class="nav-dns">DNS</a></li> 46<li><a href="domain.html" class="nav-domain">Domain</a></li> 47<li><a href="errors.html" class="nav-errors">Errors</a></li> 48<li><a href="events.html" class="nav-events">Events</a></li> 49<li><a href="fs.html" class="nav-fs">File system</a></li> 50<li><a href="globals.html" class="nav-globals">Globals</a></li> 51<li><a href="http.html" class="nav-http">HTTP</a></li> 52<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 53<li><a href="https.html" class="nav-https">HTTPS</a></li> 54<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 55<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 56<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 57<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 58<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 59<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 60<li><a href="net.html" class="nav-net">Net</a></li> 61<li><a href="os.html" class="nav-os">OS</a></li> 62<li><a href="path.html" class="nav-path">Path</a></li> 63<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 64<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 65<li><a href="process.html" class="nav-process">Process</a></li> 66<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 67<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 68<li><a href="readline.html" class="nav-readline">Readline</a></li> 69<li><a href="repl.html" class="nav-repl">REPL</a></li> 70<li><a href="report.html" class="nav-report">Report</a></li> 71<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 72<li><a href="stream.html" class="nav-stream">Stream</a></li> 73<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 74<li><a href="test.html" class="nav-test active">Test runner</a></li> 75<li><a href="timers.html" class="nav-timers">Timers</a></li> 76<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 77<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 78<li><a href="tty.html" class="nav-tty">TTY</a></li> 79<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 80<li><a href="url.html" class="nav-url">URL</a></li> 81<li><a href="util.html" class="nav-util">Utilities</a></li> 82<li><a href="v8.html" class="nav-v8">V8</a></li> 83<li><a href="vm.html" class="nav-vm">VM</a></li> 84<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 85<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 86<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 87<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 88<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 89</ul> 90<hr class="line"> 91<ul> 92<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 93</ul> 94 </div> 95 96 <div id="column1" data-id="test" class="interior"> 97 <header class="header"> 98 <div class="header-container"> 99 <h1>Node.js v18.18.2 documentation</h1> 100 <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 101 <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 102 <path fill="none" d="M0 0h24v24H0z" /> 103 <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 104 <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 105 </svg> 106 <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 107 <path d="M0 0h24v24H0z" fill="none" /> 108 <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 109 </svg> 110 </button> 111 </div> 112 <div id="gtoc"> 113 <ul> 114 <li class="pinned-header">Node.js v18.18.2</li> 115 116 <li class="picker-header"> 117 <a href="#"> 118 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 119 Table of contents 120 </a> 121 122 <div class="picker"><div class="toc"><ul> 123<li><span class="stability_1"><a href="#test-runner">Test runner</a></span> 124<ul> 125<li><a href="#subtests">Subtests</a></li> 126<li><a href="#skipping-tests">Skipping tests</a></li> 127<li><a href="#describeit-syntax"><code>describe</code>/<code>it</code> syntax</a></li> 128<li><a href="#only-tests"><code>only</code> tests</a></li> 129<li><a href="#filtering-tests-by-name">Filtering tests by name</a></li> 130<li><a href="#extraneous-asynchronous-activity">Extraneous asynchronous activity</a></li> 131<li><span class="stability_1"><a href="#watch-mode">Watch mode</a></span></li> 132<li><a href="#running-tests-from-the-command-line">Running tests from the command line</a> 133<ul> 134<li><a href="#test-runner-execution-model">Test runner execution model</a></li> 135</ul> 136</li> 137<li><a href="#collecting-code-coverage">Collecting code coverage</a></li> 138<li><a href="#mocking">Mocking</a></li> 139<li><a href="#test-reporters">Test reporters</a> 140<ul> 141<li><a href="#custom-reporters">Custom reporters</a></li> 142<li><a href="#multiple-reporters">Multiple reporters</a></li> 143</ul> 144</li> 145<li><a href="#runoptions"><code>run([options])</code></a></li> 146<li><a href="#testname-options-fn"><code>test([name][, options][, fn])</code></a></li> 147<li><a href="#testskipname-options-fn"><code>test.skip([name][, options][, fn])</code></a></li> 148<li><a href="#testtodoname-options-fn"><code>test.todo([name][, options][, fn])</code></a></li> 149<li><a href="#testonlyname-options-fn"><code>test.only([name][, options][, fn])</code></a></li> 150<li><a href="#describename-options-fn"><code>describe([name][, options][, fn])</code></a></li> 151<li><a href="#describeskipname-options-fn"><code>describe.skip([name][, options][, fn])</code></a></li> 152<li><a href="#describetodoname-options-fn"><code>describe.todo([name][, options][, fn])</code></a></li> 153<li><a href="#describeonlyname-options-fn"><code>describe.only([name][, options][, fn])</code></a></li> 154<li><a href="#itname-options-fn"><code>it([name][, options][, fn])</code></a></li> 155<li><a href="#itskipname-options-fn"><code>it.skip([name][, options][, fn])</code></a></li> 156<li><a href="#ittodoname-options-fn"><code>it.todo([name][, options][, fn])</code></a></li> 157<li><a href="#itonlyname-options-fn"><code>it.only([name][, options][, fn])</code></a></li> 158<li><a href="#beforefn-options"><code>before([fn][, options])</code></a></li> 159<li><a href="#afterfn-options"><code>after([fn][, options])</code></a></li> 160<li><a href="#beforeeachfn-options"><code>beforeEach([fn][, options])</code></a></li> 161<li><a href="#aftereachfn-options"><code>afterEach([fn][, options])</code></a></li> 162<li><a href="#class-mockfunctioncontext">Class: <code>MockFunctionContext</code></a> 163<ul> 164<li><a href="#ctxcalls"><code>ctx.calls</code></a></li> 165<li><a href="#ctxcallcount"><code>ctx.callCount()</code></a></li> 166<li><a href="#ctxmockimplementationimplementation"><code>ctx.mockImplementation(implementation)</code></a></li> 167<li><a href="#ctxmockimplementationonceimplementation-oncall"><code>ctx.mockImplementationOnce(implementation[, onCall])</code></a></li> 168<li><a href="#ctxresetcalls"><code>ctx.resetCalls()</code></a></li> 169<li><a href="#ctxrestore"><code>ctx.restore()</code></a></li> 170</ul> 171</li> 172<li><a href="#class-mocktracker">Class: <code>MockTracker</code></a> 173<ul> 174<li><a href="#mockfnoriginal-implementation-options"><code>mock.fn([original[, implementation]][, options])</code></a></li> 175<li><a href="#mockgetterobject-methodname-implementation-options"><code>mock.getter(object, methodName[, implementation][, options])</code></a></li> 176<li><a href="#mockmethodobject-methodname-implementation-options"><code>mock.method(object, methodName[, implementation][, options])</code></a></li> 177<li><a href="#mockreset"><code>mock.reset()</code></a></li> 178<li><a href="#mockrestoreall"><code>mock.restoreAll()</code></a></li> 179<li><a href="#mocksetterobject-methodname-implementation-options"><code>mock.setter(object, methodName[, implementation][, options])</code></a></li> 180</ul> 181</li> 182<li><a href="#class-testsstream">Class: <code>TestsStream</code></a> 183<ul> 184<li><a href="#event-testcoverage">Event: <code>'test:coverage'</code></a></li> 185<li><a href="#event-testdequeue">Event: <code>'test:dequeue'</code></a></li> 186<li><a href="#event-testdiagnostic">Event: <code>'test:diagnostic'</code></a></li> 187<li><a href="#event-testenqueue">Event: <code>'test:enqueue'</code></a></li> 188<li><a href="#event-testfail">Event: <code>'test:fail'</code></a></li> 189<li><a href="#event-testpass">Event: <code>'test:pass'</code></a></li> 190<li><a href="#event-testplan">Event: <code>'test:plan'</code></a></li> 191<li><a href="#event-teststart">Event: <code>'test:start'</code></a></li> 192<li><a href="#event-teststderr">Event: <code>'test:stderr'</code></a></li> 193<li><a href="#event-teststdout">Event: <code>'test:stdout'</code></a></li> 194<li><a href="#event-testwatchdrained">Event: <code>'test:watch:drained'</code></a></li> 195</ul> 196</li> 197<li><a href="#class-testcontext">Class: <code>TestContext</code></a> 198<ul> 199<li><a href="#contextbeforefn-options"><code>context.before([fn][, options])</code></a></li> 200<li><a href="#contextbeforeeachfn-options"><code>context.beforeEach([fn][, options])</code></a></li> 201<li><a href="#contextafterfn-options"><code>context.after([fn][, options])</code></a></li> 202<li><a href="#contextaftereachfn-options"><code>context.afterEach([fn][, options])</code></a></li> 203<li><a href="#contextdiagnosticmessage"><code>context.diagnostic(message)</code></a></li> 204<li><a href="#contextname"><code>context.name</code></a></li> 205<li><a href="#contextrunonlyshouldrunonlytests"><code>context.runOnly(shouldRunOnlyTests)</code></a></li> 206<li><a href="#contextsignal"><code>context.signal</code></a></li> 207<li><a href="#contextskipmessage"><code>context.skip([message])</code></a></li> 208<li><a href="#contexttodomessage"><code>context.todo([message])</code></a></li> 209<li><a href="#contexttestname-options-fn"><code>context.test([name][, options][, fn])</code></a></li> 210</ul> 211</li> 212<li><a href="#class-suitecontext">Class: <code>SuiteContext</code></a> 213<ul> 214<li><a href="#contextname_1"><code>context.name</code></a></li> 215<li><a href="#contextsignal_1"><code>context.signal</code></a></li> 216</ul> 217</li> 218</ul> 219</li> 220</ul></div></div> 221 </li> 222 223 224 <li class="picker-header"> 225 <a href="#"> 226 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 227 Index 228 </a> 229 230 <div class="picker"><ul> 231<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 232<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 233 234 <li> 235 <a href="index.html">Index</a> 236 </li> 237 </ul> 238 239<hr class="line"> 240<ul> 241<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 242<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 243<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 244<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 245<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 246<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 247<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 248<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 249<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 250<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 251<li><a href="console.html" class="nav-console">Console</a></li> 252<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 253<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 254<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 255<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 256<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 257<li><a href="dns.html" class="nav-dns">DNS</a></li> 258<li><a href="domain.html" class="nav-domain">Domain</a></li> 259<li><a href="errors.html" class="nav-errors">Errors</a></li> 260<li><a href="events.html" class="nav-events">Events</a></li> 261<li><a href="fs.html" class="nav-fs">File system</a></li> 262<li><a href="globals.html" class="nav-globals">Globals</a></li> 263<li><a href="http.html" class="nav-http">HTTP</a></li> 264<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 265<li><a href="https.html" class="nav-https">HTTPS</a></li> 266<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 267<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 268<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 269<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 270<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 271<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 272<li><a href="net.html" class="nav-net">Net</a></li> 273<li><a href="os.html" class="nav-os">OS</a></li> 274<li><a href="path.html" class="nav-path">Path</a></li> 275<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 276<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 277<li><a href="process.html" class="nav-process">Process</a></li> 278<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 279<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 280<li><a href="readline.html" class="nav-readline">Readline</a></li> 281<li><a href="repl.html" class="nav-repl">REPL</a></li> 282<li><a href="report.html" class="nav-report">Report</a></li> 283<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 284<li><a href="stream.html" class="nav-stream">Stream</a></li> 285<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 286<li><a href="test.html" class="nav-test active">Test runner</a></li> 287<li><a href="timers.html" class="nav-timers">Timers</a></li> 288<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 289<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 290<li><a href="tty.html" class="nav-tty">TTY</a></li> 291<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 292<li><a href="url.html" class="nav-url">URL</a></li> 293<li><a href="util.html" class="nav-util">Utilities</a></li> 294<li><a href="v8.html" class="nav-v8">V8</a></li> 295<li><a href="vm.html" class="nav-vm">VM</a></li> 296<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 297<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 298<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 299<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 300<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 301</ul> 302<hr class="line"> 303<ul> 304<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 305</ul></div> 306 </li> 307 308 309 <li class="picker-header"> 310 <a href="#"> 311 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 312 Other versions 313 </a> 314 <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v20.x/api/test.html">20.x</a></li> 315<li><a href="https://nodejs.org/docs/latest-v19.x/api/test.html">19.x</a></li> 316<li><a href="https://nodejs.org/docs/latest-v18.x/api/test.html">18.x <b>LTS</b></a></li></ol></div> 317 </li> 318 319 <li class="picker-header"> 320 <a href="#"> 321 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 322 Options 323 </a> 324 325 <div class="picker"> 326 <ul> 327 <li> 328 <a href="all.html">View on single page</a> 329 </li> 330 <li> 331 <a href="test.json">View as JSON</a> 332 </li> 333 <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/test.md">Edit on GitHub</a></li> 334 </ul> 335 </div> 336 </li> 337 </ul> 338 </div> 339 <hr> 340 </header> 341 342 <details id="toc" open><summary>Table of contents</summary><ul> 343<li><span class="stability_1"><a href="#test-runner">Test runner</a></span> 344<ul> 345<li><a href="#subtests">Subtests</a></li> 346<li><a href="#skipping-tests">Skipping tests</a></li> 347<li><a href="#describeit-syntax"><code>describe</code>/<code>it</code> syntax</a></li> 348<li><a href="#only-tests"><code>only</code> tests</a></li> 349<li><a href="#filtering-tests-by-name">Filtering tests by name</a></li> 350<li><a href="#extraneous-asynchronous-activity">Extraneous asynchronous activity</a></li> 351<li><span class="stability_1"><a href="#watch-mode">Watch mode</a></span></li> 352<li><a href="#running-tests-from-the-command-line">Running tests from the command line</a> 353<ul> 354<li><a href="#test-runner-execution-model">Test runner execution model</a></li> 355</ul> 356</li> 357<li><a href="#collecting-code-coverage">Collecting code coverage</a></li> 358<li><a href="#mocking">Mocking</a></li> 359<li><a href="#test-reporters">Test reporters</a> 360<ul> 361<li><a href="#custom-reporters">Custom reporters</a></li> 362<li><a href="#multiple-reporters">Multiple reporters</a></li> 363</ul> 364</li> 365<li><a href="#runoptions"><code>run([options])</code></a></li> 366<li><a href="#testname-options-fn"><code>test([name][, options][, fn])</code></a></li> 367<li><a href="#testskipname-options-fn"><code>test.skip([name][, options][, fn])</code></a></li> 368<li><a href="#testtodoname-options-fn"><code>test.todo([name][, options][, fn])</code></a></li> 369<li><a href="#testonlyname-options-fn"><code>test.only([name][, options][, fn])</code></a></li> 370<li><a href="#describename-options-fn"><code>describe([name][, options][, fn])</code></a></li> 371<li><a href="#describeskipname-options-fn"><code>describe.skip([name][, options][, fn])</code></a></li> 372<li><a href="#describetodoname-options-fn"><code>describe.todo([name][, options][, fn])</code></a></li> 373<li><a href="#describeonlyname-options-fn"><code>describe.only([name][, options][, fn])</code></a></li> 374<li><a href="#itname-options-fn"><code>it([name][, options][, fn])</code></a></li> 375<li><a href="#itskipname-options-fn"><code>it.skip([name][, options][, fn])</code></a></li> 376<li><a href="#ittodoname-options-fn"><code>it.todo([name][, options][, fn])</code></a></li> 377<li><a href="#itonlyname-options-fn"><code>it.only([name][, options][, fn])</code></a></li> 378<li><a href="#beforefn-options"><code>before([fn][, options])</code></a></li> 379<li><a href="#afterfn-options"><code>after([fn][, options])</code></a></li> 380<li><a href="#beforeeachfn-options"><code>beforeEach([fn][, options])</code></a></li> 381<li><a href="#aftereachfn-options"><code>afterEach([fn][, options])</code></a></li> 382<li><a href="#class-mockfunctioncontext">Class: <code>MockFunctionContext</code></a> 383<ul> 384<li><a href="#ctxcalls"><code>ctx.calls</code></a></li> 385<li><a href="#ctxcallcount"><code>ctx.callCount()</code></a></li> 386<li><a href="#ctxmockimplementationimplementation"><code>ctx.mockImplementation(implementation)</code></a></li> 387<li><a href="#ctxmockimplementationonceimplementation-oncall"><code>ctx.mockImplementationOnce(implementation[, onCall])</code></a></li> 388<li><a href="#ctxresetcalls"><code>ctx.resetCalls()</code></a></li> 389<li><a href="#ctxrestore"><code>ctx.restore()</code></a></li> 390</ul> 391</li> 392<li><a href="#class-mocktracker">Class: <code>MockTracker</code></a> 393<ul> 394<li><a href="#mockfnoriginal-implementation-options"><code>mock.fn([original[, implementation]][, options])</code></a></li> 395<li><a href="#mockgetterobject-methodname-implementation-options"><code>mock.getter(object, methodName[, implementation][, options])</code></a></li> 396<li><a href="#mockmethodobject-methodname-implementation-options"><code>mock.method(object, methodName[, implementation][, options])</code></a></li> 397<li><a href="#mockreset"><code>mock.reset()</code></a></li> 398<li><a href="#mockrestoreall"><code>mock.restoreAll()</code></a></li> 399<li><a href="#mocksetterobject-methodname-implementation-options"><code>mock.setter(object, methodName[, implementation][, options])</code></a></li> 400</ul> 401</li> 402<li><a href="#class-testsstream">Class: <code>TestsStream</code></a> 403<ul> 404<li><a href="#event-testcoverage">Event: <code>'test:coverage'</code></a></li> 405<li><a href="#event-testdequeue">Event: <code>'test:dequeue'</code></a></li> 406<li><a href="#event-testdiagnostic">Event: <code>'test:diagnostic'</code></a></li> 407<li><a href="#event-testenqueue">Event: <code>'test:enqueue'</code></a></li> 408<li><a href="#event-testfail">Event: <code>'test:fail'</code></a></li> 409<li><a href="#event-testpass">Event: <code>'test:pass'</code></a></li> 410<li><a href="#event-testplan">Event: <code>'test:plan'</code></a></li> 411<li><a href="#event-teststart">Event: <code>'test:start'</code></a></li> 412<li><a href="#event-teststderr">Event: <code>'test:stderr'</code></a></li> 413<li><a href="#event-teststdout">Event: <code>'test:stdout'</code></a></li> 414<li><a href="#event-testwatchdrained">Event: <code>'test:watch:drained'</code></a></li> 415</ul> 416</li> 417<li><a href="#class-testcontext">Class: <code>TestContext</code></a> 418<ul> 419<li><a href="#contextbeforefn-options"><code>context.before([fn][, options])</code></a></li> 420<li><a href="#contextbeforeeachfn-options"><code>context.beforeEach([fn][, options])</code></a></li> 421<li><a href="#contextafterfn-options"><code>context.after([fn][, options])</code></a></li> 422<li><a href="#contextaftereachfn-options"><code>context.afterEach([fn][, options])</code></a></li> 423<li><a href="#contextdiagnosticmessage"><code>context.diagnostic(message)</code></a></li> 424<li><a href="#contextname"><code>context.name</code></a></li> 425<li><a href="#contextrunonlyshouldrunonlytests"><code>context.runOnly(shouldRunOnlyTests)</code></a></li> 426<li><a href="#contextsignal"><code>context.signal</code></a></li> 427<li><a href="#contextskipmessage"><code>context.skip([message])</code></a></li> 428<li><a href="#contexttodomessage"><code>context.todo([message])</code></a></li> 429<li><a href="#contexttestname-options-fn"><code>context.test([name][, options][, fn])</code></a></li> 430</ul> 431</li> 432<li><a href="#class-suitecontext">Class: <code>SuiteContext</code></a> 433<ul> 434<li><a href="#contextname_1"><code>context.name</code></a></li> 435<li><a href="#contextsignal_1"><code>context.signal</code></a></li> 436</ul> 437</li> 438</ul> 439</li> 440</ul></details> 441 442 <div id="apicontent"> 443 <h2>Test runner<span><a class="mark" href="#test-runner" id="test-runner">#</a></span><a aria-hidden="true" class="legacy" id="test_test_runner"></a></h2> 444 445<div class="api_metadata"> 446<span>Added in: v18.0.0, v16.17.0</span> 447</div> 448<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 449<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v18.18.2/lib/test.js">lib/test.js</a></p> 450<p>The <code>node:test</code> module facilitates the creation of JavaScript tests. 451To access it:</p> 452 453<pre class="with-34-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> test <span class="hljs-keyword">from</span> <span class="hljs-string">'node:test'</span>;</code><code class="language-js cjs"><span class="hljs-keyword">const</span> test = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:test'</span>);</code><button class="copy-button">copy</button></pre> 454<p>This module is only available under the <code>node:</code> scheme. The following will not 455work:</p> 456 457<pre class="with-29-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> test <span class="hljs-keyword">from</span> <span class="hljs-string">'test'</span>;</code><code class="language-js cjs"><span class="hljs-keyword">const</span> test = <span class="hljs-built_in">require</span>(<span class="hljs-string">'test'</span>);</code><button class="copy-button">copy</button></pre> 458<p>Tests created via the <code>test</code> module consist of a single function that is 459processed in one of three ways:</p> 460<ol> 461<li>A synchronous function that is considered failing if it throws an exception, 462and is considered passing otherwise.</li> 463<li>A function that returns a <code>Promise</code> that is considered failing if the 464<code>Promise</code> rejects, and is considered passing if the <code>Promise</code> resolves.</li> 465<li>A function that receives a callback function. If the callback receives any 466truthy value as its first argument, the test is considered failing. If a 467falsy value is passed as the first argument to the callback, the test is 468considered passing. If the test function receives a callback function and 469also returns a <code>Promise</code>, the test will fail.</li> 470</ol> 471<p>The following example illustrates how tests are written using the 472<code>test</code> module.</p> 473<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'synchronous passing test'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 474 <span class="hljs-comment">// This test passes because it does not throw an exception.</span> 475 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">1</span>, <span class="hljs-number">1</span>); 476}); 477 478<span class="hljs-title function_">test</span>(<span class="hljs-string">'synchronous failing test'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 479 <span class="hljs-comment">// This test fails because it throws an exception.</span> 480 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">1</span>, <span class="hljs-number">2</span>); 481}); 482 483<span class="hljs-title function_">test</span>(<span class="hljs-string">'asynchronous passing test'</span>, <span class="hljs-keyword">async</span> (t) => { 484 <span class="hljs-comment">// This test passes because the Promise returned by the async</span> 485 <span class="hljs-comment">// function is not rejected.</span> 486 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">1</span>, <span class="hljs-number">1</span>); 487}); 488 489<span class="hljs-title function_">test</span>(<span class="hljs-string">'asynchronous failing test'</span>, <span class="hljs-keyword">async</span> (t) => { 490 <span class="hljs-comment">// This test fails because the Promise returned by the async</span> 491 <span class="hljs-comment">// function is rejected.</span> 492 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">1</span>, <span class="hljs-number">2</span>); 493}); 494 495<span class="hljs-title function_">test</span>(<span class="hljs-string">'failing test using Promises'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 496 <span class="hljs-comment">// Promises can be used directly as well.</span> 497 <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function">(<span class="hljs-params">resolve, reject</span>) =></span> { 498 <span class="hljs-title function_">setImmediate</span>(<span class="hljs-function">() =></span> { 499 <span class="hljs-title function_">reject</span>(<span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'this will cause the test to fail'</span>)); 500 }); 501 }); 502}); 503 504<span class="hljs-title function_">test</span>(<span class="hljs-string">'callback passing test'</span>, <span class="hljs-function">(<span class="hljs-params">t, done</span>) =></span> { 505 <span class="hljs-comment">// done() is the callback function. When the setImmediate() runs, it invokes</span> 506 <span class="hljs-comment">// done() with no arguments.</span> 507 <span class="hljs-title function_">setImmediate</span>(done); 508}); 509 510<span class="hljs-title function_">test</span>(<span class="hljs-string">'callback failing test'</span>, <span class="hljs-function">(<span class="hljs-params">t, done</span>) =></span> { 511 <span class="hljs-comment">// When the setImmediate() runs, done() is invoked with an Error object and</span> 512 <span class="hljs-comment">// the test fails.</span> 513 <span class="hljs-title function_">setImmediate</span>(<span class="hljs-function">() =></span> { 514 <span class="hljs-title function_">done</span>(<span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'callback failure'</span>)); 515 }); 516});</code> <button class="copy-button">copy</button></pre> 517<p>If any tests fail, the process exit code is set to <code>1</code>.</p> 518<section><h3>Subtests<span><a class="mark" href="#subtests" id="subtests">#</a></span><a aria-hidden="true" class="legacy" id="test_subtests"></a></h3> 519<p>The test context's <code>test()</code> method allows subtests to be created. This method 520behaves identically to the top level <code>test()</code> function. The following example 521demonstrates the creation of a top level test with two subtests.</p> 522<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-keyword">async</span> (t) => { 523 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'subtest 1'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 524 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">1</span>, <span class="hljs-number">1</span>); 525 }); 526 527 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'subtest 2'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 528 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">2</span>, <span class="hljs-number">2</span>); 529 }); 530});</code> <button class="copy-button">copy</button></pre> 531<p>In this example, <code>await</code> is used to ensure that both subtests have completed. 532This is necessary because parent tests do not wait for their subtests to 533complete. Any subtests that are still outstanding when their parent finishes 534are cancelled and treated as failures. Any subtest failures cause the parent 535test to fail.</p> 536</section><section><h3>Skipping tests<span><a class="mark" href="#skipping-tests" id="skipping-tests">#</a></span><a aria-hidden="true" class="legacy" id="test_skipping_tests"></a></h3> 537<p>Individual tests can be skipped by passing the <code>skip</code> option to the test, or by 538calling the test context's <code>skip()</code> method as shown in the 539following example.</p> 540<pre><code class="language-js"><span class="hljs-comment">// The skip option is used, but no message is provided.</span> 541<span class="hljs-title function_">test</span>(<span class="hljs-string">'skip option'</span>, { <span class="hljs-attr">skip</span>: <span class="hljs-literal">true</span> }, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 542 <span class="hljs-comment">// This code is never executed.</span> 543}); 544 545<span class="hljs-comment">// The skip option is used, and a message is provided.</span> 546<span class="hljs-title function_">test</span>(<span class="hljs-string">'skip option with message'</span>, { <span class="hljs-attr">skip</span>: <span class="hljs-string">'this is skipped'</span> }, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 547 <span class="hljs-comment">// This code is never executed.</span> 548}); 549 550<span class="hljs-title function_">test</span>(<span class="hljs-string">'skip() method'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 551 <span class="hljs-comment">// Make sure to return here as well if the test contains additional logic.</span> 552 t.<span class="hljs-title function_">skip</span>(); 553}); 554 555<span class="hljs-title function_">test</span>(<span class="hljs-string">'skip() method with message'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 556 <span class="hljs-comment">// Make sure to return here as well if the test contains additional logic.</span> 557 t.<span class="hljs-title function_">skip</span>(<span class="hljs-string">'this is skipped'</span>); 558});</code> <button class="copy-button">copy</button></pre> 559</section><section><h3><code>describe</code>/<code>it</code> syntax<span><a class="mark" href="#describeit-syntax" id="describeit-syntax">#</a></span><a aria-hidden="true" class="legacy" id="test_describe_it_syntax"></a></h3> 560<p>Running tests can also be done using <code>describe</code> to declare a suite 561and <code>it</code> to declare a test. 562A suite is used to organize and group related tests together. 563<code>it</code> is a shorthand for <a href="#testname-options-fn"><code>test()</code></a>.</p> 564<pre><code class="language-js"><span class="hljs-title function_">describe</span>(<span class="hljs-string">'A thing'</span>, <span class="hljs-function">() =></span> { 565 <span class="hljs-title function_">it</span>(<span class="hljs-string">'should work'</span>, <span class="hljs-function">() =></span> { 566 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">1</span>, <span class="hljs-number">1</span>); 567 }); 568 569 <span class="hljs-title function_">it</span>(<span class="hljs-string">'should be ok'</span>, <span class="hljs-function">() =></span> { 570 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">2</span>, <span class="hljs-number">2</span>); 571 }); 572 573 <span class="hljs-title function_">describe</span>(<span class="hljs-string">'a nested thing'</span>, <span class="hljs-function">() =></span> { 574 <span class="hljs-title function_">it</span>(<span class="hljs-string">'should work'</span>, <span class="hljs-function">() =></span> { 575 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-number">3</span>, <span class="hljs-number">3</span>); 576 }); 577 }); 578});</code> <button class="copy-button">copy</button></pre> 579<p><code>describe</code> and <code>it</code> are imported from the <code>node:test</code> module.</p> 580 581<pre class="with-46-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { describe, it } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:test'</span>;</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { describe, it } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:test'</span>);</code><button class="copy-button">copy</button></pre> 582</section><section><h3><code>only</code> tests<span><a class="mark" href="#only-tests" id="only-tests">#</a></span><a aria-hidden="true" class="legacy" id="test_only_tests"></a></h3> 583<p>If Node.js is started with the <a href="cli.html#--test-only"><code>--test-only</code></a> command-line option, it is 584possible to skip all top level tests except for a selected subset by passing 585the <code>only</code> option to the tests that should be run. When a test with the <code>only</code> 586option set is run, all subtests are also run. The test context's <code>runOnly()</code> 587method can be used to implement the same behavior at the subtest level.</p> 588<pre><code class="language-js"><span class="hljs-comment">// Assume Node.js is run with the --test-only command-line option.</span> 589<span class="hljs-comment">// The 'only' option is set, so this test is run.</span> 590<span class="hljs-title function_">test</span>(<span class="hljs-string">'this test is run'</span>, { <span class="hljs-attr">only</span>: <span class="hljs-literal">true</span> }, <span class="hljs-keyword">async</span> (t) => { 591 <span class="hljs-comment">// Within this test, all subtests are run by default.</span> 592 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'running subtest'</span>); 593 594 <span class="hljs-comment">// The test context can be updated to run subtests with the 'only' option.</span> 595 t.<span class="hljs-title function_">runOnly</span>(<span class="hljs-literal">true</span>); 596 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'this subtest is now skipped'</span>); 597 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'this subtest is run'</span>, { <span class="hljs-attr">only</span>: <span class="hljs-literal">true</span> }); 598 599 <span class="hljs-comment">// Switch the context back to execute all tests.</span> 600 t.<span class="hljs-title function_">runOnly</span>(<span class="hljs-literal">false</span>); 601 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'this subtest is now run'</span>); 602 603 <span class="hljs-comment">// Explicitly do not run these tests.</span> 604 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'skipped subtest 3'</span>, { <span class="hljs-attr">only</span>: <span class="hljs-literal">false</span> }); 605 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'skipped subtest 4'</span>, { <span class="hljs-attr">skip</span>: <span class="hljs-literal">true</span> }); 606}); 607 608<span class="hljs-comment">// The 'only' option is not set, so this test is skipped.</span> 609<span class="hljs-title function_">test</span>(<span class="hljs-string">'this test is not run'</span>, <span class="hljs-function">() =></span> { 610 <span class="hljs-comment">// This code is not run.</span> 611 <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'fail'</span>); 612});</code> <button class="copy-button">copy</button></pre> 613</section><section><h3>Filtering tests by name<span><a class="mark" href="#filtering-tests-by-name" id="filtering-tests-by-name">#</a></span><a aria-hidden="true" class="legacy" id="test_filtering_tests_by_name"></a></h3> 614<p>The <a href="cli.html#--test-name-pattern"><code>--test-name-pattern</code></a> command-line option can be used to only run tests 615whose name matches the provided pattern. Test name patterns are interpreted as 616JavaScript regular expressions. The <code>--test-name-pattern</code> option can be 617specified multiple times in order to run nested tests. For each test that is 618executed, any corresponding test hooks, such as <code>beforeEach()</code>, are also 619run.</p> 620<p>Given the following test file, starting Node.js with the 621<code>--test-name-pattern="test [1-3]"</code> option would cause the test runner to execute 622<code>test 1</code>, <code>test 2</code>, and <code>test 3</code>. If <code>test 1</code> did not match the test name 623pattern, then its subtests would not execute, despite matching the pattern. The 624same set of tests could also be executed by passing <code>--test-name-pattern</code> 625multiple times (e.g. <code>--test-name-pattern="test 1"</code>, 626<code>--test-name-pattern="test 2"</code>, etc.).</p> 627<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'test 1'</span>, <span class="hljs-keyword">async</span> (t) => { 628 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'test 2'</span>); 629 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'test 3'</span>); 630}); 631 632<span class="hljs-title function_">test</span>(<span class="hljs-string">'Test 4'</span>, <span class="hljs-keyword">async</span> (t) => { 633 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'Test 5'</span>); 634 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'test 6'</span>); 635});</code> <button class="copy-button">copy</button></pre> 636<p>Test name patterns can also be specified using regular expression literals. This 637allows regular expression flags to be used. In the previous example, starting 638Node.js with <code>--test-name-pattern="/test [4-5]/i"</code> would match <code>Test 4</code> and 639<code>Test 5</code> because the pattern is case-insensitive.</p> 640<p>Test name patterns do not change the set of files that the test runner executes.</p> 641</section><section><h3>Extraneous asynchronous activity<span><a class="mark" href="#extraneous-asynchronous-activity" id="extraneous-asynchronous-activity">#</a></span><a aria-hidden="true" class="legacy" id="test_extraneous_asynchronous_activity"></a></h3> 642<p>Once a test function finishes executing, the results are reported as quickly 643as possible while maintaining the order of the tests. However, it is possible 644for the test function to generate asynchronous activity that outlives the test 645itself. The test runner handles this type of activity, but does not delay the 646reporting of test results in order to accommodate it.</p> 647<p>In the following example, a test completes with two <code>setImmediate()</code> 648operations still outstanding. The first <code>setImmediate()</code> attempts to create a 649new subtest. Because the parent test has already finished and output its 650results, the new subtest is immediately marked as failed, and reported later 651to the <a href="test.html#class-testsstream" class="type"><TestsStream></a>.</p> 652<p>The second <code>setImmediate()</code> creates an <code>uncaughtException</code> event. 653<code>uncaughtException</code> and <code>unhandledRejection</code> events originating from a completed 654test are marked as failed by the <code>test</code> module and reported as diagnostic 655warnings at the top level by the <a href="test.html#class-testsstream" class="type"><TestsStream></a>.</p> 656<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'a test that creates asynchronous activity'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 657 <span class="hljs-title function_">setImmediate</span>(<span class="hljs-function">() =></span> { 658 t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'subtest that is created too late'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 659 <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'error1'</span>); 660 }); 661 }); 662 663 <span class="hljs-title function_">setImmediate</span>(<span class="hljs-function">() =></span> { 664 <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'error2'</span>); 665 }); 666 667 <span class="hljs-comment">// The test finishes after this line.</span> 668});</code> <button class="copy-button">copy</button></pre> 669</section><section><h3>Watch mode<span><a class="mark" href="#watch-mode" id="watch-mode">#</a></span><a aria-hidden="true" class="legacy" id="test_watch_mode"></a></h3> 670<div class="api_metadata"> 671<span>Added in: v18.13.0</span> 672</div> 673<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 674<p>The Node.js test runner supports running in watch mode by passing the <code>--watch</code> flag:</p> 675<pre><code class="language-bash">node --<span class="hljs-built_in">test</span> --watch</code> <button class="copy-button">copy</button></pre> 676<p>In watch mode, the test runner will watch for changes to test files and 677their dependencies. When a change is detected, the test runner will 678rerun the tests affected by the change. 679The test runner will continue to run until the process is terminated.</p> 680</section><section><h3>Running tests from the command line<span><a class="mark" href="#running-tests-from-the-command-line" id="running-tests-from-the-command-line">#</a></span><a aria-hidden="true" class="legacy" id="test_running_tests_from_the_command_line"></a></h3> 681<p>The Node.js test runner can be invoked from the command line by passing the 682<a href="cli.html#--test"><code>--test</code></a> flag:</p> 683<pre><code class="language-bash">node --<span class="hljs-built_in">test</span></code> <button class="copy-button">copy</button></pre> 684<p>By default, Node.js will recursively search the current directory for 685JavaScript source files matching a specific naming convention. Matching files 686are executed as test files. More information on the expected test file naming 687convention and behavior can be found in the <a href="#test-runner-execution-model">test runner execution model</a> 688section.</p> 689<p>Alternatively, one or more paths can be provided as the final argument(s) to 690the Node.js command, as shown below.</p> 691<pre><code class="language-bash">node --<span class="hljs-built_in">test</span> test1.js test2.mjs custom_test_dir/</code> <button class="copy-button">copy</button></pre> 692<p>In this example, the test runner will execute the files <code>test1.js</code> and 693<code>test2.mjs</code>. The test runner will also recursively search the 694<code>custom_test_dir/</code> directory for test files to execute.</p> 695<h4>Test runner execution model<span><a class="mark" href="#test-runner-execution-model" id="test-runner-execution-model">#</a></span><a aria-hidden="true" class="legacy" id="test_test_runner_execution_model"></a></h4> 696<p>When searching for test files to execute, the test runner behaves as follows:</p> 697<ul> 698<li>Any files explicitly provided by the user are executed.</li> 699<li>If the user did not explicitly specify any paths, the current working 700directory is recursively searched for files as specified in the following 701steps.</li> 702<li><code>node_modules</code> directories are skipped unless explicitly provided by the 703user.</li> 704<li>If a directory named <code>test</code> is encountered, the test runner will search it 705recursively for all all <code>.js</code>, <code>.cjs</code>, and <code>.mjs</code> files. All of these files 706are treated as test files, and do not need to match the specific naming 707convention detailed below. This is to accommodate projects that place all of 708their tests in a single <code>test</code> directory.</li> 709<li>In all other directories, <code>.js</code>, <code>.cjs</code>, and <code>.mjs</code> files matching the 710following patterns are treated as test files: 711<ul> 712<li><code>^test$</code> - Files whose basename is the string <code>'test'</code>. Examples: 713<code>test.js</code>, <code>test.cjs</code>, <code>test.mjs</code>.</li> 714<li><code>^test-.+</code> - Files whose basename starts with the string <code>'test-'</code> 715followed by one or more characters. Examples: <code>test-example.js</code>, 716<code>test-another-example.mjs</code>.</li> 717<li><code>.+[\.\-\_]test$</code> - Files whose basename ends with <code>.test</code>, <code>-test</code>, or 718<code>_test</code>, preceded by one or more characters. Examples: <code>example.test.js</code>, 719<code>example-test.cjs</code>, <code>example_test.mjs</code>.</li> 720<li>Other file types understood by Node.js such as <code>.node</code> and <code>.json</code> are not 721automatically executed by the test runner, but are supported if explicitly 722provided on the command line.</li> 723</ul> 724</li> 725</ul> 726<p>Each matching test file is executed in a separate child process. If the child 727process finishes with an exit code of 0, the test is considered passing. 728Otherwise, the test is considered to be a failure. Test files must be 729executable by Node.js, but are not required to use the <code>node:test</code> module 730internally.</p> 731<p>Each test file is executed as if it was a regular script. That is, if the test 732file itself uses <code>node:test</code> to define tests, all of those tests will be 733executed within a single application thread, regardless of the value of the 734<code>concurrency</code> option of <a href="#testname-options-fn"><code>test()</code></a>.</p> 735</section><section><h3>Collecting code coverage<span><a class="mark" href="#collecting-code-coverage" id="collecting-code-coverage">#</a></span><a aria-hidden="true" class="legacy" id="test_collecting_code_coverage"></a></h3> 736<p>When Node.js is started with the <a href="cli.html#--experimental-test-coverage"><code>--experimental-test-coverage</code></a> 737command-line flag, code coverage is collected and statistics are reported once 738all tests have completed. If the <a href="cli.html#node_v8_coveragedir"><code>NODE_V8_COVERAGE</code></a> environment variable is 739used to specify a code coverage directory, the generated V8 coverage files are 740written to that directory. Node.js core modules and files within 741<code>node_modules/</code> directories are not included in the coverage report. If 742coverage is enabled, the coverage report is sent to any <a href="#test-reporters">test reporters</a> via 743the <code>'test:coverage'</code> event.</p> 744<p>Coverage can be disabled on a series of lines using the following 745comment syntax:</p> 746<pre><code class="language-js"><span class="hljs-comment">/* node:coverage disable */</span> 747<span class="hljs-keyword">if</span> (anAlwaysFalseCondition) { 748 <span class="hljs-comment">// Code in this branch will never be executed, but the lines are ignored for</span> 749 <span class="hljs-comment">// coverage purposes. All lines following the 'disable' comment are ignored</span> 750 <span class="hljs-comment">// until a corresponding 'enable' comment is encountered.</span> 751 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'this is never executed'</span>); 752} 753<span class="hljs-comment">/* node:coverage enable */</span></code> <button class="copy-button">copy</button></pre> 754<p>Coverage can also be disabled for a specified number of lines. After the 755specified number of lines, coverage will be automatically reenabled. If the 756number of lines is not explicitly provided, a single line is ignored.</p> 757<pre><code class="language-js"><span class="hljs-comment">/* node:coverage ignore next */</span> 758<span class="hljs-keyword">if</span> (anAlwaysFalseCondition) { <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'this is never executed'</span>); } 759 760<span class="hljs-comment">/* node:coverage ignore next 3 */</span> 761<span class="hljs-keyword">if</span> (anAlwaysFalseCondition) { 762 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'this is never executed'</span>); 763}</code> <button class="copy-button">copy</button></pre> 764<p>The test runner's code coverage functionality has the following limitations, 765which will be addressed in a future Node.js release:</p> 766<ul> 767<li>Source maps are not supported.</li> 768<li>Excluding specific files or directories from the coverage report is not 769supported.</li> 770</ul> 771</section><section><h3>Mocking<span><a class="mark" href="#mocking" id="mocking">#</a></span><a aria-hidden="true" class="legacy" id="test_mocking"></a></h3> 772<p>The <code>node:test</code> module supports mocking during testing via a top-level <code>mock</code> 773object. The following example creates a spy on a function that adds two numbers 774together. The spy is then used to assert that the function was called as 775expected.</p> 776 777<pre class="with-39-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> assert <span class="hljs-keyword">from</span> <span class="hljs-string">'node:assert'</span>; 778<span class="hljs-keyword">import</span> { mock, test } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:test'</span>; 779 780<span class="hljs-title function_">test</span>(<span class="hljs-string">'spies on a function'</span>, <span class="hljs-function">() =></span> { 781 <span class="hljs-keyword">const</span> sum = mock.<span class="hljs-title function_">fn</span>(<span class="hljs-function">(<span class="hljs-params">a, b</span>) =></span> { 782 <span class="hljs-keyword">return</span> a + b; 783 }); 784 785 assert.<span class="hljs-title function_">strictEqual</span>(sum.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>.<span class="hljs-property">length</span>, <span class="hljs-number">0</span>); 786 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">sum</span>(<span class="hljs-number">3</span>, <span class="hljs-number">4</span>), <span class="hljs-number">7</span>); 787 assert.<span class="hljs-title function_">strictEqual</span>(sum.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>.<span class="hljs-property">length</span>, <span class="hljs-number">1</span>); 788 789 <span class="hljs-keyword">const</span> call = sum.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>[<span class="hljs-number">0</span>]; 790 assert.<span class="hljs-title function_">deepStrictEqual</span>(call.<span class="hljs-property">arguments</span>, [<span class="hljs-number">3</span>, <span class="hljs-number">4</span>]); 791 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">result</span>, <span class="hljs-number">7</span>); 792 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">error</span>, <span class="hljs-literal">undefined</span>); 793 794 <span class="hljs-comment">// Reset the globally tracked mocks.</span> 795 mock.<span class="hljs-title function_">reset</span>(); 796});</code><code class="language-js cjs"><span class="hljs-meta">'use strict'</span>; 797<span class="hljs-keyword">const</span> assert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:assert'</span>); 798<span class="hljs-keyword">const</span> { mock, test } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:test'</span>); 799 800<span class="hljs-title function_">test</span>(<span class="hljs-string">'spies on a function'</span>, <span class="hljs-function">() =></span> { 801 <span class="hljs-keyword">const</span> sum = mock.<span class="hljs-title function_">fn</span>(<span class="hljs-function">(<span class="hljs-params">a, b</span>) =></span> { 802 <span class="hljs-keyword">return</span> a + b; 803 }); 804 805 assert.<span class="hljs-title function_">strictEqual</span>(sum.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>.<span class="hljs-property">length</span>, <span class="hljs-number">0</span>); 806 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">sum</span>(<span class="hljs-number">3</span>, <span class="hljs-number">4</span>), <span class="hljs-number">7</span>); 807 assert.<span class="hljs-title function_">strictEqual</span>(sum.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>.<span class="hljs-property">length</span>, <span class="hljs-number">1</span>); 808 809 <span class="hljs-keyword">const</span> call = sum.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>[<span class="hljs-number">0</span>]; 810 assert.<span class="hljs-title function_">deepStrictEqual</span>(call.<span class="hljs-property">arguments</span>, [<span class="hljs-number">3</span>, <span class="hljs-number">4</span>]); 811 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">result</span>, <span class="hljs-number">7</span>); 812 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">error</span>, <span class="hljs-literal">undefined</span>); 813 814 <span class="hljs-comment">// Reset the globally tracked mocks.</span> 815 mock.<span class="hljs-title function_">reset</span>(); 816});</code><button class="copy-button">copy</button></pre> 817<p>The same mocking functionality is also exposed on the <a href="#class-testcontext"><code>TestContext</code></a> object 818of each test. The following example creates a spy on an object method using the 819API exposed on the <code>TestContext</code>. The benefit of mocking via the test context is 820that the test runner will automatically restore all mocked functionality once 821the test finishes.</p> 822<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'spies on an object method'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 823 <span class="hljs-keyword">const</span> number = { 824 <span class="hljs-attr">value</span>: <span class="hljs-number">5</span>, 825 <span class="hljs-title function_">add</span>(<span class="hljs-params">a</span>) { 826 <span class="hljs-keyword">return</span> <span class="hljs-variable language_">this</span>.<span class="hljs-property">value</span> + a; 827 }, 828 }; 829 830 t.<span class="hljs-property">mock</span>.<span class="hljs-title function_">method</span>(number, <span class="hljs-string">'add'</span>); 831 assert.<span class="hljs-title function_">strictEqual</span>(number.<span class="hljs-property">add</span>.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>.<span class="hljs-property">length</span>, <span class="hljs-number">0</span>); 832 assert.<span class="hljs-title function_">strictEqual</span>(number.<span class="hljs-title function_">add</span>(<span class="hljs-number">3</span>), <span class="hljs-number">8</span>); 833 assert.<span class="hljs-title function_">strictEqual</span>(number.<span class="hljs-property">add</span>.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>.<span class="hljs-property">length</span>, <span class="hljs-number">1</span>); 834 835 <span class="hljs-keyword">const</span> call = number.<span class="hljs-property">add</span>.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>[<span class="hljs-number">0</span>]; 836 837 assert.<span class="hljs-title function_">deepStrictEqual</span>(call.<span class="hljs-property">arguments</span>, [<span class="hljs-number">3</span>]); 838 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">result</span>, <span class="hljs-number">8</span>); 839 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">target</span>, <span class="hljs-literal">undefined</span>); 840 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">this</span>, number); 841});</code> <button class="copy-button">copy</button></pre> 842</section><section><h3>Test reporters<span><a class="mark" href="#test-reporters" id="test-reporters">#</a></span><a aria-hidden="true" class="legacy" id="test_test_reporters"></a></h3> 843<div class="api_metadata"> 844<details class="changelog"><summary>History</summary> 845<table> 846<tbody><tr><th>Version</th><th>Changes</th></tr> 847<tr><td>v18.17.0</td> 848<td><p>Reporters are now exposed at <code>node:test/reporters</code>.</p></td></tr> 849<tr><td>v18.15.0</td> 850<td><p><span>Added in: v18.15.0</span></p></td></tr> 851</tbody></table> 852</details> 853</div> 854<p>The <code>node:test</code> module supports passing <a href="cli.html#--test-reporter"><code>--test-reporter</code></a> 855flags for the test runner to use a specific reporter.</p> 856<p>The following built-reporters are supported:</p> 857<ul> 858<li> 859<p><code>tap</code> 860The <code>tap</code> reporter outputs the test results in the <a href="https://testanything.org/">TAP</a> format.</p> 861</li> 862<li> 863<p><code>spec</code> 864The <code>spec</code> reporter outputs the test results in a human-readable format.</p> 865</li> 866<li> 867<p><code>dot</code> 868The <code>dot</code> reporter outputs the test results in a compact format, 869where each passing test is represented by a <code>.</code>, 870and each failing test is represented by a <code>X</code>.</p> 871</li> 872</ul> 873<p>When <code>stdout</code> is a <a href="tty.html">TTY</a>, the <code>spec</code> reporter is used by default. 874Otherwise, the <code>tap</code> reporter is used by default.</p> 875<p>The reporters are available via the <code>node:test/reporters</code> module:</p> 876 877<pre class="with-58-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { tap, spec, dot } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:test/reporters'</span>;</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { tap, spec, dot } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:test/reporters'</span>);</code><button class="copy-button">copy</button></pre> 878<h4>Custom reporters<span><a class="mark" href="#custom-reporters" id="custom-reporters">#</a></span><a aria-hidden="true" class="legacy" id="test_custom_reporters"></a></h4> 879<p><a href="cli.html#--test-reporter"><code>--test-reporter</code></a> can be used to specify a path to custom reporter. 880A custom reporter is a module that exports a value 881accepted by <a href="stream.html#streamcomposestreams">stream.compose</a>. 882Reporters should transform events emitted by a <a href="test.html#class-testsstream" class="type"><TestsStream></a></p> 883<p>Example of a custom reporter using <a href="stream.html#class-streamtransform" class="type"><stream.Transform></a>:</p> 884 885<pre class="with-45-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Transform</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 886 887<span class="hljs-keyword">const</span> customReporter = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Transform</span>({ 888 <span class="hljs-attr">writableObjectMode</span>: <span class="hljs-literal">true</span>, 889 <span class="hljs-title function_">transform</span>(<span class="hljs-params">event, encoding, callback</span>) { 890 <span class="hljs-keyword">switch</span> (event.<span class="hljs-property">type</span>) { 891 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:start'</span>: 892 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> started`</span>); 893 <span class="hljs-keyword">break</span>; 894 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:pass'</span>: 895 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> passed`</span>); 896 <span class="hljs-keyword">break</span>; 897 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:fail'</span>: 898 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> failed`</span>); 899 <span class="hljs-keyword">break</span>; 900 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:plan'</span>: 901 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">'test plan'</span>); 902 <span class="hljs-keyword">break</span>; 903 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:diagnostic'</span>: 904 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, event.<span class="hljs-property">data</span>.<span class="hljs-property">message</span>); 905 <span class="hljs-keyword">break</span>; 906 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:coverage'</span>: { 907 <span class="hljs-keyword">const</span> { totalLineCount } = event.<span class="hljs-property">data</span>.<span class="hljs-property">summary</span>.<span class="hljs-property">totals</span>; 908 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">`total line count: <span class="hljs-subst">${totalLineCount}</span>\n`</span>); 909 <span class="hljs-keyword">break</span>; 910 } 911 } 912 }, 913}); 914 915<span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> customReporter;</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Transform</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 916 917<span class="hljs-keyword">const</span> customReporter = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Transform</span>({ 918 <span class="hljs-attr">writableObjectMode</span>: <span class="hljs-literal">true</span>, 919 <span class="hljs-title function_">transform</span>(<span class="hljs-params">event, encoding, callback</span>) { 920 <span class="hljs-keyword">switch</span> (event.<span class="hljs-property">type</span>) { 921 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:start'</span>: 922 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> started`</span>); 923 <span class="hljs-keyword">break</span>; 924 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:pass'</span>: 925 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> passed`</span>); 926 <span class="hljs-keyword">break</span>; 927 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:fail'</span>: 928 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> failed`</span>); 929 <span class="hljs-keyword">break</span>; 930 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:plan'</span>: 931 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">'test plan'</span>); 932 <span class="hljs-keyword">break</span>; 933 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:diagnostic'</span>: 934 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, event.<span class="hljs-property">data</span>.<span class="hljs-property">message</span>); 935 <span class="hljs-keyword">break</span>; 936 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:coverage'</span>: { 937 <span class="hljs-keyword">const</span> { totalLineCount } = event.<span class="hljs-property">data</span>.<span class="hljs-property">summary</span>.<span class="hljs-property">totals</span>; 938 <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">`total line count: <span class="hljs-subst">${totalLineCount}</span>\n`</span>); 939 <span class="hljs-keyword">break</span>; 940 } 941 } 942 }, 943}); 944 945<span class="hljs-variable language_">module</span>.<span class="hljs-property">exports</span> = customReporter;</code><button class="copy-button">copy</button></pre> 946<p>Example of a custom reporter using a generator function:</p> 947 948<pre class="with-58-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> * <span class="hljs-title function_">customReporter</span>(<span class="hljs-params">source</span>) { 949 <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> event <span class="hljs-keyword">of</span> source) { 950 <span class="hljs-keyword">switch</span> (event.<span class="hljs-property">type</span>) { 951 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:start'</span>: 952 <span class="hljs-keyword">yield</span> <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> started\n`</span>; 953 <span class="hljs-keyword">break</span>; 954 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:pass'</span>: 955 <span class="hljs-keyword">yield</span> <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> passed\n`</span>; 956 <span class="hljs-keyword">break</span>; 957 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:fail'</span>: 958 <span class="hljs-keyword">yield</span> <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> failed\n`</span>; 959 <span class="hljs-keyword">break</span>; 960 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:plan'</span>: 961 <span class="hljs-keyword">yield</span> <span class="hljs-string">'test plan'</span>; 962 <span class="hljs-keyword">break</span>; 963 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:diagnostic'</span>: 964 <span class="hljs-keyword">yield</span> <span class="hljs-string">`<span class="hljs-subst">${event.data.message}</span>\n`</span>; 965 <span class="hljs-keyword">break</span>; 966 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:coverage'</span>: { 967 <span class="hljs-keyword">const</span> { totalLineCount } = event.<span class="hljs-property">data</span>.<span class="hljs-property">summary</span>.<span class="hljs-property">totals</span>; 968 <span class="hljs-keyword">yield</span> <span class="hljs-string">`total line count: <span class="hljs-subst">${totalLineCount}</span>\n`</span>; 969 <span class="hljs-keyword">break</span>; 970 } 971 } 972 } 973}</code><code class="language-js cjs"><span class="hljs-variable language_">module</span>.<span class="hljs-property">exports</span> = <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> * <span class="hljs-title function_">customReporter</span>(<span class="hljs-params">source</span>) { 974 <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> event <span class="hljs-keyword">of</span> source) { 975 <span class="hljs-keyword">switch</span> (event.<span class="hljs-property">type</span>) { 976 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:start'</span>: 977 <span class="hljs-keyword">yield</span> <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> started\n`</span>; 978 <span class="hljs-keyword">break</span>; 979 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:pass'</span>: 980 <span class="hljs-keyword">yield</span> <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> passed\n`</span>; 981 <span class="hljs-keyword">break</span>; 982 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:fail'</span>: 983 <span class="hljs-keyword">yield</span> <span class="hljs-string">`test <span class="hljs-subst">${event.data.name}</span> failed\n`</span>; 984 <span class="hljs-keyword">break</span>; 985 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:plan'</span>: 986 <span class="hljs-keyword">yield</span> <span class="hljs-string">'test plan\n'</span>; 987 <span class="hljs-keyword">break</span>; 988 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:diagnostic'</span>: 989 <span class="hljs-keyword">yield</span> <span class="hljs-string">`<span class="hljs-subst">${event.data.message}</span>\n`</span>; 990 <span class="hljs-keyword">break</span>; 991 <span class="hljs-keyword">case</span> <span class="hljs-string">'test:coverage'</span>: { 992 <span class="hljs-keyword">const</span> { totalLineCount } = event.<span class="hljs-property">data</span>.<span class="hljs-property">summary</span>.<span class="hljs-property">totals</span>; 993 <span class="hljs-keyword">yield</span> <span class="hljs-string">`total line count: <span class="hljs-subst">${totalLineCount}</span>\n`</span>; 994 <span class="hljs-keyword">break</span>; 995 } 996 } 997 } 998};</code><button class="copy-button">copy</button></pre> 999<p>The value provided to <code>--test-reporter</code> should be a string like one used in an 1000<code>import()</code> in JavaScript code.</p> 1001<h4>Multiple reporters<span><a class="mark" href="#multiple-reporters" id="multiple-reporters">#</a></span><a aria-hidden="true" class="legacy" id="test_multiple_reporters"></a></h4> 1002<p>The <a href="cli.html#--test-reporter"><code>--test-reporter</code></a> flag can be specified multiple times to report test 1003results in several formats. In this situation 1004it is required to specify a destination for each reporter 1005using <a href="cli.html#--test-reporter-destination"><code>--test-reporter-destination</code></a>. 1006Destination can be <code>stdout</code>, <code>stderr</code>, or a file path. 1007Reporters and destinations are paired according 1008to the order they were specified.</p> 1009<p>In the following example, the <code>spec</code> reporter will output to <code>stdout</code>, 1010and the <code>dot</code> reporter will output to <code>file.txt</code>:</p> 1011<pre><code class="language-bash">node --test-reporter=spec --test-reporter=dot --test-reporter-destination=stdout --test-reporter-destination=file.txt</code> <button class="copy-button">copy</button></pre> 1012<p>When a single reporter is specified, the destination will default to <code>stdout</code>, 1013unless a destination is explicitly provided.</p> 1014</section><section><h3><code>run([options])</code><span><a class="mark" href="#runoptions" id="runoptions">#</a></span><a aria-hidden="true" class="legacy" id="test_run_options"></a></h3> 1015<div class="api_metadata"> 1016<details class="changelog"><summary>History</summary> 1017<table> 1018<tbody><tr><th>Version</th><th>Changes</th></tr> 1019<tr><td>v18.17.0</td> 1020<td><p>Add a testNamePatterns option.</p></td></tr> 1021<tr><td>v18.9.0</td> 1022<td><p><span>Added in: v18.9.0</span></p></td></tr> 1023</tbody></table> 1024</details> 1025</div> 1026<ul> 1027<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for running tests. The following 1028properties are supported: 1029<ul> 1030<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If a number is provided, 1031then that many test processes would run in parallel, where each process 1032corresponds to one test file. 1033If <code>true</code>, it would run <code>os.availableParallelism() - 1</code> test files in 1034parallel. 1035If <code>false</code>, it would only run one test file at a time. 1036<strong>Default:</strong> <code>false</code>.</li> 1037<li><code>files</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> An array containing the list of files to run. 1038<strong>Default</strong> matching files from <a href="#test-runner-execution-model">test runner execution model</a>.</li> 1039<li><code>inspectPort</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Sets inspector port of test child process. 1040This can be a number, or a function that takes no arguments and returns a 1041number. If a nullish value is provided, each process gets its own port, 1042incremented from the primary's <code>process.debugPort</code>. 1043<strong>Default:</strong> <code>undefined</code>.</li> 1044<li><code>setup</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A function that accepts the <code>TestsStream</code> instance 1045and can be used to setup listeners before any tests are run. 1046<strong>Default:</strong> <code>undefined</code>.</li> 1047<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress test execution.</li> 1048<li><code>testNamePatterns</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp" class="type"><RegExp></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> A String, RegExp or a RegExp Array, 1049that can be used to only run tests whose name matches the provided pattern. 1050Test name patterns are interpreted as JavaScript regular expressions. 1051For each test that is executed, any corresponding test hooks, such as 1052<code>beforeEach()</code>, are also run. 1053<strong>Default:</strong> <code>undefined</code>.</li> 1054<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the test execution will 1055fail after. 1056If unspecified, subtests inherit this value from their parent. 1057<strong>Default:</strong> <code>Infinity</code>.</li> 1058<li><code>watch</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether to run in watch mode or not. <strong>Default:</strong> <code>false</code>.</li> 1059</ul> 1060</li> 1061<li>Returns: <a href="test.html#class-testsstream" class="type"><TestsStream></a></li> 1062</ul> 1063 1064<pre class="with-47-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { tap } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:test/reporters'</span>; 1065<span class="hljs-keyword">import</span> process <span class="hljs-keyword">from</span> <span class="hljs-string">'node:process'</span>; 1066 1067<span class="hljs-title function_">run</span>({ <span class="hljs-attr">files</span>: [path.<span class="hljs-title function_">resolve</span>(<span class="hljs-string">'./tests/test.js'</span>)] }) 1068 .<span class="hljs-title function_">compose</span>(tap) 1069 .<span class="hljs-title function_">pipe</span>(process.<span class="hljs-property">stdout</span>);</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { tap } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:test/reporters'</span>); 1070 1071<span class="hljs-title function_">run</span>({ <span class="hljs-attr">files</span>: [path.<span class="hljs-title function_">resolve</span>(<span class="hljs-string">'./tests/test.js'</span>)] }) 1072 .<span class="hljs-title function_">compose</span>(tap) 1073 .<span class="hljs-title function_">pipe</span>(process.<span class="hljs-property">stdout</span>);</code><button class="copy-button">copy</button></pre> 1074</section><section><h3><code>test([name][, options][, fn])</code><span><a class="mark" href="#testname-options-fn" id="testname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_test_name_options_fn"></a></h3> 1075<div class="api_metadata"> 1076<details class="changelog"><summary>History</summary> 1077<table> 1078<tbody><tr><th>Version</th><th>Changes</th></tr> 1079<tr><td>v18.17.0</td> 1080<td><p>Added the <code>skip</code>, <code>todo</code>, and <code>only</code> shorthands.</p></td></tr> 1081<tr><td>v18.8.0</td> 1082<td><p>Add a <code>signal</code> option.</p></td></tr> 1083<tr><td>v18.7.0</td> 1084<td><p>Add a <code>timeout</code> option.</p></td></tr> 1085<tr><td>v18.0.0</td> 1086<td><p><span>Added in: v18.0.0</span></p></td></tr> 1087</tbody></table> 1088</details> 1089</div> 1090<ul> 1091<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The name of the test, which is displayed when reporting test 1092results. <strong>Default:</strong> The <code>name</code> property of <code>fn</code>, or <code>'<anonymous>'</code> if <code>fn</code> 1093does not have a name.</li> 1094<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the test. The following 1095properties are supported: 1096<ul> 1097<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If a number is provided, 1098then that many tests would run in parallel within the application thread. 1099If <code>true</code>, all scheduled asynchronous tests run concurrently within the 1100thread. If <code>false</code>, only one test runs at a time. 1101If unspecified, subtests inherit this value from their parent. 1102<strong>Default:</strong> <code>false</code>.</li> 1103<li><code>only</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If truthy, and the test context is configured to run 1104<code>only</code> tests, then this test will be run. Otherwise, the test is skipped. 1105<strong>Default:</strong> <code>false</code>.</li> 1106<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress test.</li> 1107<li><code>skip</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If truthy, the test is skipped. If a string is 1108provided, that string is displayed in the test results as the reason for 1109skipping the test. <strong>Default:</strong> <code>false</code>.</li> 1110<li><code>todo</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If truthy, the test marked as <code>TODO</code>. If a string 1111is provided, that string is displayed in the test results as the reason why 1112the test is <code>TODO</code>. <strong>Default:</strong> <code>false</code>.</li> 1113<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the test will fail after. 1114If unspecified, subtests inherit this value from their parent. 1115<strong>Default:</strong> <code>Infinity</code>.</li> 1116</ul> 1117</li> 1118<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The function under test. The first argument 1119to this function is a <a href="#class-testcontext"><code>TestContext</code></a> object. If the test uses callbacks, 1120the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1121function.</li> 1122<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Resolved with <code>undefined</code> once 1123the test completes, or immediately if the test runs within <a href="#describename-options-fn"><code>describe()</code></a>.</li> 1124</ul> 1125<p>The <code>test()</code> function is the value imported from the <code>test</code> module. Each 1126invocation of this function results in reporting the test to the <a href="test.html#class-testsstream" class="type"><TestsStream></a>.</p> 1127<p>The <code>TestContext</code> object passed to the <code>fn</code> argument can be used to perform 1128actions related to the current test. Examples include skipping the test, adding 1129additional diagnostic information, or creating subtests.</p> 1130<p><code>test()</code> returns a <code>Promise</code> that resolves once the test completes. 1131if <code>test()</code> is called within a <code>describe()</code> block, it resolve immediately. 1132The return value can usually be discarded for top level tests. 1133However, the return value from subtests should be used to prevent the parent 1134test from finishing first and cancelling the subtest 1135as shown in the following example.</p> 1136<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-keyword">async</span> (t) => { 1137 <span class="hljs-comment">// The setTimeout() in the following subtest would cause it to outlive its</span> 1138 <span class="hljs-comment">// parent test if 'await' is removed on the next line. Once the parent test</span> 1139 <span class="hljs-comment">// completes, it will cancel any outstanding subtests.</span> 1140 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'longer running subtest'</span>, <span class="hljs-keyword">async</span> (t) => { 1141 <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function">(<span class="hljs-params">resolve, reject</span>) =></span> { 1142 <span class="hljs-built_in">setTimeout</span>(resolve, <span class="hljs-number">1000</span>); 1143 }); 1144 }); 1145});</code> <button class="copy-button">copy</button></pre> 1146<p>The <code>timeout</code> option can be used to fail the test if it takes longer than 1147<code>timeout</code> milliseconds to complete. However, it is not a reliable mechanism for 1148canceling tests because a running test might block the application thread and 1149thus prevent the scheduled cancellation.</p> 1150</section><section><h3><code>test.skip([name][, options][, fn])</code><span><a class="mark" href="#testskipname-options-fn" id="testskipname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_test_skip_name_options_fn"></a></h3> 1151<p>Shorthand for skipping a test, 1152same as <a href="#testname-options-fn"><code>test([name], { skip: true }[, fn])</code></a>.</p> 1153</section><section><h3><code>test.todo([name][, options][, fn])</code><span><a class="mark" href="#testtodoname-options-fn" id="testtodoname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_test_todo_name_options_fn"></a></h3> 1154<p>Shorthand for marking a test as <code>TODO</code>, 1155same as <a href="#testname-options-fn"><code>test([name], { todo: true }[, fn])</code></a>.</p> 1156</section><section><h3><code>test.only([name][, options][, fn])</code><span><a class="mark" href="#testonlyname-options-fn" id="testonlyname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_test_only_name_options_fn"></a></h3> 1157<p>Shorthand for marking a test as <code>only</code>, 1158same as <a href="#testname-options-fn"><code>test([name], { only: true }[, fn])</code></a>.</p> 1159</section><section><h3><code>describe([name][, options][, fn])</code><span><a class="mark" href="#describename-options-fn" id="describename-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_describe_name_options_fn"></a></h3> 1160<ul> 1161<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The name of the suite, which is displayed when reporting test 1162results. <strong>Default:</strong> The <code>name</code> property of <code>fn</code>, or <code>'<anonymous>'</code> if <code>fn</code> 1163does not have a name.</li> 1164<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the suite. 1165supports the same options as <code>test([name][, options][, fn])</code>.</li> 1166<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The function under suite 1167declaring all subtests and subsuites. 1168The first argument to this function is a <a href="#class-suitecontext"><code>SuiteContext</code></a> object. 1169<strong>Default:</strong> A no-op function.</li> 1170<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Immediately fulfilled with <code>undefined</code>.</li> 1171</ul> 1172<p>The <code>describe()</code> function imported from the <code>node:test</code> module. Each 1173invocation of this function results in the creation of a Subtest. 1174After invocation of top level <code>describe</code> functions, 1175all top level tests and suites will execute.</p> 1176</section><section><h3><code>describe.skip([name][, options][, fn])</code><span><a class="mark" href="#describeskipname-options-fn" id="describeskipname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_describe_skip_name_options_fn"></a></h3> 1177<p>Shorthand for skipping a suite, same as <a href="#describename-options-fn"><code>describe([name], { skip: true }[, fn])</code></a>.</p> 1178</section><section><h3><code>describe.todo([name][, options][, fn])</code><span><a class="mark" href="#describetodoname-options-fn" id="describetodoname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_describe_todo_name_options_fn"></a></h3> 1179<p>Shorthand for marking a suite as <code>TODO</code>, same as 1180<a href="#describename-options-fn"><code>describe([name], { todo: true }[, fn])</code></a>.</p> 1181</section><section><h3><code>describe.only([name][, options][, fn])</code><span><a class="mark" href="#describeonlyname-options-fn" id="describeonlyname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_describe_only_name_options_fn"></a></h3> 1182<div class="api_metadata"> 1183<span>Added in: v18.15.0</span> 1184</div> 1185<p>Shorthand for marking a suite as <code>only</code>, same as 1186<a href="#describename-options-fn"><code>describe([name], { only: true }[, fn])</code></a>.</p> 1187</section><section><h3><code>it([name][, options][, fn])</code><span><a class="mark" href="#itname-options-fn" id="itname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_it_name_options_fn"></a></h3> 1188<div class="api_metadata"> 1189<details class="changelog"><summary>History</summary> 1190<table> 1191<tbody><tr><th>Version</th><th>Changes</th></tr> 1192<tr><td>v18.16.0</td> 1193<td><p>Calling <code>it()</code> is now equivalent to calling <code>test()</code>.</p></td></tr> 1194<tr><td>v18.6.0, v16.17.0</td> 1195<td><p><span>Added in: v18.6.0, v16.17.0</span></p></td></tr> 1196</tbody></table> 1197</details> 1198</div> 1199<p>Shorthand for <a href="#testname-options-fn"><code>test()</code></a>.</p> 1200<p>The <code>it()</code> function is imported from the <code>node:test</code> module.</p> 1201</section><section><h3><code>it.skip([name][, options][, fn])</code><span><a class="mark" href="#itskipname-options-fn" id="itskipname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_it_skip_name_options_fn"></a></h3> 1202<p>Shorthand for skipping a test, 1203same as <a href="#testname-options-fn"><code>it([name], { skip: true }[, fn])</code></a>.</p> 1204</section><section><h3><code>it.todo([name][, options][, fn])</code><span><a class="mark" href="#ittodoname-options-fn" id="ittodoname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_it_todo_name_options_fn"></a></h3> 1205<p>Shorthand for marking a test as <code>TODO</code>, 1206same as <a href="#testname-options-fn"><code>it([name], { todo: true }[, fn])</code></a>.</p> 1207</section><section><h3><code>it.only([name][, options][, fn])</code><span><a class="mark" href="#itonlyname-options-fn" id="itonlyname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_it_only_name_options_fn"></a></h3> 1208<div class="api_metadata"> 1209<span>Added in: v18.15.0</span> 1210</div> 1211<p>Shorthand for marking a test as <code>only</code>, 1212same as <a href="#testname-options-fn"><code>it([name], { only: true }[, fn])</code></a>.</p> 1213</section><section><h3><code>before([fn][, options])</code><span><a class="mark" href="#beforefn-options" id="beforefn-options">#</a></span><a aria-hidden="true" class="legacy" id="test_before_fn_options"></a></h3> 1214<div class="api_metadata"> 1215<span>Added in: v18.8.0</span> 1216</div> 1217<ul> 1218<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The hook function. 1219If the hook uses callbacks, 1220the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1221function.</li> 1222<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the hook. The following 1223properties are supported: 1224<ul> 1225<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress hook.</li> 1226<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the hook will fail after. 1227If unspecified, subtests inherit this value from their parent. 1228<strong>Default:</strong> <code>Infinity</code>.</li> 1229</ul> 1230</li> 1231</ul> 1232<p>This function is used to create a hook running before running a suite.</p> 1233<pre><code class="language-js"><span class="hljs-title function_">describe</span>(<span class="hljs-string">'tests'</span>, <span class="hljs-keyword">async</span> () => { 1234 <span class="hljs-title function_">before</span>(<span class="hljs-function">() =></span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'about to run some test'</span>)); 1235 <span class="hljs-title function_">it</span>(<span class="hljs-string">'is a subtest'</span>, <span class="hljs-function">() =></span> { 1236 assert.<span class="hljs-title function_">ok</span>(<span class="hljs-string">'some relevant assertion here'</span>); 1237 }); 1238});</code> <button class="copy-button">copy</button></pre> 1239</section><section><h3><code>after([fn][, options])</code><span><a class="mark" href="#afterfn-options" id="afterfn-options">#</a></span><a aria-hidden="true" class="legacy" id="test_after_fn_options"></a></h3> 1240<div class="api_metadata"> 1241<span>Added in: v18.8.0</span> 1242</div> 1243<ul> 1244<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The hook function. 1245If the hook uses callbacks, 1246the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1247function.</li> 1248<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the hook. The following 1249properties are supported: 1250<ul> 1251<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress hook.</li> 1252<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the hook will fail after. 1253If unspecified, subtests inherit this value from their parent. 1254<strong>Default:</strong> <code>Infinity</code>.</li> 1255</ul> 1256</li> 1257</ul> 1258<p>This function is used to create a hook running after running a suite.</p> 1259<pre><code class="language-js"><span class="hljs-title function_">describe</span>(<span class="hljs-string">'tests'</span>, <span class="hljs-keyword">async</span> () => { 1260 <span class="hljs-title function_">after</span>(<span class="hljs-function">() =></span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'finished running tests'</span>)); 1261 <span class="hljs-title function_">it</span>(<span class="hljs-string">'is a subtest'</span>, <span class="hljs-function">() =></span> { 1262 assert.<span class="hljs-title function_">ok</span>(<span class="hljs-string">'some relevant assertion here'</span>); 1263 }); 1264});</code> <button class="copy-button">copy</button></pre> 1265</section><section><h3><code>beforeEach([fn][, options])</code><span><a class="mark" href="#beforeeachfn-options" id="beforeeachfn-options">#</a></span><a aria-hidden="true" class="legacy" id="test_beforeeach_fn_options"></a></h3> 1266<div class="api_metadata"> 1267<span>Added in: v18.8.0</span> 1268</div> 1269<ul> 1270<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The hook function. 1271If the hook uses callbacks, 1272the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1273function.</li> 1274<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the hook. The following 1275properties are supported: 1276<ul> 1277<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress hook.</li> 1278<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the hook will fail after. 1279If unspecified, subtests inherit this value from their parent. 1280<strong>Default:</strong> <code>Infinity</code>.</li> 1281</ul> 1282</li> 1283</ul> 1284<p>This function is used to create a hook running 1285before each subtest of the current suite.</p> 1286<pre><code class="language-js"><span class="hljs-title function_">describe</span>(<span class="hljs-string">'tests'</span>, <span class="hljs-keyword">async</span> () => { 1287 <span class="hljs-title function_">beforeEach</span>(<span class="hljs-function">() =></span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'about to run a test'</span>)); 1288 <span class="hljs-title function_">it</span>(<span class="hljs-string">'is a subtest'</span>, <span class="hljs-function">() =></span> { 1289 assert.<span class="hljs-title function_">ok</span>(<span class="hljs-string">'some relevant assertion here'</span>); 1290 }); 1291});</code> <button class="copy-button">copy</button></pre> 1292</section><section><h3><code>afterEach([fn][, options])</code><span><a class="mark" href="#aftereachfn-options" id="aftereachfn-options">#</a></span><a aria-hidden="true" class="legacy" id="test_aftereach_fn_options"></a></h3> 1293<div class="api_metadata"> 1294<span>Added in: v18.8.0</span> 1295</div> 1296<ul> 1297<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The hook function. 1298If the hook uses callbacks, 1299the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1300function.</li> 1301<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the hook. The following 1302properties are supported: 1303<ul> 1304<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress hook.</li> 1305<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the hook will fail after. 1306If unspecified, subtests inherit this value from their parent. 1307<strong>Default:</strong> <code>Infinity</code>.</li> 1308</ul> 1309</li> 1310</ul> 1311<p>This function is used to create a hook running 1312after each subtest of the current test.</p> 1313<pre><code class="language-js"><span class="hljs-title function_">describe</span>(<span class="hljs-string">'tests'</span>, <span class="hljs-keyword">async</span> () => { 1314 <span class="hljs-title function_">afterEach</span>(<span class="hljs-function">() =></span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'finished running a test'</span>)); 1315 <span class="hljs-title function_">it</span>(<span class="hljs-string">'is a subtest'</span>, <span class="hljs-function">() =></span> { 1316 assert.<span class="hljs-title function_">ok</span>(<span class="hljs-string">'some relevant assertion here'</span>); 1317 }); 1318});</code> <button class="copy-button">copy</button></pre> 1319</section><section><h3>Class: <code>MockFunctionContext</code><span><a class="mark" href="#class-mockfunctioncontext" id="class-mockfunctioncontext">#</a></span><a aria-hidden="true" class="legacy" id="test_class_mockfunctioncontext"></a></h3> 1320<div class="api_metadata"> 1321<span>Added in: v18.13.0</span> 1322</div> 1323<p>The <code>MockFunctionContext</code> class is used to inspect or manipulate the behavior of 1324mocks created via the <a href="#class-mocktracker"><code>MockTracker</code></a> APIs.</p> 1325<h4><code>ctx.calls</code><span><a class="mark" href="#ctxcalls" id="ctxcalls">#</a></span><a aria-hidden="true" class="legacy" id="test_ctx_calls"></a></h4> 1326<div class="api_metadata"> 1327<span>Added in: v18.13.0</span> 1328</div> 1329<ul> 1330<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a></li> 1331</ul> 1332<p>A getter that returns a copy of the internal array used to track calls to the 1333mock. Each entry in the array is an object with the following properties.</p> 1334<ul> 1335<li><code>arguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> An array of the arguments passed to the mock function.</li> 1336<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> If the mocked function threw then this property contains the 1337thrown value. <strong>Default:</strong> <code>undefined</code>.</li> 1338<li><code>result</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> The value returned by the mocked function.</li> 1339<li><code>stack</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> An <code>Error</code> object whose stack can be used to determine the 1340callsite of the mocked function invocation.</li> 1341<li><code>target</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> If the mocked function is a constructor, this 1342field contains the class being constructed. Otherwise this will be 1343<code>undefined</code>.</li> 1344<li><code>this</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> The mocked function's <code>this</code> value.</li> 1345</ul> 1346<h4><code>ctx.callCount()</code><span><a class="mark" href="#ctxcallcount" id="ctxcallcount">#</a></span><a aria-hidden="true" class="legacy" id="test_ctx_callcount"></a></h4> 1347<div class="api_metadata"> 1348<span>Added in: v18.13.0</span> 1349</div> 1350<ul> 1351<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of times that this mock has been invoked.</li> 1352</ul> 1353<p>This function returns the number of times that this mock has been invoked. This 1354function is more efficient than checking <code>ctx.calls.length</code> because <code>ctx.calls</code> 1355is a getter that creates a copy of the internal call tracking array.</p> 1356<h4><code>ctx.mockImplementation(implementation)</code><span><a class="mark" href="#ctxmockimplementationimplementation" id="ctxmockimplementationimplementation">#</a></span><a aria-hidden="true" class="legacy" id="test_ctx_mockimplementation_implementation"></a></h4> 1357<div class="api_metadata"> 1358<span>Added in: v18.13.0</span> 1359</div> 1360<ul> 1361<li><code>implementation</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The function to be used as the 1362mock's new implementation.</li> 1363</ul> 1364<p>This function is used to change the behavior of an existing mock.</p> 1365<p>The following example creates a mock function using <code>t.mock.fn()</code>, calls the 1366mock function, and then changes the mock implementation to a different function.</p> 1367<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'changes a mock behavior'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1368 <span class="hljs-keyword">let</span> cnt = <span class="hljs-number">0</span>; 1369 1370 <span class="hljs-keyword">function</span> <span class="hljs-title function_">addOne</span>(<span class="hljs-params"></span>) { 1371 cnt++; 1372 <span class="hljs-keyword">return</span> cnt; 1373 } 1374 1375 <span class="hljs-keyword">function</span> <span class="hljs-title function_">addTwo</span>(<span class="hljs-params"></span>) { 1376 cnt += <span class="hljs-number">2</span>; 1377 <span class="hljs-keyword">return</span> cnt; 1378 } 1379 1380 <span class="hljs-keyword">const</span> fn = t.<span class="hljs-property">mock</span>.<span class="hljs-title function_">fn</span>(addOne); 1381 1382 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">1</span>); 1383 fn.<span class="hljs-property">mock</span>.<span class="hljs-title function_">mockImplementation</span>(addTwo); 1384 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">3</span>); 1385 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">5</span>); 1386});</code> <button class="copy-button">copy</button></pre> 1387<h4><code>ctx.mockImplementationOnce(implementation[, onCall])</code><span><a class="mark" href="#ctxmockimplementationonceimplementation-oncall" id="ctxmockimplementationonceimplementation-oncall">#</a></span><a aria-hidden="true" class="legacy" id="test_ctx_mockimplementationonce_implementation_oncall"></a></h4> 1388<div class="api_metadata"> 1389<span>Added in: v18.13.0</span> 1390</div> 1391<ul> 1392<li><code>implementation</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The function to be used as the 1393mock's implementation for the invocation number specified by <code>onCall</code>.</li> 1394<li><code>onCall</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The invocation number that will use <code>implementation</code>. If 1395the specified invocation has already occurred then an exception is thrown. 1396<strong>Default:</strong> The number of the next invocation.</li> 1397</ul> 1398<p>This function is used to change the behavior of an existing mock for a single 1399invocation. Once invocation <code>onCall</code> has occurred, the mock will revert to 1400whatever behavior it would have used had <code>mockImplementationOnce()</code> not been 1401called.</p> 1402<p>The following example creates a mock function using <code>t.mock.fn()</code>, calls the 1403mock function, changes the mock implementation to a different function for the 1404next invocation, and then resumes its previous behavior.</p> 1405<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'changes a mock behavior once'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1406 <span class="hljs-keyword">let</span> cnt = <span class="hljs-number">0</span>; 1407 1408 <span class="hljs-keyword">function</span> <span class="hljs-title function_">addOne</span>(<span class="hljs-params"></span>) { 1409 cnt++; 1410 <span class="hljs-keyword">return</span> cnt; 1411 } 1412 1413 <span class="hljs-keyword">function</span> <span class="hljs-title function_">addTwo</span>(<span class="hljs-params"></span>) { 1414 cnt += <span class="hljs-number">2</span>; 1415 <span class="hljs-keyword">return</span> cnt; 1416 } 1417 1418 <span class="hljs-keyword">const</span> fn = t.<span class="hljs-property">mock</span>.<span class="hljs-title function_">fn</span>(addOne); 1419 1420 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">1</span>); 1421 fn.<span class="hljs-property">mock</span>.<span class="hljs-title function_">mockImplementationOnce</span>(addTwo); 1422 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">3</span>); 1423 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">4</span>); 1424});</code> <button class="copy-button">copy</button></pre> 1425<h4><code>ctx.resetCalls()</code><span><a class="mark" href="#ctxresetcalls" id="ctxresetcalls">#</a></span><a aria-hidden="true" class="legacy" id="test_ctx_resetcalls"></a></h4> 1426<div class="api_metadata"> 1427<span>Added in: v18.13.0</span> 1428</div> 1429<p>Resets the call history of the mock function.</p> 1430<h4><code>ctx.restore()</code><span><a class="mark" href="#ctxrestore" id="ctxrestore">#</a></span><a aria-hidden="true" class="legacy" id="test_ctx_restore"></a></h4> 1431<div class="api_metadata"> 1432<span>Added in: v18.13.0</span> 1433</div> 1434<p>Resets the implementation of the mock function to its original behavior. The 1435mock can still be used after calling this function.</p> 1436</section><section><h3>Class: <code>MockTracker</code><span><a class="mark" href="#class-mocktracker" id="class-mocktracker">#</a></span><a aria-hidden="true" class="legacy" id="test_class_mocktracker"></a></h3> 1437<div class="api_metadata"> 1438<span>Added in: v18.13.0</span> 1439</div> 1440<p>The <code>MockTracker</code> class is used to manage mocking functionality. The test runner 1441module provides a top level <code>mock</code> export which is a <code>MockTracker</code> instance. 1442Each test also provides its own <code>MockTracker</code> instance via the test context's 1443<code>mock</code> property.</p> 1444<h4><code>mock.fn([original[, implementation]][, options])</code><span><a class="mark" href="#mockfnoriginal-implementation-options" id="mockfnoriginal-implementation-options">#</a></span><a aria-hidden="true" class="legacy" id="test_mock_fn_original_implementation_options"></a></h4> 1445<div class="api_metadata"> 1446<span>Added in: v18.13.0</span> 1447</div> 1448<ul> 1449<li><code>original</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> An optional function to create a mock on. 1450<strong>Default:</strong> A no-op function.</li> 1451<li><code>implementation</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> An optional function used as the 1452mock implementation for <code>original</code>. This is useful for creating mocks that 1453exhibit one behavior for a specified number of calls and then restore the 1454behavior of <code>original</code>. <strong>Default:</strong> The function specified by <code>original</code>.</li> 1455<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Optional configuration options for the mock function. The 1456following properties are supported: 1457<ul> 1458<li><code>times</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of times that the mock will use the behavior of 1459<code>implementation</code>. Once the mock function has been called <code>times</code> times, it 1460will automatically restore the behavior of <code>original</code>. This value must be an 1461integer greater than zero. <strong>Default:</strong> <code>Infinity</code>.</li> 1462</ul> 1463</li> 1464<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy" class="type"><Proxy></a> The mocked function. The mocked function contains a special 1465<code>mock</code> property, which is an instance of <a href="#class-mockfunctioncontext"><code>MockFunctionContext</code></a>, and can 1466be used for inspecting and changing the behavior of the mocked function.</li> 1467</ul> 1468<p>This function is used to create a mock function.</p> 1469<p>The following example creates a mock function that increments a counter by one 1470on each invocation. The <code>times</code> option is used to modify the mock behavior such 1471that the first two invocations add two to the counter instead of one.</p> 1472<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'mocks a counting function'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1473 <span class="hljs-keyword">let</span> cnt = <span class="hljs-number">0</span>; 1474 1475 <span class="hljs-keyword">function</span> <span class="hljs-title function_">addOne</span>(<span class="hljs-params"></span>) { 1476 cnt++; 1477 <span class="hljs-keyword">return</span> cnt; 1478 } 1479 1480 <span class="hljs-keyword">function</span> <span class="hljs-title function_">addTwo</span>(<span class="hljs-params"></span>) { 1481 cnt += <span class="hljs-number">2</span>; 1482 <span class="hljs-keyword">return</span> cnt; 1483 } 1484 1485 <span class="hljs-keyword">const</span> fn = t.<span class="hljs-property">mock</span>.<span class="hljs-title function_">fn</span>(addOne, addTwo, { <span class="hljs-attr">times</span>: <span class="hljs-number">2</span> }); 1486 1487 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">2</span>); 1488 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">4</span>); 1489 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">5</span>); 1490 assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-title function_">fn</span>(), <span class="hljs-number">6</span>); 1491});</code> <button class="copy-button">copy</button></pre> 1492<h4><code>mock.getter(object, methodName[, implementation][, options])</code><span><a class="mark" href="#mockgetterobject-methodname-implementation-options" id="mockgetterobject-methodname-implementation-options">#</a></span><a aria-hidden="true" class="legacy" id="test_mock_getter_object_methodname_implementation_options"></a></h4> 1493<div class="api_metadata"> 1494<span>Added in: v18.13.0</span> 1495</div> 1496<p>This function is syntax sugar for <a href="#mockmethodobject-methodname-implementation-options"><code>MockTracker.method</code></a> with <code>options.getter</code> 1497set to <code>true</code>.</p> 1498<h4><code>mock.method(object, methodName[, implementation][, options])</code><span><a class="mark" href="#mockmethodobject-methodname-implementation-options" id="mockmethodobject-methodname-implementation-options">#</a></span><a aria-hidden="true" class="legacy" id="test_mock_method_object_methodname_implementation_options"></a></h4> 1499<div class="api_metadata"> 1500<span>Added in: v18.13.0</span> 1501</div> 1502<ul> 1503<li><code>object</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> The object whose method is being mocked.</li> 1504<li><code>methodName</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Symbol_type" class="type"><symbol></a> The identifier of the method on <code>object</code> to mock. 1505If <code>object[methodName]</code> is not a function, an error is thrown.</li> 1506<li><code>implementation</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> An optional function used as the 1507mock implementation for <code>object[methodName]</code>. <strong>Default:</strong> The original method 1508specified by <code>object[methodName]</code>.</li> 1509<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Optional configuration options for the mock method. The 1510following properties are supported: 1511<ul> 1512<li><code>getter</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, <code>object[methodName]</code> is treated as a getter. 1513This option cannot be used with the <code>setter</code> option. <strong>Default:</strong> false.</li> 1514<li><code>setter</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, <code>object[methodName]</code> is treated as a setter. 1515This option cannot be used with the <code>getter</code> option. <strong>Default:</strong> false.</li> 1516<li><code>times</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of times that the mock will use the behavior of 1517<code>implementation</code>. Once the mocked method has been called <code>times</code> times, it 1518will automatically restore the original behavior. This value must be an 1519integer greater than zero. <strong>Default:</strong> <code>Infinity</code>.</li> 1520</ul> 1521</li> 1522<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy" class="type"><Proxy></a> The mocked method. The mocked method contains a special 1523<code>mock</code> property, which is an instance of <a href="#class-mockfunctioncontext"><code>MockFunctionContext</code></a>, and can 1524be used for inspecting and changing the behavior of the mocked method.</li> 1525</ul> 1526<p>This function is used to create a mock on an existing object method. The 1527following example demonstrates how a mock is created on an existing object 1528method.</p> 1529<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'spies on an object method'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1530 <span class="hljs-keyword">const</span> number = { 1531 <span class="hljs-attr">value</span>: <span class="hljs-number">5</span>, 1532 <span class="hljs-title function_">subtract</span>(<span class="hljs-params">a</span>) { 1533 <span class="hljs-keyword">return</span> <span class="hljs-variable language_">this</span>.<span class="hljs-property">value</span> - a; 1534 }, 1535 }; 1536 1537 t.<span class="hljs-property">mock</span>.<span class="hljs-title function_">method</span>(number, <span class="hljs-string">'subtract'</span>); 1538 assert.<span class="hljs-title function_">strictEqual</span>(number.<span class="hljs-property">subtract</span>.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>.<span class="hljs-property">length</span>, <span class="hljs-number">0</span>); 1539 assert.<span class="hljs-title function_">strictEqual</span>(number.<span class="hljs-title function_">subtract</span>(<span class="hljs-number">3</span>), <span class="hljs-number">2</span>); 1540 assert.<span class="hljs-title function_">strictEqual</span>(number.<span class="hljs-property">subtract</span>.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>.<span class="hljs-property">length</span>, <span class="hljs-number">1</span>); 1541 1542 <span class="hljs-keyword">const</span> call = number.<span class="hljs-property">subtract</span>.<span class="hljs-property">mock</span>.<span class="hljs-property">calls</span>[<span class="hljs-number">0</span>]; 1543 1544 assert.<span class="hljs-title function_">deepStrictEqual</span>(call.<span class="hljs-property">arguments</span>, [<span class="hljs-number">3</span>]); 1545 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">result</span>, <span class="hljs-number">2</span>); 1546 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">error</span>, <span class="hljs-literal">undefined</span>); 1547 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">target</span>, <span class="hljs-literal">undefined</span>); 1548 assert.<span class="hljs-title function_">strictEqual</span>(call.<span class="hljs-property">this</span>, number); 1549});</code> <button class="copy-button">copy</button></pre> 1550<h4><code>mock.reset()</code><span><a class="mark" href="#mockreset" id="mockreset">#</a></span><a aria-hidden="true" class="legacy" id="test_mock_reset"></a></h4> 1551<div class="api_metadata"> 1552<span>Added in: v18.13.0</span> 1553</div> 1554<p>This function restores the default behavior of all mocks that were previously 1555created by this <code>MockTracker</code> and disassociates the mocks from the 1556<code>MockTracker</code> instance. Once disassociated, the mocks can still be used, but the 1557<code>MockTracker</code> instance can no longer be used to reset their behavior or 1558otherwise interact with them.</p> 1559<p>After each test completes, this function is called on the test context's 1560<code>MockTracker</code>. If the global <code>MockTracker</code> is used extensively, calling this 1561function manually is recommended.</p> 1562<h4><code>mock.restoreAll()</code><span><a class="mark" href="#mockrestoreall" id="mockrestoreall">#</a></span><a aria-hidden="true" class="legacy" id="test_mock_restoreall"></a></h4> 1563<div class="api_metadata"> 1564<span>Added in: v18.13.0</span> 1565</div> 1566<p>This function restores the default behavior of all mocks that were previously 1567created by this <code>MockTracker</code>. Unlike <code>mock.reset()</code>, <code>mock.restoreAll()</code> does 1568not disassociate the mocks from the <code>MockTracker</code> instance.</p> 1569<h4><code>mock.setter(object, methodName[, implementation][, options])</code><span><a class="mark" href="#mocksetterobject-methodname-implementation-options" id="mocksetterobject-methodname-implementation-options">#</a></span><a aria-hidden="true" class="legacy" id="test_mock_setter_object_methodname_implementation_options"></a></h4> 1570<div class="api_metadata"> 1571<span>Added in: v18.13.0</span> 1572</div> 1573<p>This function is syntax sugar for <a href="#mockmethodobject-methodname-implementation-options"><code>MockTracker.method</code></a> with <code>options.setter</code> 1574set to <code>true</code>.</p> 1575</section><section><h3>Class: <code>TestsStream</code><span><a class="mark" href="#class-testsstream" id="class-testsstream">#</a></span><a aria-hidden="true" class="legacy" id="test_class_testsstream"></a></h3> 1576<div class="api_metadata"> 1577<span>Added in: v18.9.0</span> 1578</div> 1579<ul> 1580<li>Extends <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a></li> 1581</ul> 1582<p>A successful call to <a href="#runoptions"><code>run()</code></a> method will return a new <a href="test.html#class-testsstream" class="type"><TestsStream></a> 1583object, streaming a series of events representing the execution of the tests. 1584<code>TestsStream</code> will emit events, in the order of the tests definition</p> 1585<h4>Event: <code>'test:coverage'</code><span><a class="mark" href="#event-testcoverage" id="event-testcoverage">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_coverage"></a></h4> 1586<ul> 1587<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1588<ul> 1589<li><code>summary</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> An object containing the coverage report. 1590<ul> 1591<li><code>files</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> An array of coverage reports for individual files. Each 1592report is an object with the following schema: 1593<ul> 1594<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The absolute path of the file.</li> 1595<li><code>totalLineCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The total number of lines.</li> 1596<li><code>totalBranchCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The total number of branches.</li> 1597<li><code>totalFunctionCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The total number of functions.</li> 1598<li><code>coveredLineCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of covered lines.</li> 1599<li><code>coveredBranchCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of covered branches.</li> 1600<li><code>coveredFunctionCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of covered functions.</li> 1601<li><code>coveredLinePercent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The percentage of lines covered.</li> 1602<li><code>coveredBranchPercent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The percentage of branches covered.</li> 1603<li><code>coveredFunctionPercent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The percentage of functions covered.</li> 1604<li><code>uncoveredLineNumbers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> An array of integers representing line 1605numbers that are uncovered.</li> 1606</ul> 1607</li> 1608<li><code>totals</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> An object containing a summary of coverage for all 1609files. 1610<ul> 1611<li><code>totalLineCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The total number of lines.</li> 1612<li><code>totalBranchCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The total number of branches.</li> 1613<li><code>totalFunctionCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The total number of functions.</li> 1614<li><code>coveredLineCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of covered lines.</li> 1615<li><code>coveredBranchCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of covered branches.</li> 1616<li><code>coveredFunctionCount</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of covered functions.</li> 1617<li><code>coveredLinePercent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The percentage of lines covered.</li> 1618<li><code>coveredBranchPercent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The percentage of branches covered.</li> 1619<li><code>coveredFunctionPercent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The percentage of functions covered.</li> 1620</ul> 1621</li> 1622<li><code>workingDirectory</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The working directory when code coverage 1623began. This is useful for displaying relative path names in case the tests 1624changed the working directory of the Node.js process.</li> 1625</ul> 1626</li> 1627<li><code>nesting</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The nesting level of the test.</li> 1628</ul> 1629</li> 1630</ul> 1631<p>Emitted when code coverage is enabled and all tests have completed.</p> 1632<h4>Event: <code>'test:dequeue'</code><span><a class="mark" href="#event-testdequeue" id="event-testdequeue">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_dequeue"></a></h4> 1633<ul> 1634<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1635<ul> 1636<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The path of the test file, 1637<code>undefined</code> if test was run through the REPL.</li> 1638<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The test name.</li> 1639<li><code>nesting</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The nesting level of the test.</li> 1640</ul> 1641</li> 1642</ul> 1643<p>Emitted when a test is dequeued, right before it is executed.</p> 1644<h4>Event: <code>'test:diagnostic'</code><span><a class="mark" href="#event-testdiagnostic" id="event-testdiagnostic">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_diagnostic"></a></h4> 1645<ul> 1646<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1647<ul> 1648<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The path of the test file, 1649<code>undefined</code> if test was run through the REPL.</li> 1650<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The diagnostic message.</li> 1651<li><code>nesting</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The nesting level of the test.</li> 1652</ul> 1653</li> 1654</ul> 1655<p>Emitted when <a href="#contextdiagnosticmessage"><code>context.diagnostic</code></a> is called.</p> 1656<h4>Event: <code>'test:enqueue'</code><span><a class="mark" href="#event-testenqueue" id="event-testenqueue">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_enqueue"></a></h4> 1657<ul> 1658<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1659<ul> 1660<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The path of the test file, 1661<code>undefined</code> if test was run through the REPL.</li> 1662<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The test name.</li> 1663<li><code>nesting</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The nesting level of the test.</li> 1664</ul> 1665</li> 1666</ul> 1667<p>Emitted when a test is enqueued for execution.</p> 1668<h4>Event: <code>'test:fail'</code><span><a class="mark" href="#event-testfail" id="event-testfail">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_fail"></a></h4> 1669<ul> 1670<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1671<ul> 1672<li><code>details</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Additional execution metadata. 1673<ul> 1674<li><code>duration</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The duration of the test in milliseconds.</li> 1675<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> The error thrown by the test.</li> 1676</ul> 1677</li> 1678<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The path of the test file, 1679<code>undefined</code> if test was run through the REPL.</li> 1680<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The test name.</li> 1681<li><code>nesting</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The nesting level of the test.</li> 1682<li><code>testNumber</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The ordinal number of the test.</li> 1683<li><code>todo</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> Present if <a href="#contexttodomessage"><code>context.todo</code></a> is called</li> 1684<li><code>skip</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> Present if <a href="#contextskipmessage"><code>context.skip</code></a> is called</li> 1685</ul> 1686</li> 1687</ul> 1688<p>Emitted when a test fails.</p> 1689<h4>Event: <code>'test:pass'</code><span><a class="mark" href="#event-testpass" id="event-testpass">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_pass"></a></h4> 1690<ul> 1691<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1692<ul> 1693<li><code>details</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Additional execution metadata. 1694<ul> 1695<li><code>duration</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The duration of the test in milliseconds.</li> 1696</ul> 1697</li> 1698<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The path of the test file, 1699<code>undefined</code> if test was run through the REPL.</li> 1700<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The test name.</li> 1701<li><code>nesting</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The nesting level of the test.</li> 1702<li><code>testNumber</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The ordinal number of the test.</li> 1703<li><code>todo</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> Present if <a href="#contexttodomessage"><code>context.todo</code></a> is called</li> 1704<li><code>skip</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> Present if <a href="#contextskipmessage"><code>context.skip</code></a> is called</li> 1705</ul> 1706</li> 1707</ul> 1708<p>Emitted when a test passes.</p> 1709<h4>Event: <code>'test:plan'</code><span><a class="mark" href="#event-testplan" id="event-testplan">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_plan"></a></h4> 1710<ul> 1711<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1712<ul> 1713<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The path of the test file, 1714<code>undefined</code> if test was run through the REPL.</li> 1715<li><code>nesting</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The nesting level of the test.</li> 1716<li><code>count</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of subtests that have ran.</li> 1717</ul> 1718</li> 1719</ul> 1720<p>Emitted when all subtests have completed for a given test.</p> 1721<h4>Event: <code>'test:start'</code><span><a class="mark" href="#event-teststart" id="event-teststart">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_start"></a></h4> 1722<ul> 1723<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1724<ul> 1725<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The path of the test file, 1726<code>undefined</code> if test was run through the REPL.</li> 1727<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The test name.</li> 1728<li><code>nesting</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The nesting level of the test.</li> 1729</ul> 1730</li> 1731</ul> 1732<p>Emitted when a test starts reporting its own and its subtests status. 1733This event is guaranteed to be emitted in the same order as the tests are 1734defined.</p> 1735<h4>Event: <code>'test:stderr'</code><span><a class="mark" href="#event-teststderr" id="event-teststderr">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_stderr"></a></h4> 1736<ul> 1737<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1738<ul> 1739<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The path of the test file.</li> 1740<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The message written to <code>stderr</code>.</li> 1741</ul> 1742</li> 1743</ul> 1744<p>Emitted when a running test writes to <code>stderr</code>. 1745This event is only emitted if <code>--test</code> flag is passed.</p> 1746<h4>Event: <code>'test:stdout'</code><span><a class="mark" href="#event-teststdout" id="event-teststdout">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_stdout"></a></h4> 1747<ul> 1748<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1749<ul> 1750<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The path of the test file.</li> 1751<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The message written to <code>stdout</code>.</li> 1752</ul> 1753</li> 1754</ul> 1755<p>Emitted when a running test writes to <code>stdout</code>. 1756This event is only emitted if <code>--test</code> flag is passed.</p> 1757<h4>Event: <code>'test:watch:drained'</code><span><a class="mark" href="#event-testwatchdrained" id="event-testwatchdrained">#</a></span><a aria-hidden="true" class="legacy" id="test_event_test_watch_drained"></a></h4> 1758<p>Emitted when no more tests are queued for execution in watch mode.</p> 1759</section><section><h3>Class: <code>TestContext</code><span><a class="mark" href="#class-testcontext" id="class-testcontext">#</a></span><a aria-hidden="true" class="legacy" id="test_class_testcontext"></a></h3> 1760<div class="api_metadata"> 1761<details class="changelog"><summary>History</summary> 1762<table> 1763<tbody><tr><th>Version</th><th>Changes</th></tr> 1764<tr><td>v18.17.0</td> 1765<td><p>The <code>before</code> function was added to TestContext.</p></td></tr> 1766<tr><td>v18.0.0</td> 1767<td><p><span>Added in: v18.0.0</span></p></td></tr> 1768</tbody></table> 1769</details> 1770</div> 1771<p>An instance of <code>TestContext</code> is passed to each test function in order to 1772interact with the test runner. However, the <code>TestContext</code> constructor is not 1773exposed as part of the API.</p> 1774<h4><code>context.before([fn][, options])</code><span><a class="mark" href="#contextbeforefn-options" id="contextbeforefn-options">#</a></span><a aria-hidden="true" class="legacy" id="test_context_before_fn_options"></a></h4> 1775<div class="api_metadata"> 1776<span>Added in: v18.17.0</span> 1777</div> 1778<ul> 1779<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The hook function. The first argument 1780to this function is a <a href="#class-testcontext"><code>TestContext</code></a> object. If the hook uses callbacks, 1781the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1782function.</li> 1783<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the hook. The following 1784properties are supported: 1785<ul> 1786<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress hook.</li> 1787<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the hook will fail after. 1788If unspecified, subtests inherit this value from their parent. 1789<strong>Default:</strong> <code>Infinity</code>.</li> 1790</ul> 1791</li> 1792</ul> 1793<p>This function is used to create a hook running before 1794subtest of the current test.</p> 1795<h4><code>context.beforeEach([fn][, options])</code><span><a class="mark" href="#contextbeforeeachfn-options" id="contextbeforeeachfn-options">#</a></span><a aria-hidden="true" class="legacy" id="test_context_beforeeach_fn_options"></a></h4> 1796<div class="api_metadata"> 1797<span>Added in: v18.8.0</span> 1798</div> 1799<ul> 1800<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The hook function. The first argument 1801to this function is a <a href="#class-testcontext"><code>TestContext</code></a> object. If the hook uses callbacks, 1802the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1803function.</li> 1804<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the hook. The following 1805properties are supported: 1806<ul> 1807<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress hook.</li> 1808<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the hook will fail after. 1809If unspecified, subtests inherit this value from their parent. 1810<strong>Default:</strong> <code>Infinity</code>.</li> 1811</ul> 1812</li> 1813</ul> 1814<p>This function is used to create a hook running 1815before each subtest of the current test.</p> 1816<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-keyword">async</span> (t) => { 1817 t.<span class="hljs-title function_">beforeEach</span>(<span class="hljs-function">(<span class="hljs-params">t</span>) =></span> t.<span class="hljs-title function_">diagnostic</span>(<span class="hljs-string">`about to run <span class="hljs-subst">${t.name}</span>`</span>)); 1818 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>( 1819 <span class="hljs-string">'This is a subtest'</span>, 1820 <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1821 assert.<span class="hljs-title function_">ok</span>(<span class="hljs-string">'some relevant assertion here'</span>); 1822 }, 1823 ); 1824});</code> <button class="copy-button">copy</button></pre> 1825<h4><code>context.after([fn][, options])</code><span><a class="mark" href="#contextafterfn-options" id="contextafterfn-options">#</a></span><a aria-hidden="true" class="legacy" id="test_context_after_fn_options"></a></h4> 1826<div class="api_metadata"> 1827<span>Added in: v18.13.0</span> 1828</div> 1829<ul> 1830<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The hook function. The first argument 1831to this function is a <a href="#class-testcontext"><code>TestContext</code></a> object. If the hook uses callbacks, 1832the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1833function.</li> 1834<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the hook. The following 1835properties are supported: 1836<ul> 1837<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress hook.</li> 1838<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the hook will fail after. 1839If unspecified, subtests inherit this value from their parent. 1840<strong>Default:</strong> <code>Infinity</code>.</li> 1841</ul> 1842</li> 1843</ul> 1844<p>This function is used to create a hook that runs after the current test 1845finishes.</p> 1846<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-keyword">async</span> (t) => { 1847 t.<span class="hljs-title function_">after</span>(<span class="hljs-function">(<span class="hljs-params">t</span>) =></span> t.<span class="hljs-title function_">diagnostic</span>(<span class="hljs-string">`finished running <span class="hljs-subst">${t.name}</span>`</span>)); 1848 assert.<span class="hljs-title function_">ok</span>(<span class="hljs-string">'some relevant assertion here'</span>); 1849});</code> <button class="copy-button">copy</button></pre> 1850<h4><code>context.afterEach([fn][, options])</code><span><a class="mark" href="#contextaftereachfn-options" id="contextaftereachfn-options">#</a></span><a aria-hidden="true" class="legacy" id="test_context_aftereach_fn_options"></a></h4> 1851<div class="api_metadata"> 1852<span>Added in: v18.8.0</span> 1853</div> 1854<ul> 1855<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The hook function. The first argument 1856to this function is a <a href="#class-testcontext"><code>TestContext</code></a> object. If the hook uses callbacks, 1857the callback function is passed as the second argument. <strong>Default:</strong> A no-op 1858function.</li> 1859<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the hook. The following 1860properties are supported: 1861<ul> 1862<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress hook.</li> 1863<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the hook will fail after. 1864If unspecified, subtests inherit this value from their parent. 1865<strong>Default:</strong> <code>Infinity</code>.</li> 1866</ul> 1867</li> 1868</ul> 1869<p>This function is used to create a hook running 1870after each subtest of the current test.</p> 1871<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-keyword">async</span> (t) => { 1872 t.<span class="hljs-title function_">afterEach</span>(<span class="hljs-function">(<span class="hljs-params">t</span>) =></span> t.<span class="hljs-title function_">diagnostic</span>(<span class="hljs-string">`finished running <span class="hljs-subst">${t.name}</span>`</span>)); 1873 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>( 1874 <span class="hljs-string">'This is a subtest'</span>, 1875 <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1876 assert.<span class="hljs-title function_">ok</span>(<span class="hljs-string">'some relevant assertion here'</span>); 1877 }, 1878 ); 1879});</code> <button class="copy-button">copy</button></pre> 1880<h4><code>context.diagnostic(message)</code><span><a class="mark" href="#contextdiagnosticmessage" id="contextdiagnosticmessage">#</a></span><a aria-hidden="true" class="legacy" id="test_context_diagnostic_message"></a></h4> 1881<div class="api_metadata"> 1882<span>Added in: v18.0.0</span> 1883</div> 1884<ul> 1885<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Message to be reported.</li> 1886</ul> 1887<p>This function is used to write diagnostics to the output. Any diagnostic 1888information is included at the end of the test's results. This function does 1889not return a value.</p> 1890<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1891 t.<span class="hljs-title function_">diagnostic</span>(<span class="hljs-string">'A diagnostic message'</span>); 1892});</code> <button class="copy-button">copy</button></pre> 1893<h4><code>context.name</code><span><a class="mark" href="#contextname" id="contextname">#</a></span><a aria-hidden="true" class="legacy" id="test_context_name"></a></h4> 1894<div class="api_metadata"> 1895<span>Added in: v18.8.0</span> 1896</div> 1897<p>The name of the test.</p> 1898<h4><code>context.runOnly(shouldRunOnlyTests)</code><span><a class="mark" href="#contextrunonlyshouldrunonlytests" id="contextrunonlyshouldrunonlytests">#</a></span><a aria-hidden="true" class="legacy" id="test_context_runonly_shouldrunonlytests"></a></h4> 1899<div class="api_metadata"> 1900<span>Added in: v18.0.0</span> 1901</div> 1902<ul> 1903<li><code>shouldRunOnlyTests</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether or not to run <code>only</code> tests.</li> 1904</ul> 1905<p>If <code>shouldRunOnlyTests</code> is truthy, the test context will only run tests that 1906have the <code>only</code> option set. Otherwise, all tests are run. If Node.js was not 1907started with the <a href="cli.html#--test-only"><code>--test-only</code></a> command-line option, this function is a 1908no-op.</p> 1909<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1910 <span class="hljs-comment">// The test context can be set to run subtests with the 'only' option.</span> 1911 t.<span class="hljs-title function_">runOnly</span>(<span class="hljs-literal">true</span>); 1912 <span class="hljs-keyword">return</span> <span class="hljs-title class_">Promise</span>.<span class="hljs-title function_">all</span>([ 1913 t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'this subtest is now skipped'</span>), 1914 t.<span class="hljs-title function_">test</span>(<span class="hljs-string">'this subtest is run'</span>, { <span class="hljs-attr">only</span>: <span class="hljs-literal">true</span> }), 1915 ]); 1916});</code> <button class="copy-button">copy</button></pre> 1917<h4><code>context.signal</code><span><a class="mark" href="#contextsignal" id="contextsignal">#</a></span><a aria-hidden="true" class="legacy" id="test_context_signal"></a></h4> 1918<div class="api_metadata"> 1919<span>Added in: v18.7.0</span> 1920</div> 1921<ul> 1922<li><a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Can be used to abort test subtasks when the test has been 1923aborted.</li> 1924</ul> 1925<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-keyword">async</span> (t) => { 1926 <span class="hljs-keyword">await</span> <span class="hljs-title function_">fetch</span>(<span class="hljs-string">'some/uri'</span>, { <span class="hljs-attr">signal</span>: t.<span class="hljs-property">signal</span> }); 1927});</code> <button class="copy-button">copy</button></pre> 1928<h4><code>context.skip([message])</code><span><a class="mark" href="#contextskipmessage" id="contextskipmessage">#</a></span><a aria-hidden="true" class="legacy" id="test_context_skip_message"></a></h4> 1929<div class="api_metadata"> 1930<span>Added in: v18.0.0</span> 1931</div> 1932<ul> 1933<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Optional skip message.</li> 1934</ul> 1935<p>This function causes the test's output to indicate the test as skipped. If 1936<code>message</code> is provided, it is included in the output. Calling <code>skip()</code> does 1937not terminate execution of the test function. This function does not return a 1938value.</p> 1939<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1940 <span class="hljs-comment">// Make sure to return here as well if the test contains additional logic.</span> 1941 t.<span class="hljs-title function_">skip</span>(<span class="hljs-string">'this is skipped'</span>); 1942});</code> <button class="copy-button">copy</button></pre> 1943<h4><code>context.todo([message])</code><span><a class="mark" href="#contexttodomessage" id="contexttodomessage">#</a></span><a aria-hidden="true" class="legacy" id="test_context_todo_message"></a></h4> 1944<div class="api_metadata"> 1945<span>Added in: v18.0.0</span> 1946</div> 1947<ul> 1948<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Optional <code>TODO</code> message.</li> 1949</ul> 1950<p>This function adds a <code>TODO</code> directive to the test's output. If <code>message</code> is 1951provided, it is included in the output. Calling <code>todo()</code> does not terminate 1952execution of the test function. This function does not return a value.</p> 1953<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 1954 <span class="hljs-comment">// This test is marked as `TODO`</span> 1955 t.<span class="hljs-title function_">todo</span>(<span class="hljs-string">'this is a todo'</span>); 1956});</code> <button class="copy-button">copy</button></pre> 1957<h4><code>context.test([name][, options][, fn])</code><span><a class="mark" href="#contexttestname-options-fn" id="contexttestname-options-fn">#</a></span><a aria-hidden="true" class="legacy" id="test_context_test_name_options_fn"></a></h4> 1958<div class="api_metadata"> 1959<details class="changelog"><summary>History</summary> 1960<table> 1961<tbody><tr><th>Version</th><th>Changes</th></tr> 1962<tr><td>v18.8.0</td> 1963<td><p>Add a <code>signal</code> option.</p></td></tr> 1964<tr><td>v18.7.0</td> 1965<td><p>Add a <code>timeout</code> option.</p></td></tr> 1966<tr><td>v18.0.0</td> 1967<td><p><span>Added in: v18.0.0</span></p></td></tr> 1968</tbody></table> 1969</details> 1970</div> 1971<ul> 1972<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The name of the subtest, which is displayed when reporting 1973test results. <strong>Default:</strong> The <code>name</code> property of <code>fn</code>, or <code>'<anonymous>'</code> if 1974<code>fn</code> does not have a name.</li> 1975<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Configuration options for the subtest. The following 1976properties are supported: 1977<ul> 1978<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> If a number is provided, 1979then that many tests would run in parallel within the application thread. 1980If <code>true</code>, it would run all subtests in parallel. 1981If <code>false</code>, it would only run one test at a time. 1982If unspecified, subtests inherit this value from their parent. 1983<strong>Default:</strong> <code>null</code>.</li> 1984<li><code>only</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If truthy, and the test context is configured to run 1985<code>only</code> tests, then this test will be run. Otherwise, the test is skipped. 1986<strong>Default:</strong> <code>false</code>.</li> 1987<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Allows aborting an in-progress test.</li> 1988<li><code>skip</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If truthy, the test is skipped. If a string is 1989provided, that string is displayed in the test results as the reason for 1990skipping the test. <strong>Default:</strong> <code>false</code>.</li> 1991<li><code>todo</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If truthy, the test marked as <code>TODO</code>. If a string 1992is provided, that string is displayed in the test results as the reason why 1993the test is <code>TODO</code>. <strong>Default:</strong> <code>false</code>.</li> 1994<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> A number of milliseconds the test will fail after. 1995If unspecified, subtests inherit this value from their parent. 1996<strong>Default:</strong> <code>Infinity</code>.</li> 1997</ul> 1998</li> 1999<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> The function under test. The first argument 2000to this function is a <a href="#class-testcontext"><code>TestContext</code></a> object. If the test uses callbacks, 2001the callback function is passed as the second argument. <strong>Default:</strong> A no-op 2002function.</li> 2003<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Resolved with <code>undefined</code> once the test completes.</li> 2004</ul> 2005<p>This function is used to create subtests under the current test. This function 2006behaves in the same fashion as the top level <a href="#testname-options-fn"><code>test()</code></a> function.</p> 2007<pre><code class="language-js"><span class="hljs-title function_">test</span>(<span class="hljs-string">'top level test'</span>, <span class="hljs-keyword">async</span> (t) => { 2008 <span class="hljs-keyword">await</span> t.<span class="hljs-title function_">test</span>( 2009 <span class="hljs-string">'This is a subtest'</span>, 2010 { <span class="hljs-attr">only</span>: <span class="hljs-literal">false</span>, <span class="hljs-attr">skip</span>: <span class="hljs-literal">false</span>, <span class="hljs-attr">concurrency</span>: <span class="hljs-number">1</span>, <span class="hljs-attr">todo</span>: <span class="hljs-literal">false</span> }, 2011 <span class="hljs-function">(<span class="hljs-params">t</span>) =></span> { 2012 assert.<span class="hljs-title function_">ok</span>(<span class="hljs-string">'some relevant assertion here'</span>); 2013 }, 2014 ); 2015});</code> <button class="copy-button">copy</button></pre> 2016</section><section><h3>Class: <code>SuiteContext</code><span><a class="mark" href="#class-suitecontext" id="class-suitecontext">#</a></span><a aria-hidden="true" class="legacy" id="test_class_suitecontext"></a></h3> 2017<div class="api_metadata"> 2018<span>Added in: v18.7.0</span> 2019</div> 2020<p>An instance of <code>SuiteContext</code> is passed to each suite function in order to 2021interact with the test runner. However, the <code>SuiteContext</code> constructor is not 2022exposed as part of the API.</p> 2023<h4><code>context.name</code><span><a class="mark" href="#contextname_1" id="contextname_1">#</a></span><a aria-hidden="true" class="legacy" id="test_context_name_1"></a></h4> 2024<div class="api_metadata"> 2025<span>Added in: v18.8.0</span> 2026</div> 2027<p>The name of the suite.</p> 2028<h4><code>context.signal</code><span><a class="mark" href="#contextsignal_1" id="contextsignal_1">#</a></span><a aria-hidden="true" class="legacy" id="test_context_signal_1"></a></h4> 2029<div class="api_metadata"> 2030<span>Added in: v18.7.0</span> 2031</div> 2032<ul> 2033<li><a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> Can be used to abort test subtasks when the test has been 2034aborted.</li> 2035</ul></section> 2036 <!-- API END --> 2037 </div> 2038 </div> 2039 </div> 2040</body> 2041</html> 2042