lighthouse-batch-parallel

⚠️ Running Lighthouse concurrently would skew Performamce Score according to this reply from Lighthouse team, be careful of giving workersNum argument when the accuracy of performance score is important.

This is a module to help collecting website's Lighthouse audit data in batches.

You can require this module in your own project, get the report data stream in CSV, JS Object or JSON format and handle the stream by yourself, or you can just use the cli-tool which is also provided to generate the report file.

It has the capability to monitor multiple websites in parallel which can accelerate the collecting process when the target URLs are in plenty, but please be aware of the warning. You can decide how many workers working at the same time, every worker would launch an independent headless Chrome browser.

Usage

npm:

$ npm i lighthouse-batch-parallel

yarn:

$ yarn add lighthouse-batch-parallel

Example

const { lighthouseBatchParallel } = require('lighthouse-batch-parallel');

const targetWebsites = [
  {
    Device: 'mobile',
    URL:    'https://www.npmjs.com/package/lighthouse-batch-parallel'
  },
  {
    Device: 'desktop',
    URL:    'https://www.npmjs.com/package/lighthouse-batch-parallel'
  },
];

const customAuditsConfig = {
  'first-contentful-paint': 'First Contentful Paint',
  'first-meaningful-paint': 'First Meaningful Paint',
  'speed-index':            'Speed Index',
};

const lighthouseAuditing = lighthouseBatchParallel({ 
  input: {
    stream: targetWebsites,
  },
  customAudits: { stream: customAuditsConfig },
  throttling:   'applied3G',
  outputFormat: 'jsObject',
  workersNum:   2,
});

let reports = [];

lighthouseAuditing.on('data', ({ data }) => {
  reports.push(data);
});

lighthouseAuditing.on('error', ({ error }) => {
  console.log(error);
});

lighthouseAuditing.on('end', () => {
  console.log(reports);
  console.log(reports[0].audits);
});

Output of example above:

// console.log(reports);
[
  {
    Device: 'mobile',
    URL: 'https://www.npmjs.com/package/react-carousel-slider',
    audits: {
      performance: [Object],
      accessibility: [Object],
      'best-practices': [Object],
      seo: [Object],
      pwa: [Object],
      'first-contentful-paint': [Object],
      'first-meaningful-paint': [Object],
      'speed-index': [Object]
    }
  },
  {
    Device: 'desktop',
    URL: 'https://www.npmjs.com/package/react-carousel-slider',
    audits: {
      performance: [Object],
      accessibility: [Object],
      'best-practices': [Object],
      seo: [Object],
      pwa: [Object],
      'first-contentful-paint': [Object],
      'first-meaningful-paint': [Object],
      'speed-index': [Object]
    }
  }
]

// console.log(reports[0].audits);
{
  performance: { title: 'Performance', score: 0.42 },
  accessibility: { title: 'Accessibility', score: 0.78 },
  'best-practices': { title: 'Best-practices', score: 1 },
  seo: { title: 'SEO', score: 1 },
  pwa: { title: 'PWA', score: 0.31 },
  'first-contentful-paint': { title: 'First Contentful Paint', score: '2.7 s' },
  'first-meaningful-paint': { title: 'First Meaningful Paint', score: '4.2 s' },
  'speed-index': { title: 'Speed Index', score: '5.9 s' }
}

lighthouseBatchParallel(parameters)

• parameters <Object>
  • input <object> | <string>
  • customAudits <object> | <string>
  • throttling<string>
  • outputFormat<string>
  • workersNum<number>
• returns <EventEmitter>
  • 'data'
  • 'error'
  • 'end'

Parameters

input

To give all target URLs, the format could be:

• File
  • available file format:
    • .csv
    • .json

lighthouseBatchParallel({ 
  input: '/path/of/your/inputfile.json'
  ...
});

Required .json file structure:

[
  {
    "Device":"mobile",
    "URL":"https://www.npmjs.com/package/lighthouse-batch-parallel"
  },
  {
    "Device":"desktop",
    "URL":"https://www.npmjs.com/package/lighthouse-batch-parallel"
  },
]

Required .csv file structure:

Device,URL
mobile,https://www.npmjs.com/package/lighthouse-batch-parallel
desktop,https://www.npmjs.com/package/lighthouse-batch-parallel

• Object
  • available format:
    • An array of JS Objects
    • CSV string

The object requires property stream as the key of the targets data.

const csvString = `Device,URL
mobile,https://www.npmjs.com/package/lighthouse-batch-parallel
desktop,https://www.npmjs.com/package/lighthouse-batch-parallel`;

lighthouseBatchParallel({ 
  input: { stream: csvString }
  ...
});

const targets = [
  {
    Device: 'desktop',
    URL: 'https://www.npmjs.com/package/lighthouse-batch-parallel'
  },
  {
    Device: 'mobile',
    URL: 'https://www.npmjs.com/package/lighthouse-batch-parallel'
  },
];

lighthouseBatchParallel({ 
  input: { stream: targets }
  ...
});

customAudits [optional]

Decide which audits would be showed in the report, if this argument is not given, this module would use its default one, the format of this configuration could be:

• File
  • available file format:
    • .csv
    • .json

lighthouseBatchParallel({ 
  customAudits: '/path/of/your/customAudits.json'
  ...
});

Required .json file structure:

{
  "first-contentful-paint": "First Contentful Paint",
  "first-meaningful-paint": "First Meaningful Paint",
  "speed-index": "Speed Index"
}

Required .csv file structure:

first-contentful-paint, First Contentful Paint
first-meaningful-paint, First Meaningful Paint
speed-index, Speed Index

• Object
  • available format:
    • JS Object
    • CSV string

The object requires property stream which as the key of the targets data.

const csvString = `first-contentful-paint, First Contentful Paint
first-meaningful-paint, First Meaningful Paint
speed-index, Speed Index`;

lighthouseBatchParallel({ 
  customAudits: { stream: csvString }
  ...
});

const customAuditsConfig = {
  'first-contentful-paint': 'First Contentful Paint',
  'first-meaningful-paint': 'First Meaningful Paint',
  'speed-index': 'Speed Index',
};

lighthouseBatchParallel({ 
  customAudits: { stream: customAuditsConfig }
  ...
});

The values before commas (or keys in the object) which in kebab-case are subset of audit options available in Lighthouse, to add more audits for monitoring, check the URL below:

https://github.com/GoogleChrome/lighthouse/blob/d8410d5f81db8b3f98304f338afb7309719be0ae/lighthouse-core/config/default-config.js#L365

The values after comma (or values in the object) correspond to the titles in the report, they are not regulated, feel free to rename it.

throttling [optional]

Allowed properties:

'simulated3G' (default)
'applied3G'
'no'

The properties above align to the options provided in Chrome Devtools. To understand the difference between them and more details, please visit the documentation.

outputFormat [optional]

Decide the format of output stream, if this argument is not given, the default output format is csv.

Allowed properties:

'csv' (default)
'jsObject'
'json'

Output structures:

• The first output in csv format would be the titles header which is defined by customAudits:

// first output
Device,URL,Performance,Accessibility,Best-practices,SEO,PWA,First Contentful Paint,First Meaningful Paint,Speed Index

// the rest of outputs
mobile,https://www.npmjs.com/package/lighthouse-batch-parallel,0.42,0.78,1,1,0.31,2.7 s,4.0 s,5.8 s
desktop,https://www.npmjs.com/package/lighthouse-batch-parallel,0.42,0.78,1,1,0.31,2.7 s,4.1 s,5.8 s

• The output stream of jsObject would be:

{
  Device: 'desktop',
  URL: 'https://www.npmjs.com/package/lighthouse-batch-parallel',
  audits: {
    performance: { title: 'Performance', score: 0.39 },
    accessibility: { title: 'Accessibility', score: 0.78 },
    'best-practices': { title: 'Best-practices', score: 0.93 },
    seo: { title: 'SEO', score: 1 },
    pwa: { title: 'PWA', score: 0.31 },
    'first-contentful-paint': { title: 'First Contentful Paint', score: '3.0 s' },
    'first-meaningful-paint': { title: 'First Meaningful Paint', score: '4.4 s' },
    'speed-index': { title: 'Speed Index', score: '6.1 s' }
  }
}

• The output stream of json would be:

{"Device":"desktop","URL":"https://www.npmjs.com/package/lighthouse-batch-parallel","audits":{"performance":{"title":"Performance","score":0.4},"accessibility":{"title":"Accessibility","score":0.78},"best-practices":{"title":"Best-practices","score":1},"seo":{"title":"SEO","score":1},"pwa":{"title":"PWA","score":0.31},"first-contentful-paint":{"title":"First Contentful Paint","score":"2.9 s"},"first-meaningful-paint":{"title":"First Meaningful Paint","score":"4.3 s"},"speed-index":{"title":"Speed Index","score":"6.0 s"}}}

workersNum [optional]

Decide how many workers would work in parallel, if this argument is not given, the default number is 1, please be aware of the warning.

Returns

After giving the arguments to lighthouseBatchParallel, it returns an EventEmitter. Use this EventEmitter instance to register listeners which listen for following events emitted in lighthouseBatchParallel:

Event: 'data'

This event would be emitted right after each target URL is audited, the result would give to listenr's callback.

const lighthouseAuditing = lighthouseBatchParallel({ ... })
lighthouseAuditing.on('data', ({ data, progress, header }) => {...})

• Parameter of listener's callback is an object, the object contains following properties:
  • data <object> | <string> The format of the data depends on the given outputFormat.
  • progress <object> This object contains following properties:
    • device <string>
    • url <string>
    • totalTasksNum <number>
    • leftTasksNum <number>
  • header <boolean>

When outputFormat is in csv mode, the first data comes out would be the titles header, in that case, the header would be true, also device and url in progress would be undefined.

Event: 'error'

This event would be emitted when any auditing encounters problems.

• Parameter of listener's callback is an object, the object contains following property:
  • error <object> | <string> The format of the error depends on the given outputFormat.

Event: 'end'

This event would be emitted when all auditing tasks are finished.

Cli Tool

This cli-tool is a little gadget only takes file as input, and also only generates file as output, it also can be an example to show how to use this module. Install this module globally would be easier to use this cli-tool.

$ npm i lighthouse-batch-parallel -g

Input file

$ lighthouse-batch-parallel your-input.csv

The input file should follow the structure as what is required. Options below can help to pass custom settings to the module.

Options

-a <path>   ||  --audits-config <path>    { Custom audits config }

-t <method> ||  --throttling <method>     { Throttling Method }

-p <path>   ||  --path <path>             { The location of output file }

-f <name>   ||  --file-name <name>        { The name of output file }

-o <format> ||  --output-format <format>  { The output format }

-n <number> ||  --number <number>         { Number of workers }

-l          ||  --log-mode                { Log progress of process }

-e          ||  --error-log-file          { Output error log file}

• Give your own audits config by -a or --audits-config:

$ lighthouse-batch-parallel input.csv -a your-custom-audits.csv 

Should follow the structure as what is required.

• Throttling option -t or --throttling:

$ lighthouse-batch-parallel -t applied3G input.csv

Allowed properties are the same as here.

• Specify the path of output report file by -p or --path:

$ lighthouse-batch-parallel -p /your/path/to/output input.csv

If the option is not given, the report will be put into output folder which would be generated automatically in current working directory.

• Specify the name of output report file by -f or --file-name:

$ lighthouse-batch-parallel -f my-report.csv input.csv

If this option is not given, the name of file would be the time when report is generated. If the file format is specified here (.csv or .json), the -o option would be ignored. If both here and -o don't specify the output file format, the default would be .csv.

• Specify the output file format by -o or --output-format:

$ lighthouse-batch-parallel -o json input.csv

The available formats are csv and json.

If this option is not given, the default would be csv.

• Have more or less worker work parallely by giving option -n or --number :

$ lighthouse-batch-parallel input.csv  
(default 1)

$ lighthouse-batch-parallel -n 9 input.csv

• Log the progress in the console by -l or --log-mode :

$ lighthouse-batch-parallel -l input.csv

• Generate the error log file by -e or --error-log-file :

$ lighthouse-batch-parallel -e input.csv

The report will be put into errorLog folder which would be generated automatically in current working directory.