CLI: Show help when missing argument (i.e. plain/default invocation)

Author: Krinkle

ARCHITECTURE.md

@@ -20,6 +20,8 @@ Examples:
 
   This argument relates directly to a concept we know the user naturally knows and is most concerned about (their test file). There are no other unnamed arguments. There are no required options or flags. The default browser is selected automatically. No awareness of test framework is required (in most cases).
 
+  When invoking `qtap` without arguments out of curiosity, we generate not just an error message but also the `--help` usage documentation.
+
 * We favour a single way of doing something that works everywhere, over marginal gains that would introduce layers of indirection, abstraction, conditional branches, or additional dependencies.
 
 * We favour an explicit and efficient inline implementation (e.g. in the form of a single well-documented function with a clear purpose, which may be relatively long, but is readable and linear), over many local functions that are weaved together.

bin/qtap.js

@@ -42,6 +42,7 @@ program
   .option('-v, --verbose', 'Enable verbose debug logging.')
   .option('-V, --version', 'Display version number.')
   .helpOption('-h, --help', 'Display this usage information.')
+  .showHelpAfterError()
   .parse(process.argv);
 
 const opts = program.opts();

package.json

@@ -23,11 +23,11 @@
     "test": "node bin/qtap.js -v test/pass.html && npm run -s lint"
   },
   "dependencies": {
-    "@tapjs/tap-finished": "^0.0.3",
+    "@tapjs/tap-finished": "0.0.3",
     "commander": "12.1.0",
-    "kleur": "^4.1.5",
-    "tap-parser": "^5.4.0",
-    "which": "^5.0.0"
+    "kleur": "4.1.5",
+    "tap-parser": "18.0.0",
+    "which": "5.0.0"
   },
   "devDependencies": {
     "eslint": "^8.13.0",

src/browsers.js

@@ -132,7 +132,8 @@ function createFirefoxPrefsJs (prefs) {
 function * getFirefoxCandidates () {
   if (process.env.FIREFOX_BIN) yield process.env.FIREFOX_BIN;
 
-  // Find /usr/bin/firefox on platforms like linux (including WSL), freebsd, openbsd.
+  // Handle unix-like platforms such as linux (incl WSL), darwin (macOS), freebsd, openbsd.
+  // Example: /usr/bin/firefox
   yield which.sync('firefox', { nothrow: true });
 
   if (process.platform === 'darwin') {

src/server.js

@@ -6,7 +6,7 @@ import http from 'node:http';
 import path from 'node:path';
 import stream from 'node:stream';
 
-import TapParser from 'tap-parser';
+import { Parser as TapParser } from 'tap-parser';
 import tapFinished from '@tapjs/tap-finished';
 
 const MIME_TYPES = {
@@ -111,6 +111,7 @@ class ControlServer {
     const logger = this.logger.channel(`qtap_browser_${browserName}_${clientId}`);
 
     const controller = new AbortController();
+    const summary = { ok: true };
 
     let readableController;
     const readable = new ReadableStream({
@@ -120,11 +121,10 @@ class ControlServer {
     });
 
     this.browsers.set(clientId, {
-      readableController
+      logger,
+      readableController,
     });
 
-    const [readableForFinished, readeableForParser] = readable.tee();
-
     const tapFinishFinder = tapFinished({ wait: 0 }, () => {
       logger.debug('browser_tap_finished', 'Requesting browser stop');
       // Check in case browser already gone (race condition)
@@ -133,23 +133,32 @@ class ControlServer {
         controller.abort('QTap: browser_tap_finished');
       }
     });
-    readableForFinished.pipeTo(stream.Writable.toWeb(tapFinishFinder));
 
-    const tapParser = new TapParser();
-    readeableForParser.pipeTo(stream.Writable.toWeb(tapParser));
     // Also stop on bailout (tap-finished doesn't handle this)
+    const tapParser = new TapParser();
     tapParser.on('bailout', (reason) => {
+      summary.ok = false;
       logger.debug('browser_tap_bailout', reason);
+
       // Check in case browser already gone (race condition)
       if (this.browsers.get(clientId)) {
         this.browsers.delete(clientId);
         controller.abort('QTap: browser_tap_bailout');
       }
     });
+    tapParser.once('fail', () => {
+      summary.ok = false;
+      logger.debug('browser_tap_fail', 'One or more tests failed');
+    });
+
     // Debugging
     // tapParser.on('assert', logger.debug.bind(logger, 'browser_tap_assert'));
     // tapParser.on('plan', logger.debug.bind(logger, 'browser_tap_plan'));
 
+    const [readeableForParser, readableForFinished] = readable.tee();
+    readeableForParser.pipeTo(stream.Writable.toWeb(tapParser));
+    readableForFinished.pipeTo(stream.Writable.toWeb(tapFinishFinder));
+
     // TODO: Implement timeout if stream is quiet for too long
     // --timeout=3000s
     //    use in getTestFile() as QTAP_TIMEOUT for qunit_config_testtimeout
@@ -317,10 +326,12 @@ class ControlServer {
       // eslint-disable-next-line no-control-regex
       body = body.replace(/\x1b\[[0-9]+m/g, '');
       const clientId = url.searchParams.get('qtap_clientId');
-      this.logger.debug('browser_tap', clientId, JSON.stringify(body.slice(0, 30) + '…'));
       const browser = this.browsers.get(clientId);
       if (browser) {
         browser.readableController.enqueue(body);
+        browser.logger.debug('browser_tap_received', JSON.stringify(body.slice(0, 30) + '…'));
+      } else {
+        this.logger.debug('browser_tap_unhandled', clientId, JSON.stringify(body.slice(0, 30) + '…'));
       }
     });
     resp.writeHead(204);

test/fail.html

@@ -3,9 +3,8 @@
 <script>
 console.log('TAP version 13');
 console.log('ok 1 Foo bar');
-console.log('ok 2 Baz > this thing');
-console.log("not ok 3 \u001b[31mexample > hello fail\u001b[39m");
+console.log("not ok 2 \u001b[31mexample > hello fail\u001b[39m");
 console.log("  ---\n  message: \"y\"\n  severity: failed\n  actual  : {\n  \"foo\": \"50\",\n  \"quux\": \"62\"\n}\n  expected: {\n  \"foo\": \"50\",\n  \"quux\": \"70\"\n}\n  stack: |\n    @https://demo.localhost:4000/test/fail.html:21:12\n  ...");
-console.log('ok 4 Quux');
-console.log('1..4');
+console.log('ok 3 Quux');
+console.log('1..3');
 </script>