Skip to content
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.

Sign up for GitHub

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

Jump to bottom

README: update CLI help with latest. Give common examples #2182

Merged
merged 2 commits into from
May 8, 2017
Merged

README: update CLI help with latest. Give common examples #2182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
913a7f2
README: update CLI help with latest. Give common examples
ebidel May 8, 2017
191a62b
Wrap output
ebidel May 8, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions lighthouse-cli/bin.ts
View file
Open in desktop
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(' '),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a breaking change and some other folks rely on the API, but @samccone's work here will break them too and hopefully have some docs so its easy to do the right thing.

all that said, +1 to this change.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, I figure we're covered under the 2.0 veil

autoSelectChrome: !flags.selectChrome,
});

Expand Down
8 changes: 4 additions & 4 deletions lighthouse-cli/chrome-launcher.ts
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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