qunitx 0.7.0 → 0.8.1

package/.dockerignore

@@ -0,0 +1 @@
+node_modules

package/README.md

@@ -1,26 +1,33 @@
+![docker-based-ci](https://github.com/izelnakri/qunitx/workflows/docker-based-ci/badge.svg)
+[![npm version](https://badge.fury.io/js/qunitx.svg)](https://badge.fury.io/js/qunitx)
+
 # QUnitX
 
-Experimental improvements, suggestions for qunit CLI
+***Truly universal testing for JavaScript with the oldest, most mature & flexible
+testing API in the JavaScript ecosystem. Run the same test file in node.js, deno or in the browser***
 
-![QunitX terminal output](https://raw.githubusercontent.com/izelnakri/qunitx/main/docs/qunitx-help-stdout.png)
+Your test JS/TS file(s) can now run interchangably in different runtimes with
+the default test runner of node.js or deno, or with a browser runner of your
+choice!
 
-Default test output is TAP (_Test-Anything-Protocol_) thus you can use any tap reporter of your choice to display test
-output in anyway you like. Example:
+[![asciicast](https://asciinema.org/a/597066.svg)](https://asciinema.org/a/597066?autoplay=1)
 
-```zsh
-# using it with tap-difflet TAP reporter:
-qunitx tests/attachments tests/user | npx tap-difflet
-```
+In the browser you can use the same browser test/filter UI of
+[QUnit](https://github.com/qunitjs/qunit) and share the web links with your
+colleagues thanks to the test filters through query params feature of QUnit:
 
-#### Installation:
+[QUnit Test Suite Example](https://objectmodel.js.org/test/?moduleId=6e15ed5f&moduleId=950ec9c5)
 
-```zsh
-npm install -g qunitx
+**UI visual automated tests also possible with QUnit!**
 
-qunitx
-```
+![QunitX terminal output](https://raw.githubusercontent.com/izelnakri/qunitx/main/docs/qunitx-help-stdout.png)
+
+### Installation: Node & Deno
+
+This is a 0-dependency test library that runs code in your target runtime(node,
+deno or browser) test runner. Since a default test runner is a new feature of node.js, please use node.js v20.3+.
 
-In order to use qunitx to execute existing qunit tests please change:
+In order to use qunitx to convert qunit tests files please change:
 
 ```js
 import { module, test } from 'qunit';
@@ -32,7 +39,7 @@ import { module, test } from 'qunitx';
 Example:
 
 ```js
-// in some-test.js: (typescript is also supported for --browser mode and node.js with --loader flag)
+// in some-test.js: (typescript also works)
 import { module, test } from 'qunitx';
 import $ from 'jquery';
 
@@ -56,37 +63,91 @@ module('Basic sanity check', function (hooks) {
 # you can run the test in node with ES modules package.json{ "type": "module" }
 $ node --test some-test.js
 
-# Suggested mode: if you want to run it in CI/google chrome:
+# TypeScript also works, make sure on node.js mode, tsconfig.json exists with compilerOptions.module & compilerOptions.moduleResolution set to "NodeNext":
+$ node --loader=ts-node/esm/transpile-only --test some-test.ts
+
+# You can use the new watch mode of node.js to watch for files or folder patterns
+$ node --test --watch some-test.js some-folder/*.js
+
+# You can also run this test on deno. Unfortunately today deno requires one extra step to create a deno.json file:
+$ echo '{"imports": { "qunitx": "https://esm.sh/qunitx/shims/deno/index.js" } }' > deno.json
+
+# then run the tests in default deno test runner:
+$ deno test some-test.js
+```
+
+### Installation: Browser
+
+QUnitX mainly proxies to [QUnit
+API](https://api.qunitjs.com/QUnit/module/#hooks-on-nested-modules) in browser.
+You can use [QUnitX CLI](https://github.com/izelnakri/qunitx-cli) to get your
+browser tests to stdout/CI or use the watch mode during the development.
 
+```zsh
+# Install QUnitX browser runner/cli:
+$ npm install -g qunitx-cli
+$ qunitx
 $ qunitx some-test.js
 
 # with browser output enabled:
-
 $ qunitx some-test.js --debug
 
-# TypeScript also works, make sure on node.js mode, tsconfig.json exists with compilerOptions.module & compilerOptions.moduleResolution set to "NodeNext":
+```
 
-$ node --loader=ts-node/esm/transpile-only --test some-test.ts
+### Concurrency options
 
-$ qunitx some-test.ts --debug
+QUnitX API accepts an optional options object as 2nd argument to:
+- `QUnit.module(testName, optionsOrHandler?, handler?)`
+- `QUnit.test(testName, optionsOrHandler?, handler?)`
 
-```
+So you can run tests in parallel(default) or in series. You can even run them
+through the [node.js test runner run()
+api](https://nodejs.org/api/test.html#runoptions):
 
-### Code coverage
+```js
+// in some-test.js: (typescript also works)
+import { module, test } from 'qunitx';
+import $ from 'jquery';
 
-Since QUnitX proxies to default node.js test runner in when executed with node, you can use any code coverage tool you like. When running the tests in `qunit`(the browser mode) code coverage support is limited.
-```
-c8 node test/attachments test/user
+module('Basic sanity check', function (hooks) {
+  test('it works', { concurrency: false }, function (assert) {
+    assert.equal(true, true);
+  });
+
+  module('More advanced cases', { concurrency: false, permissions: { read: true }, sanitizeExit: false }, function (hooks) {
+    test('deepEqual works', function (assert) {
+      assert.deepEqual({ username: 'izelnakri' }, { username: 'izelnakri' });
+    });
+    test('can import ES & npm modules', function (assert) {
+      assert.ok(Object.keys($));
+    });
+  });
+});
 ```
 
-You can browse [c8 documentation](https://github.com/bcoe/c8) for all configuration options.
+### Code coverage
+
+Since QUnitX proxies to default node.js test runner in when executed with node,
+you can use any code coverage tool you like. When running the tests in
+`qunit`(the browser mode) code coverage support is limited.
 
-Implementing code coverage for the browser mode is currently not possible because we use esbuild --bundle feature to
-create a JS bundles for testing in the browser, this could be instrumented with `puppeteer-to-istanbul` however
-instrumentation includes transpiled npm imports of `qunitx` and other potential npm imports developer
-includes in the code, this cannot be filtered since potential filtering can only occur after the `esbuild` bundling.
-When chrome browser and puppeteer fully supports ES asset maps we can remove esbuild from the browser mode, run
-everything in deno and make instrumentation for code coverage possible with the default v8 instrumentation.
+```zsh
+$ c8 node --test test/attachments test/user
+```
 
-Esbuild plugin interface is an ongoing development, we might be able to figure out a way to generate this instrumentation
-with esbuild in the future, which could allow code coverage for --browser mode.
+You can browse [c8 documentation](https://github.com/bcoe/c8) for all
+configuration options.
+
+Implementing code coverage for the browser mode is currently not possible
+because we use esbuild --bundle feature to create a JS bundles for testing in
+the browser, this could be instrumented with `puppeteer-to-istanbul` however
+instrumentation includes transpiled npm imports of `qunitx` and other potential
+npm imports developer includes in the code, this cannot be filtered since
+potential filtering can only occur after the `esbuild` bundling. When chrome
+browser and puppeteer fully supports ES asset maps we can remove esbuild from
+the browser mode, run everything in deno and make instrumentation for code
+coverage possible with the default v8 instrumentation.
+
+Esbuild plugin interface is an ongoing development, we might be able to figure
+out a way to generate this instrumentation with esbuild in the future, which
+could allow code coverage for --browser mode.

package/build.js

@@ -0,0 +1,54 @@
+import fs from 'fs/promises';
+
+let [qunitJS, qunitCSS, _] = await Promise.all([
+  fs.readFile('./node_modules/qunit/qunit/qunit.js'),
+  fs.readFile('./node_modules/qunit/qunit/qunit.css'),
+  fs.mkdir('./vendor', { recursive: true })
+]);
+
+let newQUnit = qunitJS.toString().replace(
+  'start: function start(count) {',
+  `reset: function() {
+		ProcessingQueue.finished = false;
+		globalStartCalled = false;
+		runStarted = false;
+
+		config.queue.length = 0;
+		config.modules.length = 0;
+		config.autostart = false;
+
+    Object.assign(config.stats, { total: 0, passed: 0, failed: 0, skipped: 0, todo: 0 });
+
+		[
+			"started", "updateRate", "filter", "depth", "current",
+			"pageLoaded", "timeoutHandler", "timeout", "pollution"
+		].forEach( ( key ) => delete config[ key ] );
+
+		const suiteReport = config.currentModule.suiteReport;
+
+		suiteReport.childSuites.length = 0;
+		delete suiteReport._startTime;
+		delete suiteReport._endTime;
+
+		config.modules.push( config.currentModule );
+  },
+  start: function start(count) {`);
+
+await Promise.all([
+  fs.writeFile('./vendor/qunit.js', newQUnit),
+  fs.writeFile('./vendor/qunit.css', qunitCSS),
+  createPackageJSONIfNotExists()
+]);
+
+async function createPackageJSONIfNotExists() {
+  try {
+    await fs.stat('./vendor/package.json');
+
+    return true;
+  } catch (error) {
+    await fs.writeFile('./vendor/package.json', JSON.stringify({
+      name: 'qunitx-vendor',
+      version: '0.0.1'
+    }));
+  }
+}

package/deno.json

@@ -1,5 +1,5 @@
 {
   "imports": {
-    "qunitx": "./shims/deno.js"
+    "qunitx": "./shims/deno/index.js"
   }
-}
+}