denoland-deno/cli/js/tests/README.md

Deno runtime tests

Files in this directory are unit tests for Deno runtime.

They are run under compiled Deno binary as opposed to files in cli/js/ which are bundled and snapshotted using deno_typescript crate.

Testing Deno runtime code requires checking API under different runtime permissions (ie. running with different --allow-* flags). To accomplish this all tests exercised are created using unitTest() function.

import { unitTest } from "./test_util.ts";

unitTest(function simpleTestFn(): void {
  // test code here
});

unitTest({
    skip: Deno.build.os === "win",
    perms: { read: true, write: true },
  },
  function complexTestFn(): void {
    // test code here
  }
);

unitTest is is a wrapper function that enhances Deno.test() API in several ways:

• ability to conditionally skip tests using UnitTestOptions.skip
• ability to register required set of permissions for given test case using UnitTestOptions.perms
• sanitization of resources - ensuring that tests close all opened resources preventing interference between tests
• sanitization of async ops - ensuring that tests don't leak async ops by ensuring that all started async ops are done before test finishes

unit_test_runner.ts is main script used to run unit tests.

Runner discoveres required permissions combinations by loading cli/js/tests/unit_tests.ts and going through all registered instances of unitTest. For each discovered permission combination a new Deno process is created with respective --allow-* flags which loads cli/js/tests/unit_tests.ts and executes all unitTest that match runtime permissions.