feat(testament): add file fixture helpers, update pkg meta

packages/testament/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@thi.ng/testament",
 	"version": "0.2.12",
-	"description": "Minimal, rational & TypeScript-friendly test runner, result export as CSV/JSON, watch mode",
+	"description": "Minimal, rational & TypeScript-friendly test runner, result export as CSV/JSON, watch mode, file fixtures",
 	"type": "module",
 	"module": "./index.js",
 	"typings": "./index.d.ts",
@@ -46,7 +46,19 @@
 		"typescript": "^4.7.4"
 	},
 	"keywords": [
-		"typescript"
+		"async",
+		"cli",
+		"csv",
+		"file",
+		"fixture",
+		"group",
+		"json",
+		"logger",
+		"node",
+		"report",
+		"test",
+		"typescript",
+		"watch"
 	],
 	"publishConfig": {
 		"access": "public"
@@ -73,6 +85,9 @@
 		"./exec": {
 			"default": "./exec.js"
 		},
+		"./fixtures": {
+			"default": "./fixtures.js"
+		},
 		"./group": {
 			"default": "./group.js"
 		},

packages/testament/src/fixtures.ts

@@ -0,0 +1,51 @@
+import type { ILogger } from "@thi.ng/logger";
+import { readFileSync } from "fs";
+import { join, resolve } from "path";
+
+/**
+ * Only available for NodeJS. Returns path for given local fixture path, i.e.
+ * prefixed with `test/fixtures/` and normalized for current platform. If `abs`
+ * is true (default: false), returns absolute path.
+ *
+ * @remarks
+ * The given local path should always use `/` as path separator (will be
+ * possibly replaced with current platform's path sep).
+ *
+ * @param path
+ * @param abs
+ */
+export const fixturePath = (path: string, abs = false) => {
+	const $path = join("test", "fixtures", ...path.split("/"));
+	return abs ? resolve($path) : $path;
+};
+
+/**
+ * Takes local fixture path ID, transforms it with {@link fixturePath} and then
+ * attempts to load that file. If `binary` is true, the file is loaded as binary
+ * and returned as Uint8Array. In all other cases, the file is loaded as UTF-8
+ * text and returned it as string.
+ *
+ * @remarks
+ * If `logger` is given, a debug message with the fixture's file path is logged.
+ *
+ * @param path
+ * @param logger
+ * @param binary
+ */
+export function fileFixture(
+	path: string,
+	logger?: ILogger,
+	binary?: false
+): string;
+export function fileFixture(
+	path: string,
+	logger: ILogger | undefined,
+	binary: true
+): Uint8Array;
+export function fileFixture(path: string, logger?: ILogger, binary?: boolean) {
+	const $path = fixturePath(path);
+	logger && logger.debug("loading fixture:", $path);
+	return binary
+		? new Uint8Array(readFileSync($path))
+		: readFileSync($path, "utf-8");
+}

packages/testament/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./api.js";
 export * from "./exec.js";
+export * from "./fixtures.js";
 export * from "./group.js";
 export * from "./test.js";