-
Notifications
You must be signed in to change notification settings - Fork 9.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add html report overview writeup #5059
Conversation
docs/report.md
Outdated
|
||
Lighthouse has an indepedent report renderer that takes the **LHR** (Lighthouse Result object) and creates a DOM tree of the report. It's all done client-side. | ||
|
||
Example standalone HTML report, delivered by the CLI: https://crazy-roll.surge.sh/dbwtester.html _(View the source! 📖)_ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should we point to viewer or post something on gh-pages?
docs/report.md
Outdated
|
||
### Report Renderer components | ||
|
||
1. [`report-generator`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
single space after period
docs/report.md
Outdated
### Report Renderer components | ||
|
||
1. [`report-generator`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it | ||
- It runs natively in Node.js, but can run in the browser after a compile step applied during our bundling pipeline. That compile step uses a browserify transform that replaces any `fs.readFileSync()` calls to with the file content as strings. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
compile step is applied
docs/report.md
Outdated
### Report Renderer components | ||
|
||
1. [`report-generator`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it | ||
- It runs natively in Node.js, but can run in the browser after a compile step applied during our bundling pipeline. That compile step uses a browserify transform that replaces any `fs.readFileSync()` calls to with the file content as strings. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
calls to with the file content as strings
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
calls to fs
no?
docs/report.md
Outdated
1. [`lighthouse-core/report/html/`](https://github.com/GoogleChrome/lighthouse/tree/master/lighthouse-core/report/html) has everything required to create the HTML report | ||
1. [`lighthouse-core/report/html/renderer`](https://github.com/GoogleChrome/lighthouse/tree/master/lighthouse-core/report/html/renderer) are all client-side JS files and transform an LHR object into a report DOM tree. They are all executed within the browser. | ||
1. The DOM report is kicked off clientside with these four lines: | ||
https://github.com/GoogleChrome/lighthouse/blob/63c999789dc08b9a3b56b22f25f478f13050da29/lighthouse-core/report/html/report-template.html#L27-L31 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
shorter link like is done at the start of the above bullet points? (unfortunately looks like the github auto-quoting doesn't work in md files)
docs/report.md
Outdated
|
||
|
||
### Data Hydration | ||
`innerHTML` is avoided, the renderer relies on basic `createElement` as well as multiple components defined in `<template>` tags that are added via [`document.importNode()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/importNode) and filled in via the `querySelector`/`textContent` combo. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"is avoided" -> "is not used", just to be concrete about it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
,
-> ;
:D
docs/report.md
Outdated
|
||
1. _LH Chrome Extension_: It [creates the HTML as the runner finishes up](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-core/runner.js#L137-L138) and transforms it [into a blob url in the background page](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-extension/app/src/lighthouse-ext-background.js#L129-L143). | ||
1. _LH CLI_: It [creates the HTML as the runner finishes up](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-core/runner.js#L137-L138) and [saves it to disk](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-cli/printer.js#L71-L92). | ||
1. _Chrome DevTools Audits Panel_: It gets the `renderer` files rolled into the Chromium repo, and they execute within the DevTools context. The audits panel [receives the LHR object within a WebWorker](https://github.com/ChromeDevTools/devtools-frontend/blob/master/front_end/audits2/Audits2ProtocolService.js#L27-L35), `postMessage`'s it back to the page, and runs [the renderer within DevTools UI](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L519-L542), making a few upgrades ([one](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L570-L583), [two](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L596-L637)) and [simplifications](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L275-L304). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
maybe "The renderer
files are rolled into the Chromium repo, and they execute within the DevTools context. The audits panel receives the LHR object from a WebWorker...."
also not sure what "page" is referring to in "postMessage's it back to the page". Is it the panel?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah page -> panel might be a little more clear
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
just had to tagalong to brendan's comments :)
docs/report.md
Outdated
### Report Renderer components | ||
|
||
1. [`report-generator`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it | ||
- It runs natively in Node.js, but can run in the browser after a compile step applied during our bundling pipeline. That compile step uses a browserify transform that replaces any `fs.readFileSync()` calls to with the file content as strings. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
calls to fs
no?
docs/report.md
Outdated
### Report Renderer components | ||
|
||
1. [`report-generator`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it | ||
- It runs natively in Node.js, but can run in the browser after a compile step applied during our bundling pipeline. That compile step uses a browserify transform that replaces any `fs.readFileSync()` calls to with the file content as strings. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: no comma in Node.js but
docs/report.md
Outdated
|
||
|
||
### Data Hydration | ||
`innerHTML` is avoided, the renderer relies on basic `createElement` as well as multiple components defined in `<template>` tags that are added via [`document.importNode()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/importNode) and filled in via the `querySelector`/`textContent` combo. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
,
-> ;
:D
docs/report.md
Outdated
|
||
1. _LH Chrome Extension_: It [creates the HTML as the runner finishes up](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-core/runner.js#L137-L138) and transforms it [into a blob url in the background page](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-extension/app/src/lighthouse-ext-background.js#L129-L143). | ||
1. _LH CLI_: It [creates the HTML as the runner finishes up](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-core/runner.js#L137-L138) and [saves it to disk](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-cli/printer.js#L71-L92). | ||
1. _Chrome DevTools Audits Panel_: It gets the `renderer` files rolled into the Chromium repo, and they execute within the DevTools context. The audits panel [receives the LHR object within a WebWorker](https://github.com/ChromeDevTools/devtools-frontend/blob/master/front_end/audits2/Audits2ProtocolService.js#L27-L35), `postMessage`'s it back to the page, and runs [the renderer within DevTools UI](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L519-L542), making a few upgrades ([one](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L570-L583), [two](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L596-L637)) and [simplifications](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L275-L304). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah page -> panel might be a little more clear
lgtm plx :D |
[skip ci]
docs/report.md
Outdated
|
||
### Report Renderer components | ||
|
||
1. [`lighthouse-core/report/report-generator.js`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
end with .
docs/report.md
Outdated
### Report Renderer components | ||
|
||
1. [`lighthouse-core/report/report-generator.js`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it | ||
- It runs natively in Node.js but can run in the browser after a compile step is applied during our bundling pipeline. That compile step uses a browserify transform that takes any `fs.readFileSync()` calls and replaces them the stringified file content. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
replaces them with the stringified file content
docs/report.md
Outdated
|
||
1. [`lighthouse-core/report/report-generator.js`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it | ||
- It runs natively in Node.js but can run in the browser after a compile step is applied during our bundling pipeline. That compile step uses a browserify transform that takes any `fs.readFileSync()` calls and replaces them the stringified file content. | ||
1. [`lighthouse-core/report/html/`](https://github.com/GoogleChrome/lighthouse/tree/master/lighthouse-core/report/html) has everything required to create the HTML report |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
.
docs/report.md
Outdated
1. [`lighthouse-core/report/report-generator.js`](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/report/report-generator.js) is the current entry point. It compiles together the HTML string with everything required within it | ||
- It runs natively in Node.js but can run in the browser after a compile step is applied during our bundling pipeline. That compile step uses a browserify transform that takes any `fs.readFileSync()` calls and replaces them the stringified file content. | ||
1. [`lighthouse-core/report/html/`](https://github.com/GoogleChrome/lighthouse/tree/master/lighthouse-core/report/html) has everything required to create the HTML report | ||
1. [`lighthouse-core/report/html/renderer`](https://github.com/GoogleChrome/lighthouse/tree/master/lighthouse-core/report/html/renderer) are all client-side JS files and transform an LHR object into a report DOM tree. They are all executed within the browser. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
maybe
are all client-side JS files. They transform an LHR object into a report DOM tree. They are all executed within the browser.
docs/report.md
Outdated
|
||
|
||
### Data Hydration | ||
`innerHTML` is deliberated not used. The renderer relies on basic `createElement` as well as multiple components defined in `<template>` tags that are added via [`document.importNode()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/importNode) and filled in via the `querySelector`/`textContent` combo. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
deliberately
|
||
The renderer was designed to be portable across various environments. | ||
|
||
1. _LH Chrome Extension_: It [creates the HTML as the runner finishes up](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-core/runner.js#L137-L138) and transforms it [into a blob url in the background page](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-extension/app/src/lighthouse-ext-background.js#L129-L143). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
.
docs/report.md
Outdated
|
||
1. _LH Chrome Extension_: It [creates the HTML as the runner finishes up](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-core/runner.js#L137-L138) and transforms it [into a blob url in the background page](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-extension/app/src/lighthouse-ext-background.js#L129-L143). | ||
1. _LH CLI_: It [creates the HTML as the runner finishes up](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-core/runner.js#L137-L138) and [saves it to disk](https://github.com/GoogleChrome/lighthouse/blob/440155cdda377c458c0efce006bc3a69ce2a351c/lighthouse-cli/printer.js#L71-L92). | ||
1. _Chrome DevTools Audits Panel_: The `renderer` are rolled into the Chromium repo, and they execute within the DevTools context. The audits panel [receives the LHR object from a WebWorker](https://github.com/ChromeDevTools/devtools-frontend/blob/master/front_end/audits2/Audits2ProtocolService.js#L27-L35), `postMessage`'s it back to the panel, and runs [the renderer within DevTools UI](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L519-L542), making a few upgrades ([one](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L570-L583), [two](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L596-L637)) and [simplifications](https://github.com/ChromeDevTools/devtools-frontend/blob/fee00605cada877c1f8e3aae758a0f8d05b64476/front_end/audits2/Audits2Panel.js#L275-L304). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The renderer
files are?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
now it's saying that the panel gets the LHR and postmessages it to the panel :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM!
LS folks need this, so I figured why not document in the repo. ;)