sxy-test-runner 2.0.5 → 2.1.0

package/AGENTS.md

@@ -0,0 +1,286 @@
+# sxy-test-runner guide for coding agents
+
+This document is the practical source of truth for agents that need to add, run, or
+maintain tests using `sxy-test-runner`. It describes the current TypeScript implementation.
+For introductory human-facing usage, also see `readme.md`.
+
+## Safe default workflow
+
+1. Confirm the project uses Node.js 24 or newer and ES modules.
+2. Find the active `sxyt.config.*` or `sxy-test-runner.config.*` file. It may be in the
+   project root or `config/`.
+3. Inspect `testsBase`, `tests`, and `testsIgnore` before creating a test so the file is
+   actually discoverable.
+4. Import only `describe` from `sxy-test-runner`. Obtain `it`, `test`, and local hooks from
+   the `describe` callback.
+5. Run `npx sxy-test-runner once` for finite agent or CI work.
+6. Treat exit code `3` as test failure. Exit code `0` can also mean that no tests were
+   found, so check the output when discovery is in doubt.
+
+Do not run a test file directly with `node`. `describe()` requires runner-owned global
+state and deliberately throws if the framework has not initialized it.
+
+## Minimal test
+
+The runner supplies test organization and execution, but not an assertion library. Use
+Node's assertion API, Chai, or another ESM-compatible assertion library.
+
+```js
+import assert from 'node:assert/strict'
+import { describe } from 'sxy-test-runner'
+import { add } from '../src/add.js'
+
+describe('add()', ({ it }) => {
+    it('adds two numbers', () => {
+        assert.equal(add(1, 2), 3)
+    })
+})
+```
+
+Both describe callbacks and test callbacks may be async:
+
+```js
+describe('records', ({ test }) => {
+    test('loads a record', async () => {
+        const record = await loadRecord('example')
+        assert.equal(record.name, 'example')
+    })
+})
+```
+
+`test` is an alias of `it`. There are no built-in mocks, spies, snapshots, fake timers, or
+assertions.
+
+## CLI and discovery
+
+Available executable names are `sxyt`, `sxy-test`, and `sxy-test-runner`.
+
+```sh
+# Default: watch mode
+npx sxy-test-runner
+
+# One finite run, suitable for agents and CI
+npx sxy-test-runner once
+
+# Use a specific config
+npx sxy-test-runner once --config config/sxyt.config.js
+
+# Override the test glob in watch mode
+npx sxy-test-runner watch --files "**/*.focused.test.js"
+
+# Generate an initial config
+npx sxy-test-runner init
+```
+
+The `--files` option is currently applied by watch mode, not by `once`. For a focused
+one-off run, use a temporary/configured test pattern rather than assuming
+`once --files` filters the suite.
+
+Test discovery uses Node's built-in glob implementation. Patterns are resolved relative to
+`testsBase`, and ignore patterns are resolved from that same base.
+
+## Test lifecycle and data flow
+
+All test files run in one Node.js process. A test file is imported with a fresh
+`?instance=N` query, and the runner's ESM resolver propagates that instance through its
+static dependency graph. Importing the file registers its describe blocks in
+`global.__sxy_test_runner__`; execution happens afterward.
+
+A module whose filename contains the explicit `._cached_.js` marker uses Node's ordinary
+process-wide module cache instead. Its static dependencies are cached with it, allowing
+explicitly shared state across test files:
+
+```js
+import { database } from './fixtures/database._cached_.js'
+```
+
+The equivalent source suffixes are supported for JavaScript and TypeScript module
+extensions, including `._cached_.ts`, `._cached_.mjs`, `._cached_.mts`,
+`._cached_.cjs`, and `._cached_.cts`. Under TypeScript `NodeNext`, source imports
+normally use the emitted `._cached_.js` extension.
+
+The lifecycle is:
+
+```text
+setup
+  each test file:
+    beforeEachFile
+      each describe:
+        beforeEachDescribe
+        describe callback (register tests and local hooks)
+          each test:
+            config beforeEachTest
+            local beforeEachTest
+            test callback
+            local afterEachTest
+            config afterEachTest
+        local afterDescribe
+        afterEachDescribe
+    afterEachFile
+teardown
+```
+
+The global config hooks accept a function, a project-relative module path, or an array of
+either. Arrays run in order. Functions may return an object, and task modules may provide
+named exports.
+
+Hook values are deliberately scoped:
+
+- `beforeEachFile` values are passed only to the matching `afterEachFile`.
+- `beforeEachDescribe` values are added to the `describe` callback argument and passed to
+  the matching `afterEachDescribe`.
+- `beforeEachTest` values are added to the individual test callback argument and passed to
+  the matching `afterEachTest`.
+- Reusing the same exported key within one scope is an error.
+
+Example config-driven fixture:
+
+```js
+// sxyt.config.js
+export default {
+    testsBase: 'dist',
+    tests: '**/*.test.js',
+
+    beforeEachTest: async () => {
+        const database = await createTestDatabase()
+        return { database }
+    },
+
+    afterEachTest: async ({ database }) => {
+        await database.close()
+    }
+}
+```
+
+```js
+describe('repository', ({ it }) => {
+    it('writes a record', async ({ database }) => {
+        await database.insert({ id: 1 })
+        assert.equal(await database.count(), 1)
+    })
+})
+```
+
+Describe-local hooks are useful when the fixture belongs to one describe block:
+
+```js
+describe('server', ({ it, beforeEachTest, afterEachTest, afterDescribe }) => {
+    const server = createServer()
+
+    beforeEachTest(async () => {
+        const client = await server.createClient()
+        return { client }
+    })
+
+    afterEachTest(async () => {
+        await server.reset()
+    })
+
+    it('responds', async ({ client }) => {
+        assert.equal((await client.get('/health')).status, 200)
+    })
+
+    // Inline cleanup at the bottom of the describe callback is too early.
+    afterDescribe(async () => {
+        await server.close()
+    })
+})
+```
+
+## Execution and isolation
+
+Configuration has `execution.files`, `execution.describes`, and `execution.tests`, each
+accepting `sequential` or `parallel`.
+
+Prefer sequential execution unless the tested code and fixtures are isolated. The runner
+uses one process, so globals, environment variables, singleton modules, open ports, and
+shared databases can collide. Per-test `console.log` association also depends on sequential
+execution because the runner temporarily replaces the global `console.log`.
+
+Current implementation detail: individual tests inside a describe are awaited one at a
+time even when `execution.tests` is set to `parallel`. Do not design a suite that depends
+on parallel `it` execution.
+
+## Watch mode
+
+Watch mode builds a static dependency tree for every test. When a file changes, it reruns
+the changed test itself and tests whose static import graph includes that file. If
+`watch.reRunFailingTests` is true, previously failing files are included until they pass.
+
+Important limitations:
+
+- Dynamic imports are not found by dependency analysis.
+- All reruns still share one long-lived process.
+- A fresh ESM instance reloads the test's static module graph, but unrelated global state
+  and external resources remain the test author's responsibility.
+- Modules imported through a `._cached_.*` boundary also remain loaded for the life of the
+  process. Keep mutable access sequential or provide application-level synchronization,
+  and arrange explicit cleanup for resources such as servers and database connections.
+- Use `once` instead of watch mode for autonomous agent verification so the command
+  terminates and returns a meaningful status.
+
+## Configuration reference
+
+The exported config type is available for JavaScript type checking:
+
+```js
+// @ts-check
+
+/** @type {import('sxy-test-runner').Config} */
+export default {
+    testsBase: 'dist',
+    tests: '**/*.test.js',
+    testsIgnore: '**/node_modules/**',
+    showErrorTrace: true,
+
+    setup: undefined,
+    beforeEachFile: undefined,
+    afterEachFile: undefined,
+    beforeEachDescribe: undefined,
+    afterEachDescribe: undefined,
+    beforeEachTest: undefined,
+    afterEachTest: undefined,
+    teardown: undefined,
+
+    execution: {
+        files: 'sequential',
+        describes: 'sequential',
+        tests: 'sequential'
+    },
+
+    watch: {
+        watchFilesBase: 'dist',
+        watchFiles: '**/*.js',
+        watchFilesIgnore: '**/node_modules/**',
+        runAllOnStartup: true,
+        reRunFailingTests: true
+    }
+}
+```
+
+Set `showErrorTrace: true` when an agent needs stack traces for test failures. With the
+default `false`, failure output is intentionally shorter.
+
+## Maintaining this repository
+
+Source files live in `src/`; `dist/` is generated. Do not make a source fix only in
+`dist/`.
+
+The repository's unit tests are also TypeScript source files under `src/` and are compiled
+into `dist/**/*.unitTest.js`. The normal finite verification sequence is:
+
+```sh
+npm run build-once
+npm run unit-tests-once
+```
+
+For a targeted area, build first and then use the matching `unit-test-*` package script.
+Many targeted scripts are watch commands, so prefer `unit-tests-once` for final,
+terminating verification.
+
+When changing public behavior, check these sources together:
+
+- `src/types.ts` for the public config and callback shapes.
+- `src/cli/init.ts` for the generated config template.
+- `src/cli/lib/defaultConfig.ts` for runtime defaults.
+- `readme.md` and this guide for published behavior.

package/dist/cli/lib/defaultConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaultConfig.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/defaultConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD,eAAO,MAAM,aAAa,EAAE,WAsB3B,CAAA"}
+{"version":3,"file":"defaultConfig.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/defaultConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD,eAAO,MAAM,aAAa,EAAE,WAuB3B,CAAA"}

package/dist/cli/lib/defaultConfig.js

@@ -1,21 +1,22 @@
 export const defaultConfig = {
     testsBase: '.',
     tests: [
+        '**/*.sxyt.{js,mjs,jsx}',
         '**/*.test.{js,mjs,jsx}',
         '**/*.spec.{js,mjs,jsx}',
         '**/tests?/*.{js,mjs,jsx}',
         '**/__tests?__/*.{js,mjs,jsx}'
     ],
-    testsIgnore: ['node_modules'],
+    testsIgnore: ['**/node_modules/**/*'],
     showErrorTrace: false,
     execution: {
-        files: 'parallel',
+        files: 'sequential',
         describes: 'sequential',
         tests: 'sequential'
     },
     watch: {
         watchFilesBase: '.',
-        watchFiles: '**/*',
+        watchFiles: '**/*.js',
         watchFilesIgnore: '**/node_modules/**/*',
         runAllOnStartup: true,
         reRunFailingTests: true

package/dist/cli/lib/defaultConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaultConfig.js","sourceRoot":"","sources":["../../../src/cli/lib/defaultConfig.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,aAAa,GAAgB;IACtC,SAAS,EAAE,GAAG;IACd,KAAK,EAAE;QACH,wBAAwB;QACxB,wBAAwB;QACxB,0BAA0B;QAC1B,8BAA8B;KACjC;IACD,WAAW,EAAE,CAAC,cAAc,CAAC;IAC7B,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE;QACP,KAAK,EAAE,UAAU;QACjB,SAAS,EAAE,YAAY;QACvB,KAAK,EAAE,YAAY;KACtB;IACD,KAAK,EAAE;QACH,cAAc,EAAE,GAAG;QACnB,UAAU,EAAE,MAAM;QAClB,gBAAgB,EAAE,sBAAsB;QACxC,eAAe,EAAE,IAAI;QACrB,iBAAiB,EAAE,IAAI;KAC1B;CACJ,CAAA"}
+{"version":3,"file":"defaultConfig.js","sourceRoot":"","sources":["../../../src/cli/lib/defaultConfig.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,aAAa,GAAgB;IACtC,SAAS,EAAE,GAAG;IACd,KAAK,EAAE;QACH,wBAAwB;QACxB,wBAAwB;QACxB,wBAAwB;QACxB,0BAA0B;QAC1B,8BAA8B;KACjC;IACD,WAAW,EAAE,CAAC,sBAAsB,CAAC;IACrC,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE;QACP,KAAK,EAAE,YAAY;QACnB,SAAS,EAAE,YAAY;QACvB,KAAK,EAAE,YAAY;KACtB;IACD,KAAK,EAAE;QACH,cAAc,EAAE,GAAG;QACnB,UAAU,EAAE,SAAS;QACrB,gBAAgB,EAAE,sBAAsB;QACxC,eAAe,EAAE,IAAI;QACrB,iBAAiB,EAAE,IAAI;KAC1B;CACJ,CAAA"}

package/dist/cli/lib/loadTestFile.d.ts

@@ -1,4 +1,4 @@
-import 'esm-reload';
+import '../../packages/esmReload.js';
 import type { FinalConfig, TestFile } from '../../types.js';
 export declare function loadTestFile(config: FinalConfig, testFile: string): Promise<TestFile>;
 //# sourceMappingURL=loadTestFile.d.ts.map

package/dist/cli/lib/loadTestFile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadTestFile.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/loadTestFile.ts"],"names":[],"mappings":"AAGA,OAAO,YAAY,CAAA;AAInB,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAW3D,wBAAsB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoD3F"}
+{"version":3,"file":"loadTestFile.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/loadTestFile.ts"],"names":[],"mappings":"AAGA,OAAO,6BAA6B,CAAA;AAIpC,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAW3D,wBAAsB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoD3F"}

package/dist/cli/lib/loadTestFile.js

@@ -1,7 +1,7 @@
 import { join } from 'path';
 import chalk from '../../packages/chalk.js';
 import { createTimeProfiler } from '../../packages/timeProfiler.js';
-import 'esm-reload'; // registers import reload hook
+import '../../packages/esmReload.js'; // registers the test module reload hook
 import { showTimeProfiling } from '../../config.js';
 import { debug } from '../../output.js';
 const { timeProfileAsync } = createTimeProfiler(showTimeProfiling);

package/dist/cli/lib/loadTestFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadTestFile.js","sourceRoot":"","sources":["../../../src/cli/lib/loadTestFile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,KAAK,MAAM,yBAAyB,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,YAAY,CAAA,CAAC,+BAA+B;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAGvC,MAAM,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;AAElE,IAAI,OAAO,GAA6B,IAAI,CAAA;AAE5C,IAAI,eAAe,GAAG,CAAC,CAAA;AACvB,SAAS,WAAW,CAAC,MAAc;IAC/B,OAAO,MAAM,CAAC,MAAM,GAAG,aAAa,eAAe,EAAE,EAAE,CAAC,CAAA;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAmB,EAAE,QAAgB;IACpE,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,KAAK,CAAC,KAAK,CAAC,MAAM,CAAA,mEAAmE,CAAC,CAAA;QACtF,MAAM,OAAO,CAAA;QACb,KAAK,CAAC,KAAK,CAAC,MAAM,CAAA,iDAAiD,CAAC,CAAA;IACxE,CAAC;IAED,MAAM,WAAW,GAAG,gBAAgB,CAAC,aAAa,QAAQ,EAAE,EAAE,KAAK,IAAI,EAAE;QACrE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAA;QAEhC,qCAAqC;QACrC,MAAM,CAAC,mBAAmB,GAAG;YACzB,SAAS,EAAE,EAAE;YACb,eAAe,EAAE,CAAC;SACrB,CAAA;QAED,MAAM,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;QAE9D,MAAM,IAAI,GAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;QAEzC,MAAM,mBAAmB,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,KAAK,YAAY,CAAA;QAEnE,+BAA+B;QAC/B,IAAI,kBAAkD,CAAA;QACtD,MAAM,IAAI,GAAgB,EAAE,CAAA;QAC5B,IAAI,mBAAmB,EAAE,CAAC;YACtB,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAA,CAAC,iCAAiC;YAClE,OAAO,CAAC,GAAG,GAAG,CAAC,GAAG,KAAgB,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA,CAAC,CAAC,CAAA,CAAC,iCAAiC;QACjG,CAAC;QACD,IAAI;QAEJ,IAAI,CAAC;YACD,MAAM,WAAW,CAAC,eAAe,CAAC,CAAA;YAClC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,mBAAmB,EAAE,SAAS,IAAI,EAAE,CAAA;YAC5D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,IAAI,CAAC,KAAK,GAAG,uBAAuB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA;QACnD,CAAC;gBAAS,CAAC;YACP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;YAChB,0CAA0C;YAC1C,IAAI,mBAAmB,IAAI,kBAAkB,EAAE,CAAC;gBAC5C,OAAO,CAAC,GAAG,GAAG,kBAAkB,CAAA,CAAC,iCAAiC;YACtE,CAAC;YACD,IAAI;QACR,CAAC;QAED,OAAO,IAAI,CAAA;IACf,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,WAAW,CAAA;IAErB,OAAO,MAAM,WAAW,CAAA;AAC5B,CAAC"}
+{"version":3,"file":"loadTestFile.js","sourceRoot":"","sources":["../../../src/cli/lib/loadTestFile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,KAAK,MAAM,yBAAyB,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,6BAA6B,CAAA,CAAC,wCAAwC;AAE7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAGvC,MAAM,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;AAElE,IAAI,OAAO,GAA6B,IAAI,CAAA;AAE5C,IAAI,eAAe,GAAG,CAAC,CAAA;AACvB,SAAS,WAAW,CAAC,MAAc;IAC/B,OAAO,MAAM,CAAC,MAAM,GAAG,aAAa,eAAe,EAAE,EAAE,CAAC,CAAA;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAmB,EAAE,QAAgB;IACpE,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,KAAK,CAAC,KAAK,CAAC,MAAM,CAAA,mEAAmE,CAAC,CAAA;QACtF,MAAM,OAAO,CAAA;QACb,KAAK,CAAC,KAAK,CAAC,MAAM,CAAA,iDAAiD,CAAC,CAAA;IACxE,CAAC;IAED,MAAM,WAAW,GAAG,gBAAgB,CAAC,aAAa,QAAQ,EAAE,EAAE,KAAK,IAAI,EAAE;QACrE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAA;QAEhC,qCAAqC;QACrC,MAAM,CAAC,mBAAmB,GAAG;YACzB,SAAS,EAAE,EAAE;YACb,eAAe,EAAE,CAAC;SACrB,CAAA;QAED,MAAM,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;QAE9D,MAAM,IAAI,GAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;QAEzC,MAAM,mBAAmB,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,KAAK,YAAY,CAAA;QAEnE,+BAA+B;QAC/B,IAAI,kBAAkD,CAAA;QACtD,MAAM,IAAI,GAAgB,EAAE,CAAA;QAC5B,IAAI,mBAAmB,EAAE,CAAC;YACtB,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAA,CAAC,iCAAiC;YAClE,OAAO,CAAC,GAAG,GAAG,CAAC,GAAG,KAAgB,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA,CAAC,CAAC,CAAA,CAAC,iCAAiC;QACjG,CAAC;QACD,IAAI;QAEJ,IAAI,CAAC;YACD,MAAM,WAAW,CAAC,eAAe,CAAC,CAAA;YAClC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,mBAAmB,EAAE,SAAS,IAAI,EAAE,CAAA;YAC5D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,IAAI,CAAC,KAAK,GAAG,uBAAuB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA;QACnD,CAAC;gBAAS,CAAC;YACP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;YAChB,0CAA0C;YAC1C,IAAI,mBAAmB,IAAI,kBAAkB,EAAE,CAAC;gBAC5C,OAAO,CAAC,GAAG,GAAG,kBAAkB,CAAA,CAAC,iCAAiC;YACtE,CAAC;YACD,IAAI;QACR,CAAC;QAED,OAAO,IAAI,CAAA;IACf,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,WAAW,CAAA;IAErB,OAAO,MAAM,WAAW,CAAA;AAC5B,CAAC"}

package/dist/cli/lib/loadTestFile.unitTest.js

@@ -9,5 +9,18 @@ mochaDescribe('loadTestFile() function', function () {
         describes.at(-1)?.counter.should.equal(2);
         describes[0]?.tests.should.be.a('function');
     });
+    mochaIt('shares cached module graphs while isolating ordinary module graphs', async function () {
+        const testGlobal = global;
+        testGlobal.cacheBoundarySharedInstances = [];
+        testGlobal.cacheBoundaryIsolatedInstances = [];
+        await loadTestFile(defaultConfig, 'unitTesting/sampleTests/cacheBoundaryOne.test.js');
+        await loadTestFile(defaultConfig, 'unitTesting/sampleTests/cacheBoundaryTwo.test.js');
+        testGlobal.cacheBoundarySharedInstances.length.should.equal(2);
+        testGlobal.cacheBoundaryIsolatedInstances.length.should.equal(2);
+        chaiExpect(testGlobal.cacheBoundarySharedInstances[0])
+            .to.equal(testGlobal.cacheBoundarySharedInstances[1]);
+        chaiExpect(testGlobal.cacheBoundaryIsolatedInstances[0])
+            .not.to.equal(testGlobal.cacheBoundaryIsolatedInstances[1]);
+    });
 });
 //# sourceMappingURL=loadTestFile.unitTest.js.map

package/dist/cli/lib/loadTestFile.unitTest.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadTestFile.unitTest.js","sourceRoot":"","sources":["../../../src/cli/lib/loadTestFile.unitTest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,aAAa,CAAC,yBAAyB,EAAE;IACrC,OAAO,CAAC,mEAAmE,EAAE,KAAK;QAC9E,MAAM,cAAc,GAAG,uDAAuD,CAAA;QAE9E,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;QAE9D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAA;QACtC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAChC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACzC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;AACN,CAAC,CAAC,CAAA"}
+{"version":3,"file":"loadTestFile.unitTest.js","sourceRoot":"","sources":["../../../src/cli/lib/loadTestFile.unitTest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,aAAa,CAAC,yBAAyB,EAAE;IACrC,OAAO,CAAC,mEAAmE,EAAE,KAAK;QAC9E,MAAM,cAAc,GAAG,uDAAuD,CAAA;QAE9E,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;QAE9D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAA;QACtC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAChC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACzC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,OAAO,CAAC,oEAAoE,EAAE,KAAK;QAC/E,MAAM,UAAU,GAAG,MAGlB,CAAA;QACD,UAAU,CAAC,4BAA4B,GAAG,EAAE,CAAA;QAC5C,UAAU,CAAC,8BAA8B,GAAG,EAAE,CAAA;QAE9C,MAAM,YAAY,CAAC,aAAa,EAAE,kDAAkD,CAAC,CAAA;QACrF,MAAM,YAAY,CAAC,aAAa,EAAE,kDAAkD,CAAC,CAAA;QAErF,UAAU,CAAC,4BAA4B,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAC9D,UAAU,CAAC,8BAA8B,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAChE,UAAU,CAAC,UAAU,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC;aACjD,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC,CAAA;QACzD,UAAU,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,CAAC,CAAC;aACnD,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,CAAC,CAAC,CAAA;IACnE,CAAC,CAAC,CAAA;AAEN,CAAC,CAAC,CAAA"}

package/dist/packages/esmReload.additions.unitTest.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=esmReload.additions.unitTest.d.ts.map

package/dist/packages/esmReload.additions.unitTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esmReload.additions.unitTest.d.ts","sourceRoot":"","sources":["../../src/packages/esmReload.additions.unitTest.ts"],"names":[],"mappings":""}

package/dist/packages/esmReload.additions.unitTest.js

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { cwd, execPath } from 'node:process';
+import { pathToFileURL } from 'node:url';
+function spawnPromisified(command, args) {
+    const child = spawn(command, args);
+    let stderr = '';
+    let stdout = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (data) => { stderr += data; });
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (data) => { stdout += data; });
+    return new Promise((resolve, reject) => {
+        child.on('close', (code, signal) => {
+            resolve({ code, signal, stderr, stdout });
+        });
+        child.on('error', reject);
+    });
+}
+mochaDescribe('esmReload', function () {
+    mochaIt('reloads an ES module and its transitive dependencies', async function () {
+        const fixtureDirectory = join(cwd(), 'unitTesting/esmReload/fixtures/simple');
+        const fixture = join(fixtureDirectory, 'index.js');
+        const transitiveUrl = pathToFileURL(join(fixtureDirectory, 'transitive.js')).href;
+        const { code, signal, stderr, stdout } = await spawnPromisified(execPath, [fixture]);
+        chaiExpect(code).to.equal(0);
+        chaiExpect(signal).to.equal(null);
+        chaiExpect(stderr).to.equal('');
+        chaiExpect(stdout.trim().split(/\r?\n/)).to.deep.equal([
+            transitiveUrl,
+            `${transitiveUrl}?instance=sxy-test-runner-reload-0`,
+            `${transitiveUrl}?instance=1`,
+            `${transitiveUrl}?instance=sxy-test-runner-reload-1`,
+            `${transitiveUrl}?instance=2`
+        ]);
+    });
+    mochaIt('reloads a file and ordinary modules while sharing _cached_ exports', async function () {
+        const fixture = join(cwd(), 'unitTesting/esmReload/fixtures/repeated/index.js');
+        const { code, signal, stderr, stdout } = await spawnPromisified(execPath, [fixture]);
+        chaiExpect(code).to.equal(0);
+        chaiExpect(signal).to.equal(null);
+        chaiExpect(stderr).to.equal('');
+        chaiExpect(JSON.parse(stdout)).to.deep.equal({
+            loadedFileIsFresh: true,
+            ordinaryModuleIsFresh: true,
+            cachedExportIsShared: true
+        });
+    });
+});
+//# sourceMappingURL=esmReload.additions.unitTest.js.map

package/dist/packages/esmReload.additions.unitTest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esmReload.additions.unitTest.js","sourceRoot":"","sources":["../../src/packages/esmReload.additions.unitTest.ts"],"names":[],"mappings":"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"}

package/dist/packages/esmReload.d.ts

@@ -0,0 +1,11 @@
+interface ResolveContext {
+    parentURL?: string;
+}
+interface ResolveResult {
+    url: string;
+    [key: string]: unknown;
+}
+type NextResolve = (specifier: string, context: ResolveContext) => ResolveResult | Promise<ResolveResult>;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<ResolveResult>;
+export {};
+//# sourceMappingURL=esmReload.d.ts.map

package/dist/packages/esmReload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esmReload.d.ts","sourceRoot":"","sources":["../../src/packages/esmReload.ts"],"names":[],"mappings":"AAsBA,UAAU,cAAc;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,UAAU,aAAa;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB;AAED,KAAK,WAAW,GAAG,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,KACtB,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;AAsB3C,wBAAsB,OAAO,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,WAAW,GACzB,OAAO,CAAC,aAAa,CAAC,CA2BxB"}

package/dist/packages/esmReload.js

@@ -0,0 +1,43 @@
+import { isBuiltin, register } from 'node:module';
+const cachedModulePattern = /\._cached_\.(?:[cm]?js|[cm]?ts|jsx|tsx)$/i;
+let reloadId = 0;
+function isLoaderInstance() {
+    return new URL(import.meta.url).searchParams.has('loader');
+}
+function isThisModule(url) {
+    const candidate = new URL(url);
+    const current = new URL(import.meta.url);
+    candidate.search = '';
+    current.search = '';
+    return candidate.href === current.href;
+}
+function isCachedModule(url) {
+    return cachedModulePattern.test(url.pathname);
+}
+export async function resolve(specifier, context, nextResolve) {
+    const result = await nextResolve(specifier, context);
+    if (isThisModule(result.url) || isBuiltin(result.url) || context.parentURL === undefined) {
+        return result;
+    }
+    const url = new URL(result.url);
+    // A *._cached_.js/ts module and its dependency graph use Node's ordinary
+    // process-wide module cache instead of inheriting the test file instance.
+    if (isCachedModule(url))
+        return result;
+    const parentUrl = new URL(context.parentURL);
+    const instance = url.searchParams.get('reload') === ''
+        ? `sxy-test-runner-reload-${reloadId++}`
+        : parentUrl.searchParams.get('instance');
+    if (instance === null)
+        return result;
+    url.searchParams.delete('reload');
+    url.searchParams.set('instance', instance);
+    return {
+        ...result,
+        url: url.href
+    };
+}
+if (!isLoaderInstance()) {
+    register(`${import.meta.url}?loader`);
+}
+//# sourceMappingURL=esmReload.js.map

package/dist/packages/esmReload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esmReload.js","sourceRoot":"","sources":["../../src/packages/esmReload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAoCjD,MAAM,mBAAmB,GAAG,2CAA2C,CAAA;AAEvE,IAAI,QAAQ,GAAG,CAAC,CAAA;AAEhB,SAAS,gBAAgB;IACrB,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;AAC9D,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC7B,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACxC,SAAS,CAAC,MAAM,GAAG,EAAE,CAAA;IACrB,OAAO,CAAC,MAAM,GAAG,EAAE,CAAA;IACnB,OAAO,SAAS,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,CAAA;AAC1C,CAAC;AAED,SAAS,cAAc,CAAC,GAAQ;IAC5B,OAAO,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;AACjD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CACzB,SAAiB,EACjB,OAAuB,EACvB,WAAwB;IAExB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IAEpD,IAAI,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACvF,OAAO,MAAM,CAAA;IACjB,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAE/B,yEAAyE;IACzE,0EAA0E;IAC1E,IAAI,cAAc,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAA;IAEtC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC5C,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE;QAClD,CAAC,CAAC,0BAA0B,QAAQ,EAAE,EAAE;QACxC,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;IAE5C,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,MAAM,CAAA;IAEpC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IACjC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;IAE1C,OAAO;QACH,GAAG,MAAM;QACT,GAAG,EAAE,GAAG,CAAC,IAAI;KAChB,CAAA;AACL,CAAC;AAED,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC;IACtB,QAAQ,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAA;AACzC,CAAC"}

package/dist/packages/esmReload.unitTest.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=esmReload.unitTest.d.ts.map

package/dist/packages/esmReload.unitTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esmReload.unitTest.d.ts","sourceRoot":"","sources":["../../src/packages/esmReload.unitTest.ts"],"names":[],"mappings":""}

package/dist/packages/esmReload.unitTest.js

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { cwd, execPath } from 'node:process';
+import { pathToFileURL } from 'node:url';
+function spawnPromisified(command, args) {
+    const child = spawn(command, args);
+    let stderr = '';
+    let stdout = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (data) => { stderr += data; });
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (data) => { stdout += data; });
+    return new Promise((resolve, reject) => {
+        child.on('close', (code, signal) => {
+            resolve({ code, signal, stderr, stdout });
+        });
+        child.on('error', reject);
+    });
+}
+mochaDescribe('esmReload', function () {
+    mochaIt('reloads an ES module and its transitive dependencies', async function () {
+        const fixtureDirectory = join(cwd(), 'unitTesting/esmReload/fixtures/simple');
+        const fixture = join(fixtureDirectory, 'index.js');
+        const transitiveUrl = pathToFileURL(join(fixtureDirectory, 'transitive.js')).href;
+        const { code, signal, stderr, stdout } = await spawnPromisified(execPath, [fixture]);
+        chaiExpect(code).to.equal(0);
+        chaiExpect(signal).to.equal(null);
+        chaiExpect(stderr).to.equal('');
+        chaiExpect(stdout.trim().split(/\r?\n/)).to.deep.equal([
+            transitiveUrl,
+            `${transitiveUrl}?instance=sxy-test-runner-reload-0`,
+            `${transitiveUrl}?instance=1`,
+            `${transitiveUrl}?instance=sxy-test-runner-reload-1`,
+            `${transitiveUrl}?instance=2`
+        ]);
+    });
+    mochaIt('reloads a file and ordinary modules while sharing _cached_ exports', async function () {
+        const fixture = join(cwd(), 'unitTesting/esmReload/fixtures/repeated/index.js');
+        const { code, signal, stderr, stdout } = await spawnPromisified(execPath, [fixture]);
+        chaiExpect(code).to.equal(0);
+        chaiExpect(signal).to.equal(null);
+        chaiExpect(stderr).to.equal('');
+        chaiExpect(JSON.parse(stdout)).to.deep.equal({
+            loadedFileIsFresh: true,
+            ordinaryModuleIsFresh: true,
+            cachedExportIsShared: true
+        });
+    });
+});
+//# sourceMappingURL=esmReload.unitTest.js.map

package/dist/packages/esmReload.unitTest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esmReload.unitTest.js","sourceRoot":"","sources":["../../src/packages/esmReload.unitTest.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sxy-test-runner",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "license": "MIT",
   "homepage": "https://github.com/RobertSandiford/sxy-test-runner",
   "repository": {
@@ -31,6 +31,7 @@
   "files": [
     "dist",
     "sxy-loader.config.js",
+    "AGENTS.md",
     "readme.md"
   ],
   "dependencies": {
@@ -92,6 +93,7 @@
     "unit-test-add-exports": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/addExports.unitTest.js",
     "unit-test-describe": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/describe.unitTest.js",
     "unit-test-run-tests": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/runTests.unitTest.js",
+    "unit-test-esm-reload": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/esmReload.unitTest.js",
     "mocha-trial": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/runTest.unitTest.js"
   }
 }

package/readme.md

@@ -4,8 +4,7 @@ Mocha-like test runner for **es modules** (only), with **watch mode**, and **re-
 
 ```js
 import { describe } from 'sxy-test-runner'
-import { should as setupShould } from 'chai'
-const should = setupShould()
+import { expect } from 'chai'
 
 function add(a, b) {
     return a + b
@@ -14,8 +13,8 @@ function add(a, b) {
 describe('The add() function', ({it}) => {
     it('should add 1 and 2, making 3', () => {
         const result = add(1, 2)
-        result.should.equal(3)
-    }
+        expect(result).to.equal(3)
+    })
 })
 ```
 
@@ -104,6 +103,24 @@ sxy-test-runner runs all tests inside one node process, to improve performance (
 
 Because of this, be careful with globals, which will be shared.
 
+### Sharing a module between test files
+
+Ordinary test dependencies receive a fresh module instance for each test file. To
+deliberately share a module and its static dependency graph, give its filename a
+`._cached_.` marker:
+
+```js
+import { database } from './fixtures/database._cached_.js'
+```
+
+The module then uses Node's normal process-wide module cache, so every test file receives
+the same exported values. JavaScript and TypeScript module extensions are supported; in
+TypeScript `NodeNext` source, import the emitted `._cached_.js` name as usual.
+
+Cached modules remain loaded for the full one-off run or watch process. Avoid unsynchronised
+mutable state when tests run in parallel, and explicitly clean up shared resources such as
+servers or database connections.
+
 ## Execution modes
 
 **execution** settings let you choose whether to run test files, describe blocks, and individual tests sequentially or in parallel.
@@ -157,8 +174,7 @@ Not yet implemented.
 
 ```js
 import { describe } from 'sxy-test-runner'
-import { should as setupShould } from 'chai'
-const should = setupShould()
+import { expect } from 'chai'
 
 describe('something', ({it, beforeEachTest, afterEachTest, afterDescribe}) => {
 
@@ -178,10 +194,10 @@ describe('something', ({it, beforeEachTest, afterEachTest, afterDescribe}) => {
     })
 
     it('should do something', () => {
-        something.should.do.something
+        expect(something.didSomething()).to.equal(true)
     })
     it('should do another thing', () => {
-        something.should.do.another.thing
+        expect(something.didAnotherThing()).to.equal(true)
     })
 
     // teardown should go in afterDescribe.
@@ -198,6 +214,7 @@ describe('something', ({it, beforeEachTest, afterEachTest, afterDescribe}) => {
 # Exit codes for `once`
 
 0: success
-3: some test errors
-2: other error
-It may also crash due to exceptions without giving any of these errors codes
+1: non sxyt error
+2: sxyt error
+3: test errors
+It may also crash due to exceptions without giving any of these errors codes