sxy-test-runner 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export declare const packageName = "sxy-test-runner";
+export declare const cliName = "sxy-test";
+export declare const configFileName = "sxy-test-runner.config";
+export declare const configLocations: string[];
+export declare const debugging = false;
+export declare const showTimeProfiling = false;

package/dist/config.js

@@ -0,0 +1,6 @@
+export const packageName = 'sxy-test-runner';
+export const cliName = 'sxy-test';
+export const configFileName = 'sxy-test-runner.config';
+export const configLocations = ['', 'config']; // locations where the configs may be placed in proj folder
+export const debugging = false;
+export const showTimeProfiling = false;

package/dist/describe.d.ts

@@ -0,0 +1,12 @@
+declare global {
+    var __sxy_test_runner__: unknown;
+}
+type ShouldCallback = () => void;
+type It = (should: string, shouldCallback: ShouldCallback) => void;
+type TestsCallbackPackage = {
+    it: It;
+    test: It;
+};
+type TestsCallback = (package: TestsCallbackPackage) => void;
+export declare function describe(theThing: string, testsCallback: TestsCallback): void;
+export {};

package/dist/describe.js

@@ -0,0 +1,21 @@
+import chalk from 'chalk-extensions';
+import { debug } from './output.js';
+import { showTimeProfiling } from './config.js';
+import { createTimeProfiler } from 'sxy-dev-tools';
+//console.log('sxyDevTools', sxyDevTools)
+//console.log('createTimeProfiler', createTimeProfiler)
+const { timeProfile, timeProfileAsync } = createTimeProfiler(showTimeProfiling);
+export function describe(theThing, testsCallback) {
+    //const thisDescribeCounter = global.testState.describeCounter++ // ++: assign the value, THEN increment
+    const thisDescribeCounter = global.__sxy_test_runner__.describeCounter;
+    global.__sxy_test_runner__.describeCounter++;
+    const describe = {
+        counter: thisDescribeCounter,
+        thing: theThing,
+        tests
+    };
+    //global.testState.describes.push( describe )
+    global.__sxy_test_runner__.describes.push(describe);
+    debug(chalk.lightgrey `${thisDescribeCounter})`
+        + chalk.lightgrey ` Done with ` + chalk.brightblue `${theThing}\n`);
+}

package/dist/describe.unitTest.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/describe.unitTest.js

@@ -0,0 +1,25 @@
+import { expect } from 'chai';
+import { describe } from './describe.js';
+//import { createLoad } from 'sxy-loader'
+//const load = createLoad(import.meta.url)
+mochaDescribe('new describe() function', function () {
+    mochaIt('should run tests and output results', async function () {
+        this.timeout(6000);
+        // eslint-disable-next-line camelcase
+        global.__sxy_test_runner__ = {
+            describes: [],
+            describeCounter: 1
+        };
+        describe('a thing', ({ it }) => {
+            it('should be great', () => {
+                expect('it').to.be.great;
+            });
+            it('should be awesome', () => {
+                expect('it').to.be.awesome;
+            });
+        });
+        global.__sxy_test_runner__.describes.length.should.equal(1);
+        global.__sxy_test_runner__.describes[0].thing.should.equal('a thing');
+        global.__sxy_test_runner__.describes[0].tests.should.be.a('function');
+    });
+});

package/dist/exported.eslintrc.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+module.exports = {
+    "globals": {
+        "describe": "readonly",
+        "test": "readonly",
+        "it": "readonly",
+    }
+};

package/dist/exported.eslintrc.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { describe } from './describe.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { describe } from './describe.js';

package/dist/indexNumberToLetters.d.ts

@@ -0,0 +1 @@
+export declare const indexNumberToLetters: any;

package/dist/indexNumberToLetters.js

@@ -0,0 +1,10 @@
+export const indexNumberToLetters = sync(function indexNumberToLetters(number, uppercase = false) {
+    const charCodeStart = (uppercase) ? 65 : 97;
+    var text = '', letterIndex;
+    while (number > 0) {
+        letterIndex = (number - 1) % 26;
+        text = String.fromCharCode(charCodeStart + letterIndex) + text;
+        number = (number - letterIndex) / 26 | 0;
+    }
+    return text || undefined;
+});

package/dist/load.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/load.js

@@ -0,0 +1,3 @@
+import { createLoad } from 'sxy-loader';
+const load = createLoad(import.meta.url);
+load('../dist/testing/importTimeTarget.js');

package/dist/output.d.ts

@@ -0,0 +1,5 @@
+export declare function out(...texts: any[]): void;
+export declare function warn(...texts: any[]): void;
+export declare function error(...texts: any[]): void;
+export declare function log(...texts: any[]): void;
+export declare const debug: (...texts: any[]) => void;

package/dist/output.js

@@ -0,0 +1,26 @@
+/* eslint-disable no-console */
+import { debugging } from './config.js';
+function waitToOutput() {
+}
+export function out(...texts) {
+    waitToOutput();
+    console.log(...texts);
+}
+export function warn(...texts) {
+    waitToOutput();
+    console.log(...texts);
+}
+export function error(...texts) {
+    waitToOutput();
+    console.log(...texts);
+}
+export function log(...texts) {
+    waitToOutput();
+    console.log(...texts);
+}
+export const debug = (debugging)
+    ? function debug(...texts) {
+        waitToOutput();
+        console.log(...texts);
+    }
+    : function () { };

package/dist/testsState.d.ts

@@ -0,0 +1 @@
+export declare const testsState: {};

package/dist/testsState.js

@@ -0,0 +1,5 @@
+export const testsState = {
+//describeCounter: 1,
+//describeResults: [],
+//testResults: []
+};

package/dist/timeProfiling.d.ts

@@ -0,0 +1,2 @@
+export declare const timeProfilingOut: (name: any, start: any, finish: any) => void;
+export declare const timeProfilingOutSpecial: (name: any, start: any, finish: any) => void;

package/dist/timeProfiling.js

@@ -0,0 +1,13 @@
+import chalk from 'chalk-extensions';
+import { packageName, showTimeProfiling } from './config.js';
+import { out } from './output.js';
+export const timeProfilingOut = (showTimeProfiling)
+    ? function timeProfilingOut(name, start, finish) {
+        out(chalk.yellow(`[${packageName}] {${name}} time ${finish - start}ms`));
+    }
+    : function () { };
+export const timeProfilingOutSpecial = (showTimeProfiling)
+    ? function timeProfilingOutSpecial(name, start, finish) {
+        out(chalk.orange(`[${packageName}] {${name}} time ${finish - start}ms`));
+    }
+    : function () { };

package/package.json

@@ -0,0 +1,91 @@
+{
+    "name": "sxy-test-runner",
+    "version": "0.1.0",
+    "license": "MIT",
+    "homepage": "https://github.com/RobertSandiford/sxy-test-runner",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/RobertSandiford/sxy-test-runner"
+    },
+    "keywords": [
+        "ES Modules",
+        "ES6 Modules",
+        "Test Runner",
+        "Test Framework",
+        "Testing",
+        "Unit Testing",
+        "Automated Tests"
+    ],
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "bin": {
+        "sxy-test": "./dist/cli/index.js",
+        "sxy-test-runner": "./dist/cli/index.js"
+    },
+    "files": [
+        "dist",
+        "sxy-loader.config.js",
+        "readme.md"
+    ],
+    "scripts": {
+        "build": "tsc --watch",
+        "dev": "cross-env NODE_OPTIONS=\"--experimental-specifier-resolution=node\" nodemon --experimental-specifier-resolution=node --watch dist/cli --watch dist/cli/lib --watch sxy-test-runner.config.js --watch sxy-loader.config.js dist/cli/index.js",
+        "dev-once": "nodemon --experimental-specifier-resolution=node --watch dist/cli --watch sxy-test-runner.config.js --watch sxy-loader.config.js dist/cli/index.js once",
+        "dev-init": "node --experimental-specifier-resolution=node dist/cli/index.js init",
+        "unit-test": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/*.unitTest.js",
+        "unit-test-show-test-result": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/showTestResult.unitTest.js",
+        "unit-test-load-config": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/loadConfig.unitTest.js",
+        "unit-test-watch-files": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/watchFiles.unitTest.js",
+        "unit-test-watch-files-chokidar": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/watchFilesChokidar.unitTest.js",
+        "unit-test-watch-files-and-run-tests": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/watchFilesAndRunTests.unitTest.js",
+        "unit-test-watch-files-and-run-tests-chokidar": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/watchFilesAndRunTestsChokidar.unitTest.js",
+        "unit-test-watch": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/watch.unitTest.js",
+        "unit-test-inject-properties": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/injectProperties.unitTest.js",
+        "unit-test-run-it": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/runIt.unitTest.js",
+        "unit-test-run-describe": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/runDescribe.unitTest.js",
+        "unit-test-parse-describe": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/parseDescribe.unitTest.js",
+        "unit-test-run-describe-run": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/runDescribeRun.unitTest.js",
+        "unit-test-run-test": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/runTest.unitTest.js",
+        "unit-test-load-test-file": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/loadTestFile.unitTest.js",
+        "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",
+        "mocha-trial": "mocha --watch --parallel --config unitTesting/.mocharc.cjs --watch-files dist,unitTesting dist/**/runTest.unitTest.js"
+    },
+    "dependencies": {
+        "@babel/core": "^7.22.11",
+        "chalk-extensions": "^2.0.9",
+        "chokidar": "^3.5.3",
+        "cross-env": "^7.0.3",
+        "dependency-tree": "^8.1.2",
+        "figures": "^4.0.1",
+        "glob": "^7.2.3",
+        "globby": "^12.2.0",
+        "minimatch": "^5.1.6",
+        "node-watch": "^0.7.4",
+        "slash": "^5.1.0",
+        "sxy-dev-tools": "^1.0.6",
+        "sxy-helpers": "^1.0.0",
+        "sxy-lib": "^1.0.12",
+        "sxy-lib-object-copy": "^1.0.5",
+        "sxy-loader": "^2.1.0",
+        "sxy-standard": "^1.0.12",
+        "sxy-standard-object-copy": "^1.0.5"
+    },
+    "devDependencies": {
+        "@babel/cli": "^7.22.10",
+        "@types/node": "^20.5.7",
+        "babel-plugin-transform-awaitful": "^1.0.0",
+        "chai": "^4.3.8",
+        "chai-as-promised": "^7.1.1",
+        "eslint": "^7.32.0",
+        "eslint-config-sandi": "^1.2.0",
+        "mocha": "^9.2.2",
+        "mocha-steps": "^1.3.0",
+        "nodemon": "^2.0.22",
+        "sinon": "^12.0.1",
+        "sinon-chai": "^3.7.0",
+        "typescript": "^5.2.2"
+    }
+}

package/readme.md

@@ -0,0 +1,206 @@
+# sxy-test-runner
+
+Mocha-like test runner for **es modules** (only), with **watch mode**, and **re-running only tests related to changes** (by dependency analysis), full **async code support**
+
+```js
+import { describe } from 'sxy-test-runner'
+import { should as setupShould } from 'chai'
+const should = setupShould()
+
+function add(a, b) {
+    return a + b
+}
+
+describe('The add() function', ({it}) => {
+    it('should add 1 and 2, making 3', () => {
+        const result = add(1, 2)
+        result.should.equal(3)
+    }
+})
+```
+
+## Usage
+
+### 1. Install
+
+```
+npm i -D sxy-test-runner
+```
+
+*or*
+
+```
+yarn add -D sxy-test-runner
+```
+
+*or*
+
+```
+pnpm add -D sxy-test-runner
+```
+
+---
+
+### 2. Create a config (required)
+
+```
+sxy-test-runner init
+```
+*sxy-test is an alias for sxy-test-runner and can be used instead*
+
+This will create a config in your project folder. It can be moved to a folder named "config" if you prefer, or specify a location using --config
+
+### 3. Modify the config, specifying the base path for tests and code to watch, and glob patterns for tests and code to watch
+
+```js
+{
+    // base folder for tests matching and ignore patterns
+    testsBase: 'dist',
+
+    // glob pattern or array of glob patterns of test files
+    tests: [
+        '**/*.test.{js,jsx}'
+    ],
+
+    // watch mode configurations
+    watch: {
+
+        //// the base directory to watch files in
+        watchFilesBase: 'dist',
+
+        //// glob filter or array of global filters of files to watch
+        watchFiles: '**/*.js',
+
+    },
+}
+```
+
+The other config options and fairly well explained in the config. More info on them later.
+
+### 4. Run
+
+```
+npx sxy-test-runner
+```
+*sxy-test is an alias for sxy-test-runner and can be used instead*
+
+("npx" can be omitted in package.json scripts)
+
+sxy-test-runner runs watch mode, re-running only relevant tests, by default.
+
+To run tests only once and not watch (e.g. for ci/cd), use
+```
+npx sxy-test-runner once
+```
+
+To specific an alternate config, use -c or --config
+```
+npx sxy-test-runner --config sxy-test-runner.alternate.config.js
+```
+
+# How it works
+
+sxy-test-runner runs all tests inside one node process, to improve performance (this framework far exceeds mocha in parallel mode, which is needed to test ESM files, due to this).
+
+Because of this, be careful with globals, which will be shared.
+
+## Execution modes
+
+**execution** settings let you choose whether to run test files, describe blocks, and individual tests sequentially or in parallel.
+
+If working with globals you may want to use sequential only, to avoid conflicts on those globals.
+
+Sequential mode also allows console log output to be displayed correctly with each test. Running in parallel mode does not allow log output to be matched up to each test, due to the use of a global override on console.log (other console output methods such as console.trace() are not covered currently)
+
+If your code is isolated, and asyncronous, you can use parallel exeecution modes to radically speed up your tests, as the expense of the points mentioned above.
+
+## Dependencies
+
+Module dependencies are identified using dependency-tree. Dynamic imports will not be detected and will not trigger test re-runs.
+
+No option to re-run all tests on changes is currently available - I may add this on request, or submit a PR if you want this.
+
+## Failing test re-running
+
+Default behaviour is to re-run any failing test any time a change is made, even if that change isn't relevant to the failing test. This is to ensure you can see where attention is needed. Turn this off in the config if it is not convenient for you: config.watch.reRunFailingTests
+
+## Reloading modules
+
+A key challenge in creating an ESM test runner is re-loading modules due to the engine not letting us clear the import cache of ESM modules. This framework relies on sxy-loader, which uses a babel transform to transform modules into a reloadable format with a controllable cache. A cache of transformed code is kept to keep the process speedy.
+
+Performance is a little less than a native module import, but not so much as to be notable inconvenience. Re-running only test related to changes keep performance strong even in very large projects.
+
+# Advanced usage
+
+## 1. Run tasks at startup - setup
+
+Edit config.setup. This config value can take a function, a file to import relative to the project folder, or an array or one or both of those.
+
+## 2. Run tasks before each test file / describe / test globally
+
+Edit config.beforeEachFile / config.beforeEachDescribe / config.beforeEachTest with a function, file or array of either.
+
+If a file exports named values, or a function returns an object with properties, these keys will be added to a storage object (beware of conflicting names). This object is then passed to the afterEachFile / afterEachDescribe / afterEachTest tasks for cleanup.
+
+```js
+    // tasks to run before each test file is run
+    beforeEachFile: () => {
+        const thing = prepSomething()
+        return { thing }
+    },
+
+    // tasks to run after each test file is run
+    afterEachFile: ({thing}) => {
+        destroyingSomething(thing)
+    },
+```
+
+## 3. Run code before each describe block, or at the end of a test file - per test file
+
+Not yet implemented.
+
+## 4. Run code before each test, after each test, or after the describe block - per describe block
+
+```js
+import { describe } from 'sxy-test-runner'
+import { should as setupShould } from 'chai'
+const should = setupShould()
+
+describe('something', ({it, beforeEachTest, afterEachTest, afterDescribe}) => {
+
+    // setup can take place here without any special measures
+    // but you can only safely set globals for your test here if your
+    // execution mode for files and describes is 'sequential' (default)
+    const something = createSomething()
+
+    // run this just before each test
+    beforeEachTest(() => {
+        prepSomething(something)
+    })
+
+    // run this just after each test
+    afterEachTest(() => {
+        clearupSomething(something)
+    })
+
+    it('should do something', () => {
+        something.should.do.something
+    })
+    it('should do another thing', () => {
+        something.should.do.another.thing
+    })
+
+    // teardown should go in afterDescribe.
+    // tests are not run syncronously within the describe block (even sync tests)
+    // so cleanup code here would run too early
+    afterDescribe(() => {
+        destroySomething(something)
+    })
+
+})
+
+```
+
+# Known issues
+
+sxy-loader effectively uses eval to run modules, to get around the ESM limited of being unable to reload modules. This has a harmful effect on error reporting when code hits errors. I have some plans to work on error reporting, or work to get changes made to the ESM spec, but at current time error reporting isn't great.

package/sxy-loader.config.js

@@ -0,0 +1,10 @@
+
+export default {
+    //returnStyle: 'esm-dynamic', // 'esm-dynamic' | 'esm-static'
+    mode: process.env.NODE_ENV, // 'development' | 'production' environment
+    //transformCaching: 'content', // content | hash | false  // default content 
+    //transformCacheStorage: 'file', // 'file' | 'memory'
+    //transformCacheStorageLocation: '__cache', // null | path/to/location/from/project/dir
+    quiet: true, // disable info output
+    debug: false, // debugging output // doesn't work yet
+}