Testing

This module provides a few basic utilities to make testing easier and consistent in Deno.

Usage

The module exports a test function which is the test harness in Deno. It accepts either a function (including async functions) or an object which contains a name property and a fn property. When running tests and outputting the results, the name of the past function is used, or if the object is passed, the name property is used to identify the test. If the assertion is false an AssertionError will be thrown.

Asserts are exposed in testing/asserts.ts module.

runTests() executes the declared tests. It accepts a RunOptions parameter:

Basic usage:

import { runTests, test } from "https://deno.land/std/testing/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

test({
  name: "testing example",
  fn(): void {
    assertEquals("world", "world");
    assertEquals({ hello: "world" }, { hello: "world" });
  }
});

runTests();

Short syntax (named function instead of object):

test(function example(): void {
  assertEquals("world", "world");
  assertEquals({ hello: "world" }, { hello: "world" });
});

Using assertStrictEq():

test(function isStrictlyEqual(): void {
  const a = {};
  const b = a;
  assertStrictEq(a, b);
});

// This test fails
test(function isNotStrictlyEqual(): void {
  const a = {};
  const b = {};
  assertStrictEq(a, b);
});

Using assertThrows():

test(function doesThrow(): void {
  assertThrows(
    (): void => {
      throw new TypeError("hello world!");
    }
  );
  assertThrows((): void => {
    throw new TypeError("hello world!");
  }, TypeError);
  assertThrows(
    (): void => {
      throw new TypeError("hello world!");
    },
    TypeError,
    "hello"
  );
});

// This test will not pass
test(function fails(): void {
  assertThrows(
    (): void => {
      console.log("Hello world");
    }
  );
});

Using assertThrowsAsync():

test(async function doesThrow(): Promise<void> {
  await assertThrowsAsync(
    async (): Promise<void> => {
      throw new TypeError("hello world!");
    }
  );
  await assertThrowsAsync(async (): Promise<void> => {
    throw new TypeError("hello world!");
  }, TypeError);
  await assertThrowsAsync(
    async (): Promise<void> => {
      throw new TypeError("hello world!");
    },
    TypeError,
    "hello"
  );
  await assertThrowsAsync(
    async (): Promise<void> => {
      return Promise.reject(new Error());
    }
  );
});

// This test will not pass
test(async function fails(): Promise<void> {
  await assertThrowsAsync(
    async (): Promise<void> => {
      console.log("Hello world");
    }
  );
});

Benching Usage

Basic usage:

import { runBenchmarks, bench } from "https://deno.land/std/testing/bench.ts";

bench(function forIncrementX1e9(b): void {
  b.start();
  for (let i = 0; i < 1e9; i++);
  b.stop();
});

runBenchmarks();

Averaging execution time over multiple runs:

bench({
  name: "runs100ForIncrementX1e6",
  runs: 100,
  func(b): void {
    b.start();
    for (let i = 0; i < 1e6; i++);
    b.stop();
  }
});

Benching API

bench(benchmark: BenchmarkDefinition | BenchmarkFunction): void

Registers a benchmark that will be run once runBenchmarks is called.

runBenchmarks(opts?: BenchmarkRunOptions): Promise<void>

Runs all registered benchmarks serially. Filtering can be applied by setting BenchmarkRunOptions.only and/or BenchmarkRunOptions.skip to regular expressions matching benchmark names.

runIfMain(meta: ImportMeta, opts?: BenchmarkRunOptions): Promise<void>

Runs specified benchmarks if the enclosing script is main.

Other exports
/** Provides methods for starting and stopping a benchmark clock. */
export interface BenchmarkTimer {
  start: () => void;
  stop: () => void;
}

/** Defines a benchmark through a named function. */
export interface BenchmarkFunction {
  (b: BenchmarkTimer): void | Promise<void>;
  name: string;
}

/** Defines a benchmark definition with configurable runs. */
export interface BenchmarkDefinition {
  func: BenchmarkFunction;
  name: string;
  runs?: number;
}

/** Defines runBenchmark's run constraints by matching benchmark names. */
export interface BenchmarkRunOptions {
  only?: RegExp;
  skip?: RegExp;
}

View repository on GitHub