Skip to content

Commit

Permalink
README: update CLI help with latest. Give common examples (#2182)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ebidel @paulirish
ebidel authored and paulirish committed May 8, 2017
1 parent 4efdd20 commit d926f32
Show file tree
Hide file tree
Showing 4 changed files with 60 additions and 40 deletions.
14 changes: 11 additions & 3 deletions lighthouse-cli/bin.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,13 @@ const cliFlags = yargs
.version(() => pkg.version)
.showHelpOnFail(false, 'Specify --help for available options')

.usage('$0 url')
.usage('lighthouse <url>')
.example('lighthouse <url> --view', 'Opens the HTML report in a browser after the run completes')
.example('lighthouse <url> --config-path=./myconfig.js', 'Runs Lighthouse with your own configuration: custom audits, report generation, etc.')
.example('lighthouse <url> --output=json --output-path=./report.json --save-assets', 'Save trace, screenshots, and named JSON report.')
.example('lighthouse <url> --disable-device-emulation --disable-network-throttling', 'Disable device emulation')
.example('lighthouse <url> --chrome-flags="--window-size=412,732"', 'Launch Chrome with a specific window size')
.example('lighthouse <url> --quiet --chrome-flags="--headless"', 'Launch Headless Chrome, turn off logging')

// List of options
.group([
Expand Down Expand Up @@ -86,7 +92,7 @@ const cliFlags = yargs
'list-trace-categories': 'Prints a list of all required trace categories and exits',
'additional-trace-categories': 'Additional categories to capture with the trace (comma-delimited).',
'config-path': 'The path to the config JSON.',
'chrome-flags': 'Custom flags to pass to Chrome.',
'chrome-flags': 'Custom flags to pass to Chrome (space-delimited). For a full list of flags, see http://peter.sh/experiments/chromium-command-line-switches/.',
'perf': 'Use a performance-test-only configuration',
'port': 'The port to use for the debugging protocol. Use 0 for a random port',
'max-wait-for-load': 'The timeout (in milliseconds) to wait before the page is considered done loading and the run should continue. WARNING: Very high values can lead to large traces and instability',
Expand Down Expand Up @@ -146,6 +152,8 @@ Example: --output-path=./lighthouse-results.html`,

return true;
})
.epilogue('For more information on Lighthouse, see https://developers.google.com/web/tools/lighthouse/.')
.wrap(yargs.terminalWidth())
.argv;

// Process terminating command
Expand Down Expand Up @@ -209,7 +217,7 @@ function getDebuggableChrome(flags: {skipAutolaunch: boolean, port: number, sele
chromeFlags: string}): Promise<ChromeLauncher> {
const chromeLauncher = new ChromeLauncher({
port: flags.port,
additionalFlags: flags.chromeFlags.split(' '),
chromeFlags: flags.chromeFlags.split(' '),
autoSelectChrome: !flags.selectChrome,
});

Expand Down
8 changes: 4 additions & 4 deletions lighthouse-cli/chrome-launcher.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,14 @@ export class ChromeLauncher {
errFile?: number
pidFile: string
startingUrl: string
additionalFlags: Array<string>
chromeFlags: Array<string>
chrome?: childProcess.ChildProcess
port: number

// We can not use default args here due to support node pre 6.
constructor(opts?: {
startingUrl?: string,
additionalFlags?: Array<string>,
chromeFlags?: Array<string>,
autoSelectChrome?: Boolean,
port?: number}) {

Expand All @@ -56,7 +56,7 @@ export class ChromeLauncher {
// choose the first one (default)
this.autoSelectChrome = defaults(opts.autoSelectChrome, true);
this.startingUrl = defaults(opts.startingUrl, 'about:blank');
this.additionalFlags = defaults(opts.additionalFlags, []);
this.chromeFlags = defaults(opts.chromeFlags, []);
this.port = defaults(opts.port, 9222);
}

Expand Down Expand Up @@ -88,7 +88,7 @@ export class ChromeLauncher {
flags.push('--disable-setuid-sandbox');
}

flags.push(...this.additionalFlags);
flags.push(...this.chromeFlags);
flags.push(this.startingUrl);

return flags;
Expand Down
8 changes: 4 additions & 4 deletions lighthouse-cli/manual-chrome-launcher.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,18 +14,18 @@ require('./compiled-check.js')('chrome-launcher.js');

const args = process.argv.slice(2);

let additionalFlags;
let chromeFlags;
let startingUrl;

if (args.length) {
additionalFlags = args.filter(flag => flag.startsWith('--'));
chromeFlags = args.filter(flag => flag.startsWith('--'));
startingUrl = args.find(flag => !flag.startsWith('--'));
}

const ChromeLauncher = require('./chrome-launcher.js').ChromeLauncher;
const {ChromeLauncher} = require('./chrome-launcher');
const chromeInstance = new ChromeLauncher({
startingUrl,
additionalFlags,
chromeFlags,
});

chromeInstance.prepare();
Expand Down
70 changes: 41 additions & 29 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,43 +44,55 @@ $ lighthouse --help
lighthouse <url>

Logging:
--verbose Displays verbose logging [boolean]
--quiet Displays no progress or debug logs [boolean]
--verbose Displays verbose logging [boolean]
--quiet Displays no progress, debug logs or errors [boolean]

Configuration:
--disable-device-emulation Disable device emulation [boolean]
--disable-cpu-throttling Disable cpu throttling [boolean]
--disable-network-throttling Disable network throttling [boolean]
--save-assets Save the trace contents & screenshots to disk [boolean]
--save-artifacts Save all gathered artifacts to disk [boolean]
--list-all-audits Prints a list of all available audits and exits [boolean]
--list-trace-categories Prints a list of all required trace categories and exits [boolean]
--config-path The path to the config JSON.
--perf Use a performance-test-only configuration [boolean]
--port The port to use for the debugging protocol. Use 0 for a
random port. [default: 9222]
--max-wait-for-load The timeout (in milliseconds) to wait before the page is
considered done loading and the run should continue.
WARNING: Very high values can lead to large traces and
instability. [default: 25000]
--save-assets Save the trace contents & screenshots to disk [boolean]
--save-artifacts Save all gathered artifacts to disk [boolean]
--list-all-audits Prints a list of all available audits and exits [boolean]
--list-trace-categories Prints a list of all required trace categories and exits [boolean]
--additional-trace-categories Additional categories to capture with the trace (comma-delimited).
--config-path The path to the config JSON.
--chrome-flags Custom flags to pass to Chrome (space-delimited). For a full list of flags, see
http://peter.sh/experiments/chromium-command-line-switches/. [default: ""]
--perf Use a performance-test-only configuration [boolean]
--port The port to use for the debugging protocol. Use 0 for a random port [default: 9222]
--max-wait-for-load The timeout (in milliseconds) to wait before the page is considered done loading and the run should continue.
WARNING: Very high values can lead to large traces and instability [default: 25000]

Output:
--output Reporter for the results, supports multiple values
[choices: "json", "html"] [default: "html"]
--output-path The file path to output the results. Use 'stdout' to write to
stdout.
--output Reporter for the results, supports multiple values [choices: "json", "html", "domhtml"] [default: "html"]
--output-path The file path to output the results. Use 'stdout' to write to stdout.
If using JSON output, default is stdout.
If using HTML output, default is a file in the working
directory with a name based on the test URL and date.
If using HTML output, default is a file in the working directory with a name based on the test URL and date.
If using multiple outputs, --output-path is ignored.
Example: --output-path=./lighthouse-results.html [default: "stdout"]
Example: --output-path=./lighthouse-results.html
--view Open HTML report in your browser [boolean]

Options:
--help Show help [boolean]
--version Show version number [boolean]
--skip-autolaunch Skip autolaunch of Chrome when accessing port 9222 fails [boolean]
--select-chrome Interactively choose version of Chrome to use when multiple
installations are found [boolean]
--help Show help [boolean]
--version Show version number [boolean]
--disable-storage-reset Disable clearing the browser cache and other storage APIs before a run [boolean]
--disable-device-emulation Disable Nexus 5X emulation [boolean]
--disable-cpu-throttling Disable CPU throttling [boolean] [default: false]
--disable-network-throttling Disable network throttling [boolean]
--skip-autolaunch Skip autolaunch of Chrome when already running instance is not found [boolean]
--select-chrome Interactively choose version of Chrome to use when multiple installations are found [boolean]
--interactive Open Lighthouse in interactive mode [boolean]

Examples:
lighthouse <url> --view Opens the HTML report in a browser after the run completes
lighthouse <url> --config-path=./myconfig.js Runs Lighthouse with your own configuration: custom audits, report
generation, etc.
lighthouse <url> --output=json --output-path=./report.json --save-assets Save trace, screenshots, and named JSON report.
lighthouse <url> --disable-device-emulation --disable-network-throttling Disable device emulation
lighthouse <url> --chrome-flags="--window-size=412,732" Launch Chrome with a specific window size
lighthouse <url> --quiet --chrome-flags="--headless" Launch Headless Chrome, turn off logging

For more information on Lighthouse, see https://developers.google.com/web/tools/lighthouse/.


```

##### Output Examples
Expand Down

0 comments on commit d926f32

Please sign in to comment.