Refactor test framework.

- Test runtime loads test files from a web server.
- Allows testing of manifests on remote web servers.
- Trading off some performance to align node and browser testing.
- Moves some test setup code into config data and manifest.

Author: davidlehn

CHANGELOG.md

@@ -1,6 +1,6 @@
 # jsonld ChangeLog
 
-## 9.0.0 - 2023-xx-xx
+## 9.0.0 - 2025-xx-xx
 
 ### Changed
 - **BREAKING**: Drop support for Node.js < 18.
@@ -23,6 +23,11 @@
   - Use newer corejs version.
   - Build with modern browserslist defaults and no IE support.
   - Support for older browsers requires a custom build.
+- Refactor test framework.
+  - Test runtime loads test files from a web server.
+  - Allows testing of manifests on remote web servers.
+  - Trading off some performance to align node and browser testing.
+  - Moves some test setup code into config data and manifest.
 
 ### Removed
 - **BREAKING**: Remove `application/nquads` alias for `application/n-quads`.

karma.conf.js

@@ -10,12 +10,40 @@
  */
 const os = require('os');
 const webpack = require('webpack');
+const {TestServer} = require('./tests/test-server.js');
+
+// karma test server proxy details
+const _proxyTestsPrefix = '/tests';
+
+let testServer;
+
+// shutdown test server "reporter" hook
+function ShutdownTestServer(baseReporterDecorator) {
+  baseReporterDecorator(this);
+
+  this.onRunComplete = async function() {
+    await testServer.close();
+  };
+}
+
+// Inject the base reporter
+ShutdownTestServer.$inject = ['baseReporterDecorator', 'config'];
+
+// local "reporter" plugin
+const shutdownTestServer = {
+  'reporter:shutdown-test-server': ['type', ShutdownTestServer]
+};
+
+module.exports = async function(config) {
+  testServer = new TestServer({
+    earlFilename: process.env.EARL
+  });
+  await testServer.start();
 
-module.exports = function(config) {
   // bundler to test: webpack, browserify
   const bundler = process.env.BUNDLER || 'webpack';
 
-  const frameworks = ['mocha', 'server-side'];
+  const frameworks = ['mocha'];
   // main bundle preprocessors
   const preprocessors = ['babel'];
 
@@ -66,7 +94,8 @@ module.exports = function(config) {
           'process.env.EARL': JSON.stringify(process.env.EARL),
           'process.env.TESTS': JSON.stringify(process.env.TESTS),
           'process.env.TEST_ENV': JSON.stringify(process.env.TEST_ENV),
-          'process.env.TEST_ROOT_DIR': JSON.stringify(__dirname),
+          'process.env.TEST_SERVER_URL': JSON.stringify(_proxyTestsPrefix),
+          'process.env.AUTH_TOKEN': JSON.stringify(testServer.authToken),
           'process.env.VERBOSE_SKIP': JSON.stringify(process.env.VERBOSE_SKIP),
           // for 'auto' test env
           'process.env._TEST_ENV_ARCH': JSON.stringify(process.arch),
@@ -151,11 +180,20 @@ module.exports = function(config) {
       ]
     },
 
+    // local server shutdown plugin
+    plugins: [
+      'karma-*',
+      shutdownTestServer
+    ],
+
     // test results reporter to use
     // possible values: 'dots', 'progress'
     // available reporters: https://npmjs.org/browse/keyword/karma-reporter
     //reporters: ['progress'],
-    reporters: ['mocha'],
+    reporters: [
+      'mocha',
+      'shutdown-test-server'
+    ],
 
     // web server port
     port: 9876,
@@ -197,6 +235,8 @@ module.exports = function(config) {
     },
 
     // Proxied paths
-    proxies: {}
+    proxies: {
+      '/tests': testServer.url
+    }
   });
 };

package.json

@@ -63,7 +63,6 @@
     "karma-mocha": "^2.0.1",
     "karma-mocha-reporter": "^2.2.5",
     "karma-safari-launcher": "^1.0.0",
-    "karma-server-side": "^1.8.0",
     "karma-sourcemap-loader": "^0.4.0",
     "karma-tap-reporter": "0.0.6",
     "karma-webpack": "^5.0.1",

tests/test-karma.js

@@ -6,18 +6,15 @@
  * @author Dave Longley
  * @author David I. Lehn
  *
- * Copyright (c) 2011-2023 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2011-2025 Digital Bazaar, Inc. All rights reserved.
  */
-/* global serverRequire */
 // FIXME: hack to ensure delay is set first
 mocha.setup({delay: true, ui: 'bdd'});
 
 const assert = require('chai').assert;
 const benchmark = require('benchmark');
 const common = require('./test.js');
-const server = require('karma-server-side');
 const webidl = require('./test-webidl');
-const join = require('join-path-js');
 
 // special benchmark setup
 const _ = require('lodash');
@@ -26,70 +23,25 @@ window.Benchmark = Benchmark;
 
 const entries = [];
 
+// setup test server url, add localhost if needed
+let testServerUrl = process.env.TEST_SERVER_URL;
+if(!testServerUrl.endsWith('/')) {
+  testServerUrl += '/';
+}
+if(!(testServerUrl.startsWith('http:') || testServerUrl.startsWith('https:'))) {
+  const pathname = testServerUrl;
+  testServerUrl = new URL(window.location);
+  testServerUrl.pathname = pathname;
+}
+
 if(process.env.TESTS) {
   entries.push(...process.env.TESTS.split(' '));
 } else {
-  const _top = process.env.TEST_ROOT_DIR;
-  // TODO: support just adding certain entries in EARL mode?
-
-  // json-ld-api main test suite
-  entries.push((async () => {
-    const testPath = join(_top, 'test-suites/json-ld-api/tests');
-    const siblingPath = join(_top, '../json-ld-api/tests');
-    return server.run(testPath, siblingPath, function(testPath, siblingPath) {
-      const fs = serverRequire('fs-extra');
-      // use local tests if setup
-      if(fs.existsSync(testPath)) {
-        return testPath;
-      }
-      // default to sibling dir
-      return siblingPath;
-    });
-  })());
-
-  // json-ld-framing main test suite
-  entries.push((async () => {
-    const testPath = join(_top, 'test-suites/json-ld-framing/tests');
-    const siblingPath = join(_top, '../json-ld-framing/tests');
-    return server.run(testPath, siblingPath, function(testPath, siblingPath) {
-      const fs = serverRequire('fs-extra');
-      // use local tests if setup
-      if(fs.existsSync(testPath)) {
-        return testPath;
-      }
-      // default to sibling dir
-      return siblingPath;
-    });
-  })());
-
-  /*
-  // TODO: use json-ld-framing once tests are moved
-  // json-ld.org framing test suite
-  // FIXME: add path detection
-  entries.push(join(
-    _top, 'test-suites/json-ld.org/test-suite/tests/frame-manifest.jsonld'));
-  entries.push(join(
-    _top, '../json-ld.org/test-suite/tests/frame-manifests.jsonld'));
-  */
+  entries.push(new URL('tests/default/', testServerUrl));
 
-  // W3C RDF Dataset Canonicalization "rdf-canon" test suite
-  entries.push((async () => {
-    const testPath = join(_top, 'test-suites/rdf-canon/tests');
-    const siblingPath = join(_top, '../rdf-canon/tests');
-    return server.run(testPath, siblingPath, function(testPath, siblingPath) {
-      const fs = serverRequire('fs-extra');
-      // use local tests if setup
-      if(fs.existsSync(testPath)) {
-        return testPath;
-      }
-      // default to sibling dir
-      return siblingPath;
-    });
-  })());
+  // TODO: support just adding certain entries in EARL mode?
 
-  // other tests
-  entries.push(join(_top, 'tests/misc.js'));
-  entries.push(join(_top, 'tests/graph-container.js'));
+  // other tests (including js ones) added with options.addExtraTests
 
   // WebIDL tests
   entries.push(webidl);
@@ -126,33 +78,35 @@ const options = {
     throw new Error('exit not implemented');
   },
   earl: {
+    enabled: !!process.env.EARL,
     filename: process.env.EARL
   },
   entries,
+  addExtraTests: async () => {
+    // direct load for bundling
+    // called after handling other entry loading
+    require('./misc.js');
+    require('./graph-container.js');
+  },
   testEnvDefaults,
-  readFile: filename => {
-    return server.run(filename, function(filename) {
-      const fs = serverRequire('fs-extra');
-      return fs.readFile(filename, 'utf8').then(data => {
-        return data;
-      });
-    });
+  get testServerUrl() {
+    return testServerUrl;
   },
-  writeFile: (filename, data) => {
-    return server.run(filename, data, function(filename, data) {
-      const fs = serverRequire('fs-extra');
-      return fs.outputFile(filename, data);
-    });
+  get authToken() {
+    return process.env.AUTH_TOKEN;
   },
-  /* eslint-disable-next-line no-unused-vars */
   import: f => {
     console.error('import not implemented for "' + f + '"');
-  }
+  },
+  cleanup: async () => {}
 };
 
-// wait for setup of all tests then run mocha
-common(options).then(() => {
+async function main() {
+  // wait for setup of all tests then run mocha
+  await common.setup(options);
   run();
-}).catch(err => {
+}
+
+main().catch(err => {
   console.error(err);
 });