dazscript-framework 1.0.29 → 1.0.30

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,
 };

package/dist/scripts/integration.js

@@ -0,0 +1,304 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const defaultTimeoutMs = 300000;
+
+function isDazPath(value) {
+  return /^[A-Za-z]:[\\/]/.test(String(value || ''));
+}
+
+function normalizeForDaz(value) {
+  const normalized = String(value).replace(/\\/g, '/');
+  const driveMatch = normalized.match(/\/drive_([A-Za-z])\/(.+)$/);
+  if (driveMatch) {
+    return `${driveMatch[1].toUpperCase()}:/${driveMatch[2]}`;
+  }
+
+  return normalized;
+}
+
+function unquoteEnvValue(value) {
+  const trimmed = String(value || '').trim();
+  if (trimmed.length < 2) return trimmed;
+
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if ((first === '"' && last === '"') || (first === '\'' && last === '\'')) {
+    return trimmed.substring(1, trimmed.length - 1);
+  }
+
+  return trimmed;
+}
+
+function loadEnvFile(envPath, targetEnv) {
+  if (!envPath || !fs.existsSync(envPath)) return false;
+
+  const lines = fs.readFileSync(envPath, 'utf8').split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (!line || line[0] === '#') continue;
+
+    const separatorIndex = line.indexOf('=');
+    if (separatorIndex <= 0) continue;
+
+    const key = line.substring(0, separatorIndex).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    if (targetEnv[key] !== undefined) continue;
+
+    targetEnv[key] = unquoteEnvValue(line.substring(separatorIndex + 1));
+  }
+
+  return true;
+}
+
+function assertRequiredFile(label, filePath, allowDazPath) {
+  if (!filePath) {
+    throw new Error(`missing required env: ${label}`);
+  }
+
+  if (allowDazPath && isDazPath(filePath)) {
+    return filePath;
+  }
+
+  const resolvedPath = path.resolve(filePath);
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`${label} does not exist: ${resolvedPath}`);
+  }
+
+  return resolvedPath;
+}
+
+function resolveIntegrationOptions(cwd, rawOptions, env) {
+  const options = rawOptions || {};
+  const projectRoot = path.resolve(cwd || process.cwd());
+  const envFile = path.resolve(projectRoot, options.envFile || '.env.integration.local');
+  const fixturePath = options.fixture
+    ? path.resolve(projectRoot, options.fixture)
+    : '';
+
+  if (!fixturePath) {
+    throw new Error('missing required option: --fixture <path>');
+  }
+  if (!fs.existsSync(fixturePath)) {
+    throw new Error(`fixture file does not exist: ${fixturePath}`);
+  }
+
+  const dazStudioExe = assertRequiredFile(
+    'DAZ_STUDIO_EXE',
+    options.dazStudio || env.DAZ_STUDIO_EXE,
+    false
+  );
+
+  const rawContentPath = options.contentDuf || env.DAZ_TEST_CONTENT_DUF || '';
+  if (options.requireContent) {
+    assertRequiredFile('DAZ_TEST_CONTENT_DUF', rawContentPath, true);
+  }
+  else if (rawContentPath && !isDazPath(rawContentPath) && !fs.existsSync(path.resolve(rawContentPath))) {
+    throw new Error(`DAZ_TEST_CONTENT_DUF does not exist: ${path.resolve(rawContentPath)}`);
+  }
+
+  const timeoutMs = Number(options.timeoutMs || env.DAZ_TEST_TIMEOUT_MS || defaultTimeoutMs);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`invalid timeout: ${options.timeoutMs || env.DAZ_TEST_TIMEOUT_MS}`);
+  }
+
+  const outDir = path.resolve(projectRoot, options.outDir || './test/integration/out');
+  const fixtureName = path.basename(fixturePath).replace(/\.dsa\.ts$/i, '').replace(/\.ts$/i, '');
+  const fixtureRoot = path.join(outDir, 'fixture');
+  const resultPath = path.join(fixtureRoot, 'result.json');
+  const frameworkRoot = path.resolve(__dirname, '..', '..');
+
+  return {
+    projectRoot,
+    frameworkRoot,
+    envFile,
+    fixturePath,
+    fixtureName,
+    outDir,
+    fixtureRoot,
+    resultPath,
+    dazStudioExe,
+    contentPath: rawContentPath ? normalizeForDaz(rawContentPath) : '',
+    requireContent: Boolean(options.requireContent),
+    timeoutMs,
+    appDataPath: options.appDataPath || 'DazScriptFramework/integration-tests',
+    bundleName: options.bundleName || 'Integration Test Fixture',
+    env,
+  };
+}
+
+function run(command, args, options) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    encoding: 'utf8',
+    stdio: options.stdio || 'inherit',
+    timeout: options.timeoutMs,
+  });
+
+  if (result.error) {
+    if (result.error.code === 'ETIMEDOUT') {
+      throw new Error(`${command} timed out after ${options.timeoutMs}ms`);
+    }
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} exited with code ${result.status}`);
+  }
+
+  return result;
+}
+
+function writeFile(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function buildFixtureProject(options) {
+  fs.rmSync(options.fixtureRoot, { recursive: true, force: true });
+  fs.mkdirSync(path.join(options.fixtureRoot, 'src'), { recursive: true });
+
+  writeFile(path.join(options.fixtureRoot, 'package.json'), JSON.stringify({
+    private: true,
+    scripts: {
+      build: 'dazscript build --out-dir ./out',
+    },
+    dependencies: {
+      'dazscript-framework': `file:${options.frameworkRoot}`,
+      'dazscript-types': '^1.0.1',
+    },
+    devDependencies: {},
+  }, null, 2));
+
+  writeFile(path.join(options.fixtureRoot, 'dazscript.config.ts'), [
+    "import { defineConfig } from 'dazscript-framework/config';",
+    '',
+    'export default defineConfig({',
+    "  scriptsPath: './src',",
+    "  outDir: './out',",
+    "  defaultMenuPath: '/DazScriptFramework/Integration',",
+    `  appDataPath: '${options.appDataPath}',`,
+    `  bundleName: '${options.bundleName}'`,
+    '});',
+    '',
+  ].join('\n'));
+
+  writeFile(path.join(options.fixtureRoot, 'tsconfig.json'), JSON.stringify({
+    compilerOptions: {
+      target: 'ES5',
+      baseUrl: '.',
+      ignoreDeprecations: '5.0',
+      lib: ['ES5'],
+      experimentalDecorators: true,
+      emitDecoratorMetadata: true,
+      noLib: false,
+      useDefineForClassFields: false,
+      module: 'ESNext',
+      paths: {
+        '@dst/*': ['node_modules/dazscript-types/src/types/*'],
+        '@dsf/*': ['node_modules/dazscript-framework/src/*'],
+      },
+      declaration: false,
+      inlineSourceMap: false,
+      removeComments: true,
+      preserveConstEnums: true,
+      esModuleInterop: true,
+      forceConsistentCasingInFileNames: true,
+      strict: false,
+      strictNullChecks: false,
+      strictPropertyInitialization: false,
+      noImplicitAny: false,
+      strictFunctionTypes: true,
+      alwaysStrict: true,
+      skipLibCheck: true,
+    },
+    include: [
+      'node_modules/dazscript-types/src/types/**/*',
+      'src/**/*',
+    ],
+  }, null, 2));
+
+  fs.copyFileSync(options.fixturePath, path.join(options.fixtureRoot, 'src', `${options.fixtureName}.dsa.ts`));
+  run('npm', ['install', '--ignore-scripts'], { cwd: options.fixtureRoot });
+  run('npm', ['run', 'build'], { cwd: options.fixtureRoot });
+}
+
+function runDazFixture(options) {
+  const launcherPath = path.join(options.fixtureRoot, 'out', `${options.fixtureName}.dsa`);
+  if (!fs.existsSync(launcherPath)) {
+    throw new Error(`generated launcher was not found: ${launcherPath}`);
+  }
+
+  const dazArgs = [
+    '-headless',
+    '-noPrompt',
+    '-scriptArg',
+    normalizeForDaz(options.resultPath),
+  ];
+
+  if (options.contentPath) {
+    dazArgs.push('-scriptArg', options.contentPath);
+  }
+
+  dazArgs.push('-script', normalizeForDaz(launcherPath));
+
+  const useWine = process.platform !== 'win32' && /\.exe$/i.test(options.dazStudioExe);
+  const command = useWine ? 'wine' : options.dazStudioExe;
+  const commandArgs = useWine ? [options.dazStudioExe].concat(dazArgs) : dazArgs;
+
+  console.log(`[dazscript integration] launching DAZ: ${useWine ? `${command} ${options.dazStudioExe}` : command}`);
+  run(command, commandArgs, {
+    cwd: options.fixtureRoot,
+    env: options.env,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+function readIntegrationResult(resultPath) {
+  if (!fs.existsSync(resultPath)) {
+    throw new Error(`DAZ did not write result JSON: ${resultPath}`);
+  }
+
+  let result;
+  try {
+    result = JSON.parse(fs.readFileSync(resultPath, 'utf8'));
+  }
+  catch (error) {
+    throw new Error(`could not parse result JSON: ${error}`);
+  }
+
+  if (!result || result.ok !== true) {
+    const failures = result && result.failures ? result.failures : ['unknown DAZ integration failure'];
+    throw new Error(`DAZ integration assertions failed:\n${failures.map((item) => `- ${item}`).join('\n')}\n\nResult: ${resultPath}`);
+  }
+
+  return result;
+}
+
+async function runIntegration(rawOptions, injectedEnv, cwd) {
+  const env = { ...(injectedEnv || process.env) };
+  const projectRoot = path.resolve(cwd || process.cwd());
+  const envFile = path.resolve(projectRoot, (rawOptions && rawOptions.envFile) || '.env.integration.local');
+  loadEnvFile(envFile, env);
+
+  const options = resolveIntegrationOptions(projectRoot, rawOptions, env);
+  buildFixtureProject(options);
+  runDazFixture(options);
+  const result = readIntegrationResult(options.resultPath);
+  console.log(`[dazscript integration] passed: ${options.resultPath}`);
+  return result;
+}
+
+module.exports = {
+  loadEnvFile,
+  normalizeForDaz,
+  readIntegrationResult,
+  resolveIntegrationOptions,
+  buildFixtureProject,
+  runDazFixture,
+  runIntegration,
+};

package/dist/scripts/launchers.js

@@ -96,7 +96,13 @@ function makeLauncherSource(implementationRelativePath, appDataImplementationRel
     `        MessageBox.warning('Unable to load script implementation:\\n' + implementationPath, 'Script Load Error', '&OK;', '');`,
     '        script.deleteLater();',
     '    } else {',
-    "        var args = typeof getArguments == 'function' ? getArguments() : [];",
+    '        var args = [];',
+    "        if (typeof getArguments == 'function') {",
+    '            args = getArguments();',
+    '        }',
+    '        if (!args || args.length === 0) {',
+    '            args = App.scriptArgs || [];',
+    '        }',
     '        script.execute(args);',
     '        script.deleteLater();',
     '    }',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dazscript-framework",
-  "version": "1.0.29",
+  "version": "1.0.30",
   "author": "Freddy Diaz",
   "license": "MPL-2.0",
   "description": "",
@@ -13,6 +13,7 @@
     "icons": "node ./dist/scripts/cli.js icons --out-dir ./out",
     "installer": "node ./dist/scripts/cli.js installer --scripts-path ./src/examples --menu-path /DazScriptFramework",
     "test": "vitest run",
+    "test:integration": "node ./dist/scripts/cli.js integration --fixture ./test/integration/fixtures/framework-integration.dsa.ts --require-content",
     "test:watch": "vitest"
   },
   "bin": {

package/src/helpers/script-helper.ts

@@ -17,7 +17,12 @@ export const getScriptPath = (): string => {
 
 export const getScriptArguments = (): any[] => {
     try {
-        return typeof getArguments === 'function' ? getArguments() : []
+        if (typeof getArguments === 'function') {
+            const args = getArguments()
+            if (args && args.length > 0) return args
+        }
+
+        return App.scriptArgs ?? []
     }
     catch (e) {
         return []

package/src/scripts/init.test.ts

@@ -0,0 +1,131 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const { initIntegrationTests, initUnitTests } = require('../../dist/scripts/init')
+
+const tempDirs: string[] = []
+
+const makeProject = (name = 'toolbox-test'): string => {
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), `${name}-`))
+    tempDirs.push(projectDir)
+    fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify({
+        private: true,
+        scripts: {
+            test: 'vitest run',
+        },
+    }, null, 2))
+    return projectDir
+}
+
+const toFixtureName = (projectDir: string): string =>
+    path.basename(projectDir)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'project'
+
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop()
+        if (dir) fs.rmSync(dir, { recursive: true, force: true })
+    }
+})
+
+describe('init integration tests', () => {
+    it('creates the fixture, docs, env examples, npm script, and ignore entries', () => {
+        const projectDir = makeProject('toolbox-test')
+        const fixtureBaseName = toFixtureName(projectDir)
+
+        initIntegrationTests(projectDir, { force: false })
+
+        const fixturePath = path.join(projectDir, `test/integration/fixtures/${fixtureBaseName}-smoke.dsa.ts`)
+        const packageJson = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8'))
+        const gitignore = fs.readFileSync(path.join(projectDir, '.gitignore'), 'utf8')
+
+        expect(fs.existsSync(fixturePath)).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, 'test/integration/README.md'))).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, '.env.integration.linux.example'))).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, '.env.integration.windows.example'))).toBe(true)
+        expect(packageJson.scripts['test:integration']).toBe(
+            `dazscript integration --fixture ./test/integration/fixtures/${fixtureBaseName}-smoke.dsa.ts`
+        )
+        expect(gitignore).toContain('test/integration/out/')
+        expect(gitignore).toContain('.env.integration.local')
+    })
+
+    it('does not replace an existing integration script or duplicate ignore entries', () => {
+        const projectDir = makeProject('existing-test')
+        const packageJsonPath = path.join(projectDir, 'package.json')
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+        packageJson.scripts['test:integration'] = 'custom command'
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2))
+        fs.writeFileSync(path.join(projectDir, '.gitignore'), 'test/integration/out/\n')
+
+        initIntegrationTests(projectDir, { force: false })
+        initIntegrationTests(projectDir, { force: false })
+
+        const updatedPackageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+        const gitignore = fs.readFileSync(path.join(projectDir, '.gitignore'), 'utf8')
+
+        expect(updatedPackageJson.scripts['test:integration']).toBe('custom command')
+        expect(gitignore.match(/test\/integration\/out\//g)?.length).toBe(1)
+        expect(gitignore.match(/\.env\.integration\.local/g)?.length).toBe(1)
+    })
+})
+
+describe('init unit tests', () => {
+    it('creates Vitest config, sample test, docs, npm scripts, and dev dependency', () => {
+        const projectDir = makeProject('unit-test')
+        const packageJsonPath = path.join(projectDir, 'package.json')
+        const initialPackageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+        delete initialPackageJson.scripts.test
+        fs.writeFileSync(packageJsonPath, JSON.stringify(initialPackageJson, null, 2))
+
+        initUnitTests(projectDir, { force: false })
+
+        const packageJson = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8'))
+
+        expect(fs.existsSync(path.join(projectDir, 'vitest.config.ts'))).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, 'tsconfig.test.json'))).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, 'test/unit/smoke.test.ts'))).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, 'test/unit/README.md'))).toBe(true)
+        expect(packageJson.scripts.test).toBe('vitest run')
+        expect(packageJson.scripts['test:watch']).toBe('vitest')
+        expect(packageJson.devDependencies.vitest).toBe('^3.0.0')
+    })
+
+    it('does not replace existing unit test scripts or duplicate Vitest dependency', () => {
+        const projectDir = makeProject('existing-unit-test')
+        const packageJsonPath = path.join(projectDir, 'package.json')
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+        packageJson.scripts.test = 'custom test'
+        packageJson.scripts['test:watch'] = 'custom watch'
+        packageJson.devDependencies = {
+            vitest: '^4.0.0',
+        }
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2))
+
+        initUnitTests(projectDir, { force: false })
+
+        const updatedPackageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+
+        expect(updatedPackageJson.scripts.test).toBe('custom test')
+        expect(updatedPackageJson.scripts['test:watch']).toBe('custom watch')
+        expect(updatedPackageJson.devDependencies.vitest).toBe('^4.0.0')
+    })
+
+    it('replaces the default npm init failing test script', () => {
+        const projectDir = makeProject('npm-default-unit-test')
+        const packageJsonPath = path.join(projectDir, 'package.json')
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+        packageJson.scripts.test = 'echo "Error: no test specified" && exit 1'
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2))
+
+        initUnitTests(projectDir, { force: false })
+
+        const updatedPackageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+
+        expect(updatedPackageJson.scripts.test).toBe('vitest run')
+    })
+})

package/src/scripts/integration.test.ts

@@ -0,0 +1,97 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const {
+    loadEnvFile,
+    readIntegrationResult,
+    resolveIntegrationOptions,
+} = require('../../dist/scripts/integration')
+
+const tempDirs: string[] = []
+
+const makeProject = (): string => {
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsf-integration-'))
+    tempDirs.push(projectDir)
+    fs.mkdirSync(path.join(projectDir, 'test/integration/fixtures'), { recursive: true })
+    fs.writeFileSync(path.join(projectDir, 'test/integration/fixtures/smoke.dsa.ts'), 'action({}, function() {})\n')
+    fs.writeFileSync(path.join(projectDir, 'DAZStudio.exe'), '')
+    return projectDir
+}
+
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop()
+        if (dir) fs.rmSync(dir, { recursive: true, force: true })
+    }
+})
+
+describe('integration env loader', () => {
+    it('loads simple values without overriding existing values', () => {
+        const projectDir = makeProject()
+        const envPath = path.join(projectDir, '.env.integration.local')
+        fs.writeFileSync(envPath, [
+            '# local machine settings',
+            'DAZ_STUDIO_EXE=/from/file/DAZStudio.exe',
+            'DAZ_TEST_TIMEOUT_MS="12345"',
+            'INVALID KEY=ignored',
+            '',
+        ].join('\n'))
+
+        const env: Record<string, string> = {
+            DAZ_STUDIO_EXE: '/from/shell/DAZStudio.exe',
+        }
+
+        expect(loadEnvFile(envPath, env)).toBe(true)
+        expect(env.DAZ_STUDIO_EXE).toBe('/from/shell/DAZStudio.exe')
+        expect(env.DAZ_TEST_TIMEOUT_MS).toBe('12345')
+        expect(env['INVALID KEY']).toBeUndefined()
+    })
+})
+
+describe('integration option resolution', () => {
+    it('uses project-relative fixture and output defaults without requiring content', () => {
+        const projectDir = makeProject()
+        const options = resolveIntegrationOptions(projectDir, {
+            fixture: './test/integration/fixtures/smoke.dsa.ts',
+        }, {
+            DAZ_STUDIO_EXE: path.join(projectDir, 'DAZStudio.exe'),
+        })
+
+        expect(options.fixturePath).toBe(path.join(projectDir, 'test/integration/fixtures/smoke.dsa.ts'))
+        expect(options.outDir).toBe(path.join(projectDir, 'test/integration/out'))
+        expect(options.fixtureRoot).toBe(path.join(projectDir, 'test/integration/out/fixture'))
+        expect(options.resultPath).toBe(path.join(projectDir, 'test/integration/out/fixture/result.json'))
+        expect(options.contentPath).toBe('')
+    })
+
+    it('requires content only when requested', () => {
+        const projectDir = makeProject()
+
+        expect(() => resolveIntegrationOptions(projectDir, {
+            fixture: './test/integration/fixtures/smoke.dsa.ts',
+            requireContent: true,
+        }, {
+            DAZ_STUDIO_EXE: path.join(projectDir, 'DAZStudio.exe'),
+        })).toThrow(/DAZ_TEST_CONTENT_DUF/)
+    })
+})
+
+describe('integration result reader', () => {
+    it('accepts successful result JSON', () => {
+        const projectDir = makeProject()
+        const resultPath = path.join(projectDir, 'result.json')
+        fs.writeFileSync(resultPath, JSON.stringify({ ok: true }))
+
+        expect(readIntegrationResult(resultPath)).toEqual({ ok: true })
+    })
+
+    it('reports fixture failures', () => {
+        const projectDir = makeProject()
+        const resultPath = path.join(projectDir, 'result.json')
+        fs.writeFileSync(resultPath, JSON.stringify({ ok: false, failures: ['bad frame'] }))
+
+        expect(() => readIntegrationResult(resultPath)).toThrow(/bad frame/)
+    })
+})