@altano/vitest-plugins 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @altano/vitest-plugins
 
+## 1.0.0
+
+### Major Changes
+
+- 989abbb: added snapshot serializers and a matcher
+
+### Patch Changes
+
+- 4c2162f: remove unused dependencies
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,3 +1,5 @@
+/_ eslint-disable @typescript-eslint/no-empty-object-type _/
+
 # vitest-plugins
 
 [![npm](https://badgen.net/npm/v/@altano/vitest-plugins)](https://www.npmjs.com/package/@altano/vitest-plugins) ![Typed with TypeScript](https://badgen.net/npm/types/@altano/vitest-plugins) ![ESM only](https://badgen.net/badge/module/esm%20only?icon=js)
@@ -79,6 +81,14 @@ FormattedVFile {
 
 Will replace any instances of `process.cwd()` with `<cwd>` in the snapshot. Useful when serializing strings that contain absolute paths, since those will be different on other machines running the tests.
 
+### URLs
+
+Canonicalizes parts of a URL that might not be deterministic in tests. Tries to be conservative, so at the moment, this only strips the port from localhost urls, e.g. `http://localhost:1234` is converted to `http://localhost`.
+
+### HTML
+
+HTML is prettier formatted. Only works on well-formed HTML that starts with `<html` or `<!doctype`. To avoid infinitely reformatting the HTML, it is preprended with `<!-- Formatted HTML -->`.
+
 ## Matchers
 
 Vitest's error matchers let you match against the error message, but not the rest of the Error object:
@@ -124,7 +134,7 @@ expect("/private/some/path").toBePath("/some/path");
 
 ### toBeFile
 
-Verify a file exists
+Verify a file exists (on the filesystem)
 
 ```ts
 expect(import.meta.filename).toBeFile();
@@ -132,7 +142,7 @@ expect(import.meta.filename).toBeFile();
 
 ### toBeDirectory
 
-Verify a directory exists
+Verify a directory exists (on the filesystem)
 
 ```ts
 expect("/").toBeDirectory();
@@ -140,8 +150,20 @@ expect("/").toBeDirectory();
 
 ### toEqualFile
 
-Verify that the given path matches the contents of another file
+Verify that the contents of a file at a given path match the contents of a file at a another path
 
 ```ts
 expect("/some/file.txt").toEqualFile("/other/file.txt");
 ```
+
+### toHaveExifProperty
+
+Similar to the `toHaveProperty` matcher, but checks exif properties on the given buffer (or any object parseable by the `exifr` library).
+
+### toHaveHeader (on Response objects)
+
+Verify that Response has an expected header and optional value
+
+### toHaveStatus (on Response objects)
+
+Verify that a Response has an expected status code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altano/vitest-plugins",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Custom matchers and snapshot serializers to enhance vitest",
   "homepage": "https://github.com/altano/npm-packages/tree/main/packages/vitest-plugins",
   "repository": {
@@ -26,22 +26,21 @@
   },
   "dependencies": {
     "@prettier/sync": "^0.5.2",
+    "exifr": "^7.1.3",
     "serialize-error": "^11.0.3",
     "vfile": "^6.0.3",
-    "vitest": "^2.1.3"
+    "vitest": "^3.0.9"
   },
   "devDependencies": {
-    "@mdx-js/mdx": "^3.1.0",
-    "@types/node": "^20.16.5",
-    "@vitest/coverage-v8": "^2.1.3",
-    "@vitest/expect": "^2.1.3",
-    "eslint": "^9.13.0",
-    "mdast-util-mdxjs-esm": "^2.0.1",
+    "@types/node": "^22.13.10",
+    "@vitest/coverage-v8": "^3.0.9",
+    "@vitest/expect": "^3.0.9",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.22.0",
     "prettier": "^3.3.3",
-    "typescript": "^5.6.3",
-    "unified": "^11.0.5",
-    "vite": "^5.4.10",
-    "vitest": "^2.1.3",
+    "typescript": "^5.8.2",
+    "vite": "^6.2.3",
+    "vitest": "^3.0.9",
     "@altano/tsconfig": "0.0.0"
   },
   "publishConfig": {
@@ -50,6 +49,7 @@
   "scripts": {
     "check:types:src": "tsc --noEmit",
     "check:types:test": "tsc --noEmit --project ./tests/tsconfig.json",
+    "check:unused-dependencies": "depcheck",
     "clean": "rm -rf .turbo && rm -rf .tsbuildinfo && rm -rf node_modules && rm -rf dist",
     "format": "prettier --check src",
     "format:fix": "prettier --write src",

package/src/matchers/response/toHaveHeader.ts

@@ -0,0 +1,26 @@
+import type { Matcher } from "../matcher.js";
+
+const toHaveHeader: Matcher = function (
+  response: Response,
+  header: string,
+  value?: string | number,
+) {
+  const headers = response.headers;
+  const hasProperty = headers.has(header);
+  const receivedValue = headers.get(header);
+
+  const { isNot } = this;
+
+  return {
+    message: () =>
+      value === undefined
+        ? `Received ${isNot ? "should not have" : "does not have"} the header "${header}"`
+        : `Header "${header}" ${isNot ? "should not be" : "is not"} expected value`,
+    pass:
+      hasProperty && (value === undefined || this.equals(receivedValue, value)),
+    actual: receivedValue,
+    expected: value,
+  };
+};
+
+export default toHaveHeader;

package/src/matchers/response/toHaveStatus.ts

@@ -0,0 +1,20 @@
+import type { Matcher } from "../matcher.js";
+
+const toHaveStatus: Matcher = function (
+  response: Response,
+  expectedStatus: number,
+) {
+  const receivedStatus = response.status;
+
+  const { isNot } = this;
+
+  return {
+    message: () =>
+      `Status ${isNot ? "should not be expected value" : "is not expected value"}`,
+    pass: this.equals(receivedStatus, expectedStatus),
+    actual: receivedStatus,
+    expected: expectedStatus,
+  };
+};
+
+export default toHaveStatus;

package/src/matchers/setup.ts

@@ -6,12 +6,20 @@ import toBeDirectory from "./toBeDirectory.js";
 import toEqualFile from "./toEqualFile.js";
 import toMatchError from "./toMatchError.js";
 import toThrowErrorMatching from "./toThrowErrorMatching.js";
+import toHaveExifProperty from "./toHaveExifProperty.js";
+import toHaveHeader from "./response/toHaveHeader.js";
+import toHaveStatus from "./response/toHaveStatus.js";
 
 expect.extend({
-  toBePath,
-  toBeFile,
   toBeDirectory,
+  toBeFile,
+  toBePath,
   toEqualFile,
+  toHaveExifProperty,
   toMatchError,
   toThrowErrorMatching,
+
+  // Response matchers
+  toHaveHeader,
+  toHaveStatus,
 });

package/src/matchers/toHaveExifProperty.ts

@@ -0,0 +1,32 @@
+import { parse } from "exifr";
+import type { Matcher } from "./matcher.js";
+
+export type Input = Parameters<typeof parse>[0];
+
+const toHaveExifProperty: Matcher = async function (
+  buffer: Input,
+  property: string,
+  value?: string | number,
+) {
+  const exifData = (await parse(buffer)) as unknown;
+  const hasProperty = Object.prototype.hasOwnProperty.call(exifData, property);
+
+  const receivedValue =
+    // @ts-expect-error we're checking for property existence, so obviously this
+    // might not be valid. don't need a TS error to tell us that.
+    exifData[property] as unknown;
+  const { isNot } = this;
+
+  return {
+    message: () =>
+      value === undefined
+        ? `Received ${isNot ? "should not have" : "does not have"} the property "${property}"`
+        : `Property "${property}" ${isNot ? "should not be expected value" : "is not expected value"}`,
+    pass:
+      hasProperty && (value === undefined || this.equals(receivedValue, value)),
+    actual: receivedValue,
+    expected: value,
+  };
+};
+
+export default toHaveExifProperty;

package/src/matchers/types.d.ts

@@ -4,18 +4,57 @@ import type { Assertion, AsymmetricMatchersContaining } from "vitest";
 
 interface CustomMatchers<R = unknown> {
   /**
-   * compare the realpath (canonical path) of expected/received
+   * Verify the realpath (canonical path) of expected. More lenient than a
+   * string check when dealing with logical paths, symlinks, etc.
    */
   toBePath(expected: string): R;
+  /** Verify a file exists (on the filesystem) */
   toBeFile(): R;
+  /** Verify a directory exists (on the filesystem) */
   toBeDirectory(): R;
+  /** Verify that the contents of a file at a given path match the contents of a file at a another path */
   toEqualFile(pathOfFileWithExpectedContents: string): R;
+  /**
+   * Similar to the `toHaveProperty` matcher, but checks exif properties on the
+   * given buffer (or any object parseable by the `exifr` library).
+   */
+  toHaveExifProperty(property: string, value?: string | number): Promise<R>;
+  /**
+   * Verify any part of an error object (e.g. the stack):
+   *
+   * @example
+   * expect(new Error("face")).toMatchError(
+   *   expect.objectContaining({
+   *     stack: expect.stringContaining("readme.spec.ts"),
+   *   }),
+   * );
+   */
   toMatchError(expected: unknown): R;
+  /**
+   * Verify any part of a _thrown_ error object (e.g. the stack):
+   *
+   * @example
+   * expect(() => {
+   *   throw new Error("face");
+   * }).toThrowErrorMatching(
+   *   expect.objectContaining({
+   *     stack: expect.stringContaining("readme.spec.ts"),
+   *   }),
+   * );
+   */
   toThrowErrorMatching(expected: unknown): R;
 }
 
+interface ResponseMatchers<R = unknown> {
+  /** Verify that Response has an expected header and optional value */
+  toHaveHeader(header: string, value?: string | number): R;
+  /** Verify that a Response has an expected status code */
+  toHaveStatus(expectedStatus: number): R;
+}
+
 /* eslint-disable @typescript-eslint/no-empty-object-type */
 declare module "vitest" {
   interface Assertion<T> extends CustomMatchers<T> {}
+  interface Assertion<T> extends ResponseMatchers<T> {}
   interface AsymmetricMatchersContaining extends CustomMatchers {}
 }

package/src/serializers/html.ts

@@ -0,0 +1,39 @@
+import prettier from "@prettier/sync";
+import prettierConfig from "./.prettierrc.json" with { type: "json" };
+import type { Options } from "prettier";
+import type { SnapshotSerializer } from "vitest";
+
+const htmlPattern = /^(<html|<!doctype)/gi;
+
+/**
+ * Prettier format html
+ */
+function formatHtml(unformattedHtml: string): string {
+  try {
+    const formattedHtml = prettier
+      .format(unformattedHtml, {
+        filepath: "index.html",
+        ...(prettierConfig as Options),
+      })
+      .trim();
+    return `<!-- Formatted HTML -->
+${formattedHtml}`;
+  } catch (e: unknown) {
+    // Prettier can't parse this text as html. That's fine, pass it through
+    // unformatted.
+    return unformattedHtml;
+  }
+}
+
+const serializer: SnapshotSerializer = {
+  serialize(val: string, config, indentation, depth, refs, printer) {
+    const formattedHtml = formatHtml(val);
+    // Wrap the text to prevent infinite recursion
+    return printer(formattedHtml, config, indentation, depth, refs);
+  },
+  test(val) {
+    return typeof val === "string" && htmlPattern.test(val);
+  },
+};
+
+export default serializer;

package/src/serializers/setup.ts

@@ -3,5 +3,11 @@ import { expect } from "vitest";
 import absolutePathSerializer from "./absolutePath.js";
 expect.addSnapshotSerializer(absolutePathSerializer);
 
+import urlSerializer from "./url.js";
+expect.addSnapshotSerializer(urlSerializer);
+
 import vFileSerializer from "./vFile.js";
 expect.addSnapshotSerializer(vFileSerializer);
+
+import htmlSerializer from "./html.js";
+expect.addSnapshotSerializer(htmlSerializer);

package/src/serializers/url.ts

@@ -0,0 +1,21 @@
+import type { SnapshotSerializer } from "vitest";
+
+const localhostPattern = /(https?:\/\/localhost):[0-9]+/gi;
+
+/**
+ * Strip the (potentially random) port from the URL
+ */
+function stripPort(str: string): string {
+  return str.replaceAll(localhostPattern, "$1");
+}
+
+const urlSerializer: SnapshotSerializer = {
+  serialize(val: string, config, indentation, depth, refs, printer) {
+    return printer(stripPort(val), config, indentation, depth, refs);
+  },
+  test(val) {
+    return typeof val === "string" && localhostPattern.test(val);
+  },
+};
+
+export default urlSerializer;

package/src/serializers/vFile.ts

@@ -1,5 +1,5 @@
 import prettier from "@prettier/sync";
-import prettierConfig from "./.prettierrc.json";
+import prettierConfig from "./.prettierrc.json" with { type: "json" };
 import { VFile, type Value as VFileValue } from "vfile";
 import type { Options } from "prettier";
 import type { SnapshotSerializer } from "vitest";

package/tests/unit/matchers/readme.spec.ts

@@ -5,7 +5,7 @@ describe("readme", () => {
   it("should describe toMatchError", () => {
     expect(new Error("face")).toMatchError(
       expect.objectContaining({
-        stack: expect.stringContaining("readme.spec.ts"),
+        stack: expect.stringContaining("readme.spec.ts") as unknown,
       }),
     );
   });
@@ -14,7 +14,7 @@ describe("readme", () => {
       throw new Error("face");
     }).toThrowErrorMatching(
       expect.objectContaining({
-        stack: expect.stringContaining("readme.spec.ts"),
+        stack: expect.stringContaining("readme.spec.ts") as unknown,
       }),
     );
   });

package/tests/unit/matchers/response/toHaveHeader.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import "../../../../src/matchers/setup";
+
+describe("toHaveHeader", () => {
+  const r = new Response("", {
+    headers: {
+      "Content-Type": "image/png",
+    },
+  });
+
+  it("should pass when the property exists", async () => {
+    expect(r).toHaveHeader("Content-Type");
+  });
+  it("should pass when the property doesn't exist", async () => {
+    expect(r).not.toHaveHeader("face");
+  });
+  it("should pass when the property value is correct", async () => {
+    expect(r).toHaveHeader("Content-Type", "image/png");
+  });
+  it("should pass when the property value is incorrect", async () => {
+    expect(r).not.toHaveHeader("Content-Type", 15);
+    expect(r).not.toHaveHeader("face", 15);
+  });
+  it("should error when the property should not exist but does", async () => {
+    expect(() =>
+      expect(r).not.toHaveHeader("Content-Type"),
+    ).toThrowErrorMatchingInlineSnapshot(`[Error: Received should not have the header "Content-Type"]`);
+  });
+  it("should error when the property should exist but doesn't", async () => {
+    expect(() =>
+      expect(r).toHaveHeader("face"),
+    ).toThrowErrorMatchingInlineSnapshot(`[Error: Received does not have the header "face"]`);
+  });
+  it("should error when the value should not match but does", async () => {
+    expect(() =>
+      expect(r).not.toHaveHeader("Content-Type", "image/png"),
+    ).toThrowErrorMatchingInlineSnapshot(`[Error: Header "Content-Type" should not be expected value]`);
+  });
+  it("should error when the value should match but doesn't", async () => {
+    expect(() =>
+      expect(r).toHaveHeader("Content-Type", 17),
+    ).toThrowErrorMatchingInlineSnapshot(`[Error: Header "Content-Type" is not expected value]`);
+  });
+  it("should error when a non-buffer is passed in", async () => {
+    expect(() =>
+      expect(1234).toHaveHeader("face"),
+    ).toThrowErrorMatchingInlineSnapshot(`[TypeError: Cannot read properties of undefined (reading 'has')]`);
+  });
+});

package/tests/unit/matchers/response/toHaveStatus.spec.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import "../../../../src/matchers/setup";
+
+const getResponse = (status: number): Response =>
+  new Response("", {
+    status,
+  });
+
+describe("toHaveStatus", () => {
+  const status200 = getResponse(200);
+  const status404 = getResponse(404);
+
+  it("should pass when the status is correct", async () => {
+    expect(status200).toHaveStatus(200);
+    expect(status404).toHaveStatus(404);
+  });
+  it("should pass when the status is incorrect", async () => {
+    expect(status200).not.toHaveStatus(500);
+    expect(status404).not.toHaveStatus(500);
+  });
+  it("should error when the value should not match but does", async () => {
+    expect(() =>
+      expect(status200).not.toHaveStatus(200),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Status should not be expected value]`,
+    );
+  });
+  it("should error when the value should match but doesn't", async () => {
+    expect(() =>
+      expect(status200).toHaveStatus(500),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Status is not expected value]`,
+    );
+  });
+  it("should error when a non-Response is passed in", async () => {
+    expect(() =>
+      expect(1234).toHaveStatus(3),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Status is not expected value]`,
+    );
+  });
+});

package/tests/unit/matchers/toHaveExifProperty.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import "../../../src/matchers/setup";
+
+describe("toHaveExifProperty", () => {
+  const buffer = Buffer.from(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIW2O4v3EyBwAGwgIsY3pRcwAAAABJRU5ErkJggg==",
+    "base64url",
+  );
+
+  it("should pass when the property exists", async () => {
+    await expect(buffer).toHaveExifProperty("ImageWidth");
+  });
+  it("should pass when the property doesn't exist", async () => {
+    await expect(buffer).not.toHaveExifProperty("face");
+  });
+  it("should pass when the property value is correct", async () => {
+    await expect(buffer).toHaveExifProperty("ImageHeight", 1);
+    await expect(buffer).toHaveExifProperty("ImageWidth", 1);
+  });
+  it("should pass when the property value is incorrect", async () => {
+    await expect(buffer).not.toHaveExifProperty("ImageWidth", 15);
+    await expect(buffer).not.toHaveExifProperty("face", 15);
+  });
+  it("should error when the property should not exist but does", async () => {
+    await expect(async () =>
+      expect(buffer).not.toHaveExifProperty("ImageWidth"),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Received should not have the property "ImageWidth"]`,
+    );
+  });
+  it("should error when the property should exist but doesn't", async () => {
+    await expect(async () =>
+      expect(buffer).toHaveExifProperty("face"),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Received does not have the property "face"]`,
+    );
+  });
+  it("should error when the value should not match but does", async () => {
+    await expect(async () =>
+      expect(buffer).not.toHaveExifProperty("ImageWidth", 1),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Property "ImageWidth" should not be expected value]`,
+    );
+  });
+  it("should error when the value should match but doesn't", async () => {
+    await expect(async () =>
+      expect(buffer).toHaveExifProperty("ImageWidth", 17),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Property "ImageWidth" is not expected value]`,
+    );
+  });
+  it("should error when a non-buffer is passed in", async () => {
+    await expect(async () =>
+      expect(1234).toHaveExifProperty("face"),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Invalid input argument]`,
+    );
+  });
+});

package/tests/unit/matchers/toMatchError.spec.ts

@@ -8,14 +8,14 @@ describe("matchers", () => {
         expect.objectContaining({
           message: "face",
           name: "Error",
-          stack: expect.any(String),
+          stack: expect.any(String) as unknown,
         }),
       );
     });
     it("should match an error by substring", () => {
       expect(new Error("your stupid face")).toMatchError(
         expect.objectContaining({
-          message: expect.stringContaining("stupid"),
+          message: expect.stringContaining("stupid") as unknown,
         }),
       );
     });

package/tests/unit/serializers/html.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import htmlSerializer from "../../../src/serializers/html.js";
+expect.addSnapshotSerializer(htmlSerializer);
+
+describe("serializers", () => {
+  describe("html", () => {
+    it("should prettier format the html", () => {
+      expect(
+        `<html><head><title>your face</title></head><body>is stupid</body></html>`,
+      ).toMatchInlineSnapshot(`
+        "<!-- Formatted HTML -->
+        <html>
+          <head>
+            <title>your face</title>
+          </head>
+          <body>
+            is stupid
+          </body>
+        </html>"
+      `);
+    });
+    it("should ignore already formatted html", () => {
+      const html = `
+        <html>
+          <head>
+            <title>your face</title>
+          </head>
+          <body>
+            is stupid
+          </body>
+        </html>"
+      `;
+      expect(html).toMatchInlineSnapshot(`
+        "
+                <html>
+                  <head>
+                    <title>your face</title>
+                  </head>
+                  <body>
+                    is stupid
+                  </body>
+                </html>"
+              "
+      `);
+    });
+    it("should ignore non-html strings", () => {
+      expect(`I'm just some content that isn't html`).toMatchInlineSnapshot(
+        `"I'm just some content that isn't html"`,
+      );
+    });
+    it("should ignore malformed html", () => {
+      expect(`<html><p>oiajsdfpoiajsdf</a></q></face>`).toMatchInlineSnapshot(`
+        "<html><p>oiajsdfpoiajsdf</a></q></face>"
+      `);
+    });
+  });
+});

package/tests/unit/serializers/url.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+
+import urlSerializer from "../../../src/serializers/url.js";
+expect.addSnapshotSerializer(urlSerializer);
+
+describe("serializers", () => {
+  describe("url", () => {
+    it("should remove the port in a localhost http[s] url", () => {
+      expect(
+        `String with http://localhost:1234/path/to/face url`,
+      ).toMatchInlineSnapshot(`"String with http://localhost/path/to/face url"`);
+    });
+  });
+});