feat(testing): Implement "assertSnapshot"

node/_tools/test/common/index.js

@@ -51,6 +51,7 @@ let knownGlobals = [
   getParent,
   window,
   self,
+  reportError,
 ];
 
 if (global.AbortController)

testing/README.md

@@ -31,6 +31,7 @@ pretty-printed diff of failing assertion.
   `expected` values.
 - `assertObjectMatch()` - Make an assertion that `actual` object match
   `expected` subset object
+- `assertSnapshot()` - Make an assertion that `actual` matches a snapshot
 - `assertThrows()` - Expects the passed `fn` to throw. If `fn` does not throw,
   this function does. Also compares any errors thrown to an optional expected
   `Error` class and checks that the error `.message` includes an optional
@@ -87,6 +88,22 @@ Deno.test("isNotStrictlyEqual", function (): void {
 });
 ```
 
+Using `assertSnapshot()`:
+
+For more usage information, see [Snapshot Testing](#snapshot-testing).
+
+```ts
+import { assertSnapshot } from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
+
+Deno.test("isSnapshotMatch", async function (t): Promise<void> {
+  const a = {
+    hello: "world!",
+    example: 123,
+  };
+  await assertSnapshot(t, a);
+});
+```
+
 Using `assertThrows()`:
 
 ```ts
@@ -154,6 +171,76 @@ Deno.test("fails", async function () {
 });
 ```
 
+## Snapshot Testing
+
+### Basic usage:
+
+The `assertSnapshot` function will create a snapshot of a value and compare it
+to a reference snapshot, which is stored alongside the test file in the
+`__snapshots__` directory.
+
+```ts
+// example_test.ts
+import { assertSnapshot } from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
+
+Deno.test("isSnapshotMatch", async function (t): Promise<void> {
+  const a = {
+    hello: "world!",
+    example: 123,
+  };
+  await assertSnapshot(t, a);
+});
+```
+
+```js
+// __snapshots__/example_test.ts.snap
+export const snapshot = {};
+
+snapshot[`isSnapshotMatch 1`] = `
+{
+  example: 123,
+  hello: "world!",
+}
+`;
+```
+
+Calling `assertSnapshot` in a test will throw an `AssertionError`, causing the
+test to fail, if the snapshot created during the test does not match the one in
+the snapshot file.
+
+### Updating Snapshots:
+
+When adding new snapshot assertions to your test suite, or when intentionally
+making changes which cause your snapshots to fail, you can update your snapshots
+by running the snapshot tests in update mode. Tests can be run in update mode by
+passing the `--update` or `-u` flag as an argument when running the test. When
+this flag is passed, then any snapshots which do not match will be updated.
+
+```sh
+deno test --allow-all -- --update
+```
+
+Additionally, new snapshots will only be created when this flag is present.
+
+### Permissions:
+
+When running snapshot tests, the `--allow-read` permission must be enabled, or
+else any calls to `assertSnapshot` will fail due to insufficient permissions.
+Additionally, when updating snapshots, the `--allow-write` permission must also
+be enabled, as this is required in order to update snapshot files.
+
+The `assertSnapshot` function will only attempt to read from and write to
+snapshot files. As such, the allow list for `--allow-read` and `--allow-write`
+can be limited to only include existing snapshot files, if so desired.
+
+### Version Control:
+
+Snapshot testing works best when changes to snapshot files are comitted
+alongside other code changes. This allows for changes to reference snapshots to
+be reviewed along side the code changes that caused them, and ensures that when
+others pull your changes, their tests will pass without needing to update
+snapshots locally.
+
 ## Benching
 
 These APIs are deprecated. Use Deno.bench() instead. See

testing/__snapshots__/snapshot_test.ts.snap

@@ -0,0 +1,178 @@
+export const snapshot = {};
+
+snapshot[`Snapshot Test 1`] = `
+{
+  a: 1,
+  b: 2,
+}
+`;
+
+snapshot[`Snapshot Test 2`] = `
+TestClass {
+  a: 1,
+  b: 2,
+}
+`;
+
+snapshot[`Snapshot Test 3`] = `
+Map {
+  "Hello" => "World!",
+  1 => 2,
+  [Function] => "World!",
+}
+`;
+
+snapshot[`Snapshot Test 4`] = `
+Set {
+  1,
+  2,
+  3,
+}
+`;
+
+snapshot[`Snapshot Test 5`] = `
+{
+  fn: [Function: fn],
+}
+`;
+
+snapshot[`Snapshot Test 6`] = `[Function: fn]`;
+
+snapshot[`Snapshot Test 7`] = `
+[
+  1,
+  2,
+  3,
+]
+`;
+
+snapshot[`Snapshot Test 8`] = `"hello world"`;
+
+snapshot[`Snapshot Test - step 1`] = `
+{
+  a: 1,
+  b: 2,
+}
+`;
+
+snapshot[`Snapshot Test - step > Nested 1`] = `
+TestClass {
+  a: 1,
+  b: 2,
+}
+`;
+
+snapshot[`Snapshot Test - step > Nested 2`] = `
+Map {
+  "Hello" => "World!",
+  1 => 2,
+  [Function] => "World!",
+}
+`;
+
+snapshot[`Snapshot Test - step > Nested > Nested Nested 1`] = `
+Set {
+  1,
+  2,
+  3,
+}
+`;
+
+snapshot[`Snapshot Test - step > Nested > Nested Nested 2`] = `
+{
+  fn: [Function: fn],
+}
+`;
+
+snapshot[`Snapshot Test - step > Nested > Nested Nested 3`] = `[Function: fn]`;
+
+snapshot[`Snapshot Test - step > Nested 3`] = `
+[
+  1,
+  2,
+  3,
+]
+`;
+
+snapshot[`Snapshot Test - step 2`] = `"hello world"`;
+
+snapshot[`Snapshot Test - Adverse String \\ \` \${} 1`] = `"\\\\ \` \${}"`;
+
+snapshot[`Snapshot Test - Failed Assertion > Object 1`] = `
+[
+  1,
+  2,
+  3,
+]
+`;
+
+snapshot[`Snapshot Test - Failed Assertion > Object 2`] = `
+[
+  "Snapshot does not match:",
+  "",
+  "",
+  "    [Diff] Actual / Expected",
+  "",
+  "",
+  "    [",
+  "      1,",
+  "      2,",
+  "+     3,",
+  "    ]",
+  "",
+]
+`;
+
+snapshot[`Snapshot Test - Failed Assertion > String 1`] = `"Hello World!"`;
+
+snapshot[`Snapshot Test - Failed Assertion > String 2`] = `
+[
+  "Snapshot does not match:",
+  "",
+  "",
+  "    [Diff] Actual / Expected",
+  "",
+  "",
+  '-   "Hello!"',
+  '+   "Hello World!"',
+  "",
+  "",
+]
+`;
+
+snapshot[`Snapshot Test - Update 1`] = `
+[
+  "running 1 test from testing/.tmp/test.ts",
+  "Snapshot Test - Update ... ok (--ms)",
+  "",
+  " > 1 snapshots updated.",
+  "",
+  "test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (--ms)",
+  "",
+  "",
+]
+`;
+
+snapshot[`Snapshot Test - Update 2`] = `
+[
+  "running 1 test from testing/.tmp/test.ts",
+  "Snapshot Test - Update ... ok (--ms)",
+  "",
+  "test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (--ms)",
+  "",
+  "",
+]
+`;
+
+snapshot[`Snapshot Test - Update 3`] = `
+[
+  "running 1 test from testing/.tmp/test.ts",
+  "Snapshot Test - Update ... ok (--ms)",
+  "",
+  " > 1 snapshots updated.",
+  "",
+  "test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (--ms)",
+  "",
+  "",
+]
+`;

testing/_diff.ts

@@ -1,6 +1,16 @@
 // Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
+import {
+  bgGreen,
+  bgRed,
+  bold,
+  gray,
+  green,
+  red,
+  white,
+} from "../fmt/colors.ts";
+
 interface FarthestPoint {
   y: number;
   id: number;
@@ -358,3 +368,68 @@ export function diffstr(A: string, B: string) {
 
   return diffResult;
 }
+
+/**
+ * Colors the output of assertion diffs
+ * @param diffType Difference type, either added or removed
+ */
+function createColor(
+  diffType: DiffType,
+  { background = false } = {},
+): (s: string) => string {
+  switch (diffType) {
+    case DiffType.added:
+      return (s: string): string =>
+        background ? bgGreen(white(s)) : green(bold(s));
+    case DiffType.removed:
+      return (s: string): string => background ? bgRed(white(s)) : red(bold(s));
+    default:
+      return white;
+  }
+}
+
+/**
+ * Prefixes `+` or `-` in diff output
+ * @param diffType Difference type, either added or removed
+ */
+function createSign(diffType: DiffType): string {
+  switch (diffType) {
+    case DiffType.added:
+      return "+   ";
+    case DiffType.removed:
+      return "-   ";
+    default:
+      return "    ";
+  }
+}
+
+export function buildMessage(
+  diffResult: ReadonlyArray<DiffResult<string>>,
+  { stringDiff = false } = {},
+): string[] {
+  const messages: string[] = [], diffMessages: string[] = [];
+  messages.push("");
+  messages.push("");
+  messages.push(
+    `    ${gray(bold("[Diff]"))} ${red(bold("Actual"))} / ${
+      green(bold("Expected"))
+    }`,
+  );
+  messages.push("");
+  messages.push("");
+  diffResult.forEach((result: DiffResult<string>): void => {
+    const c = createColor(result.type);
+    const line = result.details?.map((detail) =>
+      detail.type !== DiffType.common
+        ? createColor(detail.type, { background: true })(detail.value)
+        : detail.value
+    ).join("") ?? result.value;
+    diffMessages.push(c(`${
+      createSign(result.type)
+    }${line}`));
+  });
+  messages.push(...(stringDiff ? [diffMessages.join("")] : diffMessages));
+  messages.push("");
+
+  return messages;
+}