repository·main·Indexed 12 days ago
https://github.com/googlechrome/lighthouseAn automated tool for improving web page quality by analyzing web apps and pages to collect performance metrics and provide insights on developer best practices. Version 13.4.1 supports programmatic use as a Node module, CLI auditing, trace processing, and integration with Puppeteer for authenticated page testing.
lighthouse-logger is a shared logging utility class designed for use within Lighthouse and related projects. It provides a standardized way to handle logging across different modules.The Lighthouse Report Generator is the entry point for transforming a Lighthouse Result object (LHR) into human-readable or machine-readable formats. It supports generating reports in HTML, JSON, and CSV formats.
inline-fs. This step replaces fs.readFileSync() calls with the actual stringified file content to allow for file access in environments without a filesystem.Lighthouse provides several specialized guides and recipes for advanced usage:
Documentation Topics
Recipes
A Lighthouse plugin is a Node module that extends Lighthouse functionality by implementing a set of custom checks (audits) and adding them to the report as a new category. Plugins are ideal for sharing domain-specific insights via NPM and provide a semver-stable API.
Use a Plugin if you need to:
Use a Custom Config if you need to:
config.settings properties.You can run specific subsets of the Lighthouse lifecycle using the --gather-mode (-G) and --audit-mode (-A) flags. This is useful for separating the browser interaction/artifact collection phase from the analysis phase.
-G): Launches the browser, collects artifacts (traces, screenshots, etc.), and saves them to disk (defaults to ./latest-run/), then quits.-A): Skips browser interaction, loads artifacts from disk, runs audits on them, and generates a report.-GA): Performs both gathering and auditing in one run, but also saves the artifacts to disk for later use with -A.You can provide a custom directory for these artifacts by passing a path to the flag (e.g., -GA=./my-artifacts).
# 1. Collect artifacts only
lighthouse http://example.com -G
# 2. Run audits using previously collected artifacts
lighthouse http://example.com -A
# 3. Collect and save artifacts, then immediately audit
lighthouse http://example.com -GA
# 4. Use a custom directory for artifacts
lighthouse -GA=./custom-dir https://example.comLighthouse supports auditing user flows, which involves a specialized audit phase and specific configuration context. Key features introduced in version 9.5.0 include:
artifacts.json file.frame url in the gather context.logLevel to the config context.By default, Lighthouse applies network and CPU throttling:
To run Lighthouse without throttling, use the Node CLI and disable it using the --throttling.* flags.
For more details, refer to the network throttling guide.
Lighthouse can analyze trace and performance data (like .trace.json and .devtoolslog.json) collected from other tools like WebPageTest or ChromeDriver. You can provide absolute paths to these files in your configuration to perform trace-only runs.
```json
{
"settings": {
"auditMode": "/User/me/lighthouse/core/test/fixtures/artifacts/perflog/",
},
"audits": [
"user-timings",
"critical-request-chains"
],
"categories": {
"performance": {
"name": "Performance Metrics",
"description": "These encapsulate your web app's performance.",
"audits": [
{"id": "user-timings", "weight": 1},
{"id": "critical-request-chains", "weight": 1}
]
}
}
}Run with: lighthouse --config-path=config.json http://www.random.url
In version 8.0.0, the Performance Category underwent significant scoring changes to better reflect the current state of the web. These changes include:
For a detailed breakdown of how these changes affect your scores, refer to the v8.0 Performance FAQ.
The LHR (Lighthouse Result) round trip flow describes how a Lighthouse JSON report is processed through protocol buffers to ensure data integrity. The flow consists of two main stages:
lighthouse_result.proto file is compiled using protoc (e.g., --python_out) to generate the lighthouse_result.pb2 file.lhr.json is passed through proto_preprocessor.js to create lhr_processed.json, which is then processed by json_roundtrip_via_proto.py to produce the final lhr.round_trip.json.Note: During round trips, the order of JSON keys and lists may be jumbled.
Lighthouse v5.2.0 introduced Total Blocking Time (TBT) as an experimental metric. TBT serves as a companion to Time to Interactive (TTI) to help prioritize unblocking the main thread.
Note: Because it is experimental, TBT is unscored and appears only in the raw Lighthouse Result (LHR) JSON, not in the HTML report.