puty 0.0.6 → 0.1.0

package/README.md

@@ -21,6 +21,7 @@ Puty is ideal for testing pure functions - functions that always return the same
 ## Features
 
 - 📝 Write tests in simple YAML format
+- 🔌 Zero-config Vitest plugin
 - 📦 Modular test organization with `!include` directive
 - 🎯 Clear separation of test data and test logic
 - 🧪 Mock support for testing functions with dependencies
@@ -44,17 +45,20 @@ Get up and running with Puty in just a few minutes!
 ### Step 1: Install Puty
 
 ```bash
-npm install puty
+npm install puty vitest
 ```
 
-### Step 2: Setup Your Project
+### Step 2: Configure Vitest
 
-Ensure your `package.json` has ES modules enabled:
+Create `vitest.config.js`:
 
-```json
-{
-  "type": "module"
-}
+```js
+import { defineConfig } from 'vitest/config'
+import { putyPlugin } from 'puty/vitest'
+
+export default defineConfig({
+  plugins: [putyPlugin()]
+})
 ```
 
 ### Step 3: Create a Function to Test
@@ -108,23 +112,22 @@ in: ['a']
 out: 'A'
 ```
 
-### Step 5: Create Test Runner
-
-Create `puty.test.js`:
-
-```js
-import path from 'path'
-import { setupTestSuiteFromYaml } from 'puty'
+### Step 5: Add Test Script
 
-const __dirname = path.dirname(new URL(import.meta.url).pathname)
+Add a test script to your `package.json`:
 
-await setupTestSuiteFromYaml(__dirname);
+```json
+{
+  "scripts": {
+    "test": "vitest run"
+  }
+}
 ```
 
 ### Step 6: Run Your Tests
 
 ```bash
-npx vitest
+npm test
 ```
 
 You should see output like:
@@ -138,26 +141,6 @@ You should see output like:
 
 🎉 **That's it!** You've just created declarative tests using YAML instead of JavaScript.
 
-### Recommended Vitest Configuration
-
-To enable automatic test reruns when YAML test files change, create a `vitest.config.js` file in your project root:
-
-```js
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    forceRerunTriggers: [
-      '**/*.js',
-      '**/*.{test,spec}.yaml',
-      '**/*.{test,spec}.yml'
-    ],
-  },
-});
-```
-
-This configuration ensures that Vitest will re-run your tests whenever you modify either your JavaScript source files or your YAML test files.
-
 ## Usage
 
 ### Testing Functions

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "puty",
-  "version": "0.0.6",
+  "version": "0.1.0",
   "description": "A tooling function to test javascript functions and classes.",
   "main": "src/index.js",
   "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./vitest": "./src/vitest-plugin.js",
+    "./setup": "./src/setup.js"
+  },
   "files": [
     "src"
   ],
@@ -24,5 +29,8 @@
   },
   "devDependencies": {
     "vitest": "^3.2.1"
+  },
+  "peerDependencies": {
+    "vitest": ">=1.0.0"
   }
 }

package/src/index.js

@@ -4,9 +4,16 @@
  */
 
 import { setupTestSuiteFromYaml } from "./puty.js";
+import { putyPlugin } from "./vitest-plugin.js";
 
 /**
  * Main entry point function for discovering and setting up test suites from YAML files
  * @see {@link setupTestSuiteFromYaml} for detailed documentation
  */
 export { setupTestSuiteFromYaml };
+
+/**
+ * Vitest plugin for automatic YAML test file discovery
+ * @see {@link putyPlugin} for detailed documentation
+ */
+export { putyPlugin };

package/src/puty.js

@@ -92,6 +92,12 @@ const callNestedMethod = (obj, path, args = []) => {
  */
 const extensions = [".test.yaml", ".test.yml", ".spec.yaml", ".spec.yml"];
 
+/**
+ * Registry of processed YAML test files to prevent duplicate registration
+ * @type {Set<string>}
+ */
+const processedFiles = new Set();
+
 /**
  * Parses YAML content containing multiple documents separated by '---' into a structured test configuration
  * @param {string} yamlContent - Raw YAML content string to parse
@@ -506,8 +512,9 @@ export const injectFunctions = (module, originalTestConfig) => {
 };
 
 /**
- * Discovers and sets up test suites from all YAML test files in a directory and its subdirectories
+ * Discovers and sets up test suites from YAML test files
  * @param {string} dirname - Directory path to search for YAML test files
+ * @param {string} [filename] - Optional specific filename to process (instead of scanning directory)
  * @returns {Promise<void>} Promise that resolves when all test suites are set up
  * @throws {Error} When YAML files cannot be parsed or modules cannot be imported
  * @example
@@ -517,11 +524,25 @@ export const injectFunctions = (module, originalTestConfig) => {
  * // Set up tests from a specific directory
  * await setupTestSuiteFromYaml('./tests');
  *
+ * // Set up a single YAML test file
+ * await setupTestSuiteFromYaml('./tests', 'math.test.yaml');
+ *
  * // This will find all files matching: *.test.yaml, *.test.yml, *.spec.yaml, *.spec.yml
  */
-export const setupTestSuiteFromYaml = async (dirname) => {
-  const testYamlFiles = traverseAllFiles(dirname, extensions);
+export const setupTestSuiteFromYaml = async (dirname, filename) => {
+  // If filename is provided, process only that file
+  const testYamlFiles = filename
+    ? [path.join(dirname, filename)]
+    : traverseAllFiles(dirname, extensions);
+
   for (const file of testYamlFiles) {
+    // Skip already processed files to prevent duplicate test registration
+    const absolutePath = path.resolve(file);
+    if (processedFiles.has(absolutePath)) {
+      continue;
+    }
+    processedFiles.add(absolutePath);
+
     try {
       const testConfig = parseWithIncludes(file);
       const filepathRelativeToSpecFile = path.join(

package/src/setup.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Vitest setup file for puty - discovers and registers YAML test files
+ */
+
+import { setupTestSuiteFromYaml } from "./puty.js";
+
+// Use globalThis to ensure setup only runs once across all imports
+if (!globalThis.__putySetupComplete) {
+  globalThis.__putySetupComplete = true;
+  await setupTestSuiteFromYaml(process.cwd());
+}

package/src/utils.js

@@ -88,6 +88,10 @@ export const traverseAllFiles = (startPath, extensions) => {
   const results = [];
   const files = fs.readdirSync(startPath);
   for (const file of files) {
+    // Skip node_modules and hidden directories
+    if (file === "node_modules" || file.startsWith(".")) {
+      continue;
+    }
     const filePath = path.join(startPath, file);
     const stats = fs.statSync(filePath);
     if (stats.isDirectory()) {

package/src/vitest-plugin.js

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Vitest plugin for puty - enables YAML test files without manual setup
+ */
+
+import path from "node:path";
+
+/**
+ * Vitest plugin that automatically configures puty for YAML test discovery
+ * @returns {import('vite').Plugin} Vite/Vitest plugin
+ * @example
+ * // vitest.config.js
+ * import { defineConfig } from 'vitest/config'
+ * import { putyPlugin } from 'puty/vitest'
+ *
+ * export default defineConfig({
+ *   plugins: [putyPlugin()]
+ * })
+ */
+export function putyPlugin() {
+  return {
+    name: "vitest:puty",
+
+    config() {
+      return {
+        test: {
+          include: [
+            "**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}",
+            "**/*.{test,spec}.{yaml,yml}",
+          ],
+          forceRerunTriggers: ["**/*.{test,spec}.{yaml,yml}"],
+        },
+      };
+    },
+
+    transform(code, id) {
+      // Only transform YAML test files
+      if (!/\.(test|spec)\.(yaml|yml)$/.test(id)) {
+        return null;
+      }
+
+      const yamlDir = path.dirname(id);
+
+      // Generate a JS module that loads and runs this specific YAML file
+      const transformedCode = `
+import { setupTestSuiteFromYaml } from 'puty';
+await setupTestSuiteFromYaml('${yamlDir}', '${path.basename(id)}');
+`;
+
+      return {
+        code: transformedCode,
+        map: null,
+      };
+    },
+  };
+}