BREAKING(asserts): move std/testing/asserts to std/assert

.github/workflows/ci.yml

@@ -94,9 +94,6 @@ jobs:
       - name: Check Import paths in Docs
         run: "deno task lint:doc-imports"
 
-      - name: Check non-test assertions
-        run: deno task lint:check-assertions
-
       - name: Spell-check
         uses: crate-ci/typos@master
         with:

README.md

@@ -106,13 +106,6 @@ _For maintainers_:
 
 To release a new version a tag in the form of `x.y.z` should be added.
 
-### Internal Assertions
-
-All internal non-test code, that is files that do not have `test` or `bench` in
-the name, must use the assertion functions within `_utils/asserts.ts` and not
-`testing/asserts.ts`. This is to create a separation of concerns between
-internal and testing assertions.
-
 ### Types
 
 Deno is moving away from non-native IO functions and interfaces in favor of the

testing/_diff_test.ts → _util/diff_test.ts

@@ -1,6 +1,6 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
-import { diff, diffstr, DiffType } from "./_diff.ts";
-import { assertEquals } from "../testing/asserts.ts";
+import { diff, diffstr, DiffType } from "./diff.ts";
+import { assertEquals } from "../assert/mod.ts";
 
 Deno.test({
   name: "empty",

archive/tar.ts

@@ -42,7 +42,7 @@ export { type TarInfo, type TarMeta, type TarOptions };
 
 import { MultiReader } from "../io/multi_reader.ts";
 import { Buffer } from "../io/buffer.ts";
-import { assert } from "../_util/asserts.ts";
+import { assert } from "../assert/assert.ts";
 import { recordSize } from "./_common.ts";
 
 const ustar = "ustar\u000000";

archive/tar_test.ts

@@ -9,7 +9,7 @@
  * **to run this test**
  * deno run --allow-read archive/tar_test.ts
  */
-import { assert, assertEquals } from "../testing/asserts.ts";
+import { assert, assertEquals } from "../assert/mod.ts";
 import { resolve } from "../path/mod.ts";
 import { Tar } from "./tar.ts";
 import { Untar } from "./untar.ts";

archive/untar_test.ts

@@ -1,5 +1,5 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
-import { assert, assertEquals, assertExists } from "../testing/asserts.ts";
+import { assert, assertEquals, assertExists } from "../assert/mod.ts";
 import { resolve } from "../path/mod.ts";
 import { Tar, type TarMeta } from "./tar.ts";
 import { TarEntry, type TarHeader, Untar } from "./untar.ts";

assert/_constants.ts

@@ -0,0 +1,2 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+export const CAN_NOT_DISPLAY = "[Cannot display]";

testing/_format_test.ts → assert/_format_test.ts

@@ -1,6 +1,6 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 import { green, red, stripColor } from "../fmt/colors.ts";
-import { assertEquals, assertThrows } from "./asserts.ts";
+import { assertEquals, assertThrows } from "../assert/mod.ts";
 import { format } from "./_format.ts";
 
 Deno.test("assert diff formatting (strings)", () => {

assert/assert.ts

@@ -0,0 +1,9 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+import { AssertionError } from "./assertion_error.ts";
+
+/** Make an assertion, error will be thrown if `expr` does not have truthy value. */
+export function assert(expr: unknown, msg = ""): asserts expr {
+  if (!expr) {
+    throw new AssertionError(msg);
+  }
+}

assert/assert_almost_equals.ts

@@ -0,0 +1,41 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+import { AssertionError } from "./assertion_error.ts";
+
+/**
+ * Make an assertion that `actual` and `expected` are almost equal numbers through
+ * a given tolerance. It can be used to take into account IEEE-754 double-precision
+ * floating-point representation limitations.
+ * If the values are not almost equal then throw.
+ *
+ * @example
+ * ```ts
+ * import { assertAlmostEquals, assertThrows } from "https://deno.land/std@$STD_VERSION/assert/mod.ts";
+ *
+ * assertAlmostEquals(0.1, 0.2);
+ *
+ * // Using a custom tolerance value
+ * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-16);
+ * assertThrows(() => assertAlmostEquals(0.1 + 0.2, 0.3, 1e-17));
+ * ```
+ */
+export function assertAlmostEquals(
+  actual: number,
+  expected: number,
+  tolerance = 1e-7,
+  msg?: string,
+) {
+  if (Object.is(actual, expected)) {
+    return;
+  }
+  const delta = Math.abs(expected - actual);
+  if (delta <= tolerance) {
+    return;
+  }
+
+  const msgSuffix = msg ? `: ${msg}` : ".";
+  const f = (n: number) => Number.isInteger(n) ? n : n.toExponential();
+  throw new AssertionError(
+    `Expected actual: "${f(actual)}" to be close to "${f(expected)}": \
+delta "${f(delta)}" is greater than "${f(tolerance)}"${msgSuffix}`,
+  );
+}

assert/assert_almost_equals_test.ts

@@ -0,0 +1,43 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+import { assertAlmostEquals, AssertionError, assertThrows } from "./mod.ts";
+
+Deno.test("assert almost equals number", () => {
+  //Default precision
+  assertAlmostEquals(-0, +0);
+  assertAlmostEquals(Math.PI, Math.PI);
+  assertAlmostEquals(0.1 + 0.2, 0.3);
+  assertAlmostEquals(NaN, NaN);
+  assertAlmostEquals(Number.NaN, Number.NaN);
+  assertThrows(() => assertAlmostEquals(1, 2));
+  assertThrows(() => assertAlmostEquals(1, 1.1));
+
+  //Higher precision
+  assertAlmostEquals(0.1 + 0.2, 0.3, 1e-16);
+  assertThrows(
+    () => assertAlmostEquals(0.1 + 0.2, 0.3, 1e-17),
+    AssertionError,
+    `Expected actual: "${
+      (
+        0.1 + 0.2
+      ).toExponential()
+    }" to be close to "${(0.3).toExponential()}"`,
+  );
+
+  //Special cases
+  assertAlmostEquals(Infinity, Infinity);
+  assertThrows(
+    () => assertAlmostEquals(0, Infinity),
+    AssertionError,
+    'Expected actual: "0" to be close to "Infinity"',
+  );
+  assertThrows(
+    () => assertAlmostEquals(-Infinity, +Infinity),
+    AssertionError,
+    'Expected actual: "-Infinity" to be close to "Infinity"',
+  );
+  assertThrows(
+    () => assertAlmostEquals(Infinity, NaN),
+    AssertionError,
+    'Expected actual: "Infinity" to be close to "NaN"',
+  );
+});

assert/assert_array_includes.ts

@@ -0,0 +1,46 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+import { equal } from "./equal.ts";
+import { format } from "./_format.ts";
+import { AssertionError } from "./assertion_error.ts";
+
+/**
+ * Make an assertion that `actual` includes the `expected` values.
+ * If not then an error will be thrown.
+ *
+ * Type parameter can be specified to ensure values under comparison have the same type.
+ *
+ * @example
+ * ```ts
+ * import { assertArrayIncludes } from "https://deno.land/std@$STD_VERSION/assert/assert_array_includes.ts";
+ *
+ * assertArrayIncludes<number>([1, 2], [2])
+ * ```
+ */
+export function assertArrayIncludes<T>(
+  actual: ArrayLike<T>,
+  expected: ArrayLike<T>,
+  msg?: string,
+) {
+  const missing: unknown[] = [];
+  for (let i = 0; i < expected.length; i++) {
+    let found = false;
+    for (let j = 0; j < actual.length; j++) {
+      if (equal(expected[i], actual[j])) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      missing.push(expected[i]);
+    }
+  }
+  if (missing.length === 0) {
+    return;
+  }
+
+  const msgSuffix = msg ? `: ${msg}` : ".";
+  msg = `Expected actual: "${format(actual)}" to include: "${
+    format(expected)
+  }"${msgSuffix}\nmissing: ${format(missing)}`;
+  throw new AssertionError(msg);
+}

assert/assert_array_includes_test.ts

@@ -0,0 +1,34 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+import { assertArrayIncludes, AssertionError, assertThrows } from "./mod.ts";
+
+Deno.test("ArrayContains", function () {
+  const fixture = ["deno", "iz", "luv"];
+  const fixtureObject = [{ deno: "luv" }, { deno: "Js" }];
+  assertArrayIncludes(fixture, ["deno"]);
+  assertArrayIncludes(fixtureObject, [{ deno: "luv" }]);
+  assertArrayIncludes(
+    Uint8Array.from([1, 2, 3, 4]),
+    Uint8Array.from([1, 2, 3]),
+  );
+  assertThrows(
+    () => assertArrayIncludes(fixtureObject, [{ deno: "node" }]),
+    AssertionError,
+    `Expected actual: "[
+  {
+    deno: "luv",
+  },
+  {
+    deno: "Js",
+  },
+]" to include: "[
+  {
+    deno: "node",
+  },
+]".
+missing: [
+  {
+    deno: "node",
+  },
+]`,
+  );
+});