@nan0web/ui 1.12.1 → 1.12.2

package/README.md

@@ -250,6 +250,16 @@ const res = await ScenarioTest.run(ValidatedApp, [
 	{ field: 'code', value: '' } // Simulating empty response
 ])
 ```
+### Story Testing (.nan0 spec files)
+
+The `SpecRunner.executeFile` helper allows running `.nan0` spec stories automatically without boilerplate DBFS setup.
+All manual assertions are omitted because `SpecAdapter` handles strict expectation matching internally.
+
+How to execute .nan0 spec files automatically?
+```js
+import { SpecRunner } from '@nan0web/ui/testing'
+const { SpecRunner } = await import('./testing/index.js')
+```
 All components, adapters, and models are designed to be testable
 with minimal setup.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nan0web/ui",
-  "version": "1.12.1",
+  "version": "1.12.2",
   "description": "NaN•Web UI. One application logic (algorithm) and many UI.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -77,20 +77,20 @@
     "@nan0web/db-fs": "1.2.2",
     "@nan0web/event": "1.0.1",
     "@nan0web/i18n": "1.5.0",
-    "@nan0web/icons": "1.1.0",
     "@nan0web/inspect": "1.0.0",
+    "@nan0web/test": "1.1.4",
     "@nan0web/ui-cli": "2.13.1",
-    "@nan0web/nan0web.app": "0.1.0",
+    "@nan0web/release": "1.0.3",
+    "@nan0web/icons": "1.1.0",
     "@nan0web/ui-lit": "1.1.0",
-    "@nan0web/test": "1.1.4",
-    "@nan0web/release": "1.0.3"
+    "@nan0web/nan0web.app": "0.1.0"
   },
   "dependencies": {
     "string-width": "^7.2.0",
     "@nan0web/co": "2.0.1",
     "@nan0web/core": "1.1.3",
-    "@nan0web/log": "1.1.1",
-    "@nan0web/types": "1.7.3"
+    "@nan0web/types": "1.7.3",
+    "@nan0web/log": "1.1.1"
   },
   "scripts": {
     "prebuild": "rm -rf types/",

package/src/core/GeneratorRunner.js

@@ -276,6 +276,14 @@ export async function runGenerator(generator, handlers, options = {}) {
 				break
 			}
 
+			case 'result': {
+				if (handlers.result) {
+					await handlers.result(intent)
+				}
+				nextVal = undefined
+				break
+			}
+
 			default:
 				throw IntentErrorModel.error('unhandled_intent', { type: /** @type {any} */ (intent).type })
 		}

package/src/testing/SpecRunner.js

@@ -35,6 +35,43 @@ export class SpecRunner extends ModelAsApp {
 		this.registry
 	}
 
+	/**
+	 * Convenience method to load a .nan0 file and run a specific scenario.
+	 * 
+	 * 💡 Note on Expectations:
+	 * You do NOT need to write manual assertions when using this method. 
+	 * The `for await (const _ of runner.run()) {}` loop drives the generator,
+	 * but ALL assertions are handled automatically inside `SpecAdapter.js`.
+	 * 
+	 * Whenever the App yields an intent (`ask`, `show`, `result`), `SpecAdapter`
+	 * intercepts it and compares it strictly against the next step in the `.nan0` file.
+	 * - If it matches, the test continues (and `$value` is injected back into the App).
+	 * - If it mismatches, it throws an `assert.fail()` which fails the Node.js test immediately.
+	 * - If the App finishes early, it throws an `unhandledSteps` error.
+	 * 
+	 * @param {string} fileDir The directory containing the file (e.g., import.meta.dirname)
+	 * @param {string} fileName The name of the .nan0 file
+	 * @param {string} scenarioName The name of the scenario to run
+	 * @param {Record<string, any>} registry The Model Class registry
+	 * @param {Partial<import('../index.js').ModelAsAppOptions>} [options={}] Additional runner context options
+	 * @throws {Error} If the scenario is missing or if expectations fail during execution
+	 */
+	static async executeFile(fileDir, fileName, scenarioName, registry, options = {}) {
+		const DB = (await import('@nan0web/db-fs')).DBFS
+		const db = new DB({ root: fileDir })
+		const doc = await db.loadDocument(fileName)
+		const scenarios = Array.isArray(doc) ? doc : [doc]
+		const scenario = scenarios.find((s) => s.name === scenarioName) || scenarios[0]
+
+		if (!scenario) throw new Error(`Scenario ${scenarioName} not found in ${fileName}`)
+		if (!scenario.story) throw new Error(`Scenario ${scenarioName} has no story array`)
+
+		const runner = new this({ stream: scenario.story, registry }, options)
+		for await (const _ of runner.run()) {
+			// Iterate completely
+		}
+	}
+
 	/**
 	 * @throws {Error}
 	 * @returns {AsyncGenerator<import('../core/Intent.js').Intent, import('../core/Intent.js').ResultIntent, any>}

package/types/testing/SpecRunner.d.ts

@@ -16,6 +16,28 @@ export class SpecRunner extends ModelAsApp {
         running: string;
         unhandledSteps: string;
     };
+    /**
+     * Convenience method to load a .nan0 file and run a specific scenario.
+     *
+     * 💡 Note on Expectations:
+     * You do NOT need to write manual assertions when using this method.
+     * The `for await (const _ of runner.run()) {}` loop drives the generator,
+     * but ALL assertions are handled automatically inside `SpecAdapter.js`.
+     *
+     * Whenever the App yields an intent (`ask`, `show`, `result`), `SpecAdapter`
+     * intercepts it and compares it strictly against the next step in the `.nan0` file.
+     * - If it matches, the test continues (and `$value` is injected back into the App).
+     * - If it mismatches, it throws an `assert.fail()` which fails the Node.js test immediately.
+     * - If the App finishes early, it throws an `unhandledSteps` error.
+     *
+     * @param {string} fileDir The directory containing the file (e.g., import.meta.dirname)
+     * @param {string} fileName The name of the .nan0 file
+     * @param {string} scenarioName The name of the scenario to run
+     * @param {Record<string, any>} registry The Model Class registry
+     * @param {Partial<import('../index.js').ModelAsAppOptions>} [options={}] Additional runner context options
+     * @throws {Error} If the scenario is missing or if expectations fail during execution
+     */
+    static executeFile(fileDir: string, fileName: string, scenarioName: string, registry: Record<string, any>, options?: Partial<import("../index.js").ModelAsAppOptions>): Promise<void>;
     /**
      * Run a Nan0Spec sequence programmatically (for unit tests).
      *