Improve documentation on standalone mode runners

[ChristopherPHolder]

I have notices that lighthouse is exposing a method called startTimespan .

But I cant seem to find any documentation on it: user-flow docs.

I have attempted to use it but have not been successful.

This leads my to have a couple questions:

• Is it intentionally exposed?

• Is it something that a consumer of the library can use?

• Are there any docs?

[connorjclark]

ctrl+f flow.startTimespan on that page for two different examples of using timespan mode.

Are these examples sufficient to show you how to work with timespan mode?

[ChristopherPHolder]

I guess I did not explain it correctly. Sorry for that @connorjclark

of course the startTimespan has valid examples, but you are refering to this import

import { startFlow } from 'lighthouse';

const flow = startFlow(page)

await flow.startTimespan();
// Timespan Action
await flow.endTimespan();

And that one makes sense, but i can also import and use it this way.

import { startTimespan } 'lighthouse';

const timespan = await startTimespan(page);
// Timespan Action
const results = await timespan.endTimespan();

if i run this inside a flow it will not be used in the final report. example:

import { startFlow } from 'lighthouse';

const flow = startFlow(page)

const timespan = await startTimespan(page);
// Timespan Action
const results = await timespan.endTimespan();

const report = await flow.generateReport(); // This report does not include that timespan as its not part of the flow. 

[connorjclark]

oh I see. I didn't realize we expoed startTimespan directly. I think it's just for convenience if all you need is a timespan report. Is that right @adamraine ? Is it expected to not work w/ a flow (I'd assume it shouldnt work together)? We may want to document somewhere (in its jsdoc may be sufficient) or remove

[adamraine]

Yeah exposing startTimespan is intentional, but it's not a well documented feature. This is basically the node equivalent of running timespan mode in the DevTools panel.

Is it expected to not work w/ a flow (I'd assume it shouldnt work together)?

No. It won't work with a flow you need to call flow.startTimespan to get timespan results in the flow report.

We should add some better documentation here.

[ChristopherPHolder]

Thanks for the information:

I have built this small example that seems to work.

import { startTimespan } from 'lighthouse';
import { launch } from "puppeteer";
import { writeFileSync } from "fs";

const browser = await launch({headless: false});
const page = await browser.newPage();

await page.goto('https://web.dev/');

const timespan = await startTimespan(page);

await page.click('button[search-open]');
const searchBox = await page.waitForSelector('devsite-search[search-active] input');
await searchBox?.type('CLS');
await searchBox?.press('Enter');

// Ensure search results have rendered before moving on.
await page.waitForSelector('devsite-content a[href="https://web.dev/articles/cls"]');

const timespanResults = await timespan.endTimespan();

// Save results as JSON.
writeFileSync('timespan-result.json', JSON.stringify(timespanResults, null, 2));

await browser.close();

And the JSON can be viewed by uploading it in the lighthouse viewer

Is there a way to convert the results to an html result?

Should the stand alone mode runners docs be inside of the main user-flow docs or linked in a separate readme?

And i assume the docs should then include navigation, timespan and snapshot.