feat: add createAssertSnapshot (#2403)

Author: bcheidemann

testing/README.md

@@ -235,6 +235,71 @@ 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.
 
+### Options:
+
+The `assertSnapshot` function optionally accepts an options object.
+
+```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, {
+    // options
+  });
+});
+```
+
+You can also configure default options for `assertSnapshot`.
+
+```ts
+// example_test.ts
+import { createAssertSnapshot } from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
+
+const assertSnapshot = createAssertSnapshot({
+  // options
+});
+```
+
+When configuring default options like this, the resulting `assertSnapshot`
+function will function the same as the default function exported from the
+snapshot module. If passed an optional options object, this will take precedence
+over the default options, where the value provded for an option differs.
+
+It is possible to "extend" an `assertSnapshot` function which has been
+configured with default options.
+
+```ts
+// example_test.ts
+import { createAssertSnapshot } from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
+import { stripColor } from "https://deno.land/std@$STD_VERSION/fmt/colors.ts";
+
+const assertSnapshot = createAssertSnapshot({
+  dir: ".snaps",
+});
+
+const assertMonochromeSnapshot = createAssertSnapshot<string>(
+  { serializer: stripColor },
+  assertSnapshot,
+);
+
+Deno.test("isSnapshotMatch", async function (t): Promise<void> {
+  const a = "\x1b[32mThis green text has had it's colours stripped\x1b[39m";
+  await assertMonochromeSnapshot(t, a);
+});
+```
+
+```js
+// .snaps/example_test.ts.snap
+export const snapshot = {};
+
+snapshot[`isSnapshotMatch 1`] = `This green text has had it's colours stripped`;
+```
+
 ### Version Control:
 
 Snapshot testing works best when changes to snapshot files are comitted

testing/__snapshots__/snapshot_test.ts.snap

@@ -364,3 +364,11 @@ snapshot[`Snapshot Test - Regression #2144 1`] = `
 `;
 
 snapshot[`Snapshot Test - Empty #2245 1`] = ``;
+
+snapshot[`SnapshotTest - createAssertSnapshot > No Options 1`] = `This green text has had it's colours stripped`;
+
+snapshot[`SnapshotTest - createAssertSnapshot - Options Object - Custom Name 1`] = `This green text has had it's colours stripped`;
+
+snapshot[`SnapshotTest - createAssertSnapshot > Message 1`] = `"This snapshot has failed as expected"`;
+
+snapshot[`SnapshotTest - createAssertSnapshot - Composite - Custom Name 1`] = `This green text has had it's colours stripped`;

testing/snapshot.ts

@@ -358,7 +358,7 @@ class AssertSnapshotContext {
  * ```
  */
 export async function assertSnapshot<T>(
-  t: Deno.TestContext,
+  context: Deno.TestContext,
   actual: T,
   options: SnapshotOptions<T>,
 ): Promise<void>;
@@ -442,3 +442,25 @@ export async function assertSnapshot(
     return context.name;
   }
 }
+
+export function createAssertSnapshot<T>(
+  options: SnapshotOptions<T>,
+  baseAssertSnapshot: typeof assertSnapshot = assertSnapshot,
+): typeof assertSnapshot {
+  return async function _assertSnapshot(
+    context: Deno.TestContext,
+    actual: T,
+    messageOrOptions?: string | SnapshotOptions<T>,
+  ): Promise<void> {
+    const mergedOptions: SnapshotOptions<T> = {
+      ...options,
+      ...(typeof messageOrOptions === "string"
+        ? {
+          msg: messageOrOptions,
+        }
+        : messageOrOptions),
+    };
+
+    await baseAssertSnapshot(context, actual, mergedOptions);
+  };
+}

testing/snapshot_test.ts

@@ -1,8 +1,14 @@
 // Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
 import { stripColor } from "../fmt/colors.ts";
 import { dirname, fromFileUrl, join, toFileUrl } from "../path/mod.ts";
-import { assert, assertInstanceOf, AssertionError, fail } from "./asserts.ts";
-import { assertSnapshot, serialize } from "./snapshot.ts";
+import {
+  assert,
+  assertInstanceOf,
+  AssertionError,
+  assertRejects,
+  fail,
+} from "./asserts.ts";
+import { assertSnapshot, createAssertSnapshot, serialize } from "./snapshot.ts";
 
 const SNAPSHOT_MODULE_URL = toFileUrl(join(
   dirname(fromFileUrl(import.meta.url)),
@@ -491,3 +497,55 @@ Deno.test("Snapshot Test - Regression #2144", async (t) => {
 Deno.test("Snapshot Test - Empty #2245", async (t) => {
   await assertSnapshot(t, "", { serializer: (x) => x });
 });
+
+Deno.test("SnapshotTest - createAssertSnapshot", async (t) => {
+  const assertMonochromeSnapshot = createAssertSnapshot<string>({
+    serializer: stripColor,
+  });
+
+  await t.step("No Options", async (t) => {
+    await assertMonochromeSnapshot(
+      t,
+      "\x1b[32mThis green text has had it's colours stripped\x1b[39m",
+    );
+  });
+
+  await t.step("Options Object", async (t) => {
+    await assertMonochromeSnapshot(
+      t,
+      "\x1b[32mThis green text has had it's colours stripped\x1b[39m",
+      {
+        name:
+          "SnapshotTest - createAssertSnapshot - Options Object - Custom Name",
+      },
+    );
+  });
+
+  await t.step("Message", async (t) => {
+    const assertMissingSnapshot = createAssertSnapshot<string>({
+      mode: "assert",
+      name: "[MISSING SNAPSHOT]",
+    });
+
+    const err = await assertRejects(async () => {
+      await assertMissingSnapshot(
+        t,
+        null,
+        "This snapshot has failed as expected",
+      );
+    }, AssertionError);
+
+    await assertSnapshot(t, err.message);
+  });
+
+  await t.step("Composite", async (t) => {
+    const assertMonochromeSnapshotComposite = createAssertSnapshot<string>({
+      name: "SnapshotTest - createAssertSnapshot - Composite - Custom Name",
+    }, assertMonochromeSnapshot);
+
+    await assertMonochromeSnapshotComposite(
+      t,
+      "\x1b[32mThis green text has had it's colours stripped\x1b[39m",
+    );
+  });
+});