Added some documentation to Karma configuration files.

cms/static/karma_cms.conf.js

 // Karma config for cms suite.
-// Docs in common/static/common/js/karma.common.conf.js
+// Docs and troubleshooting tips in common/static/common/js/karma.common.conf.js
 
 /* jshint node: true */
 /*jshint -W079 */
@@ -13,6 +13,8 @@ var options = {
 
     libraryFiles: [],
 
+    // Make sure the patterns in sourceFiles and specFiles do not match the same file.
+    // Otherwise Istanbul which is used for coverage tracking will cause tests to not run.
     sourceFiles: [
         {pattern: 'coffee/src/**/!(*spec).js'},
         {pattern: 'js/**/!(*spec|djangojs).js'}

cms/static/karma_cms_squire.conf.js

 // Karma config for cms-squire suite.
-// Docs in common/static/common/js/karma.common.conf.js
+// Docs and troubleshooting tips in common/static/common/js/karma.common.conf.js
 
 /* jshint node: true */
 /*jshint -W079 */
@@ -13,6 +13,8 @@ var options = {
 
     libraryFiles: [],
 
+    // Make sure the patterns in sourceFiles and specFiles do not match the same file.
+    // Otherwise Istanbul which is used for coverage tracking will cause tests to not run.
     sourceFiles: [
         {pattern: 'coffee/src/**/!(*spec).js'},
         {pattern: 'js/**/!(*spec|djangojs).js'}

common/lib/xmodule/xmodule/js/karma_xmodule.conf.js

 // Karma config for xmodule suite.
-// Docs in common/static/common/js/karma.common.conf.js
+// Docs and troubleshooting tips in common/static/common/js/karma.common.conf.js
 
 /* jshint node: true */
 /*jshint -W079 */
@@ -16,6 +16,7 @@ var options = {
         return pattern;
     },
 
+    // Avoid adding files to this list. Use RequireJS.
     libraryFilesToInclude: [
         {pattern: 'common_static/js/vendor/requirejs/require.js', included: true},
         {pattern: 'RequireJS-namespace-undefine.js', included: true},
@@ -55,6 +56,8 @@ var options = {
         {pattern: 'common_static/edx-pattern-library/js/**/*.js'}
     ],
 
+    // Make sure the patterns in sourceFiles and specFiles do not match the same file.
+    // Otherwise Istanbul which is used for coverage tracking will cause tests to not run.
     sourceFiles: [
         {pattern: 'src/xmodule.js', included: true, ignoreCoverage: true}, // To prevent getting instrumented twice.
         {pattern: 'src/**/*.js', included: true}

common/static/common/js/karma.common.conf.js

@@ -19,6 +19,19 @@
 //
 // where `BROWSER` could be Chrome or Firefox.
 //
+//
+// Troubleshooting tips:
+//
+// If you get an error like: "TypeError: __cov_KBCc7ZI4xZm8W2BC5NQLDg.s is undefined",
+// that means the patterns in sourceFiles and specFiles are matching the same file.
+// This causes Istanbul, which is used for tracking coverage to instrument the file
+// multiple times.
+//
+//
+// If you see the error: "EMFILE, too many open files" that means the files pattern
+// that has been added is matching too many files. The glob library used by Karma
+// does not use graceful-fs and tries to read files simultaneously.
+//
 
 
 /* jshint node: true */
@@ -29,6 +42,7 @@ var path = require('path');
 var _ = require('underscore');
 var appRoot = path.join(__dirname, '../../../../');
 
+// Files which are needed by all lms/cms suites.
 var commonFiles = {
     libraryFiles: [
         {pattern: 'common/js/vendor/**/*.js'},
@@ -148,6 +162,12 @@ function junitSettings(config) {
     };
 }
 
+/**
+ * Return absolute path for files in common and xmodule_js symlink dirs.
+ * @param {String} appRoot
+ * @param {String} pattern
+ * @return {String}
+ */
 var defaultNormalizeFunc = function (appRoot, pattern) {
     if (pattern.match(/^common\/js/)) {
         pattern = path.join(appRoot, '/common/static/' + pattern);
@@ -339,6 +359,8 @@ var configure = function(config, options) {
       files.unshift({pattern: 'common/js/utils/require-serial.js', included: true});
     }
 
+    // Karma sets included=true by default.
+    // We set it to false by default because RequireJS should be used instead.
     files = setDefaults(files);
 
     // With nocache=true, Karma always serves the latest files from disk.
@@ -353,6 +375,8 @@ var configure = function(config, options) {
         )
     );
 
+    // If we give symlink paths to Istanbul, coverage for each path gets tracked
+    // separately. So we pass absolute paths to the karma-coverage preprocessor.
     var preprocessors = _.extend(
       {},
       options.preprocessors,

common/static/common/js/spec/main_requirejs.js

@@ -181,6 +181,8 @@
         'common/js/spec_helpers/jasmine-waituntil'
     ];
 
+    // Jasmine has a global stack for creating a tree of specs. We need to load
+    // spec files one by one, otherwise some end up getting nested under others.
     window.requireSerial(specHelpers.concat(testFiles), function () {
         // start test run, once Require.js is done
         window.__karma__.start();

common/static/karma_common.conf.js

 // Karma config for common suite.
-// Docs in common/static/common/js/karma.common.conf.js
+// Docs and troubleshooting tips in common/static/common/js/karma.common.conf.js
 
 /* jshint node: true */
 /*jshint -W079 */
@@ -15,6 +15,7 @@ var options = {
         return path.join(appRoot, '/common/static/' + pattern);
     },
 
+    // Avoid adding files to this list. Use RequireJS.
     libraryFilesToInclude: [
         {pattern: 'coffee/src/ajax_prefix.js', included: true},
         {pattern: 'js/vendor/draggabilly.js', included: true},
@@ -45,6 +46,8 @@ var options = {
     libraryFiles: [
     ],
 
+    // Make sure the patterns in sourceFiles and specFiles do not match the same file.
+    // Otherwise Istanbul which is used for coverage tracking will cause tests to not run.
     sourceFiles: [
         {pattern: 'js/xblock/**/*.js', included: true},
         {pattern: 'coffee/src/**/*.js', included: true},

common/static/karma_common_requirejs.conf.js

 // Karma config for common-requirejs suite.
-// Docs in common/static/common/js/karma.common.conf.js
+// Docs and troubleshooting tips in common/static/common/js/karma.common.conf.js
 
 /* jshint node: true */
 /*jshint -W079 */
@@ -23,6 +23,8 @@ var options = {
         {pattern: 'js/vendor/**/*.js'}
     ],
 
+    // Make sure the patterns in sourceFiles and specFiles do not match the same file.
+    // Otherwise Istanbul which is used for coverage tracking will cause tests to not run.
     sourceFiles: [],
 
     specFiles: [

lms/static/karma_lms.conf.js

 // Karma config for lms suite.
-// Docs in common/static/common/js/karma.common.conf.js
+// Docs and troubleshooting tips in common/static/common/js/karma.common.conf.js
 
 /* jshint node: true */
 /*jshint -W079 */
@@ -11,6 +11,7 @@ var options = {
 
     includeCommonFiles: true,
 
+    // Avoid adding files to this list. Use RequireJS.
     libraryFilesToInclude: [
         {pattern: 'xmodule_js/common_static/js/vendor/jquery.event.drag-2.2.js', included: true},
         {pattern: 'xmodule_js/common_static/js/vendor/slick.core.js', included: true},
@@ -21,6 +22,8 @@ var options = {
         {pattern: 'js/RequireJS-namespace-undefine.js'}
     ],
 
+    // Make sure the patterns in sourceFiles and specFiles do not match the same file.
+    // Otherwise Istanbul which is used for coverage tracking will cause tests to not run.
     sourceFiles: [
         {pattern: 'coffee/src/**/!(*spec).js'},
         {pattern: 'js/**/!(*spec|djangojs).js'},

lms/static/karma_lms_coffee.conf.js

 // Karma config for lms-coffee suite.
-// Docs in common/static/common/js/karma.common.conf.js
+// Docs and troubleshooting tips in common/static/common/js/karma.common.conf.js
 
 /* jshint node: true */
 /*jshint -W079 */
@@ -13,6 +13,7 @@ var options = {
     useRequireJs: false,
     includeCommonFiles: true,
 
+    // Avoid adding files to this list. Use RequireJS.
     libraryFilesToInclude: [
         {pattern: 'xmodule_js/common_static/js/vendor/requirejs/require.js', included: true},
         {pattern: 'js/spec/main_requirejs_coffee.js', included: true},
@@ -47,6 +48,8 @@ var options = {
         {pattern: 'xmodule_js/common_static/js/vendor/**/*.js'}
     ],
 
+    // Make sure the patterns in sourceFiles and specFiles do not match the same file.
+    // Otherwise Istanbul which is used for coverage tracking will cause tests to not run.
     sourceFiles: [
         {pattern: 'coffee/src/**/*.js', included: true}
     ],