Adds reportTitle option (allow reproducible build) (#354)

Adds CLI options '-t' and '--title' taking strings
Adds api option 'reportTitle' taking strings and functions
Retains existing title behaviours as a default function
Updates README
Adds tests for plugin option reportTitle as string, function, errored function
  and default value
Adds tests for cli option title as string and default value

Author: eoingroat

CHANGELOG.md

@@ -14,6 +14,9 @@ _Note: Gaps between patch versions are faulty, broken or test releases._
 
 <!-- Add changelog entries for new changes under this section -->
 
+* **New Feature**
+   * Adds option reportTitle to set title in HTML reports; default remains date of report generation ([#354](https://github.com/webpack-contrib/webpack-bundle-analyzer/pull/354)) by [@eoingroat](https://github.com/eoingroat)
+
 ## 3.8.0
 
  * **Improvement**

README.md

@@ -60,6 +60,7 @@ new BundleAnalyzerPlugin(options?: object)
 |**`analyzerHost`**|`{String}`|Default: `127.0.0.1`. Host that will be used in `server` mode to start HTTP server.|
 |**`analyzerPort`**|`{Number}` or `auto`|Default: `8888`. Port that will be used in `server` mode to start HTTP server.|
 |**`reportFilename`**|`{String}`|Default: `report.html`. Path to bundle report file that will be generated in `static` mode. It can be either an absolute path or a path relative to a bundle output directory (which is output.path in webpack config).|
+|**`reportTitle`**|`{String\|function}`|Default: function that returns pretty printed current date and time. Content of the HTML `title` element; or a function of the form `() => string` that provides the content.|
 |**`defaultSizes`**|One of: `stat`, `parsed`, `gzip`|Default: `parsed`. Module sizes to show in report by default. [Size definitions](#size-definitions) section describes what these values mean.|
 |**`openAnalyzer`**|`{Boolean}`|Default: `true`. Automatically open report in default browser.|
 |**`generateStatsFile`**|`{Boolean}`|Default: `false`. If `true`, webpack stats JSON file will be generated in bundle output directory|
@@ -118,6 +119,7 @@ Directory containing all generated bundles.
   -h, --host <host>           Host that will be used in `server` mode to start HTTP server. (default: 127.0.0.1)
   -p, --port <n>              Port that will be used in `server` mode to start HTTP server. Should be a number or `auto` (default: 8888)
   -r, --report <file>         Path to bundle report file that will be generated in `static` mode. (default: report.html)
+  -t, --title <title>         String to use in title element of html report. (default: pretty printed current date)
   -s, --default-sizes <type>  Module sizes to show in treemap by default.
                               Possible values: stat, parsed, gzip (default: parsed)
   -O, --no-open               Don't open report in default browser automatically.

src/BundleAnalyzerPlugin.js

@@ -5,13 +5,15 @@ const {bold} = require('chalk');
 
 const Logger = require('./Logger');
 const viewer = require('./viewer');
+const utils = require('./utils');
 
 class BundleAnalyzerPlugin {
   constructor(opts = {}) {
     this.opts = {
       analyzerMode: 'server',
       analyzerHost: '127.0.0.1',
       reportFilename: null,
+      reportTitle: utils.defaultTitle,
       defaultSizes: 'parsed',
       openAnalyzer: true,
       generateStatsFile: false,
@@ -108,6 +110,7 @@ class BundleAnalyzerPlugin {
         openBrowser: this.opts.openAnalyzer,
         host: this.opts.analyzerHost,
         port: this.opts.analyzerPort,
+        reportTitle: this.opts.reportTitle,
         bundleDir: this.getBundleDirFromCompiler(),
         logger: this.logger,
         defaultSizes: this.opts.defaultSizes,
@@ -129,6 +132,7 @@ class BundleAnalyzerPlugin {
     await viewer.generateReport(stats, {
       openBrowser: this.opts.openAnalyzer,
       reportFilename: path.resolve(this.compiler.outputPath, this.opts.reportFilename || 'report.html'),
+      reportTitle: this.opts.reportTitle,
       bundleDir: this.getBundleDirFromCompiler(),
       logger: this.logger,
       defaultSizes: this.opts.defaultSizes,

src/bin/analyzer.js

@@ -9,6 +9,7 @@ const {magenta} = require('chalk');
 const analyzer = require('../analyzer');
 const viewer = require('../viewer');
 const Logger = require('../Logger');
+const utils = require('../utils');
 
 const SIZES = new Set(['stat', 'parsed', 'gzip']);
 
@@ -48,6 +49,10 @@ const program = commander
     '-r, --report <file>',
     'Path to bundle report file that will be generated in `static` mode.'
   )
+  .option(
+    '-t, --title <title>',
+    'String to use in title element of html report.'
+  )
   .option(
     '-s, --default-sizes <type>',
     'Module sizes to show in treemap by default.' +
@@ -77,6 +82,7 @@ let {
   host,
   port,
   report: reportFilename,
+  title: reportTitle,
   defaultSizes,
   logLevel,
   open: openBrowser,
@@ -85,6 +91,10 @@ let {
 } = program;
 const logger = new Logger(logLevel);
 
+if (typeof reportTitle === 'undefined') {
+  reportTitle = utils.defaultTitle;
+}
+
 if (!bundleStatsFile) showHelp('Provide path to Webpack Stats file as first argument');
 if (mode !== 'server' && mode !== 'static' && mode !== 'json') {
   showHelp('Invalid mode. Should be either `server`, `static` or `json`.');
@@ -116,6 +126,7 @@ if (mode === 'server') {
     port,
     host,
     defaultSizes,
+    reportTitle,
     bundleDir,
     excludeAssets,
     logger: new Logger(logLevel)
@@ -124,6 +135,7 @@ if (mode === 'server') {
   viewer.generateReport(bundleStats, {
     openBrowser,
     reportFilename: resolve(reportFilename || 'report.html'),
+    reportTitle,
     defaultSizes,
     bundleDir,
     excludeAssets,

src/utils.js

@@ -39,12 +39,15 @@ function createAssetsFilter(excludePatterns) {
  * @desc get string of current time
  * format: dd/MMM HH:mm
  * */
-exports.getCurrentTime = function () {
+exports.defaultTitle = function () {
   const time = new Date();
   const year = time.getFullYear();
   const month = MONTHS[time.getMonth()];
   const day = time.getDate();
   const hour = `0${time.getHours()}`.slice(-2);
   const minute = `0${time.getMinutes()}`.slice(-2);
-  return `${day} ${month} ${year} at ${hour}:${minute}`;
+
+  const currentTime = `${day} ${month} ${year} at ${hour}:${minute}`;
+
+  return `${process.env.npm_package_name || 'Webpack Bundle Analyzer'} [${currentTime}]`;
 };

src/viewer.js

@@ -10,13 +10,20 @@ const opener = require('opener');
 const mkdir = require('mkdirp');
 const {bold} = require('chalk');
 
-const utils = require('./utils');
 const Logger = require('./Logger');
 const analyzer = require('./analyzer');
 
 const projectRoot = path.resolve(__dirname, '..');
 const assetsRoot = path.join(projectRoot, 'public');
 
+function resolveTitle(reportTitle) {
+  if (typeof reportTitle === 'function') {
+    return reportTitle();
+  } else {
+    return reportTitle;
+  }
+}
+
 module.exports = {
   startServer,
   generateReport,
@@ -25,8 +32,6 @@ module.exports = {
   start: startServer
 };
 
-const title = `${process.env.npm_package_name || 'Webpack Bundle Analyzer'} [${utils.getCurrentTime()}]`;
-
 async function startServer(bundleStats, opts) {
   const {
     port = 8888,
@@ -35,7 +40,8 @@ async function startServer(bundleStats, opts) {
     bundleDir = null,
     logger = new Logger(),
     defaultSizes = 'parsed',
-    excludeAssets = null
+    excludeAssets = null,
+    reportTitle
   } = opts || {};
 
   const analyzerOpts = {logger, excludeAssets};
@@ -56,7 +62,7 @@ async function startServer(bundleStats, opts) {
   app.use('/', (req, res) => {
     res.render('viewer', {
       mode: 'server',
-      title,
+      title: resolveTitle(reportTitle),
       get chartData() { return chartData },
       defaultSizes,
       enableWebSocket: true,
@@ -123,6 +129,7 @@ async function generateReport(bundleStats, opts) {
   const {
     openBrowser = true,
     reportFilename,
+    reportTitle,
     bundleDir = null,
     logger = new Logger(),
     defaultSizes = 'parsed',
@@ -138,7 +145,7 @@ async function generateReport(bundleStats, opts) {
       `${projectRoot}/views/viewer.ejs`,
       {
         mode: 'static',
-        title,
+        title: resolveTitle(reportTitle),
         chartData,
         defaultSizes,
         enableWebSocket: false,

test/analyzer.js

@@ -114,6 +114,35 @@ describe('Analyzer', function () {
     const chartData = require(path.resolve(__dirname, 'output/report.json'));
     expect(chartData).to.containSubset(require('./stats/with-modules-in-chunks/expected-chart-data'));
   });
+
+  describe('options', function () {
+    describe('title', function () {
+      it('should take the --title option', async function () {
+        const reportTitle = 'A string report title';
+        generateReportFrom('with-modules-chunk.json', `--title "${reportTitle}"`);
+
+        const generatedReportTitle = await getTitleFromReport();
+
+        expect(generatedReportTitle).to.equal(reportTitle);
+      });
+      it('should take the -t option', async function () {
+        const reportTitle = 'A string report title';
+
+        generateReportFrom('with-modules-chunk.json', `-t "${reportTitle}"`);
+
+        const generatedReportTitle = await getTitleFromReport();
+
+        expect(generatedReportTitle).to.equal(reportTitle);
+      });
+      it('should use a suitable default title', async function () {
+        generateReportFrom('with-modules-chunk.json');
+
+        const generatedReportTitle = await getTitleFromReport();
+
+        expect(generatedReportTitle).to.match(/^webpack-bundle-analyzer \[.* at \d{2}:\d{2}\]/u);
+      });
+    });
+  });
 });
 
 function generateJSONReportFrom(statsFilename) {
@@ -122,10 +151,16 @@ function generateJSONReportFrom(statsFilename) {
   });
 }
 
-function generateReportFrom(statsFilename) {
-  childProcess.execSync(`../lib/bin/analyzer.js -m static -r output/report.html -O stats/${statsFilename}`, {
-    cwd: __dirname
-  });
+function generateReportFrom(statsFilename, additionalOptions = '') {
+  childProcess.execSync(
+    `../lib/bin/analyzer.js ${additionalOptions} -m static -r output/report.html -O stats/${statsFilename}`,
+    {
+      cwd: __dirname
+    });
+}
+
+async function getTitleFromReport() {
+  return await nightmare.goto(`file://${__dirname}/output/report.html`).title();
 }
 
 async function getChartData() {

test/plugin.js

@@ -96,6 +96,63 @@ describe('Plugin', function () {
         expect(_.map(chartData, 'label')).to.deep.equal(['bundle.js']);
       });
     });
+
+    describe('reportTitle', function () {
+      it('should have a sensible default', async function () {
+        const config = makeWebpackConfig();
+
+        await webpackCompile(config);
+
+        const generatedReportTitle = await getTitleFromReport();
+
+        expect(generatedReportTitle).to.match(/^webpack-bundle-analyzer \[.* at \d{2}:\d{2}\]/u);
+      });
+      it('should use a string', async function () {
+        const reportTitle = 'A string report title';
+        const config = makeWebpackConfig({
+          analyzerOpts: {
+            reportTitle
+          }
+        });
+
+        await webpackCompile(config);
+
+        const generatedReportTitle = await getTitleFromReport();
+
+        expect(generatedReportTitle).to.equal(reportTitle);
+      });
+      it('should use a function', async function () {
+        const reportTitleResult = 'A string report title';
+        const config = makeWebpackConfig({
+          analyzerOpts: {
+            reportTitle: () => reportTitleResult
+          }
+        });
+
+        await webpackCompile(config);
+
+        const generatedReportTitle = await getTitleFromReport();
+
+        expect(generatedReportTitle).to.equal(reportTitleResult);
+      });
+      it('should propogate an error in a function', async function () {
+        const reportTitleError = new Error();
+        const config = makeWebpackConfig({
+          analyzerOpts: {
+            reportTitle: () => {throw reportTitleError}
+          }
+        });
+
+        let error = null;
+        try {
+          await webpackCompile(config);
+        } catch (e) {
+          error = e;
+        }
+
+        expect(error).to.equal(reportTitleError);
+      });
+    });
   });
 
   async function expectValidReport(opts) {
@@ -123,6 +180,10 @@ describe('Plugin', function () {
     return require(path.resolve(__dirname, `output/${reportFilename}`));
   }
 
+  async function getTitleFromReport(reportFilename = 'report.html') {
+    return await nightmare.goto(`file://${__dirname}/output/${reportFilename}`).title();
+  }
+
   async function getChartDataFromReport(reportFilename = 'report.html') {
     return await nightmare.goto(`file://${__dirname}/output/${reportFilename}`).evaluate(() => window.chartData);
   }