adapt-authoring-core 1.9.2 → 2.0.0

package/docs/writing-tests.md

@@ -1,6 +1,6 @@
 # Writing tests
 
-Instructions for writing tests in this module.
+Instructions for writing tests in this project. Both unit tests (per-module) and integration tests (full application) use the same stack and assertion style.
 
 ## Stack
 
@@ -9,57 +9,7 @@ Instructions for writing tests in this module.
 
 No external test dependencies are needed. Do not introduce Mocha, Jest, or other test frameworks.
 
-> **Note:** Some older modules in the project use Mocha + Should.js. New tests in this module use the built-in Node.js test library instead.
-
-## File placement and naming
-
-- Tests live in a `tests/` directory at the module root
-- One test file per source module, named `<moduleName>.spec.js`
-- Test data/fixtures go in `tests/data/`
-
-```
-my-module/
-├── lib/
-│   ├── myModule.js
-│   └── myUtils.js
-└── tests/
-    ├── data/
-    │   └── fixtures.json
-    ├── myModule.spec.js
-    └── myUtils.spec.js
-```
-
-## File structure
-
-Every test file follows this structure:
-
-```js
-import { describe, it, before } from 'node:test'
-import assert from 'node:assert/strict'
-import MyModule from '../lib/myModule.js'
-
-describe('My Module', () => {
-  let instance
-
-  before(() => {
-    instance = new MyModule()
-  })
-
-  describe('#methodName()', () => {
-    it('should describe expected behaviour', () => {
-      assert.equal(instance.methodName(), 'expected')
-    })
-  })
-})
-```
-
-Key rules:
-
-- Import `describe`, `it`, `before`, `after` etc. from `node:test`
-- Import `assert` from `node:assert/strict` (strict mode uses `deepStrictEqual` by default)
-- Use ES module `import` syntax — this project is `"type": "module"`
-- Group tests by method using nested `describe` blocks, prefixed with `#` for instance methods
-- Store shared state in `let` variables scoped to the `describe` block
+> **Note:** Some older modules in the project use Mocha + Should.js. New tests use the built-in Node.js test library instead.
 
 ## Assertions
 
@@ -96,6 +46,17 @@ assert.notEqual(a, b)
 assert.notDeepEqual(obj1, obj2)
 ```
 
+## Async tests
+
+`node:test` supports `async/await` directly:
+
+```js
+it('should connect successfully', async () => {
+  const result = await instance.connect()
+  assert.equal(typeof result, 'object')
+})
+```
+
 ## Dynamic test generation
 
 When testing a function against multiple inputs, generate tests in a loop:
@@ -117,18 +78,64 @@ invalidInputs.forEach((input) => {
 })
 ```
 
-## Async tests
+## General rules
 
-`node:test` supports `async/await` directly:
+- Import `describe`, `it`, `before`, `after` etc. from `node:test`
+- Import `assert` from `node:assert/strict` (strict mode uses `deepStrictEqual` by default)
+- Use ES module `import` syntax — this project is `"type": "module"`
+- Store shared state in `let` variables scoped to the `describe` block
+- Don't add external test dependencies — `node:test` and `node:assert` are sufficient
+- Don't mock more than necessary — prefer testing real behaviour
+
+---
+
+## Unit tests
+
+Unit tests live inside individual modules and test classes and utilities in isolation.
+
+### File placement and naming
+
+- Tests live in a `tests/` directory at the module root
+- One test file per source module, named `<moduleName>.spec.js`
+- Test data/fixtures go in `tests/data/`
+
+```
+my-module/
+├── lib/
+│   ├── myModule.js
+│   └── myUtils.js
+└── tests/
+    ├── data/
+    │   └── fixtures.json
+    ├── myModule.spec.js
+    └── myUtils.spec.js
+```
+
+### File structure
 
 ```js
-it('should connect successfully', async () => {
-  const result = await instance.connect()
-  assert.equal(typeof result, 'object')
+import { describe, it, before } from 'node:test'
+import assert from 'node:assert/strict'
+import MyModule from '../lib/myModule.js'
+
+describe('My Module', () => {
+  let instance
+
+  before(() => {
+    instance = new MyModule()
+  })
+
+  describe('#methodName()', () => {
+    it('should describe expected behaviour', () => {
+      assert.equal(instance.methodName(), 'expected')
+    })
+  })
 })
 ```
 
-## Test data
+- Group tests by method using nested `describe` blocks, prefixed with `#` for instance methods
+
+### Test data
 
 Place fixture files in `tests/data/`. Use `import` or `fs` to load them:
 
@@ -141,33 +148,31 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 const fixtures = JSON.parse(readFileSync(join(__dirname, 'data', 'fixtures.json')))
 ```
 
-## What to test
+### What to test
 
 - All public methods on exported classes and utilities
 - Both success and error paths
 - Edge cases (empty input, missing arguments, invalid types)
 - That errors are thrown or returned where expected (use `assert.throws` / `assert.rejects`)
 
-## What NOT to do
+### What NOT to do
 
 - Don't test private/internal methods (prefixed with `_`)
-- Don't add external test dependencies — `node:test` and `node:assert` are sufficient
 - Don't write tests that depend on execution order between `describe` blocks
-- Don't mock more than necessary — prefer testing real behaviour
 
-## Add script to package.json
+### Add script to package.json
 
-The tests should be accessible via an npm script in package.json:
-```
+```json
 "scripts": {
   "test": "node --test tests/"
 }
 ```
 
-## Add GitHub workflow
+### Add GitHub workflow
 
-The following workflow should be added to /.github:
-```
+The following workflow should be added to `/.github`:
+
+```yaml
 name: Tests
 on: push
 jobs:
@@ -183,7 +188,7 @@ jobs:
       - run: npm test
 ```
 
-## Running tests
+### Running unit tests
 
 ```bash
 # run the test suite
@@ -194,3 +199,212 @@ npx standard
 ```
 
 Both must pass before submitting a pull request.
+
+---
+
+## Integration tests
+
+Integration tests live in the `integration-tests/` package and test the full application with a real database. They boot the app once and exercise cross-module workflows such as authentication, content CRUD, course import, and course build/export.
+
+See the [integration-tests README](../../integration-tests/README.md) for setup and run instructions.
+
+### File placement and naming
+
+All integration test files live in `integration-tests/tests/`, named `<area>.spec.js`:
+
+```
+integration-tests/
+├── bin/
+│   └── run.js              # test runner entry point
+├── lib/
+│   ├── app.js              # app bootstrap helpers
+│   ├── db.js               # database utilities
+│   └── fixtures.js         # fixture management
+├── tests/
+│   ├── auth.spec.js
+│   ├── content.spec.js
+│   ├── mongodb.spec.js
+│   ├── adaptframework-import.spec.js
+│   └── ...
+└── fixtures/
+    ├── manifest.json        # maps fixture keys to files
+    └── course-export.zip
+```
+
+### App bootstrap helpers
+
+Integration tests share a single app instance. Use the helpers from `lib/app.js`:
+
+```js
+import { getApp, getModule, cleanDb } from '../lib/app.js'
+
+// getApp()    — boots the app (cached, only boots once per run)
+// getModule() — waits for a named module to be ready (e.g. 'content', 'auth-local')
+// cleanDb()   — deletes documents from test collections
+```
+
+### File structure
+
+Every integration test follows this pattern:
+
+```js
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { getApp, getModule, cleanDb } from '../lib/app.js'
+
+let content
+
+describe('Content CRUD operations', () => {
+  before(async () => {
+    await getApp()
+    content = await getModule('content')
+  })
+
+  after(async () => {
+    await cleanDb(['content', 'users', 'authtokens'])
+  })
+
+  describe('Course creation', () => {
+    it('should insert a course', async () => {
+      const course = await content.insert(
+        { _type: 'course', title: 'Test Course', createdBy },
+        { validate: false, schemaName: 'course' }
+      )
+      assert.ok(course._id, 'course should have an _id')
+      assert.equal(course._type, 'course')
+    })
+  })
+})
+```
+
+Key differences from unit tests:
+
+- Always call `await getApp()` in `before()` to ensure the app is booted
+- Use `getModule(name)` to get module instances — never import modules directly
+- Always clean up in `after()` using `cleanDb(collections)` to avoid cross-test pollution
+
+### Database cleanup
+
+`cleanDb()` accepts an array of collection names to clear. Pass only the collections your tests touch:
+
+```js
+after(async () => {
+  await cleanDb(['content', 'users', 'authtokens'])
+})
+```
+
+The default collections (used when called with no arguments) are: `content`, `assets`, `courseassets`, `tags`, `adaptbuilds`, `contentplugins`.
+
+> **Important:** Always include `contentplugins` when cleaning content-related data. Stale plugin records cause `MISSING_SCHEMA` errors on subsequent runs.
+
+### Available modules
+
+Modules are accessed by name via `getModule()`. Common modules used in tests:
+
+| Name | Description |
+|------|-------------|
+| `content` | Content CRUD (`insert`, `find`, `update`, `delete`) |
+| `auth` | Core authentication (token management, `disavowUser`) |
+| `auth-local` | Local auth (`register`, `registerSuper`, `setUserEnabled`) |
+| `users` | User management (`find`, `update`, `delete`) |
+| `roles` | Role management (`find`, `getScopesForRole`) |
+| `mongodb` | Raw database access (`find`, `insert`, `getCollection`) |
+| `adaptframework` | Course import/build/export (`importCourse`, `buildCourse`) |
+
+### Fixtures
+
+Integration tests use a fixture system for test data such as course export zips.
+
+Fixtures are declared in `fixtures/manifest.json`:
+
+```json
+{
+  "course-export": "course-export.zip"
+}
+```
+
+Load a fixture in your test with `getFixture()`, which copies the file to a temp directory to preserve the original:
+
+```js
+import { getFixture } from '../lib/fixtures.js'
+
+it('should import a course', async () => {
+  const framework = await getModule('adaptframework')
+  const importer = await framework.importCourse({
+    importPath: await getFixture('course-export'),
+    userId: '000000000000000000000000',
+    tags: [],
+    importContent: true,
+    importPlugins: true,
+    migrateContent: true,
+    updatePlugins: false,
+    removeSource: false
+  })
+  assert.ok(importer.summary.courseId)
+})
+```
+
+Custom fixtures can be provided via the `CUSTOM_DIR` environment variable. Custom fixtures override built-in fixtures when keys collide.
+
+### Writing assertions
+
+Be specific with assertions. Check exact counts, validate required fields, and verify relationships — don't just check that something is truthy or non-empty:
+
+```js
+// Bad — only checks existence
+const items = await content.find({ _courseId, _type: 'block' })
+assert.ok(items.length > 0, 'should have blocks')
+
+// Good — checks exact count and validates structure
+const items = await content.find({ _courseId, _type: 'block' })
+assert.equal(items.length, 23, 'should have 23 blocks')
+for (const item of items) {
+  assert.ok(item.title, `block "${item._id}" should have a title`)
+  assert.ok(articleIds.has(item._parentId?.toString()),
+    `block "${item._id}" should have an article as parent`)
+}
+```
+
+When validating content hierarchy, verify that parent references point to items of the correct type:
+
+```js
+const blockIds = new Set(
+  (await content.find({ _courseId, _type: 'block' })).map(b => b._id.toString())
+)
+for (const component of components) {
+  assert.ok(blockIds.has(component._parentId?.toString()),
+    `component "${component._id}" should have a block as parent`)
+}
+```
+
+### Error assertions
+
+Use a predicate function with `assert.rejects` when errors may have different structures across modules:
+
+```js
+await assert.rejects(
+  () => authLocal.registerSuper({ email: 'second@example.com', password }),
+  (err) => {
+    assert.ok(
+      err.code === 'SUPER_USER_EXISTS' || err.id === 'SUPER_USER_EXISTS',
+      `expected SUPER_USER_EXISTS, got: ${err.code || err.id || err.message}`
+    )
+    return true
+  }
+)
+```
+
+### Running integration tests
+
+From the adapt-authoring app directory:
+
+```bash
+# run all integration tests
+npx at-integration-test
+
+# run specific test files
+npx at-integration-test auth content
+
+# include custom tests
+CUSTOM_DIR=/path/to/custom npx at-integration-test
+```

package/index.js

@@ -2,4 +2,4 @@ export { default as AbstractModule } from './lib/AbstractModule.js'
 export { default as App } from './lib/App.js'
 export { default as DependencyLoader } from './lib/DependencyLoader.js'
 export { default as Hook } from './lib/Hook.js'
-export { default as Utils } from './lib/Utils.js'
+export { metadataFileName, packageFileName, isObject, getArgs, spawn, readJson, writeJson, toBoolean, ensureDir, escapeRegExp } from './lib/Utils.js'

package/lib/App.js

@@ -2,7 +2,7 @@ import AbstractModule from './AbstractModule.js'
 import DependencyLoader from './DependencyLoader.js'
 import fs from 'fs'
 import path from 'path'
-import Utils from './Utils.js'
+import { metadataFileName, packageFileName, getArgs } from './Utils.js'
 
 let instance
 /**
@@ -27,8 +27,8 @@ class App extends AbstractModule {
   /** @override */
   constructor () {
     const rootDir = process.env.ROOT_DIR ?? process.cwd()
-    const adaptJson = JSON.parse(fs.readFileSync(path.join(rootDir, Utils.metadataFileName)))
-    const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, Utils.packageFileName)))
+    const adaptJson = JSON.parse(fs.readFileSync(path.join(rootDir, metadataFileName)))
+    const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, packageFileName)))
     super(null, { ...packageJson, ...adaptJson, name: 'adapt-authoring-core', rootDir })
     this.git = this.getGitInfo()
   }
@@ -39,7 +39,7 @@ class App extends AbstractModule {
      * Reference to the passed arguments (parsed for easy reference)
      * @type {Object}
      */
-    this.args = Utils.getArgs()
+    this.args = getArgs()
     /**
      * Instance of App instance (required by all AbstractModules)
      * @type {App}

package/lib/DependencyLoader.js

@@ -4,7 +4,7 @@ import fs from 'fs-extra'
 import { glob } from 'glob'
 import path from 'path'
 import Hook from './Hook.js'
-import Utils from './Utils.js'
+import { metadataFileName, packageFileName } from './Utils.js'
 /**
  * Handles the loading of Adapt authoring tool module dependencies.
  * @memberof core
@@ -88,9 +88,9 @@ class DependencyLoader {
    */
   async loadConfigs () {
     /** @ignore */ this._configsLoaded = false
-    const files = await glob(`${this.app.rootDir}/node_modules/**/${Utils.metadataFileName}`)
+    const files = await glob(`${this.app.rootDir}/node_modules/**/${metadataFileName}`)
     const deps = files
-      .map(d => d.replace(`${Utils.metadataFileName}`, ''))
+      .map(d => d.replace(`${metadataFileName}`, ''))
       .sort((a, b) => a.length < b.length ? -1 : 1)
 
     const configCache = {}
@@ -125,8 +125,8 @@ class DependencyLoader {
    */
   async loadModuleConfig (modDir) {
     return {
-      ...await fs.readJson(path.join(modDir, Utils.packageFileName)),
-      ...await fs.readJson(path.join(modDir, Utils.metadataFileName)),
+      ...await fs.readJson(path.join(modDir, packageFileName)),
+      ...await fs.readJson(path.join(modDir, metadataFileName)),
       rootDir: modDir
     }
   }

package/lib/Utils.js

@@ -1,76 +1,9 @@
-import App from './App.js'
-import minimist from 'minimist'
-import { spawn } from 'child_process'
-/**
- * Miscellaneous utility functions for use throughout the application
- * @memberof core
- */
-class Utils {
-  /**
-   * The name of the file used for defining Adapt authoring tool metadata
-   * @return {String}
-   */
-  static get metadataFileName () {
-    return 'adapt-authoring.json'
-  }
-
-  /**
-   * The name of the Node.js package file
-   * @return {String}
-   */
-  static get packageFileName () {
-    return 'package.json'
-  }
-
-  /**
-   * Returns the passed arguments, parsed by minimist for easy access
-   * @return {Object} The parsed arguments
-   * @see {@link https://github.com/substack/minimist#readme}
-   */
-  static getArgs () {
-    const args = minimist(process.argv)
-    args.params = args._.slice(2)
-    return args
-  }
-
-  /**
-   * Determines if param is a Javascript object (note: returns false for arrays, functions and null)
-   * @return {Boolean}
-   */
-  static isObject (o) {
-    return typeof o === 'object' && o !== null && !Array.isArray(o)
-  }
-
-  /**
-   * Reusable Promise-based spawn wrapper, which handles output/error handling
-   * @param {Object} options
-   * @param {String} options.cmd Command to run
-   * @param {String} options.cwd Current working directory
-   * @param {Array<String>} options.args
-   * @returns Promise
-   */
-  static async spawn (options) {
-    return new Promise((resolve, reject) => {
-      if (!options.cwd) options.cwd = ''
-      App.instance.log('verbose', 'SPAWN', options)
-      const task = spawn(options.cmd, options.args ?? [], { cwd: options.cwd })
-      let stdout = ''
-      let stderr = ''
-      let error
-      task.stdout.on('data', data => {
-        stdout += data
-      })
-      task.stderr.on('data', data => {
-        stderr += data
-      })
-      task.on('error', e => {
-        error = e
-      })
-      task.on('close', exitCode => {
-        exitCode !== 0 ? reject(App.instance.errors.SPAWN.setData({ error: error ?? stderr ?? stdout })) : resolve(stdout)
-      })
-    })
-  }
-}
-
-export default Utils
+export { metadataFileName, packageFileName } from './utils/constants.js'
+export { isObject } from './utils/isObject.js'
+export { getArgs } from './utils/getArgs.js'
+export { spawn } from './utils/spawn.js'
+export { readJson } from './utils/readJson.js'
+export { writeJson } from './utils/writeJson.js'
+export { toBoolean } from './utils/toBoolean.js'
+export { ensureDir } from './utils/ensureDir.js'
+export { escapeRegExp } from './utils/escapeRegExp.js'

package/lib/utils/constants.js

@@ -0,0 +1,11 @@
+/**
+ * The name of the file used for defining Adapt authoring tool metadata
+ * @type {string}
+ */
+export const metadataFileName = 'adapt-authoring.json'
+
+/**
+ * The name of the Node.js package file
+ * @type {string}
+ */
+export const packageFileName = 'package.json'

package/lib/utils/ensureDir.js

@@ -0,0 +1,14 @@
+import fs from 'fs/promises'
+
+/**
+ * Ensures a directory exists, creating it recursively if needed.
+ * @param {string} dir - Absolute path to the directory
+ * @returns {Promise<void>}
+ */
+export async function ensureDir (dir) {
+  try {
+    await fs.mkdir(dir, { recursive: true })
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e
+  }
+}

package/lib/utils/escapeRegExp.js

@@ -0,0 +1,8 @@
+/**
+ * Escapes special regex characters in a string.
+ * @param {string} string
+ * @returns {string}
+ */
+export function escapeRegExp (string) {
+  return string.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&')
+}

package/lib/utils/getArgs.js

@@ -0,0 +1,12 @@
+import minimist from 'minimist'
+
+/**
+ * Returns the passed arguments, parsed by minimist for easy access
+ * @return {Object} The parsed arguments
+ * @see {@link https://github.com/substack/minimist#readme}
+ */
+export function getArgs () {
+  const args = minimist(process.argv)
+  args.params = args._.slice(2)
+  return args
+}

package/lib/utils/isObject.js

@@ -0,0 +1,8 @@
+/**
+ * Determines if param is a Javascript object (note: returns false for arrays, functions and null)
+ * @param {*} o
+ * @return {Boolean}
+ */
+export function isObject (o) {
+  return typeof o === 'object' && o !== null && !Array.isArray(o)
+}

package/lib/utils/readJson.js

@@ -0,0 +1,10 @@
+import fs from 'fs/promises'
+
+/**
+ * Reads and parses a JSON file.
+ * @param {string} filepath - Absolute path to the JSON file
+ * @returns {Promise<Object>}
+ */
+export async function readJson (filepath) {
+  return JSON.parse(await fs.readFile(filepath))
+}

package/lib/utils/spawn.js

@@ -0,0 +1,33 @@
+import App from '../App.js'
+import { spawn as nodeSpawn } from 'child_process'
+
+/**
+ * Reusable Promise-based spawn wrapper, which handles output/error handling
+ * @param {Object} options
+ * @param {String} options.cmd Command to run
+ * @param {String} options.cwd Current working directory
+ * @param {Array<String>} options.args
+ * @returns Promise
+ */
+export async function spawn (options) {
+  return new Promise((resolve, reject) => {
+    if (!options.cwd) options.cwd = ''
+    App.instance.log('verbose', 'SPAWN', options)
+    const task = nodeSpawn(options.cmd, options.args ?? [], { cwd: options.cwd })
+    let stdout = ''
+    let stderr = ''
+    let error
+    task.stdout.on('data', data => {
+      stdout += data
+    })
+    task.stderr.on('data', data => {
+      stderr += data
+    })
+    task.on('error', e => {
+      error = e
+    })
+    task.on('close', exitCode => {
+      exitCode !== 0 ? reject(App.instance.errors.SPAWN.setData({ error: error ?? stderr ?? stdout })) : resolve(stdout)
+    })
+  })
+}

package/lib/utils/toBoolean.js

@@ -0,0 +1,9 @@
+/**
+ * Converts a value to a boolean. Returns `true` only for `true` or `"true"`.
+ * Returns `undefined` if the value is `undefined`.
+ * @param {*} val
+ * @returns {boolean|undefined}
+ */
+export function toBoolean (val) {
+  if (val !== undefined) return val === true || val === 'true'
+}

package/lib/utils/writeJson.js

@@ -0,0 +1,11 @@
+import fs from 'fs/promises'
+
+/**
+ * Writes data as formatted JSON to a file.
+ * @param {string} filepath - Absolute path to the JSON file
+ * @param {*} data - Data to serialise
+ * @returns {Promise<void>}
+ */
+export function writeJson (filepath, data) {
+  return fs.writeFile(filepath, JSON.stringify(data, null, 2))
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-core",
-  "version": "1.9.2",
+  "version": "2.0.0",
   "description": "A bundle of reusable 'core' functionality",
   "homepage": "https://github.com/adapt-security/adapt-authoring-core",
   "license": "GPL-3.0",

package/tests/utils-constants.spec.js

@@ -0,0 +1,16 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { metadataFileName, packageFileName } from '../lib/utils/constants.js'
+
+describe('metadataFileName', () => {
+  it('should be adapt-authoring.json', () => {
+    assert.equal(metadataFileName, 'adapt-authoring.json')
+  })
+})
+
+describe('packageFileName', () => {
+  it('should be package.json', () => {
+    assert.equal(packageFileName, 'package.json')
+  })
+})

package/tests/utils-ensureDir.spec.js

@@ -0,0 +1,41 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+import { ensureDir } from '../lib/utils/ensureDir.js'
+
+describe('ensureDir()', () => {
+  it('should create a directory that does not exist', async () => {
+    const tmpDir = path.join(os.tmpdir(), `ensureDir-test-${Date.now()}`)
+    try {
+      await ensureDir(tmpDir)
+      const stat = await fs.stat(tmpDir)
+      assert.ok(stat.isDirectory())
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it('should create nested directories recursively', async () => {
+    const tmpDir = path.join(os.tmpdir(), `ensureDir-nested-${Date.now()}`, 'a', 'b', 'c')
+    try {
+      await ensureDir(tmpDir)
+      const stat = await fs.stat(tmpDir)
+      assert.ok(stat.isDirectory())
+    } finally {
+      await fs.rm(path.join(os.tmpdir(), `ensureDir-nested-${Date.now()}`), { recursive: true, force: true }).catch(() => {})
+    }
+  })
+
+  it('should not throw if the directory already exists', async () => {
+    const tmpDir = path.join(os.tmpdir(), `ensureDir-exists-${Date.now()}`)
+    try {
+      await fs.mkdir(tmpDir, { recursive: true })
+      await assert.doesNotReject(() => ensureDir(tmpDir))
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true })
+    }
+  })
+})

package/tests/utils-escapeRegExp.spec.js

@@ -0,0 +1,65 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { escapeRegExp } from '../lib/utils/escapeRegExp.js'
+
+describe('escapeRegExp()', () => {
+  it('should escape dots', () => {
+    assert.equal(escapeRegExp('file.js'), 'file\\.js')
+  })
+
+  it('should escape asterisks', () => {
+    assert.equal(escapeRegExp('a*b'), 'a\\*b')
+  })
+
+  it('should escape plus signs', () => {
+    assert.equal(escapeRegExp('a+b'), 'a\\+b')
+  })
+
+  it('should escape question marks', () => {
+    assert.equal(escapeRegExp('a?b'), 'a\\?b')
+  })
+
+  it('should escape parentheses and pipe', () => {
+    assert.equal(escapeRegExp('(a|b)'), '\\(a\\|b\\)')
+  })
+
+  it('should escape square brackets', () => {
+    assert.equal(escapeRegExp('[abc]'), '\\[abc\\]')
+  })
+
+  it('should escape curly braces', () => {
+    assert.equal(escapeRegExp('{1,2}'), '\\{1,2\\}')
+  })
+
+  it('should escape caret and dollar', () => {
+    assert.equal(escapeRegExp('^start$'), '\\^start\\$')
+  })
+
+  it('should escape backslashes', () => {
+    assert.equal(escapeRegExp('a\\b'), 'a\\\\b')
+  })
+
+  it('should escape hyphens', () => {
+    assert.equal(escapeRegExp('a-b'), 'a\\-b')
+  })
+
+  it('should return plain strings unchanged', () => {
+    assert.equal(escapeRegExp('hello'), 'hello')
+  })
+
+  it('should escape all special characters', () => {
+    const special = '.*+\\-?^${}()|[]'
+    const escaped = escapeRegExp(special)
+    const re = new RegExp(escaped)
+    assert.ok(re.test(special))
+  })
+
+  it('should produce a string usable in RegExp', () => {
+    const input = 'file.name+(v2)[1].js'
+    const escaped = escapeRegExp(input)
+    const regex = new RegExp(escaped)
+    assert.ok(regex.test(input))
+    assert.ok(!regex.test('filexname'))
+  })
+})

package/tests/utils-getArgs.spec.js

@@ -0,0 +1,22 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { getArgs } from '../lib/utils/getArgs.js'
+
+describe('getArgs()', () => {
+  it('should return an object with parsed arguments', () => {
+    const args = getArgs()
+    assert.equal(typeof args, 'object')
+    assert.ok(Array.isArray(args.params))
+  })
+
+  it('should include the underscore array from minimist', () => {
+    const args = getArgs()
+    assert.ok(Array.isArray(args._))
+  })
+
+  it('should derive params by slicing first two entries from _', () => {
+    const args = getArgs()
+    assert.deepEqual(args.params, args._.slice(2))
+  })
+})

package/tests/utils-isObject.spec.js

@@ -0,0 +1,49 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { isObject } from '../lib/utils/isObject.js'
+
+describe('isObject()', () => {
+  const validObjects = [
+    { value: {}, label: 'empty object' },
+    { value: { key: 'value' }, label: 'object with properties' },
+    { value: { nested: { key: 'value' } }, label: 'nested object' }
+  ]
+
+  validObjects.forEach(({ value, label }) => {
+    it(`should return true for ${label}`, () => {
+      assert.equal(isObject(value), true)
+    })
+  })
+
+  const objectLikeButValid = [
+    { value: new Date(), label: 'Date instance' },
+    { value: /regex/, label: 'RegExp instance' }
+  ]
+
+  objectLikeButValid.forEach(({ value, label }) => {
+    it(`should return true for ${label}`, () => {
+      assert.equal(isObject(value), true)
+    })
+  })
+
+  const invalidObjects = [
+    { value: null, label: 'null' },
+    { value: [], label: 'empty array' },
+    { value: [1, 2, 3], label: 'array with values' },
+    { value: 'string', label: 'string' },
+    { value: 123, label: 'number' },
+    { value: true, label: 'boolean' },
+    { value: undefined, label: 'undefined' },
+    { value: () => {}, label: 'function' },
+    { value: 0, label: 'zero' },
+    { value: '', label: 'empty string' },
+    { value: NaN, label: 'NaN' }
+  ]
+
+  invalidObjects.forEach(({ value, label }) => {
+    it(`should return false for ${label}`, () => {
+      assert.equal(isObject(value), false)
+    })
+  })
+})

package/tests/utils-readJson.spec.js

@@ -0,0 +1,53 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+import { readJson } from '../lib/utils/readJson.js'
+
+describe('readJson()', () => {
+  it('should read and parse a valid JSON file', async () => {
+    const tmpFile = path.join(os.tmpdir(), `readJson-test-${Date.now()}.json`)
+    await fs.writeFile(tmpFile, JSON.stringify({ name: 'test', version: '1.0.0' }))
+    try {
+      const result = await readJson(tmpFile)
+      assert.equal(result.name, 'test')
+      assert.equal(result.version, '1.0.0')
+    } finally {
+      await fs.unlink(tmpFile)
+    }
+  })
+
+  it('should handle nested JSON structures', async () => {
+    const tmpFile = path.join(os.tmpdir(), `readJson-nested-${Date.now()}.json`)
+    const data = { a: { b: [1, 2, 3] } }
+    await fs.writeFile(tmpFile, JSON.stringify(data))
+    try {
+      const result = await readJson(tmpFile)
+      assert.deepEqual(result, data)
+    } finally {
+      await fs.unlink(tmpFile)
+    }
+  })
+
+  it('should throw on non-existent file', async () => {
+    await assert.rejects(
+      () => readJson('/tmp/does-not-exist-readjson.json'),
+      { code: 'ENOENT' }
+    )
+  })
+
+  it('should throw on invalid JSON', async () => {
+    const tmpFile = path.join(os.tmpdir(), `readJson-invalid-${Date.now()}.json`)
+    await fs.writeFile(tmpFile, '{ not valid json }')
+    try {
+      await assert.rejects(
+        () => readJson(tmpFile),
+        SyntaxError
+      )
+    } finally {
+      await fs.unlink(tmpFile)
+    }
+  })
+})

package/tests/utils-spawn.spec.js

@@ -0,0 +1,76 @@
+import { describe, it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import App from '../lib/App.js'
+
+mock.getter(App, 'instance', () => ({
+  log () {},
+  errors: {
+    SPAWN: {
+      setData (data) {
+        const e = new Error('SPAWN')
+        e.data = data
+        return e
+      }
+    }
+  }
+}))
+
+const { spawn } = await import('../lib/utils/spawn.js')
+
+describe('spawn()', () => {
+  it('should resolve with stdout on success', async () => {
+    const result = await spawn({ cmd: 'echo', args: ['hello'] })
+    assert.equal(result.trim(), 'hello')
+  })
+
+  it('should resolve with empty string when command produces no output', async () => {
+    const result = await spawn({ cmd: 'true' })
+    assert.equal(result, '')
+  })
+
+  it('should reject with SPAWN error on non-zero exit code', async () => {
+    await assert.rejects(
+      () => spawn({ cmd: 'false' }),
+      (err) => {
+        assert.equal(err.message, 'SPAWN')
+        return true
+      }
+    )
+  })
+
+  it('should reject with stderr data on failure', async () => {
+    await assert.rejects(
+      () => spawn({ cmd: 'node', args: ['-e', 'process.stderr.write("oops"); process.exit(1)'] }),
+      (err) => {
+        assert.equal(err.message, 'SPAWN')
+        assert.equal(err.data.error, 'oops')
+        return true
+      }
+    )
+  })
+
+  it('should default cwd to empty string when not provided', async () => {
+    const result = await spawn({ cmd: 'echo', args: ['test'] })
+    assert.equal(result.trim(), 'test')
+  })
+
+  it('should use provided cwd', async () => {
+    const result = await spawn({ cmd: 'pwd', cwd: '/tmp' })
+    assert.match(result.trim(), /tmp/)
+  })
+
+  it('should pass args to the command', async () => {
+    const result = await spawn({ cmd: 'echo', args: ['-n', 'no newline'] })
+    assert.equal(result, 'no newline')
+  })
+
+  it('should reject with error event data for invalid commands', async () => {
+    await assert.rejects(
+      () => spawn({ cmd: 'nonexistent-command-that-does-not-exist' }),
+      (err) => {
+        assert.equal(err.message, 'SPAWN')
+        return true
+      }
+    )
+  })
+})

package/tests/utils-toBoolean.spec.js

@@ -0,0 +1,42 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { toBoolean } from '../lib/utils/toBoolean.js'
+
+describe('toBoolean()', () => {
+  it('should return true for true', () => {
+    assert.equal(toBoolean(true), true)
+  })
+
+  it('should return true for "true"', () => {
+    assert.equal(toBoolean('true'), true)
+  })
+
+  it('should return false for false', () => {
+    assert.equal(toBoolean(false), false)
+  })
+
+  it('should return false for "false"', () => {
+    assert.equal(toBoolean('false'), false)
+  })
+
+  it('should return false for 0', () => {
+    assert.equal(toBoolean(0), false)
+  })
+
+  it('should return false for an empty string', () => {
+    assert.equal(toBoolean(''), false)
+  })
+
+  it('should return false for null', () => {
+    assert.equal(toBoolean(null), false)
+  })
+
+  it('should return undefined for undefined', () => {
+    assert.equal(toBoolean(undefined), undefined)
+  })
+
+  it('should return false for a non-"true" string', () => {
+    assert.equal(toBoolean('yes'), false)
+  })
+})

package/tests/utils-writeJson.spec.js

@@ -0,0 +1,34 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+import { writeJson } from '../lib/utils/writeJson.js'
+
+describe('writeJson()', () => {
+  it('should write formatted JSON to a file', async () => {
+    const tmpFile = path.join(os.tmpdir(), `writeJson-test-${Date.now()}.json`)
+    const data = { name: 'test', items: [1, 2, 3] }
+    try {
+      await writeJson(tmpFile, data)
+      const content = await fs.readFile(tmpFile, 'utf-8')
+      assert.equal(content, JSON.stringify(data, null, 2))
+    } finally {
+      await fs.unlink(tmpFile).catch(() => {})
+    }
+  })
+
+  it('should overwrite an existing file', async () => {
+    const tmpFile = path.join(os.tmpdir(), `writeJson-overwrite-${Date.now()}.json`)
+    try {
+      await writeJson(tmpFile, { old: true })
+      await writeJson(tmpFile, { new: true })
+      const content = JSON.parse(await fs.readFile(tmpFile, 'utf-8'))
+      assert.equal(content.new, true)
+      assert.equal(content.old, undefined)
+    } finally {
+      await fs.unlink(tmpFile).catch(() => {})
+    }
+  })
+})

package/tests/Utils.spec.js

@@ -1,80 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-import Utils from '../lib/Utils.js'
-
-describe('Utils', () => {
-  describe('.metadataFileName', () => {
-    it('should return the metadata file name', () => {
-      assert.equal(Utils.metadataFileName, 'adapt-authoring.json')
-    })
-  })
-
-  describe('.packageFileName', () => {
-    it('should return the package file name', () => {
-      assert.equal(Utils.packageFileName, 'package.json')
-    })
-  })
-
-  describe('.getArgs()', () => {
-    it('should return an object with parsed arguments', () => {
-      const args = Utils.getArgs()
-      assert.equal(typeof args, 'object')
-      assert.ok(Array.isArray(args.params))
-    })
-
-    it('should include the underscore array from minimist', () => {
-      const args = Utils.getArgs()
-      assert.ok(Array.isArray(args._))
-    })
-
-    it('should derive params by slicing first two entries from _', () => {
-      const args = Utils.getArgs()
-      assert.deepEqual(args.params, args._.slice(2))
-    })
-  })
-
-  describe('.isObject()', () => {
-    const validObjects = [
-      { value: {}, label: 'empty object' },
-      { value: { key: 'value' }, label: 'object with properties' },
-      { value: { nested: { key: 'value' } }, label: 'nested object' }
-    ]
-
-    validObjects.forEach(({ value, label }) => {
-      it(`should return true for ${label}`, () => {
-        assert.equal(Utils.isObject(value), true)
-      })
-    })
-
-    const objectLikeButValid = [
-      { value: new Date(), label: 'Date instance' },
-      { value: /regex/, label: 'RegExp instance' }
-    ]
-
-    objectLikeButValid.forEach(({ value, label }) => {
-      it(`should return true for ${label}`, () => {
-        assert.equal(Utils.isObject(value), true)
-      })
-    })
-
-    const invalidObjects = [
-      { value: null, label: 'null' },
-      { value: [], label: 'empty array' },
-      { value: [1, 2, 3], label: 'array with values' },
-      { value: 'string', label: 'string' },
-      { value: 123, label: 'number' },
-      { value: true, label: 'boolean' },
-      { value: undefined, label: 'undefined' },
-      { value: () => {}, label: 'function' },
-      { value: 0, label: 'zero' },
-      { value: '', label: 'empty string' },
-      { value: NaN, label: 'NaN' }
-    ]
-
-    invalidObjects.forEach(({ value, label }) => {
-      it(`should return false for ${label}`, () => {
-        assert.equal(Utils.isObject(value), false)
-      })
-    })
-  })
-})