hacking-tips.md

A few assorted scripts and tips to make hacking on Lighthouse a bit easier

Eng team resources

• LH Build Tracker - plotted results of build-tracker data
• LH PR Tracking - stats about open PRs, collected daily.

Evaluate Lighthouse's runtime performance

Lighthouse has instrumentation to collect timing data for its operations. The data is exposed at LHR.timing.entries. You can generate a trace from this data for closer analysis.

View example trace

To generate, run yarn timing-trace with the LHR json:

lighthouse http://example.com --output=json --output-path=lhr.json
yarn timing-trace lhr.json

That will generate lhr.json.timing.trace.json. Then, drag 'n drop that file into chrome://tracing.

Unhandled promise rejections

Getting errors like these?

(node:12732) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1) (node:12732) DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

Use --trace-warnings to get actual stack traces.

node --trace-warnings cli http://example.com

Iterating on the report

This will generate new reports from the same results json.

# capture some results first:
lighthouse http://example.com --output=json > temp.report.json

# quickly generate reports:
node generate_report.js > temp.report.html; open temp.report.html

// generate_report.js

import {ReportGenerator} from './report/generator/report-generator.js';
import results from './temp.report.json' assert { type: 'json' };
const html = ReportGenerator.generateReportHtml(results);

console.log(html);

Using Audit Classes Directly, Providing Your Own Artifacts

See gist.

Mocking modules with testdouble

We use testdouble and mocha to mock modules for testing. However, mocha will not "hoist" the mocks so any imports that depend on a mocked module need to be done dynamically after the testdouble mock is applied.

Analyzing the dependency trees can be complicated, so we recommend importing as many modules as possible (read: all non-test modules, typically) dynamically and only using static imports for test libraries (e.g. testdouble, jest-mock, assert). For example:

import jestMock from 'jest-mock';
import * as td from 'testdouble';

await td.replaceEsm('./module-to-mock.js', {
  mockedFunction: jestMock.fn(),
});

// module-to-mock.js is imported somewhere in the dependency tree of root-module.js
const rootModule = await import('./root-module.js');