Adding JSDocs checks (#1081)

* Adding JSDocs checks

* Fixed failing doc builds locally

* If we test docs in the actual test script, we can skip testing docs on travis

* Seperating all tests from other packages so it isn't run multiple times needlessly

* Adding some logging to see why travis is unhappy

* switch to log helper

* Glob for nested html files too

* Try a different path / glob for travis

* Travis has build in it - sigh

* Back to simpler tests

* Correcting the gulp command for windows

* Fix jsdoc test for windows on appveyor

* Disable test on windows

.travis.yml

@@ -21,7 +21,6 @@ install:
 
 script:
   - gulp test
-  - gulp docs:build
 
 after_success:
   - npm run coveralls

gulp-tasks/test-node.js

@@ -36,24 +36,33 @@ const runNodeTestSuite = async (testPath, nodeEnv) => {
   }
 };
 
-const runNodeTestsWithEnv = async (nodeEnv) => {
-  let globFolderPattern = global.packageOrStar;
-  // This means will run the package tests along with the "all" tests.
-  if (global.packageOrStar !== '*') {
-    globFolderPattern = `{${[global.packageOrStar, 'all'].join(',')}}`;
+const runNodeTestsWithEnv = async (testGroup, nodeEnv) => {
+  let globConfig = {
+    ignore: [
+      '**/all/**',
+    ],
+  };
+
+  if (testGroup === 'all') {
+    globConfig.ignore = [];
   }
-  const packagesToTest = glob.sync(`test/${globFolderPattern}/node`);
+
+  const packagesToTest = glob.sync(`test/${testGroup}/node`, globConfig);
   for (const packageToTest of packagesToTest) {
     await runNodeTestSuite(packageToTest, nodeEnv);
   }
 };
 
 gulp.task('test-node:prod', gulp.series(
-  () => runNodeTestsWithEnv(constants.BUILD_TYPES.prod),
+  () => runNodeTestsWithEnv(global.packageOrStar, constants.BUILD_TYPES.prod),
 ));
 
 gulp.task('test-node:dev', gulp.series(
-  () => runNodeTestsWithEnv(constants.BUILD_TYPES.dev),
+  () => runNodeTestsWithEnv(global.packageOrStar, constants.BUILD_TYPES.dev),
+));
+
+gulp.task('test-node:all', gulp.series(
+  () => runNodeTestsWithEnv('all', constants.BUILD_TYPES.prod),
 ));
 
 gulp.task('test-node:clean', () => {
@@ -76,5 +85,6 @@ gulp.task('test-node', gulp.series(
   'test-node:clean',
   'test-node:dev',
   'test-node:prod',
+  'test-node:all',
   'test-node:coverage',
 ));

jsdoc.conf

@@ -7,7 +7,7 @@
       "packages/workbox-cli"
     ],
     "includePattern": ".+\\.(js(doc|x)?|mjs)$",
-    "excludePattern": "((^|\\/|\\\\)build(\\/|\\\\)|(^|\\/|\\\\)test(\\/|\\\\)|(^|\\/|\\\\)node_modules(\\/|\\\\)|(^|\\/|\\\\)demo(\\/|\\\\))"
+    "excludePattern": "((^|\\/|\\\\)packages\\/.*\\/build(\\/|\\\\)|(^|\\/|\\\\)test(\\/|\\\\)|(^|\\/|\\\\)node_modules(\\/|\\\\)|(^|\\/|\\\\)demo(\\/|\\\\))"
   },
   "opts": {
     "recurse": true

test/all/node/test-jsdocs.mjs

@@ -0,0 +1,44 @@
+import path from 'path';
+import glob from 'glob';
+import {expect} from 'chai';
+import fs from 'fs-extra';
+import spawn from '../../../gulp-tasks/utils/spawn-promise-wrapper';
+
+describe('[all] JSDocs', function() {
+  it('should run JSDocs and have no unexpected results', async function() {
+    // Windows is super unhappy with the JSDocs build pipeline.
+    // With gulp.cmd in spawn, the query string used by the baseline template
+    // causes issues.
+    if (process.platform === 'win32') {
+      this.skip();
+      return;
+    }
+    // Building docs takes time.
+    this.timeout(60 * 1000);
+
+    const projectRoot = path.join(__dirname, '..', '..', '..');
+    const docsPath = path.join(projectRoot, 'docs');
+    await spawn('gulp', ['docs:build'], {
+      cwd: projectRoot,
+    });
+
+    const docs = glob.sync('*.html', {
+      cwd: docsPath,
+    });
+
+    // global.html is only added when the docs have stray global values.
+    if (docs.indexOf('global.html') !== -1) {
+      throw new Error('There should be **no** globals in the JSDocs.');
+    }
+
+    // On some occassions module.exports can leak into JSDocs and breaks
+    // in the final template.
+    expect(docs.indexOf('index-all.html')).to.not.equal(-1);
+    const indexAllContents = fs.readFileSync(path.join(docsPath, 'index-all.html'))
+      .toString();
+    if (indexAllContents.indexOf('<a href="module.html#.exports">module.exports</a>') !== -1) {
+      throw new Error('There is a stray `module.exports` in the docs. ' +
+        'Find and fix this issue.');
+    }
+  });
+});