Migrate JavaScript tests from Karma to the Jasmine framework (#12754)

.github/workflows/nodejs.yml

@@ -6,7 +6,6 @@ on:
       - ".github/workflows/nodejs.yml"
       - "sphinx/themes/**.js"
       - "tests/js/**"
-      - "karma.conf.js"
       - "package.json"
       - "package-lock.json"
   pull_request:
@@ -14,7 +13,6 @@ on:
       - ".github/workflows/nodejs.yml"
       - "sphinx/themes/**.js"
       - "tests/js/**"
-      - "karma.conf.js"
       - "package.json"
       - "package-lock.json"
 

CHANGES.rst

@@ -28,3 +28,7 @@ Bugs fixed
 
 Testing
 -------
+
+* #12141: Migrate from the deprecated ``karma`` JavaScript test framework to
+  the actively-maintained ``jasmine`` framework.  Test coverage is unaffected.
+  Patch by James Addison.

doc/internals/contributing.rst

@@ -174,10 +174,10 @@ Style and type checks can be run as follows:
 Unit tests
 ~~~~~~~~~~
 
-Sphinx is tested using pytest_ for Python code and Karma_ for JavaScript.
+Sphinx is tested using pytest_ for Python code and Jasmine_ for JavaScript.
 
 .. _pytest: https://docs.pytest.org/en/latest/
-.. _Karma: https://karma-runner.github.io
+.. _Jasmine: https://jasmine.github.io/
 
 To run Python unit tests, we recommend using :program:`tox`, which provides a number
 of targets and allows testing against multiple different Python environments:
@@ -216,13 +216,10 @@ To run JavaScript tests, use :program:`npm`:
 
 .. tip::
 
-   :program:`karma` requires a Firefox binary to use as a test browser.
+   :program:`jasmine` requires a Firefox binary to use as a test browser.
 
-   For Unix-based systems, you can specify the path to the Firefox binary using:
-
-   .. code-block:: shell
-
-      FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test
+   On Unix systems, you can check the presence and location of the ``firefox``
+   binary at the command-line by running ``command -v firefox``.
 
 New unit tests should be included in the :file:`tests/` directory where necessary:
 

karma.conf.js

@@ -1,75 +0,0 @@
-// Karma configuration
-// Generated on Sat Jul 21 2018 22:01:48 GMT+0200 (CEST)
-
-module.exports = function(config) {
-  config.set({
-
-    // base path that will be used to resolve all patterns (eg. files, exclude)
-    basePath: '',
-
-
-    // frameworks to use
-    // available frameworks: https://npmjs.org/browse/keyword/karma-adapter
-    frameworks: ['jasmine'],
-
-
-    // list of files / patterns to load in the browser
-    files: [
-      { pattern: 'tests/js/fixtures/**/*.js', included: false, served: true },
-      'tests/js/documentation_options.js',
-      'tests/js/language_data.js',
-      'sphinx/themes/basic/static/doctools.js',
-      'sphinx/themes/basic/static/searchtools.js',
-      'sphinx/themes/basic/static/sphinx_highlight.js',
-      'tests/js/*.js'
-    ],
-
-
-    // list of files / patterns to exclude
-    exclude: [
-    ],
-
-
-    // preprocess matching files before serving them to the browser
-    // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
-    preprocessors: {
-    },
-
-
-    // test results reporter to use
-    // possible values: 'dots', 'progress'
-    // available reporters: https://npmjs.org/browse/keyword/karma-reporter
-    reporters: ['progress'],
-
-
-    // web server port
-    port: 9876,
-
-
-    // enable / disable colors in the output (reporters and logs)
-    colors: true,
-
-
-    // level of logging
-    // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG
-    logLevel: config.LOG_INFO,
-
-
-    // enable / disable watching file and executing tests whenever any file changes
-    autoWatch: true,
-
-
-    // start these browsers
-    // available browser launchers: https://npmjs.org/browse/keyword/karma-launcher
-    browsers: ["Firefox"],
-
-
-    // Continuous Integration mode
-    // if true, Karma captures browsers, runs the tests and exits
-    singleRun: false,
-
-    // Concurrency level
-    // how many browser should be started simultaneous
-    concurrency: Infinity
-  })
-}

package.json

@@ -1,7 +1,7 @@
 {
   "name": "sphinx",
   "scripts": {
-    "test": "./node_modules/.bin/karma start --browsers Firefox --single-run"
+    "test": "npx jasmine-browser-runner runSpecs --config=tests/js/jasmine-browser.mjs"
   },
   "repository": {
     "type": "git",
@@ -11,9 +11,7 @@
     "url": "https://github.com/sphinx-doc/sphinx/issues"
   },
   "devDependencies": {
-    "jasmine-core": "^3.4.0",
-    "karma": "^6.3.16",
-    "karma-firefox-launcher": "^2.0.0",
-    "karma-jasmine": "^4.0.0"
+    "jasmine-browser-runner": "^2.5.0",
+    "jasmine-core": "^5.2.0"
   }
 }

tests/js/jasmine-browser.mjs

@@ -0,0 +1,29 @@
+export default {
+  srcDir: ".",
+  srcFiles: [
+    'sphinx/themes/basic/static/doctools.js',
+    'sphinx/themes/basic/static/searchtools.js',
+    'sphinx/themes/basic/static/sphinx_highlight.js',
+    'tests/js/fixtures/**/*.js',
+    'tests/js/documentation_options.js',
+    'tests/js/language_data.js',
+  ],
+  specDir: "tests/js",
+  specFiles: [
+    'searchtools.js',
+    'sphinx_highlight.js'
+  ],
+  helpers: [],
+  env: {
+    stopSpecOnExpectationFailure: false,
+    stopOnSpecFailure: false,
+    random: true
+  },
+
+  listenAddress: "127.0.0.1",
+  hostname: "127.0.0.1",
+
+  browser: {
+    name: "firefox"
+  }
+};

tests/js/searchtools.js

@@ -2,7 +2,7 @@ describe('Basic html theme search', function() {
 
   function loadFixture(name) {
       req = new XMLHttpRequest();
-      req.open("GET", `base/tests/js/fixtures/${name}`, false);
+      req.open("GET", `__src__/tests/js/fixtures/${name}`, false);
       req.send(null);
       return req.responseText;
   }