From 1e82625d48d4bf66f779b01e4a67436ea0f78bc0 Mon Sep 17 00:00:00 2001 From: Csaba Palfi Date: Mon, 27 Jan 2020 16:48:51 +0000 Subject: [PATCH] docs: better readme --- CHANGELOG.md | 1 + README.md | 92 +++++++++++++++++++++++++++++++++++----------------- 2 files changed, 64 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9223e67..9a6e492 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Fixed - docs: add CHANGELOG +- docs: better README ## [1.0.0] - 2020-01-27 ### Added diff --git a/README.md b/README.md index ceb893e..6fe5152 100644 --- a/README.md +++ b/README.md @@ -7,21 +7,22 @@ Google PageSpeed score command line toolkit Get a score and metrics via the Google PageSpeed Insights API or a local Lighthouse run. - - [Recommendations for using the score and metrics values](#recommendations-for-using-the-score-and-metrics-values) +> For recommendations about using the score check out my blog post: [What's in the Google PageSpeed score?](https://medium.com/expedia-group-tech/whats-in-the-google-pagespeed-score-a5fc93f91e91) + - [Requirements](#requirements) - [Usage](#usage) - - [`--strategy` - mobile or desktop](#--strategy---mobile-or-desktop) - - [`--runs` - multiple runs](#--runs---multiple-runs) - - [`--local` - local mode](#--local---local-mode) - - [`LANTERN_DEBUG=true` - save metrics estimation traces](#lantern_debugtrue---save-metrics-estimation-traces) - -## Recommendations for using the score and metrics values - -Check out my blog post for more details: [What's in the Google PageSpeed score?](https://medium.com/expedia-group-tech/whats-in-the-google-pagespeed-score-a5fc93f91e91) + - [multiple runs](#multiple-runs) + - [mobile or desktop strategy](#mobile-or-desktop-strategy) + - [save result JSON to disk](#save-result-json-to-disk) + - [Local mode](#local-mode) + - [set CPU slowdown multiplier](#set-cpu-slowdown-multiplier) + - [save trace & devtools log to disk](#save-trace--devtools-log-to-disk) + - [save Lantern metrics estimation traces](#save-lantern-metrics-estimation-traces) ## Requirements -The pagespeed score CLI requires **node.js 10+** (because it relies on async iterators). +* **node.js 10+** - because of [`for-await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) +* (**Google Chrome**) - in case you want to run [local mode](#local-mode) ## Usage @@ -37,9 +38,26 @@ FCP, FMP, SI, FCI, TTI are the values (in seconds) for the 5 metrics that affect Use `--help` see the list of all options. -### `--strategy` - mobile or desktop +### multiple runs + +`--runs ` overrides the number of runs (default: 1). For more than 1 runs stats will be calculated. + +``` +$ npx pagespeed-score --runs 3 https://www.google.com +name score FCP FMP SI FCI TTI +run 1 96 0.9 1.0 1.2 3.1 3.9 +run 2 96 0.9 1.0 1.0 3.1 3.7 +run 3 95 0.9 1.0 1.2 3.5 4.0 + +median 96 0.9 1.0 1.2 3.1 3.9 +stddev 0.6 0.0 0.0 0.1 0.2 0.2 +min 95 0.9 1.0 1.0 3.1 3.7 +max 96 0.9 1.0 1.2 3.5 4.0 +``` + +### mobile or desktop strategy -`--strategy ` sets the lighthouse strategy (default: mobile) +`--strategy ` sets the Lighthouse strategy (default: mobile) ``` $ npx pagespeed-score --strategy desktop https://www.google.com @@ -47,43 +65,60 @@ name score FCP FMP SI FCI TTI run 1 100 0.5 0.5 0.5 0.9 0.9 ``` -### `--runs` - multiple runs +### save result JSON to disk -`--runs ` overrides the number of runs (default: 1). For more than 1 runs stats will be calculated. +`--save-results` will save all Lighthouse results (from the PSI API response or local Lighthouse run) as JSON files. ``` -$ npx pagespeed-score --runs 3 https://www.google.com +$ npx pagespeed-score --save-results --runs=2 https://www.google.com name score FCP FMP SI FCI TTI run 1 96 0.9 1.0 1.2 3.1 3.9 run 2 96 0.9 1.0 1.0 3.1 3.7 -run 3 95 0.9 1.0 1.2 3.5 4.0 -median 96 0.9 1.0 1.2 3.1 3.9 -stddev 0.6 0.0 0.0 0.1 0.2 0.2 -min 95 0.9 1.0 1.0 3.1 3.7 -max 96 0.9 1.0 1.2 3.5 4.0 +$ ls +1-0.result.json +2-0.result.json ``` -### `--local` - local mode +## Local mode Switches to running Lighthouse locally instead of calling the PSI API. This can be useful for non-public URLs (e.g. staging environment on a private network) or debugging. To ensure the local results are close to the PSI API results this module: - * uses the same version of LightHouse as PSI (5.0.0 as of 26 June 2019) - * uses the [LightRider mobile config](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/lr-mobile-config.js) - * allows throttling of CPU with `--cpu-slowdown` (default 4x). Please note that PSI infrastructure already runs on a slower CPU (that's like a mobile device) hence the need to slow our laptops CPU down for local runs. - * you can also use the same Chrome version as PSI (76 as of 21 June 2019) by specifying CHROME_PATH + * uses the same version of LightHouse as PSI (5.6.0 as of 2020-01-27) + * uses the [LightRider mobile config](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/lr-mobile-config.js) like PSI + * allows throttling of CPU to better match PSI infrastructure limits + * you can also use the same Chrome version as PSI (78 as of 2020-01-27) by specifying CHROME_PATH (and ensuring you have the correct version installed) ```sh -CHROME_PATH="/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary" \ +CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \ npx pagespeed-score --local "" ``` Local results will still differ from the PSI API because of local hardware and network variability. +### set CPU slowdown multiplier + +`--cpu-slowdown` will allow setting CPU throttling multiplier (default 4x). Only available in [local mode](#local-mode). + +Please note that PSI infrastructure already runs on a slower CPU (that's like a mobile device) hence the need to slow our machines CPU down for local runs. + +### save trace & devtools log to disk + +`--save-assets` will save trace & devtools log to disk. Only available in [local mode](#local-mode). + +``` +$ npx pagespeed-score --save-assets --local https://www.google.com +name score FCP FMP SI FCI TTI +run 1 95 1.4 1.4 1.7 3.6 3.8 + +$ ls +1-0.devtoolslog.json +1-0.trace.json +``` -### `LANTERN_DEBUG=true` - save metrics estimation traces +### save Lantern metrics estimation traces -Setting `LANTERN_DEBUG=true` along with `--save-assets --local` will save traces for how metrics were simulated by Lantern. +Setting the `LANTERN_DEBUG=true` environment variable along with `--save-assets --local` will save traces for how metrics were simulated by Lantern. Only available in [local mode](#local-mode). ``` $ LANTERN_DEBUG=true npx pagespeed-score \ @@ -93,7 +128,6 @@ run 1 95 1.4 1.4 1.7 3.6 3.8 $ ls 1-0.devtoolslog.json -1-0.report.json 1-0.trace.json 1-optimisticFirstContentfulPaint.trace.json 1-optimisticFirstMeaningfulPaint.trace.json