Merge pull request #5207 from TimKam/5186-js-test-infrastructure

5186 set up JavaScript test infrastructure

.gitignore

@@ -29,3 +29,5 @@ doc/locale/
 tests/.coverage
 tests/build/
 utils/regression_test.js
+
+node_modules/

.travis.yml

@@ -7,6 +7,7 @@ env:
   global:
     - PYTHONFAULTHANDLER=x
     - SKIP_LATEX_BUILD=1
+    - IS_PYTHON=true
 
 matrix:
   include:
@@ -37,11 +38,21 @@ matrix:
     - python: '3.6'
       env: TOXENV=flake8
 
+    - language: node_js
+      node_js:
+        - 10.7
+      env: IS_PYTHON=false
+      before_script:
+        - export DISPLAY=:99.0
+        - sh -e /etc/init.d/xvfb start
+
 install:
-  - pip install -U tox codecov
+  - if [ $IS_PYTHON = true ]; then pip install -U tox codecov; fi
+  - if [ $IS_PYTHON = false ]; then npm install; fi
 
 script:
-  - tox -- -v
+  - if [ $IS_PYTHON = true ]; then tox -- -v; fi
+  - if [ $IS_PYTHON = false ]; then npm test; fi
 
 after_success:
   - if [[ -e .coverage ]]; then codecov -e $TOXENV; fi

CONTRIBUTING.rst

@@ -154,6 +154,12 @@ These are the basic steps needed to start developing on Sphinx.
 
          tox -e docs -- -b html,latexpdf
 
+   * To run JavaScript tests with `Karma <https://karma-runner.github.io>`_,
+     execute the following commands (requires `Node.js <https://nodejs.org>`_)::
+
+      npm install
+      npm run test
+
    You can also test by installing dependencies in your local environment. ::
 
        pip install .[test]
@@ -302,8 +308,8 @@ Debugging Tips
   in `this repository <https://github.com/shibukawa/snowball-stemmer.jsx>`_.
   You can get the resulting JavaScript files using the following command::
 
-     $ npm install
+     npm install
-     $ node_modules/.bin/grunt build # -> dest/*.global.js
+     node_modules/.bin/grunt build # -> dest/*.global.js
 
 
 Branch Model
@@ -402,3 +408,6 @@ and other ``test_*.py`` files under ``tests`` directory.
 
 .. versionadded:: 1.6
    ``sphinx.testing`` as a experimental.
+
+.. versionadded:: 1.8
+   Sphinx also runs JavaScript tests.

karma.conf.js

@@ -0,0 +1,72 @@
+// 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: [
+      'sphinx/themes/basic/static/underscore.js',
+      'sphinx/themes/basic/static/jquery.js',
+      'sphinx/themes/basic/static/doctools.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: ['Chrome', '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

@@ -0,0 +1,20 @@
+{
+  "name": "sphinx",
+  "scripts": {
+    "test": "./node_modules/.bin/karma start --browsers Firefox --single-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sphinx-doc/sphinx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sphinx-doc/sphinx/issues"
+  },
+  "devDependencies": {
+    "jasmine-core": "^3.1.0",
+    "karma": "^2.0.4",
+    "karma-chrome-launcher": "^2.2.0",
+    "karma-firefox-launcher": "^1.1.0",
+    "karma-jasmine": "^1.1.2"
+  }
+}

sphinx/themes/basic/static/doctools.js

@@ -150,9 +150,9 @@ var Documentation = {
     this.fixFirefoxAnchorBug();
     this.highlightSearchWords();
     this.initIndexTable();
-    {% if theme_navigation_with_keys|tobool %}
+    if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) {
-    this.initOnKeyListeners();
+      this.initOnKeyListeners();
-    {% endif %}
+    }
   },
 
   /**

sphinx/themes/basic/static/documentation_options.js_t

@@ -5,5 +5,20 @@ var DOCUMENTATION_OPTIONS = {
     COLLAPSE_INDEX: false,
     FILE_SUFFIX: '{{ '' if no_search_suffix else file_suffix }}',
     HAS_SOURCE: {{ has_source|lower }},
-    SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}'
+    SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}',
+    NAVIGATION_WITH_KEYS: {{ 'true' if theme_navigation_with_keys|tobool else 'false'}},
+    SEARCH_LANGUAGE_STOP_WORDS: {{ search_language_stop_words }}
 };
+
+
+{% if search_language_stemming_code %}
+/* Non-minified version JS is _stemmer.js if file is provided */ {% endif -%}
+{{ search_language_stemming_code|safe }}
+
+{% if search_scorer_tool %}
+{{ search_scorer_tool|safe }}
+{% endif -%}
+
+{% if search_word_splitter_code %}
+{{ search_word_splitter_code }}
+{% endif -%}

sphinx/themes/basic/static/searchtools.js

@@ -1,5 +1,5 @@
 /*
- * searchtools.js_t
+ * searchtools.js
  * ~~~~~~~~~~~~~~~~
  *
  * Sphinx JavaScript utilities for the full-text search.
@@ -9,51 +9,43 @@
  *
  */
 
-{% if search_language_stemming_code %}
+if (!Scorer) {
-/* Non-minified version JS is _stemmer.js if file is provided */ {% endif -%}
+  /**
-{{ search_language_stemming_code|safe }}
+   * Simple result scoring code.
+   */
+  var Scorer = {
+    // Implement the following function to further tweak the score for each result
+    // The function takes a result array [filename, title, anchor, descr, score]
+    // and returns the new score.
+    /*
+    score: function(result) {
+      return result[4];
+    },
+    */
 
-{% if search_scorer_tool %}
+    // query matches the full name of an object
-{{ search_scorer_tool|safe }}
+    objNameMatch: 11,
-{% else %}
+    // or matches in the last dotted part of the object name
-/**
+    objPartialMatch: 6,
- * Simple result scoring code.
+    // Additive scores depending on the priority of the object
- */
+    objPrio: {0:  15,   // used to be importantResults
-var Scorer = {
+              1:  5,   // used to be objectResults
-  // Implement the following function to further tweak the score for each result
+              2: -5},  // used to be unimportantResults
-  // The function takes a result array [filename, title, anchor, descr, score]
+    //  Used when the priority is not in the mapping.
-  // and returns the new score.
+    objPrioDefault: 0,
-  /*
-  score: function(result) {
-    return result[4];
-  },
-  */
 
-  // query matches the full name of an object
+    // query found in title
-  objNameMatch: 11,
+    title: 15,
-  // or matches in the last dotted part of the object name
+    // query found in terms
-  objPartialMatch: 6,
+    term: 5
-  // Additive scores depending on the priority of the object
+  };
-  objPrio: {0:  15,   // used to be importantResults
+}
-            1:  5,   // used to be objectResults
+
-            2: -5},  // used to be unimportantResults
+if (!splitQuery) {
-  //  Used when the priority is not in the mapping.
+  function splitQuery(query) {
-  objPrioDefault: 0,
+    return query.split(/\s+/);
-
+  }
-  // query found in title
-  title: 15,
-  // query found in terms
-  term: 5
-};
-{% endif %}
-
-{% if search_word_splitter_code %}
-{{ search_word_splitter_code }}
-{% else %}
-function splitQuery(query) {
-    return query.split(/\s+/);
 }
-{% endif %}
 
 /**
  * Search Module
@@ -146,7 +138,7 @@ var Search = {
    */
   query : function(query) {
     var i;
-    var stopwords = {{ search_language_stop_words }};
+    var stopwords = DOCUMENTATION_OPTIONS.SEARCH_LANGUAGE_STOP_WORDS;
 
     // stem the searchterms and add them to the correct list
     var stemmer = new Stemmer();

tests/js/doctools.js

@@ -0,0 +1,32 @@
+var DOCUMENTATION_OPTIONS = {};
+
+describe('urldecode', function() {
+
+  it('should correctly decode URLs and replace `+`s with a spaces', function() {
+    var test_encoded_string =
+      '%D1%88%D0%B5%D0%BB%D0%BB%D1%8B+%D1%88%D0%B5%D0%BB%D0%BB%D1%8B';
+    var test_decoded_string = 'шеллы шеллы';
+    expect(jQuery.urldecode(test_encoded_string)).toEqual(test_decoded_string);
+  });
+
+});
+
+describe('getQueryParameters', function() {
+  var paramString = '?q=test+this&check_keywords=yes&area=default';
+  var queryParamObject = {
+    area: ['default'],
+    check_keywords: ['yes'],
+    q: ['test this']
+  };
+
+  it('should correctly create query parameter object from string', function() {
+    expect(jQuery.getQueryParameters(paramString)).toEqual(queryParamObject);
+  });
+
+  it('should correctly create query param object from URL params', function() {
+    history.pushState({}, '_', window.location + paramString);
+    expect(jQuery.getQueryParameters()).toEqual(queryParamObject);
+  });
+
+});
+