[tests] JavaScript: extract searchindex.js-format test fixtures.

.gitignore

@@ -31,6 +31,7 @@ doc/_build/
 doc/locale/
 tests/.coverage
 tests/build/
+tests/js/roots/*/_build
 tests/test-server.lock
 utils/regression_test.js
 

.ruff.toml

@@ -9,6 +9,7 @@ exclude = [
     ".tox",
     ".venv",
     "tests/roots/*",
+    "tests/js/roots/*",
     "build/*",
     "doc/_build/*",
     "sphinx/search/*",

CHANGES.rst

@@ -159,6 +159,7 @@ Testing
   servers.  As a side-effect, this removes the need for test server lockfiles,
   meaning that any remaining ``tests/test-server.lock`` files can safely be
   deleted.
+* karma: refactor HTML search tests to use fixtures generated by Sphinx.
 
 Release 7.2.6 (released Sep 13, 2023)
 =====================================

doc/internals/contributing.rst

@@ -338,3 +338,9 @@ Debugging tips
   Minified files in ``sphinx/search/minified-js/*.js`` are generated from
   non-minified ones using ``uglifyjs`` (installed via npm), with ``-m``
   option to enable mangling.
+
+* The ``searchindex.js`` files found in the ``tests/js/fixtures/*`` directories
+  are generated by using the standard Sphinx HTML builder on the corresponding
+  input projects found in ``tests/js/roots/*``.  The fixtures provide test data
+  used by the Sphinx JavaScript unit tests, and can be regenerated by running
+  the ``utils/generate_js_fixtures.py`` script.

karma.conf.js

@@ -15,7 +15,9 @@ module.exports = function(config) {
 
     // 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',

sphinx/themes/basic/static/searchtools.js

@@ -268,16 +268,7 @@ const Search = {
     else Search.deferQuery(query);
   },
 
-  /**
-   * execute search (requires search index to be loaded)
-   */
-  query: (query) => {
-    const filenames = Search._index.filenames;
-    const docNames = Search._index.docnames;
-    const titles = Search._index.titles;
-    const allTitles = Search._index.alltitles;
-    const indexEntries = Search._index.indexentries;
-
+  _parseQuery: (query) => {
     // stem the search terms and add them to the correct list
     const stemmer = new Stemmer();
     const searchTerms = new Set();
@@ -313,6 +304,19 @@ const Search = {
     // console.info("required: ", [...searchTerms]);
     // console.info("excluded: ", [...excludedTerms]);
 
+    return [query, searchTerms, excludedTerms, highlightTerms, objectTerms];
+  },
+
+  /**
+   * execute search (requires search index to be loaded)
+   */
+  _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => {
+    const filenames = Search._index.filenames;
+    const docNames = Search._index.docnames;
+    const titles = Search._index.titles;
+    const allTitles = Search._index.alltitles;
+    const indexEntries = Search._index.indexentries;
+
     // Collect multiple result groups to be sorted separately and then ordered.
     // Each is an array of [docname, title, anchor, descr, score, filename].
     const normalResults = [];
@@ -394,7 +398,12 @@ const Search = {
       return acc;
     }, []);
 
-    results = results.reverse();
+    return results.reverse();
+  },
+
+  query: (query) => {
+    const searchParameters = Search._parseQuery(query);
+    const results = Search._performSearch(...searchParameters);
 
     // for debugging
     //Search.lastresults = results.slice();  // a copy

tests/js/language_data.js

@@ -0,0 +1,26 @@
+/*
+ * language_data.js
+ * ~~~~~~~~~~~~~~~~
+ *
+ * This script contains the language-specific data used by searchtools.js,
+ * namely the list of stopwords, stemmer, scorer and splitter.
+ *
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+var stopwords = [];
+
+
+/* Non-minified version is copied as a separate JS file, if available */
+
+/**
+ * Dummy stemmer for languages without stemming rules.
+ */
+var Stemmer = function() {
+  this.stemWord = function(w) {
+    return w;
+  }
+}
+

tests/js/roots/cpp/index.rst

@@ -0,0 +1,5 @@
+This is a sample C++ project used to generate a search engine index fixture.
+
+.. cpp:class:: public Sphinx
+
+   The description of Sphinx class.

tests/js/roots/multiterm/index.rst

@@ -0,0 +1,4 @@
+Main Page
+=========
+
+Welcome to the... main page!

tests/js/roots/partial/index.rst

@@ -0,0 +1,4 @@
+sphinx_utils module
+===================
+
+Useful utilities.

tests/js/searchtools.js

@@ -1,20 +1,20 @@
 describe('Basic html theme search', function() {
 
+  function loadFixture(name) {
+      req = new XMLHttpRequest();
+      req.open("GET", `base/tests/js/fixtures/${name}`, false);
+      req.send(null);
+      return req.responseText;
+  }
+
   describe('terms search', function() {
 
     it('should find "C++" when in index', function() {
-      index = {
-        docnames:["index"],
-        filenames:["index.rst"],
-        terms:{'c++':0},
-        titles:["<no title>"],
-        titleterms:{}
-      }
-      Search.setIndex(index);
-      searchterms = ['c++'];
-      excluded = [];
-      terms = index.terms;
-      titleterms = index.titleterms;
+      eval(loadFixture("cpp/searchindex.js"));
+
+      [/* first-ignored */, searchterms, excluded, /*rest-ignored*/] = Search._parseQuery('C++');
+      terms = Search._index.terms;
+      titleterms = Search._index.titleterms;
 
       hits = [[
         "index",
@@ -28,22 +28,11 @@ describe('Basic html theme search', function() {
     });
 
     it('should be able to search for multiple terms', function() {
-      index = {
-        alltitles: {
-          'Main Page': [[0, 'main-page']],
-        },
-        docnames:["index"],
-        filenames:["index.rst"],
-        terms:{main:0, page:0},
-        titles:["Main Page"],
-        titleterms:{ main:0, page:0 }
-      }
-      Search.setIndex(index);
-
-      searchterms = ['main', 'page'];
-      excluded = [];
-      terms = index.terms;
-      titleterms = index.titleterms;
+      eval(loadFixture("multiterm/searchindex.js"));
+
+      [/* first-ignored */, searchterms, excluded, /*rest-ignored*/] = Search._parseQuery('main page');
+      terms = Search._index.terms;
+      titleterms = Search._index.titleterms;
       hits = [[
         'index',
         'Main Page',
@@ -55,18 +44,11 @@ describe('Basic html theme search', function() {
     });
 
     it('should partially-match "sphinx" when in title index', function() {
-      index = {
-        docnames:["index"],
-        filenames:["index.rst"],
-        terms:{'useful': 0, 'utilities': 0},
-        titles:["sphinx_utils module"],
-        titleterms:{'sphinx_utils': 0}
-      }
-      Search.setIndex(index);
-      searchterms = ['sphinx'];
-      excluded = [];
-      terms = index.terms;
-      titleterms = index.titleterms;
+      eval(loadFixture("partial/searchindex.js"));
+
+      [/* first-ignored */, searchterms, excluded, /*rest-ignored*/] = Search._parseQuery('sphinx');
+      terms = Search._index.terms;
+      titleterms = Search._index.titleterms;
 
       hits = [[
         "index",
@@ -81,6 +63,37 @@ describe('Basic html theme search', function() {
 
   });
 
+  describe('aggregation of search results', function() {
+
+    it('should combine document title and document term matches', function() {
+      eval(loadFixture("multiterm/searchindex.js"));
+
+      searchParameters = Search._parseQuery('main page');
+
+      // fixme: duplicate result due to https://github.com/sphinx-doc/sphinx/issues/11961
+      hits = [
+        [
+          'index',
+          'Main Page',
+          '',
+          null,
+          15,
+          'index.rst'
+        ],
+        [
+          'index',
+          'Main Page',
+          '#main-page',
+          null,
+          100,
+          'index.rst'
+        ]
+      ];
+      expect(Search._performSearch(...searchParameters)).toEqual(hits);
+    });
+
+  });
+
 });
 
 describe("htmlToText", function() {

tests/test_search.py

@@ -2,6 +2,7 @@
 
 import json
 import warnings
+from hashlib import sha256
 from io import BytesIO
 
 import pytest
@@ -10,6 +11,8 @@
 
 from sphinx.search import IndexBuilder
 
+from tests.utils import TESTS_ROOT
+
 
 class DummyEnvironment:
     def __init__(self, version, domains):
@@ -341,3 +344,20 @@ def assert_is_sorted(item, path):
     # Pretty print the index. Only shown by pytest on failure.
     print(f'searchindex.js contents:\n\n{json.dumps(index, indent=2)}')
     assert_is_sorted(index, '')
+
+
+@pytest.mark.parametrize('directory', (
+    directory for directory in (TESTS_ROOT / 'js' / 'roots').iterdir()
+))
+def test_check_js_search_indexes(make_app, sphinx_test_tempdir, directory):
+    app = make_app('html', srcdir=directory, builddir=sphinx_test_tempdir / directory.name)
+    app.build()
+
+    fresh_searchindex = (app.outdir / 'searchindex.js')
+    fresh_hash = sha256(fresh_searchindex.read_bytes()).digest()
+
+    existing_searchindex = (TESTS_ROOT / 'js' / 'fixtures' / directory.name / 'searchindex.js')
+    existing_hash = sha256(existing_searchindex.read_bytes()).digest()
+
+    msg = f"Search index fixture {existing_searchindex} does not match regenerated copy."
+    assert fresh_hash == existing_hash, msg

utils/generate_js_fixtures.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+
+import subprocess
+from pathlib import Path
+
+SPHINX_ROOT = Path(__file__).resolve().parent.parent
+TEST_JS_FIXTURES = SPHINX_ROOT / 'tests' / 'js' / 'fixtures'
+TEST_JS_ROOTS = SPHINX_ROOT / 'tests' / 'js' / 'roots'
+
+
+def build(srcdir: Path) -> None:
+    cmd = ('sphinx-build', '-E', '-q', '-b', 'html', f'{srcdir}', f'{srcdir}/_build')
+    subprocess.run(cmd, check=True, capture_output=True)
+
+
+for directory in TEST_JS_ROOTS.iterdir():
+    searchindex = directory / '_build' / 'searchindex.js'
+    destination = TEST_JS_FIXTURES / directory.name / 'searchindex.js'
+
+    print(f'Building {directory} ... ', end='')
+    build(directory)
+    print('done')
+
+    print(f'Moving {searchindex} to {destination} ... ', end='')
+    searchindex.replace(destination)
+    print('done')