dazscript-framework 1.0.29 → 1.0.31

package/README.md

@@ -9,6 +9,8 @@
 - [Quick Start: A Simple Dialog](#quick-start-a-simple-dialog)
 - [Documentation](#documentation)
   - [Installation & Setup](#installation--setup)
+  - [Unit Tests](#unit-tests)
+  - [DAZ Studio Integration Tests](#daz-studio-integration-tests)
   - [Project Configuration](#project-configuration)
   - [The `action(...)` Entrypoint](#the-action-entrypoint)
   - [Build Output: Launcher Shims](#build-output-launcher-shims)
@@ -55,6 +57,13 @@ npx dazscript init
 
 Follow the prompt for your AppData author namespace (e.g. `YourName/my-project`). This creates `dazscript.config.ts`, `tsconfig.json`, and wires the `build`, `build:encrypted`, `build:release`, `watch`, `encrypt`, `icons`, and `installer` scripts into `package.json`.
 
+To include optional test scaffolds, run one or both:
+
+```bash
+npx dazscript init --unit-tests
+npx dazscript init --integration-tests
+```
+
 ### 3. Write the script
 
 Create `src/hello-world.dsa.ts`:
@@ -166,6 +175,8 @@ Available `init` flags:
 
 ```bash
 npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out --app-data-path YourName/my-project
+npx dazscript init --unit-tests --app-data-path YourName/my-project
+npx dazscript init --integration-tests --app-data-path YourName/my-project
 ```
 
 | Flag | Description |
@@ -174,11 +185,43 @@ npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out -
 | `--scripts-path` | Where the generator scans for runnable `.dsa.ts` entry files |
 | `--out-dir` | Where `build` writes `.dsa` files and copies icons |
 | `--app-data-path` | AppData namespace for launcher fallback (`Author/Product` format) |
+| `--unit-tests` | Add Vitest config, sample unit test, unit-test docs, `test` scripts, and the `vitest` dev dependency |
+| `--integration-tests` | Add a DAZ Studio headless integration-test fixture, env examples, ignore entries, and `test:integration` script |
 
 Builds also accept `--log-level <trace|debug|info|warn|error|off>`. This sets the minimum runtime log level for the compiled scripts. When omitted, builds default to `debug`; use `warn` for release packages.
 
 Use `--scripts-path ./src/scripts` when runnable files live under a subfolder; use `--scripts-path ./src` when they are at the source root.
 
+### Unit tests
+
+Projects can bootstrap fast Node-side TypeScript tests with:
+
+```bash
+npx dazscript init --unit-tests
+```
+
+This adds:
+
+- `vitest.config.ts`
+- `tsconfig.test.json`
+- `test/unit/smoke.test.ts`
+- `test/unit/README.md`
+- `npm test`
+- `npm run test:watch`
+- `vitest` as a dev dependency
+
+Use unit tests for pure TypeScript helpers, parsing, normalization, and code that does not need Daz Studio runtime objects.
+
+### DAZ Studio integration tests
+
+Projects can run real DAZ Studio smoke tests through the published CLI:
+
+```bash
+npm run test:integration
+```
+
+The generated script calls `dazscript integration --fixture ./test/integration/fixtures/<project>-smoke.dsa.ts`. Configure local machine paths in an ignored `.env.integration.local`; `DAZ_STUDIO_EXE` is always required, and `DAZ_TEST_CONTENT_DUF` is required only for tests that use `--require-content`. See `test/integration/README.md` in this repository for maintainer and consuming-project details.
+
 ---
 
 ### Project Configuration
@@ -528,14 +571,29 @@ my-daz-scripts/
 │   ├── my-dialog-model.ts       # plain TypeScript — model or helper class
 │   ├── my-dialog.ts
 │   └── my-dialog-script.dsa.ts  # runnable entry point
+├── test/
+│   ├── integration/
+│   │   ├── fixtures/
+│   │   │   └── my-daz-scripts-smoke.dsa.ts
+│   │   ├── out/                 # integration output, ignored by git
+│   │   └── README.md
+│   └── unit/
+│       ├── smoke.test.ts
+│       └── README.md
 ├── out/                         # build output — launchers, bundles, icons
+├── .env.integration.linux.example
+├── .env.integration.windows.example
 ├── dazscript.config.ts
 ├── tsconfig.json
+├── tsconfig.test.json
+├── vitest.config.ts
 └── package.json
 ```
 
 Files ending in `.dsa.ts` are treated as runnable entry points and compiled to `.dsa`. Plain `.ts` files are modules — imported by entry points but not compiled independently.
 
+The `test/unit/` files are generated only when you run `dazscript init --unit-tests`. The `test/integration/` files and env examples are generated only when you run `dazscript init --integration-tests`.
+
 **Common commands**
 
 | Command | What it does |
@@ -545,6 +603,8 @@ Files ending in `.dsa.ts` are treated as runnable entry points and compiled to `
 | `npm run watch` | Recompile on every save |
 | `npm run installer` | Generate the setup dialog |
 | `npm run icons` | Copy icon assets to the output folder |
+| `npm test` | Run fast Node/Vitest tests |
+| `npm run test:integration` | Run a DAZ Studio headless integration fixture |
 
 ---
 

package/dist/scripts/cli.js

@@ -9,6 +9,7 @@ const { copyIcons } = require('./icons');
 const { runEncrypt } = require('./encrypt');
 const { generateInstallerFiles } = require('./install-generator');
 const { initProject } = require('./init');
+const { runIntegration } = require('./integration');
 
 function printHelp() {
   console.log(`dazscript <command> [options]
@@ -20,6 +21,7 @@ Commands:
   encrypt             Encrypt built implementation bundles through Daz Studio
   icons               Copy png assets into the output directory
   installer           Generate Install.dsa.ts and Uninstall.dsa.ts
+  integration         Run a DAZ Studio headless integration fixture
 
 Options:
   --menu-path <path>    Default menu path. Default: /MyScripts
@@ -30,6 +32,11 @@ Options:
   --daz-studio <path>   Daz Studio executable for encrypt
   --keep-source         Keep source script.dsa files after encrypting
   --timeout-ms <value>  Daz Studio encrypt timeout. Default: 300000
+  --fixture <path>      Integration fixture .dsa.ts file
+  --env-file <path>     Integration env file. Default: .env.integration.local
+  --require-content     Require DAZ_TEST_CONTENT_DUF for integration tests
+  --unit-tests          Add Vitest unit-test scaffold during init
+  --integration-tests   Add integration-test scaffold during init
   --force               Overwrite generated files
   --help                Show this message
 `);
@@ -92,6 +99,16 @@ function parseOptions(args, defaults) {
       continue;
     }
 
+    if (arg === '--integration-tests') {
+      options.integrationTests = true;
+      continue;
+    }
+
+    if (arg === '--unit-tests') {
+      options.unitTests = true;
+      continue;
+    }
+
     if (arg === '--menu-path') {
       options.menuPath = args[index + 1];
       index += 1;
@@ -139,6 +156,23 @@ function parseOptions(args, defaults) {
       continue;
     }
 
+    if (arg === '--fixture') {
+      options.fixture = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--env-file') {
+      options.envFile = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--require-content') {
+      options.requireContent = true;
+      continue;
+    }
+
     if (arg === '--file') {
       options.file = args[index + 1];
       index += 1;
@@ -191,6 +225,11 @@ async function main(argv) {
     dazStudio: undefined,
     keepSource: false,
     timeoutMs: undefined,
+    fixture: undefined,
+    envFile: undefined,
+    requireContent: false,
+    unitTests: false,
+    integrationTests: false,
   });
 
   if (options.help) {
@@ -198,6 +237,11 @@ async function main(argv) {
     return;
   }
 
+  if (command === 'integration') {
+    await runIntegration(options, process.env, workdir);
+    return;
+  }
+
   const commandOptions =
     command === 'init'
       ? await resolveInitOptions(workdir, options)

package/dist/scripts/init.js

@@ -37,11 +37,28 @@ function writeFileIfNeeded(filePath, content, force) {
     return false;
   }
 
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, content);
   console.log(`write ${path.basename(filePath)}`);
   return true;
 }
 
+function ensureLine(filePath, line) {
+  const existing = fs.existsSync(filePath)
+    ? fs.readFileSync(filePath, 'utf8')
+    : '';
+  const lines = existing.split(/\r?\n/).map((item) => item.trim()).filter(Boolean);
+
+  if (lines.includes(line)) {
+    return false;
+  }
+
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(filePath, `${prefix}${line}\n`);
+  console.log(`update ${path.basename(filePath)}`);
+  return true;
+}
+
 function buildConfigContent(options) {
   return `import { defineConfig } from 'dazscript-framework/config';
 
@@ -63,6 +80,13 @@ function toBundleName(projectName) {
     .join(' ');
 }
 
+function toFixtureName(projectName) {
+  return projectName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'project';
+}
+
 function buildTsconfigContent() {
   return `{
   "extends": "./node_modules/dazscript-framework/tsconfig.json",
@@ -106,6 +130,299 @@ function updatePackageJson(workdir, options) {
   console.log('update package.json');
 }
 
+function updatePackageJsonForIntegration(workdir, fixturePath) {
+  const packageJsonPath = path.join(workdir, 'package.json');
+  const packageJson = fs.existsSync(packageJsonPath)
+    ? readJson(packageJsonPath)
+    : { private: true };
+
+  packageJson.scripts = packageJson.scripts || {};
+  if (packageJson.scripts['test:integration']) {
+    console.log('skip package.json test:integration');
+  }
+  else {
+    packageJson.scripts['test:integration'] = `dazscript integration --fixture ${fixturePath}`;
+    writeJson(packageJsonPath, packageJson);
+    console.log('update package.json');
+  }
+}
+
+function isNpmDefaultTestScript(scriptName, command) {
+  return scriptName === 'test' && command === 'echo "Error: no test specified" && exit 1';
+}
+
+function setPackageScript(packageJson, scriptName, command) {
+  packageJson.scripts = packageJson.scripts || {};
+  const existingCommand = packageJson.scripts[scriptName];
+  if (existingCommand && !isNpmDefaultTestScript(scriptName, existingCommand)) {
+    console.log(`skip package.json ${scriptName}`);
+    return false;
+  }
+
+  packageJson.scripts[scriptName] = command;
+  return true;
+}
+
+function setDevDependency(packageJson, dependencyName, version) {
+  packageJson.devDependencies = packageJson.devDependencies || {};
+  if (packageJson.devDependencies[dependencyName]) {
+    return false;
+  }
+
+  packageJson.devDependencies[dependencyName] = version;
+  return true;
+}
+
+function updatePackageJsonForUnitTests(workdir) {
+  const packageJsonPath = path.join(workdir, 'package.json');
+  const packageJson = fs.existsSync(packageJsonPath)
+    ? readJson(packageJsonPath)
+    : { private: true };
+
+  let changed = false;
+  changed = setPackageScript(packageJson, 'test', 'vitest run') || changed;
+  changed = setPackageScript(packageJson, 'test:watch', 'vitest') || changed;
+  changed = setDevDependency(packageJson, 'vitest', '^3.0.0') || changed;
+
+  if (changed) {
+    writeJson(packageJsonPath, packageJson);
+    console.log('update package.json');
+  }
+}
+
+function buildVitestConfigContent() {
+  return `import path from 'node:path'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+    test: {
+        environment: 'node',
+        include: ['src/**/*.test.ts', 'test/unit/**/*.test.ts']
+    },
+    resolve: {
+        alias: {
+            '@dsf': path.resolve(__dirname, 'node_modules/dazscript-framework/src'),
+            '@dst': path.resolve(__dirname, 'node_modules/dazscript-types/src/types')
+        }
+    }
+})
+`;
+}
+
+function buildTestTsconfigContent() {
+  return `{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "Node"
+  },
+  "include": ["src/**/*.test.ts", "test/unit/**/*.test.ts"],
+  "exclude": []
+}
+`;
+}
+
+function buildUnitTestContent() {
+  return `import { describe, expect, it } from 'vitest'
+
+const toTitleCase = (value: string): string =>
+    value
+        .split(/[-_\\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ')
+
+describe('unit test scaffold', () => {
+    it('runs TypeScript tests with Vitest', () => {
+        expect(toTitleCase('hello-daz-script')).toBe('Hello Daz Script')
+    })
+})
+`;
+}
+
+function buildUnitTestReadmeContent() {
+  return `# Unit Tests
+
+This project uses Vitest for fast Node-side unit tests.
+
+Run once:
+
+\`\`\`bash
+npm test
+\`\`\`
+
+Watch mode:
+
+\`\`\`bash
+npm run test:watch
+\`\`\`
+
+Unit tests are useful for pure TypeScript helpers, parsing, normalization, and other logic that does not require Daz Studio runtime objects. Use DAZ Studio integration tests for helpers that must execute inside Daz Studio.
+`;
+}
+
+function initUnitTests(workdir, options) {
+  writeFileIfNeeded(
+    path.join(workdir, 'vitest.config.ts'),
+    buildVitestConfigContent(),
+    options.force
+  );
+  writeFileIfNeeded(
+    path.join(workdir, 'tsconfig.test.json'),
+    buildTestTsconfigContent(),
+    options.force
+  );
+  writeFileIfNeeded(
+    path.join(workdir, 'test/unit/smoke.test.ts'),
+    buildUnitTestContent(),
+    options.force
+  );
+  writeFileIfNeeded(
+    path.join(workdir, 'test/unit/README.md'),
+    buildUnitTestReadmeContent(),
+    options.force
+  );
+  updatePackageJsonForUnitTests(workdir);
+}
+
+function buildIntegrationFixtureContent() {
+  return `import { action } from '@dsf/core/action'
+import { saveToFile } from '@dsf/helpers/file-helper'
+import { currentTime, frameToTime, getCurrentFrame, timeToFrame } from '@dsf/helpers/scene-helper'
+import { getStringScriptArguments } from '@dsf/helpers/script-helper'
+
+type IntegrationResult = {
+    ok: boolean
+    project: string
+    checks: Record<string, unknown>
+    failures: string[]
+}
+
+const isNumber = (value: unknown): boolean => typeof value === 'number' && !isNaN(value as number)
+
+action({ text: 'Integration Smoke Test', menuPath: false }, () => {
+    const args = getStringScriptArguments()
+    const resultPath = args.length > 0 ? args[0] : ''
+    const failures: string[] = []
+    const frame = getCurrentFrame()
+    const time = frameToTime(frame)
+    const current = currentTime()
+    const roundTripFrame = timeToFrame(time)
+
+    if (!resultPath) {
+        failures.push('missing result path argument')
+    }
+    if (!isNumber(frame)) {
+        failures.push('scene-helper getCurrentFrame did not return a number')
+    }
+    if (current === null || current === undefined) {
+        failures.push('scene-helper currentTime returned null or undefined')
+    }
+    if (roundTripFrame !== frame) {
+        failures.push(\`frame/time round trip failed: \${frame} -> \${time} -> \${roundTripFrame}\`)
+    }
+
+    const result: IntegrationResult = {
+        ok: failures.length === 0,
+        project: 'integration-smoke',
+        checks: {
+            frame,
+            time: String(time),
+            currentTime: String(current),
+            roundTripFrame
+        },
+        failures
+    }
+
+    if (resultPath) {
+        saveToFile(resultPath, JSON.stringify(result, null, 2))
+    }
+})
+`;
+}
+
+function buildIntegrationReadmeContent(fixturePath) {
+  return `# Integration Tests
+
+This project uses the framework DAZ Studio headless integration harness.
+
+Create a local env file from the example for your OS:
+
+\`\`\`bash
+cp .env.integration.linux.example .env.integration.local
+\`\`\`
+
+\`\`\`powershell
+Copy-Item .env.integration.windows.example .env.integration.local
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+npm run test:integration
+\`\`\`
+
+The default smoke fixture is figure-independent:
+
+\`\`\`text
+${fixturePath}
+\`\`\`
+
+Generated output is written to \`test/integration/out/\` and ignored by git.
+`;
+}
+
+function buildLinuxEnvExample() {
+  return `# Copy this file to .env.integration.local and edit paths for your machine.
+# Shell environment variables override values in .env.integration.local.
+# DAZ_STUDIO_EXE is required for all integration tests.
+# DAZ_TEST_CONTENT_DUF is required only when the fixture or npm script uses --require-content.
+
+WINEPREFIX=/home/your-user/.local/share/daz-wine/prefix
+DAZ_STUDIO_EXE=/home/your-user/.local/share/daz-wine/prefix/drive_c/Program Files/DAZ 3D/DAZStudio4/DAZStudio.exe
+# DAZ_TEST_CONTENT_DUF=/home/your-user/.local/share/daz-wine/prefix/drive_c/users/Public/Documents/My DAZ 3D Library/People/Genesis 9/Genesis 9.duf
+DAZ_TEST_TIMEOUT_MS=300000
+`;
+}
+
+function buildWindowsEnvExample() {
+  return `# Copy this file to .env.integration.local and edit paths for your machine.
+# Shell environment variables override values in .env.integration.local.
+# Forward slashes avoid escaping issues in env files.
+# DAZ_STUDIO_EXE is required for all integration tests.
+# DAZ_TEST_CONTENT_DUF is required only when the fixture or npm script uses --require-content.
+
+DAZ_STUDIO_EXE=C:/Program Files/DAZ 3D/DAZStudio4/DAZStudio.exe
+# DAZ_TEST_CONTENT_DUF=C:/Users/Public/Documents/My DAZ 3D Library/People/Genesis 9/Genesis 9.duf
+DAZ_TEST_TIMEOUT_MS=300000
+`;
+}
+
+function initIntegrationTests(workdir, options) {
+  const fixtureBaseName = `${toFixtureName(path.basename(workdir))}-smoke.dsa.ts`;
+  const fixturePath = `./test/integration/fixtures/${fixtureBaseName}`;
+  const localFixturePath = path.join(workdir, fixturePath);
+
+  writeFileIfNeeded(localFixturePath, buildIntegrationFixtureContent(), options.force);
+  writeFileIfNeeded(
+    path.join(workdir, 'test/integration/README.md'),
+    buildIntegrationReadmeContent(fixturePath),
+    options.force
+  );
+  writeFileIfNeeded(
+    path.join(workdir, '.env.integration.linux.example'),
+    buildLinuxEnvExample(),
+    options.force
+  );
+  writeFileIfNeeded(
+    path.join(workdir, '.env.integration.windows.example'),
+    buildWindowsEnvExample(),
+    options.force
+  );
+  updatePackageJsonForIntegration(workdir, fixturePath);
+  ensureLine(path.join(workdir, '.gitignore'), 'test/integration/out/');
+  ensureLine(path.join(workdir, '.gitignore'), '.env.integration.local');
+}
+
 function initProject(workdir, rawOptions) {
   const projectName = path.basename(workdir);
   const options = {
@@ -115,6 +432,8 @@ function initProject(workdir, rawOptions) {
     outDir: normalizePath(rawOptions.outDir, './out'),
     appDataPath: normalizePath(rawOptions.appDataPath, `YourName/${projectName}`),
     bundleName: toBundleName(projectName),
+    unitTests: Boolean(rawOptions.unitTests),
+    integrationTests: Boolean(rawOptions.integrationTests),
   };
 
   writeFileIfNeeded(
@@ -129,8 +448,18 @@ function initProject(workdir, rawOptions) {
   );
 
   updatePackageJson(workdir, options);
+
+  if (options.unitTests) {
+    initUnitTests(workdir, options);
+  }
+
+  if (options.integrationTests) {
+    initIntegrationTests(workdir, options);
+  }
 }
 
 module.exports = {
+  initIntegrationTests,
+  initUnitTests,
   initProject,
 };