Testing Asynchronous Functions

Async tests must wait for the Promise being tested. A missing await can make tests finish before an assertion executes or before a rejection is observed. Test both resolved values and expected rejections with your runner's async assertion helpers.

await pauses this test function until loadStatus resolves. The assertion then checks the value. The rejection handler marks the process as failed if the async test rejects.

Calling an async function without awaiting or returning its Promise can hide delayed failures from a test runner.

Save as testing-asynchronous-functions.ts. The following program passed strict TypeScript compilation, and the displayed output was captured by executing its emitted JavaScript with Node.js 22.16.0.

TypeScript source

async function loadStatus(): Promise<string> { return "ready"; }
async function test(): Promise<void> {
  const status = await loadStatus();
  if (status !== "ready") throw new Error("Unexpected status");
  console.log("Async test passed");
}
test().catch(error => { console.error(error); process.exitCode = 1; });

Verified output

Async test passed

Compile: npx tsc --strict --target es2022 --module commonjs testing-asynchronous-functions.ts; run: node testing-asynchronous-functions.js. For Node.js API examples, install @types/node first. For browser projects, use the browser-specific instructions below.

The example demonstrates the code-level behavior; the related configuration or test commands are shown separately when needed.

await pauses this test function until loadStatus resolves. The assertion then checks the value. The rejection handler marks the process as failed if the async test rejects.

Predict what changes if you alter one input. Then run the code to compare your reasoning with the real output.

Practical project lab: These are real configuration and source-file examples, not a TypeScript object that merely describes settings. Place the files at the named paths relative to one project directory.

service.ts

export const status = async (): Promise<string> => "ready";

service.test.ts

import {test} from "node:test";
import {strict as assert} from "node:assert";
import {status} from "./service";
test("awaits result",async()=> { assert.equal(await status(), "ready"); });

Commands

npx tsc --strict --module commonjs --target es2022 service.ts service.test.ts
node --test service.test.js

An async test callback returns a Promise to the test runner.

This local compiler or test-runner mini-project was validated in addition to the primary program.

Calling an async function without awaiting or returning its Promise can hide delayed failures from a test runner.

Identify whether the failure is a type-checking issue, a configuration issue, or a runtime behavior issue before choosing a fix.

Add an async function that rejects and use a try/catch assertion to verify its error message.

Write down your expected result first. For configuration examples, compare compiler output and diagnostics; for test examples, make the assertion fail deliberately to verify that the tool reports it.

For the exact current options and platform behavior, consult the official documentation. These examples were verified using the tool versions described above.

Async tests must wait for the Promise being tested.

Run the primary example, then complete the practice task or environment-specific lab.