@altano/vitest-plugins 0.0.2

package/.eslintrc.cjs

@@ -0,0 +1,19 @@
+module.exports = {
+  extends: ["altano"],
+  overrides: [
+    {
+      files: ["src/**/!(*.d).{ts,tsx}", "*.config.ts"],
+      parserOptions: {
+        project: ["./tsconfig.json"],
+        tsconfigRootDir: __dirname,
+      },
+    },
+    {
+      files: ["tests/**/*.ts", "tests/**/*.tsx"],
+      parserOptions: {
+        project: ["./tsconfig.json"],
+        tsconfigRootDir: `${__dirname}/tests/`,
+      },
+    },
+  ],
+};

package/.turbo/turbo-lint.log

@@ -0,0 +1,5 @@
+
+> @altano/vitest-plugins@0.0.2 lint /home/runner/work/npm-packages/npm-packages/packages/vitest-plugins
+> eslint package.json src/**/*.ts*
+
+Warning: React version was set to "detect" in eslint-plugin-react settings, but the "react" package is not installed. Assuming latest React version for linting.

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @altano/vitest-plugins
+
+## 0.0.2
+
+### Patch Changes
+
+- 7d75608: initial package publish

package/README.md

@@ -0,0 +1,115 @@
+# 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)
+
+Custom matchers and snapshot serializers to enhance vitest.
+
+# Installation
+
+```
+npm install -D @altano/vitest-plugins
+```
+
+## To install the custom matchers
+
+Modify vite.config.ts / vitest.config.ts:
+
+```ts
+export default defineConfig({
+  test: {
+    setupFiles: [
+      "@altano/vitest-plugins/matchers",
+      // ...
+    ],
+    // ...
+  },
+});
+```
+
+Add matcher types to your tsconfig.json (if using TypeScript):
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@altano/vitest-plugins/matchers"]
+  }
+}
+```
+
+## To install the snapshot serializers
+
+Modify vite.config.ts / vitest.config.ts:
+
+```ts
+export default defineConfig({
+  test: {
+    setupFiles: [
+      "@altano/vitest-plugins/serializers",
+      // ...
+    ],
+    // ...
+  },
+});
+```
+
+NOTE: You can pick and choose what to install: the matchers and serializers don't depend on each other.
+
+# Details
+
+## Snapshot Serializers
+
+### VFile
+
+Will format the contents of a [vfile](https://unifiedjs.com/explore/package/vfile/) using Prettier (auto-detecting the type from the vfile's filename), e.g.
+
+```snap
+FormattedVFile {
+  "cwd": "<cwd>",
+  "data": {},
+  "history": [
+    "tests/unit/__fixtures__/basic/input.js",
+  ],
+  "map": undefined,
+  "messages": [],
+  "value": "function face() { }"
+}
+```
+
+### Absolute Paths
+
+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.
+
+## Matchers
+
+Vitest's error matchers let you match against the error message, but not the rest of the Error object:
+
+- `toThrow(error?)` - error is thrown ([docs](https://jestjs.io/docs/expect#tothrowerror))
+- `toThrowErrorMatching[Inline]Snapshot` - an error _exactly_ matches a snapshot ([docs](https://jestjs.io/docs/expect#tothrowerrormatchingsnapshothint))
+
+If you want to assert anything more complicated (e.g. an error contains some substring in the stack) then you'll need these custom matchers:
+
+### toMatchError
+
+Assert on any part of an error object (e.g. the stack):
+
+```ts
+expect(new Error("face")).toMatchError(
+  expect.objectContaining({
+    stack: expect.stringContaining("readme.spec.ts"),
+  }),
+);
+```
+
+### toThrowErrorMatching
+
+Assert on any part of a _thrown_ error object (e.g. the stack):
+
+```ts
+expect(() => {
+  throw new Error("face");
+}).toThrowErrorMatching(
+  expect.objectContaining({
+    stack: expect.stringContaining("readme.spec.ts"),
+  }),
+);
+```

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@altano/vitest-plugins",
+  "version": "0.0.2",
+  "description": "Custom matchers and snapshot serializers to enhance vitest",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./matchers": {
+      "default": "./src/matchers/setup.ts",
+      "types": "./src/matchers/types.d.ts"
+    },
+    "./matchers/*": "./src/matchers/*.ts",
+    "./serializers": "./src/serializers/setup.ts",
+    "./serializers/*": "./src/serializers/*.ts"
+  },
+  "author": {
+    "name": "Alan Norbauer",
+    "email": "altano@gmail.com",
+    "url": "https://alan.norbauer.com"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/altano/npm-packages",
+    "directory": "packages/vitest-plugins"
+  },
+  "homepage": "https://github.com/altano/npm-packages/tree/main/packages/vitest-plugins",
+  "devDependencies": {
+    "@mdx-js/mdx": "^2.3.0",
+    "@prettier/sync": "^0.5.1",
+    "@types/node": "^20.11.25",
+    "@vitest/coverage-v8": "^1.4.0",
+    "@vitest/expect": "^1.4.0",
+    "@vitest/ui": "^1.4.0",
+    "eslint": "^8.57.0",
+    "mdast-util-mdxjs-esm": "^2.0.1",
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.2",
+    "unified": "^10.1.2",
+    "vfile": "^5.3.7",
+    "vitest": "^1.4.0",
+    "@altano/tsconfig": "0.0.0",
+    "eslint-config-altano": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "serialize-error": "^11.0.3"
+  },
+  "scripts": {
+    "clean": "rm -rf .turbo && rm -rf .tsbuildinfo && rm -rf node_modules && rm -rf dist",
+    "format": "prettier --check src",
+    "format:fix": "prettier --write src",
+    "lint": "eslint package.json src/**/*.ts*",
+    "lint:fix": "TIMING=1 pnpm lint --fix",
+    "lint:timing": "TIMING=1 pnpm lint",
+    "test:typecheck": "tsc --project ./tests/tsconfig.json --noEmit",
+    "test:unit": "vitest --run",
+    "test:unit:watch": "vitest",
+    "typecheck:src": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit --project ./tests/tsconfig.json"
+  }
+}

package/src/matchers/matcher.ts

@@ -0,0 +1,5 @@
+import { expect } from "vitest";
+
+type MatchersObject = Parameters<typeof expect.extend>[0];
+
+export type Matcher = MatchersObject[keyof MatchersObject];

package/src/matchers/setup.ts

@@ -0,0 +1,9 @@
+import { expect } from "vitest";
+
+import toMatchError from "./toMatchError";
+import toThrowErrorMatching from "./toThrowErrorMatching";
+
+expect.extend({
+  toMatchError,
+  toThrowErrorMatching,
+});

package/src/matchers/toMatchError.ts

@@ -0,0 +1,18 @@
+import { serializeError } from "serialize-error";
+import type { Matcher } from "./matcher";
+
+const toMatchError: Matcher = function (received: Error, expected: unknown) {
+  // If we don't serialize the error before passing it to vitest, vitest will
+  // output just the error message (e.g. `"[Error: face]"`). If we let people
+  // match against the other Error fields (e.g. `stack`) we should display those
+  // instead of simplifying them out of the output.
+  const serializedError = serializeError(received);
+  return {
+    message: () => `Expected errors to match`,
+    pass: this.equals(received, expected, this.customTesters),
+    actual: serializedError,
+    expected: expected,
+  };
+};
+
+export default toMatchError;

package/src/matchers/toThrowErrorMatching.ts

@@ -0,0 +1,26 @@
+import toMatchError from "./toMatchError";
+import type { Matcher } from "./matcher";
+
+const toThrowErrorMatching: Matcher = function (
+  received: () => never,
+  expected: unknown,
+) {
+  let error: unknown = null;
+  try {
+    received();
+  } catch (e: unknown) {
+    error = e;
+  }
+  if (error instanceof Error) {
+    return toMatchError.call(this, error, expected);
+  } else {
+    return {
+      message: () => `Did not throw an Error`,
+      pass: false,
+      actual: error,
+      expected: `[Error]`,
+    };
+  }
+};
+
+export default toThrowErrorMatching;

package/src/matchers/types.d.ts

@@ -0,0 +1,13 @@
+// Have to import these to get declaration merging.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Assertion, AsymmetricMatchersContaining } from "vitest";
+
+interface CustomMatchers<R = unknown> {
+  toMatchError(expected: unknown): R;
+  toThrowErrorMatching(expected: unknown): R;
+}
+
+declare module "vitest" {
+  interface Assertion<T> extends CustomMatchers<T> {}
+  interface AsymmetricMatchersContaining extends CustomMatchers {}
+}

package/src/serializers/absolutePath.ts

@@ -0,0 +1,30 @@
+import process from "node:process";
+import type { SnapshotSerializer } from "vitest";
+
+function getCWD(): string {
+  return process.cwd();
+}
+
+/**
+ * Strip absolute paths from the output to make tests portable
+ */
+function stripAbsolutePaths(str: string): string {
+  return str.replaceAll(getCWD(), "<cwd>");
+}
+
+const serializer: SnapshotSerializer = {
+  serialize(val: string, config, indentation, depth, refs, printer) {
+    return printer(stripAbsolutePaths(val), config, indentation, depth, refs);
+  },
+  test(val) {
+    return (
+      typeof val === "string" &&
+      // This is potentially really expensive, given large strings, but I can't
+      // find a better way to do this. Without this check, the string will keep
+      // getting reprocessed by this serializer over and over.
+      val.includes(getCWD())
+    );
+  },
+};
+
+export default serializer;

package/src/serializers/setup.ts

@@ -0,0 +1,7 @@
+import { expect } from "vitest";
+
+import absolutePathSerializer from "./absolutePath";
+expect.addSnapshotSerializer(absolutePathSerializer);
+
+import vFileSerializer from "./vFile";
+expect.addSnapshotSerializer(vFileSerializer);

package/src/serializers/vFile.ts

@@ -0,0 +1,45 @@
+import prettier from "@prettier/sync";
+import prettierConfig from "../../../../.prettierrc.json";
+import { VFile, type Value as VFileValue } from "vfile";
+import type { Options } from "prettier";
+import type { SnapshotSerializer } from "vitest";
+
+class FormattedVFile extends VFile {
+  constructor(vfile: VFile, formattedContents: VFileValue) {
+    super(vfile);
+    this.value = formattedContents;
+  }
+}
+
+const vFileSerializer: SnapshotSerializer = {
+  serialize(vfile: VFile, config, indentation, depth, refs, printer) {
+    const unformattedContents = vfile.toString();
+    let vFileToPrint: VFile;
+
+    try {
+      const formattedContents = prettier
+        .format(unformattedContents, {
+          filepath: vfile.path,
+          ...(prettierConfig as Options),
+        })
+        .trim();
+      vFileToPrint = new FormattedVFile(vfile, formattedContents);
+    } catch (e: unknown) {
+      if (e instanceof Error && e.name === "UndefinedParserError") {
+        // Prettier doesn't have a parser for this vfile. That's fine, pass it
+        // through unformatted.
+        vFileToPrint = new FormattedVFile(vfile, vfile.value);
+      } else {
+        // Rethrow any other errors
+        throw e;
+      }
+    }
+
+    return printer(vFileToPrint, config, indentation, depth, refs);
+  },
+  test(val: unknown) {
+    return val instanceof VFile && !(val instanceof FormattedVFile);
+  },
+};
+
+export default vFileSerializer;

package/tests/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["."],
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "..",
+    "types": ["../src/matchers/types"]
+  }
+}

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

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import "../../../src/matchers/setup";
+
+describe("readme", () => {
+  it("should describe toMatchError", () => {
+    expect(new Error("face")).toMatchError(
+      expect.objectContaining({
+        stack: expect.stringContaining("readme.spec.ts"),
+      }),
+    );
+  });
+  it("should describe toThrowErrorMatching", () => {
+    expect(() => {
+      throw new Error("face");
+    }).toThrowErrorMatching(
+      expect.objectContaining({
+        stack: expect.stringContaining("readme.spec.ts"),
+      }),
+    );
+  });
+});

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

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import "../../../src/matchers/setup";
+
+describe("matchers", () => {
+  describe("toMatchError", () => {
+    it("should match an error exactly", () => {
+      expect(new Error("face")).toMatchError(
+        expect.objectContaining({
+          message: "face",
+          name: "Error",
+          stack: expect.any(String),
+        }),
+      );
+    });
+    it("should match an error by substring", () => {
+      expect(new Error("your stupid face")).toMatchError(
+        expect.objectContaining({
+          message: expect.stringContaining("stupid"),
+        }),
+      );
+    });
+    it("should NOT match an invalid string", () => {
+      expect(new Error("face")).not.toMatchError(
+        expect.objectContaining({
+          message: "hat",
+        }),
+      );
+    });
+    it("should throw an error when there is no match", () => {
+      expect(() => {
+        expect(new Error("face")).toMatchError(
+          expect.objectContaining({
+            message: "hat",
+          }),
+        );
+      }).toThrowErrorMatchingInlineSnapshot(
+        `[Error: Expected errors to match]`,
+      );
+    });
+    it.todo("should display the other Error fields in the error", () => {
+      // I don't know how to capture vitest's full error output to verify it
+      // contains what we expect.
+    });
+  });
+});

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

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import "../../../src/matchers/setup";
+
+describe("matchers", () => {
+  describe("toThrowErrorMatching", () => {
+    it("should match an error exactly", () => {
+      expect(() => {
+        throw new Error("face");
+      }).toThrow("fac");
+    });
+    it("should NOT match an just the message", () => {
+      expect(() => {
+        throw new Error("face");
+      }).not.toThrowErrorMatching("face");
+    });
+    it("should NOT match an invalid message", () => {
+      expect(() => {
+        throw new Error("face");
+      }).not.toThrowErrorMatching(
+        expect.objectContaining({
+          message: "hat",
+        }),
+      );
+    });
+    it("should throw an error when an error wasn't thrown", () => {
+      expect(() => {
+        expect(() => 1).toThrowErrorMatching("face");
+      }).toThrowErrorMatchingInlineSnapshot(`[Error: Did not throw an Error]`);
+    });
+  });
+});

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

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+
+import absolutePathSerializer from "../../../src/serializers/absolutePath";
+expect.addSnapshotSerializer(absolutePathSerializer);
+
+describe("serializers", () => {
+  describe("absolutePath", () => {
+    it("should remove absolute file paths in a string", () => {
+      expect(
+        `String with an absolute path: ${import.meta.dirname}`,
+      ).toMatchInlineSnapshot(
+        `"String with an absolute path: <cwd>/tests/unit/serializers"`,
+      );
+    });
+  });
+});

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

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { VFile } from "vfile";
+
+// We're not testing the absolute path serializer, but the test isn't
+// reproducible without it. So just add both.
+import "../../../src/serializers/setup";
+
+describe("serializers", () => {
+  describe("vFile", () => {
+    it("should produce a snapshot for a plain text VFile (not Prettier supported)", () => {
+      const file = new VFile({
+        path: "~/example.txt",
+        value: "Alpha *braavo* charlie.",
+      });
+      expect(file).toMatchInlineSnapshot(`
+        FormattedVFile {
+          "cwd": "<cwd>",
+          "data": {},
+          "history": [
+            "~/example.txt",
+          ],
+          "messages": [],
+          "value": "Alpha *braavo* charlie.",
+        }
+      `);
+    });
+    it("should produce a formatted snapshot for a Prettier-compatible file", () => {
+      const file = new VFile({
+        path: "~/example.js",
+        value: `function face(  ) {console.log("hi" );   }`,
+      });
+      expect(file).toMatchInlineSnapshot(`
+        FormattedVFile {
+          "cwd": "<cwd>",
+          "data": {},
+          "history": [
+            "~/example.js",
+          ],
+          "messages": [],
+          "value": "function face() {
+          console.log("hi");
+        }",
+        }
+      `);
+    });
+    it("should throw if given a file that Prettier supports but can't format", () => {
+      const file = new VFile({
+        path: "~/example.js",
+        value: `function (  ) {1   }`,
+      });
+      file.cwd = "/root/path"; // make snapshot reproducible
+      expect(() => {
+        expect(file).toMatchInlineSnapshot(`"function (  ) {1   }"`);
+      }).toThrowErrorMatchingInlineSnapshot(`
+        [PrettyFormatPluginError: Unexpected token (1:10)
+        > 1 | function (  ) {1   }
+            |          ^]
+      `);
+    });
+    it("should remove absolute file paths in a vFile", () => {
+      const file = new VFile({
+        path: "~/example.json",
+        value: `{ "key": "${import.meta.dirname}" }`,
+      });
+      expect(file).toMatchInlineSnapshot(`
+        FormattedVFile {
+          "cwd": "<cwd>",
+          "data": {},
+          "history": [
+            "~/example.json",
+          ],
+          "messages": [],
+          "value": "{
+          "key": "<cwd>/tests/unit/serializers"
+        }",
+        }
+      `);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@altano/tsconfig/node.json",
+  "include": ["src", "*.config.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,24 @@
+import { defineProject } from "vitest/config";
+
+export default defineProject({
+  test: {
+    dir: "tests/unit",
+    coverage: {
+      enabled: true,
+
+      exclude: [
+        "tests/e2e",
+        "playwright.config.ts",
+        ".eslintrc.cjs",
+        "tests/unit/**/*.benchmark.tsx",
+      ],
+
+      provider: "v8",
+      all: true,
+      clean: true,
+      skipFull: true,
+      thresholds: { "100": true },
+      reportsDirectory: ".coverage",
+    },
+  },
+});