diff --git a/docs/readme.md b/docs/readme.md index b6212d05dfa5..4f6d843876d2 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -68,6 +68,10 @@ const flags = {logLevel: 'info'}; await lighthouse('https://example.com', flags); ``` +## User flows and standalone modes + +For multi-step user flow reports and the three Lighthouse modes (navigation, timespan, snapshot), see [User Flows](user-flows.md). That guide also documents the standalone mode runners (`navigation`, `startTimespan`, `snapshot`) for one-shot audits without `startFlow`. + ## Configuration In order to extend the Lighthouse configuration programmatically, you need to pass the config object as the 3rd argument. If omitted, a default configuration is used. diff --git a/docs/user-flows.md b/docs/user-flows.md index 4bb807e0987d..0b9ac6f60e18 100644 --- a/docs/user-flows.md +++ b/docs/user-flows.md @@ -137,6 +137,74 @@ writeFileSync('report.html', await flow.generateReport());
+ +## Standalone mode runners + +If you only need a single navigation, timespan, or snapshot report (the Node equivalent of choosing a mode in the DevTools Lighthouse panel), you can call the top-level helpers exported from `lighthouse` directly: + +* `navigation(page, urlOrRequestor, options?)` +* `startTimespan(page, options?)` → returns `{endTimespan}` +* `snapshot(page, options?)` + +These are intentional public APIs. They are separate from the flow-attached methods on a `UserFlow` instance (`flow.navigate`, `flow.startTimespan` / `flow.endTimespan`, `flow.snapshot`). + +| Goal | Use | +| --- | --- | +| One-shot audit (DevTools-style) | `navigation`, `startTimespan`, or `snapshot` | +| Multi-step flow report | `startFlow`, then `flow.navigate` / `flow.startTimespan` / `flow.snapshot` | + +Standalone runners do **not** attach to a flow. If you call `startTimespan(page)` (or `navigation` / `snapshot`) while a `startFlow` session is open, that run will not appear in `flow.generateReport()`. To include a timespan in a flow report you must use `flow.startTimespan()` / `flow.endTimespan()`. + +Each standalone call returns a Lighthouse `RunnerResult` (`{lhr, report, artifacts}`). You can write `result.report` for HTML, `JSON.stringify(result.lhr)` for JSON (also viewable in the [Lighthouse Viewer](https://googlechrome.github.io/lighthouse/viewer/)), or pass `result.lhr` to `generateReport`. + +### Standalone timespan example + +```js +import {writeFileSync} from 'fs'; +import puppeteer from 'puppeteer'; +import {startTimespan, generateReport} from 'lighthouse'; + +const browser = await puppeteer.launch(); +const page = await browser.newPage(); + +await page.goto('https://example.com'); + +const timespan = await startTimespan(page); + +// Interact within the timespan (avoid hard navigations here; use navigation mode for those). +await page.type('#search', 'performance'); +await page.click('#submit'); +await page.waitForSelector('#results'); + +const result = await timespan.endTimespan(); +if (!result) throw new Error('Lighthouse failed to produce a result'); + +writeFileSync('timespan-result.json', JSON.stringify(result.lhr, null, 2)); +writeFileSync('timespan-report.html', result.report); +// Or: writeFileSync('timespan-report.html', generateReport(result.lhr)); + +await browser.close(); +``` + +### Standalone navigation and snapshot + +```js +import puppeteer from 'puppeteer'; +import {navigation, snapshot} from 'lighthouse'; + +const browser = await puppeteer.launch(); +const page = await browser.newPage(); + +const navResult = await navigation(page, 'https://example.com'); +console.log(navResult.lhr.categories.performance.score); + +await page.click('#expand-sidebar'); +const snapResult = await snapshot(page); +console.log(snapResult.lhr.categories.accessibility.score); + +await browser.close(); +``` + ## Creating a Flow