puty 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yuusoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Puty: Pure Unit Test in Yaml
+
+Write unit test specifications using YAML files, powered by vitest as the test runner.
+
+## Installation
+
+```bash
+npm install puty
+```
+
+create a file in your project `puty.test.js`
+```js
+import { setupTestSuiteFromYaml } from "./puty.js";
+await setupTestSuiteFromYaml();
+```
+
+This function will read for all `.spec.yaml` and `.test.yaml` files in the current directory and run the tests.
+
+run
+
+```
+vitest
+```
+
+It should run all the tests in the file.
+
+## Usage
+
+```yaml
+file: './math.js'
+group: math
+suites: [add, increment]
+---
+### Add
+suite: add
+exportName: add
+---
+case: add 1 and 2
+in:
+  - 1
+  - 2
+out: 3
+---
+case: add 2 and 2
+in:
+  - 2
+  - 2
+out: 4
+---
+### Increment
+suite: increment
+exportName: default
+---
+case: increment 1
+in:
+  - 1
+out: 2
+---
+case: increment 2
+in:
+  - 2
+out: 3
+```

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "puty",
+  "version": "0.0.1",
+  "description": "A tooling function to test javascript functions and classes.",
+  "main": "src/index.js",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuusoft-org/puty.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "js-yaml": "~4.1.0"
+  },
+  "scripts": {
+    "lint": "bunx prettier src tests -c",
+    "lint:fix": "bunx prettier src tests -w",
+    "build": "bun run esbuild.js"
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+import { setupTestSuiteFromYaml } from "./puty.js";
+
+export { setupTestSuiteFromYaml };

package/src/puty.js

@@ -0,0 +1,128 @@
+import path from "node:path";
+import fs from "node:fs";
+import yaml from "js-yaml";
+import { expect, test, describe } from "vitest";
+
+import { traverseAllFiles } from "./utils.js";
+
+const extensions = [".test.yaml", ".test.yml", ".spec.yaml", ".spec.yml"];
+
+/**
+ * Parse YAML content with document separators into structured test config
+ */
+export const parseYamlDocuments = (yamlContent) => {
+  const docs = yaml.loadAll(yamlContent);
+  const config = {
+    file: null,
+    group: null,
+    suites: [],
+  };
+
+  let currentSuite = null;
+
+  for (const doc of docs) {
+    if (doc.file) {
+      config.file = doc.file;
+      config.group = doc.group || doc.name;
+      if (doc.suites) {
+        config.suiteNames = doc.suites;
+      }
+    } else if (doc.suite) {
+      if (currentSuite) {
+        config.suites.push(currentSuite);
+      }
+      currentSuite = {
+        name: doc.suite,
+        exportName: doc.exportName || doc.suite,
+        cases: [],
+      };
+    } else if (doc.case && currentSuite) {
+      currentSuite.cases.push({
+        name: doc.case,
+        in: doc.in || [],
+        out: doc.out,
+      });
+    }
+  }
+
+  if (currentSuite) {
+    config.suites.push(currentSuite);
+  }
+
+  return config;
+};
+
+/**
+ *
+ * @param {*} testConfig
+ */
+const setupTestSuite = (testConfig) => {
+  const { group, suites, skip } = testConfig;
+  if (skip) {
+    return;
+  }
+  describe(group, () => {
+    for (const suite of suites) {
+      describe(suite.name, () => {
+        const { cases } = suite;
+        for (const testCase of cases) {
+          const {
+            name,
+            in: inArg,
+            out: expectedOut,
+            functionUnderTest,
+          } = testCase;
+          test(name, () => {
+            const out = functionUnderTest(...(inArg || []));
+            if (out instanceof Error) {
+              expect(out.message).toEqual(out.message);
+            } else {
+              expect(out).toEqual(expectedOut);
+            }
+          });
+        }
+      });
+    }
+  });
+};
+
+/**
+ *
+ * @param {*} module
+ * @param {*} originalTestConfig
+ * @returns
+ */
+export const injectFunctions = (module, originalTestConfig) => {
+  const testConfig = structuredClone(originalTestConfig);
+  let functionUnderTest = module[testConfig.exportName || "default"];
+
+  for (const suite of testConfig.suites) {
+    if (suite.exportName) {
+      functionUnderTest = module[suite.exportName];
+    }
+    for (const testCase of suite.cases) {
+      testCase.functionUnderTest = functionUnderTest;
+    }
+  }
+  return testConfig;
+};
+
+/**
+ * Setup test suites from all yaml files in the current directory and its subdirectories
+ */
+export const setupTestSuiteFromYaml = async (dirname) => {
+  const testYamlFiles = traverseAllFiles(dirname, extensions);
+  for (const file of testYamlFiles) {
+    const yamlContent = fs.readFileSync(file, "utf8");
+    const testConfig = parseYamlDocuments(yamlContent);
+    const filepathRelativeToSpecFile = path.join(
+      path.dirname(file),
+      testConfig.file,
+    );
+
+    // testConfig.file is relative to the spec file
+    const module = await import(filepathRelativeToSpecFile);
+    const testConfigWithInjectedFunctions = injectFunctions(module, testConfig);
+    setupTestSuite(testConfigWithInjectedFunctions);
+  }
+};

package/src/utils.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path, { join } from "node:path";
+
+import yaml from "js-yaml";
+
+export const loadYamlWithPath = (path) => {
+  const includeType = new yaml.Type("!include", {
+    kind: "scalar",
+    construct: function (filePath) {
+      const content = fs.readFileSync(join(path, "..", filePath), "utf8");
+      return yaml.load(content); // you could recurse here
+    },
+  });
+  const schema = yaml.DEFAULT_SCHEMA.extend([includeType]);
+  return yaml.load(fs.readFileSync(path, "utf8"), { schema });
+};
+
+/**
+ * Traverse all files in the current directory and its subdirectories
+ * Return an array of full path of files
+ */
+export const traverseAllFiles = (startPath, extensions) => {
+  const results = [];
+  const files = fs.readdirSync(startPath);
+  for (const file of files) {
+    const filePath = path.join(startPath, file);
+    const stats = fs.statSync(filePath);
+    if (stats.isDirectory()) {
+      results.push(...traverseAllFiles(filePath, extensions));
+    } else if (extensions.some((ext) => file.endsWith(ext))) {
+      results.push(filePath);
+    }
+  }
+  return results;
+};