From 3c23e975d8aa3b60a3b97da4074888a7e528008b Mon Sep 17 00:00:00 2001 From: Jonathan Lee Date: Wed, 26 Apr 2017 22:39:14 -0400 Subject: [PATCH] More updates to docs --- .../sitespeed.io/metrics/index.md | 22 ++++---- .../sitespeed.io/performance-budget/index.md | 8 +-- .../sitespeed.io/plugins/index.md | 54 ++++++++++--------- .../sitespeed.io/prepostscript/index.md | 11 ++-- 4 files changed, 48 insertions(+), 47 deletions(-) diff --git a/docs/documentation/sitespeed.io/metrics/index.md b/docs/documentation/sitespeed.io/metrics/index.md index 076049486..1a79d4594 100644 --- a/docs/documentation/sitespeed.io/metrics/index.md +++ b/docs/documentation/sitespeed.io/metrics/index.md @@ -20,12 +20,14 @@ twitterdescription: Configuring metrics to use Sitespeed.io collects a lot of metrics which are filtered before they are sent to Graphite. You can remove filters and/or add your own filters. Some sensible defaults have been set for you, if you have suggestions to change them create an [issue at Github](https://github.com/sitespeedio/sitespeed.io/issues/new). ## Summary vs pageSummary -We group the metrics in two different groups: pageSummary encapsulates the metrics for a single page. For example if we test a single page 10 times, it will have the min/median/max here for values that change. +The metrics are separated into two groups: + +The pageSummary encapsulates the metrics for a single page. For example if we test a single page 10 times, it will have the min/median/max here for values that change. The summary holds information per group, or specifically per domain. If you test ten different pages on a site (same domain), the summary of those metrics will end up here. ## List configured metrics -You can list the metrics that are configured by **\-\-metrics.filterList**. The list is dependent on which plugins you are loading, so you need to do an actual run to generate the list. The list is stored in the data folder in a file named **configuredMetrics.txt**. +You can list the metrics that are configured by **\-\-metrics.filterList**. The list is dependent on which plugins you are loading, so you will need to do an actual run to generate the list. The list is stored in the data folder in a file named **configuredMetrics.txt**. ~~~ bash $ sitespeed.io https://www.sitespeed.io --metrics.filterList @@ -94,26 +96,26 @@ $ tools/tcp-server.js $ Server listening on :::52860 ~~~ -It will output the port, so use it when you run sitespeed.io: +It will output the port, so you can then use it when you run sitespeed.io: ~~~ bash $ sitespeed.io --metrics.list https://www.sitespeed.io -n 1 --metrics.filter coach.pageSummary.advice.performance.adviceList.*.score --graphite.host 127.0.0.1 --graphite.port 52860 ~~~ -It will log all metrics you will send to Graphite. +The the previous example it will log all metrics you send to Graphite to the console. #### Example: Add all Coach advice -By default the total score for performance, accessibility and bestpractice is configured to send to Graphite. And previously we looked at sending all the score for the performance advice. If you want to send all the scores for all different advice, you can do that too, by adding all the three categories in the CLI: +By default the total score for performance, accessibility and bestpractice is configured to send to Graphite. Previously we looked at sending all the score for the performance advice. If you want to send all the scores for all advice, you can do that easily, by adding all three categories in the CLI: ~~~ bash --metrics.filter coach.pageSummary.advice.performance.adviceList.*.score coach.pageSummary.advice.bestpractice.adviceList.*.score coach.pageSummary.advice.accessibility.adviceList.*.score ~~~ #### Example: Use JSON config to pass the metrics configuration -If you have a lot of different metrics that you want to send to Graphite the command line will be overloaded. But hey, there's a solution to the problem: Use the JSON configuration option --config (read more [here]({{site.baseurl}}/documentation/sitespeed.io/configuration/#configuration-as-json)). +If you have a lot of different metrics that you want to send to Graphite the command line will be overloaded. We have a solution to the problem: Use the JSON configuration option --config (read more [here]({{site.baseurl}}/documentation/sitespeed.io/configuration/#configuration-as-json)). -If you wanna send the three coach metrics, you can add them as a config file like this and pass the filename to the --config parameter: +If you want to send the three coach metrics, you can add them as a config file like this and pass the filename to the --config parameter: ~~~ json { @@ -128,11 +130,9 @@ If you wanna send the three coach metrics, you can add them as a config file lik ~~~ ### Remove metrics -Sitespeed.io does not currently have support to remove single metrics, but you can -remove all configured metrics with the parameter value *\*-* +Sitespeed.io does not currently have support removal of a single metric, but you can +remove all configured metrics with the parameter value *\*-*. Here is an example sending only the **coach.pageSummary.advice.performance.adviceList.\*.score** metrics. ~~~ bash $ sitespeed.io --metrics.list https://www.sitespeed.io -n 1 --metrics.filter *- coach.pageSummary.advice.performance.adviceList.*.score --graphite.host 127.0.0.1 --graphite.port 52860 ~~~ - -will send only the **coach.pageSummary.advice.performance.adviceList.\*.score** metrics. diff --git a/docs/documentation/sitespeed.io/performance-budget/index.md b/docs/documentation/sitespeed.io/performance-budget/index.md index 23f6e742a..c65156202 100644 --- a/docs/documentation/sitespeed.io/performance-budget/index.md +++ b/docs/documentation/sitespeed.io/performance-budget/index.md @@ -16,11 +16,11 @@ twitterdescription: Performance budget with sitespeed.io. {:toc} ## Performance budget -Have you heard of a performance budget? If not, please go read these excellent posts by Tim Kadlec. Don't worry we will be here when you get back. [Setting a performance budget](http://timkadlec.com/2013/01/setting-a-performance-budget/) and [Fast enough](http://timkadlec.com/2014/01/fast-enough/). Also read Daniel Malls [How to make a performance budget](http://danielmall.com/articles/how-to-make-a-performance-budget/). Welcome back, let's continue the setup of sitespeed.io performance budgets. :) +Have you heard of a performance budget? If not, please go read these excellent posts by Tim Kadlec. Don't worry we will be here when you get back. [Setting a performance budget](http://timkadlec.com/2013/01/setting-a-performance-budget/) and [Fast enough](http://timkadlec.com/2014/01/fast-enough/). You should also read Daniel Malls [How to make a performance budget](http://danielmall.com/articles/how-to-make-a-performance-budget/). Welcome back, let's continue the setup of sitespeed.io performance budgets. :) ### How it works -When you run sitespeed.io configured with a budget, the script will exit with a exit status > 0 if the budget fails. It will log the budget items that are failing and the ones that are working, and create a HTML report for the budget. +When you run sitespeed.io configured with a budget, the script will exit with a exit status > 0 if the budget fails. It will log all budget items regardless if they pass or fail and generate a HTML report. The log will look something like this: @@ -37,7 +37,7 @@ The report looks like this. ![Example of the budget]({{site.baseurl}}/img/budget.png) {: .img-thumbnail} -Lets see how you configure budgets. +Now let's see how you configure budgets. ### The budget file @@ -100,7 +100,7 @@ Then run it like this: $ sitespeed.io https://www.sitespeed.io/ --budget.configPath myBudget.json -b chrome -n 11 ~~~ -And if the budget fails the exit status will be > 0. You can also choose to report the budget as JUnitXML (Jenkins) and TAP. +And if the budget fails the exit status will be > 0. You can also choose to report the budget as JUnitXML (Jenkins) or TAP. ### JUnit XML You can output a JUnit XML file from the budget result like this. diff --git a/docs/documentation/sitespeed.io/plugins/index.md b/docs/documentation/sitespeed.io/plugins/index.md index b61c035a0..09fc80cb6 100644 --- a/docs/documentation/sitespeed.io/plugins/index.md +++ b/docs/documentation/sitespeed.io/plugins/index.md @@ -15,9 +15,9 @@ twitterdescription: Create your own plugin for sitespeed.io * Lets place the TOC here {:toc} -Sitespeed.io uses a plugin architecture where you can add/remove/create your own plugins that runs additional tests on URLs or do something else with the result, like store it to a database. +Sitespeed.io uses a plugin architecture. This architecture allows you to add/remove/create your own plugins that can run additional tests on URLs or do othere things with the result, like store it to a database. -The basic you can do is list configured plugins (which are currently used), disable one of the default plugin or add/enable more plugins. +The most basic things you can do is list configured plugins (which are currently used), disable one of the default plugin, or add/enable more plugins. ## List configured plugins You can list the plugins that will be used when you do a run: @@ -26,7 +26,7 @@ You can list the plugins that will be used when you do a run: $ sitespeed.io --plugins.list https://en.wikipedia.org/wiki/Barack_Obama ~~~ -And you will get a log entry looking something like this: +And you will get a log entry that looks something like this: ~~~ ... @@ -34,37 +34,37 @@ The following plugins are enabled: assets,browsertime,coach,domains,html,screens ... ~~~ -These are the default plugins. The default plugins lives in the [plugin folder](https://github.com/sitespeedio/sitespeed.io/tree/master/lib/plugins) in the sitespeed.io source tree. That's a good start to look if you wanna build your own plugin. +The default plugins lives in the [plugin folder](https://github.com/sitespeedio/sitespeed.io/tree/master/lib/plugins). This is a good starting place to look at if you wanna build your own plugin. ## Disable a plugin -You can disable default plugins if you want. Maybe you don't want to output HTML and only want to send the data to Graphite or you don't need the screenshots. +You can disable default plugins if needed. For instance you may not want to output HTML and strictly send the data to Graphite. ~~~ bash $ sitespeed.io https://www.sitespeed.io --plugins.disable html ~~~ -If you want to disable multiple plugins: +If you want to disable multiple plugins say you don't need the html or screenshots: ~~~ bash $ sitespeed.io https://www.sitespeed.io --plugins.disable html screenshot ~~~ -And if you want to verify that it worked, add the plugins.list: +At anytime if you want to verify that disabling worked, add the plugins.list to your command: ~~~ bash $ sitespeed.io https://www.sitespeed.io --plugins.disable html screenshot --plugins.list ~~~ ## Add a plugin -You can also add a plugin. Plugins you create yourself, plugins others has created or plugins that are not enabled by default. +You can also add a plugin. This is great if you have plugins you created yourself, plugins others have created, or plugins that are not enabled by default. -There's a plugin bundled with sitespeed.io called *analysisstorer* plugin that isn't enabled by default. It stores the original JSON data from all analyzers (from Browsertime, Coach data, WebPageTest etc) to disk. You can enable it like this: +There's a plugin bundled with sitespeed.io called *analysisstorer* plugin that isn't enabled by default. It stores the original JSON data from all analyzers (from Browsertime, Coach data, WebPageTest etc) to disk. You can enable this plugin like so: ~~~ bash $ sitespeed.io https://www.sitespeed.io --plugins.load analysisstorer ~~~ -If you want to run plugins that you created yourself or shared from others, you can either install the plugin using npm (locally) and load it by name or point out the directory where the plugin lives. +If you want to run plugins that you created yourself or that are shared from others, you can either install the plugin using npm (locally) and load it by name or point out the directory where the plugin lives. ~~~ bash $ sitespeed.io https://www.sitespeed.io --plugins.load ../my/super/plugin @@ -72,10 +72,10 @@ $ sitespeed.io https://www.sitespeed.io --plugins.load ../my/super/plugin ## Plugins in Docker -If you run in Docker and you should. :-) You should mount your plugin directory as a volume. This is the recommended best practice. Practically you should clone your repo on your server and then mount it like this. +If you run in Docker and you should. You will need to mount your plugin directory as a volume. This is the recommended best practice. Practically you should clone your repo on your server and then mount it like this. ~~~ bash -docker run -v /Users/peter/git/myplugin/:/myplugin sitespeedio/sitespeed.io -b firefox --plugins.load /myplugin -n 1 https://www.sitespeed.io/ +docker run -v /Users/sitespeedio/git/myplugin/:/myplugin sitespeedio/sitespeed.io -b firefox --plugins.load /myplugin -n 1 https://www.sitespeed.io/ ~~~ If you want to create an image of sitespeedio with your plugins pre-baked for sharing you can also do so using the following Dockerfile. @@ -98,8 +98,10 @@ Finally you can run it the same way as mentioned above without the volume mount. docker run my-custom-sitespeedio firefox --plugins.load /my-custom-plugin --my-custom-plugin.option test -n 1 https://www.sitespeed.io/ ~~~ -## Create your own plugin -You can create your own plugin! Share it with others by publish it to npm or just use Github. +Pretty cool, huh? :-) + +## How to create your own plugin +First let us know about your cool plugin! Then share it with others by publish it to npm or just use Github. ### Basic structure Your plugin needs to follow this structure. @@ -137,7 +139,7 @@ module.exports = { This is the name of your plugin. You can use the name when you want to target specific options to your plugin. If you're plugin name is *browsertime* you can make sure all your options start with that name. ### open(context, options) -The open function is called once when sitespeed.io starts, it's here you can initialize whatever you need in your plugin. You will get the *context* and the *options*. +The open function is called once when sitespeed.io starts, it's in this function you can initialize whatever you need within your plugin. You will get the *context* and the *options*. The *context* holds information for this specific run that generated at runtime and looks like this: @@ -151,23 +153,23 @@ The *context* holds information for this specific run that generated at runtime } ~~~ -You can checkout the [StorageManager](https://github.com/sitespeedio/sitespeed.io/blob/master/lib/support/storageManager.js) and the [DataCollection](https://github.com/sitespeedio/sitespeed.io/blob/master/lib/support/dataCollection.js) to get a feeling of what you can do. +You can checkout the [StorageManager](https://github.com/sitespeedio/sitespeed.io/blob/master/lib/support/storageManager.js) and the [DataCollection](https://github.com/sitespeedio/sitespeed.io/blob/master/lib/support/dataCollection.js) to get a feel of what you can accomplish. -The *options* are the options that you supply in the CLI, checkout the [CLI implementation](https://github.com/sitespeedio/sitespeed.io/blob/master/lib/support/cli.js) to see all the options. +The *options* are the options that a user will supply in the CLI, checkout the [CLI implementation](https://github.com/sitespeedio/sitespeed.io/blob/master/lib/support/cli.js) to see all the options. ### processMessage(message, queue) -The processMessage function in your plugin is called for each and every message that is passed in the application. So what's a message then? Everything is message in sitespeed.io :) A message contains the following information: +The processMessage function in your plugin is called for each and every message that is passed in the application. So what's a message you may ask? Everything is a message in sitespeed.io.:) A message contains the following information: * **uuid** a unique id - * **type** the type of a message, so you as a plugin know if you are interested in this message type or not. + * **type** the type of a message, so your plugin know if it is interested in this message type or not. * **timestamp** when the message was created * **source** who created the message * **data** the data that is sent in the message * **extras** whatever extra that you wanna include in a message -When you start the application and feed it with URLs, each URL will generate a message if type URL and is sent to all configured plugins. +When you start the application and feed it with URLs, each URL will generate a message of type URL and will be sent to all configured plugins. -If you wanna catch it, you can do something like this: +If you want to catch it, you can do something like this: ~~~ switch (message.type) { @@ -177,9 +179,9 @@ switch (message.type) { } ~~~ -Then when you are finished analyzing the URL, your plugin can then send a message with the result, so other plugins can use it. +When you are finished analyzing the URL, your plugin can then send a message with the result, so other plugins can use it. -Here's a snippet of when Browsertime sends the screenshots message (the actual screenshot is in *results.screenshots*): +Here's a snippet of Browsertime sending the screenshots message (the actual screenshot is in *results.screenshots*): ~~~ const messageMaker = require('support/messageMaker'); @@ -191,7 +193,7 @@ queue.postMessage(make('browsertime.screenshot', results.screenshots, { })); ~~~ -If you wanna send messages inside your plugin, your plugin needs to depend on sitespeed and you can require the message maker like this: +If you want to send messages from within your plugin, the plugin will need to depend on sitespeed and you can use require to include the message maker like this: ~~~ const messageMaker = require('sitespeed.io/lib/support/messageMaker'); @@ -199,7 +201,7 @@ const messageMaker = require('sitespeed.io/lib/support/messageMaker'); ### close(options, errors) -When all URLs is analyzed, the close function is called once for each plugin. You can use that to store data that you collected. +When all URLs have been analyzed, the close function is called once for each plugin. You can use this function to store the data that you collected. ## What's missing -There's no way for a plugin to tell the CLI about what type of configuration/options that's needed, but there's an [issue](https://github.com/sitespeedio/sitespeed.io/issues/1065) for that. +There's no way for a plugin to tell the CLI about what type of configuration/options that are needed, but there's an [issue](https://github.com/sitespeedio/sitespeed.io/issues/1065) for that. Help us out if you have ideas! diff --git a/docs/documentation/sitespeed.io/prepostscript/index.md b/docs/documentation/sitespeed.io/prepostscript/index.md index dbfe5fa12..92e49b4f6 100644 --- a/docs/documentation/sitespeed.io/prepostscript/index.md +++ b/docs/documentation/sitespeed.io/prepostscript/index.md @@ -16,12 +16,12 @@ twitterdescription: Pre/post scripts (log in the user) {:toc} # Selenium -Before sitespeed.io loads and tests a URL you can run your own Selenium script. Maybe you want to access a URL and pre-load the cache or maybe you want to login as a user and then measure a URL. +Before sitespeed.io loads and tests a URL you can run your own Selenium script. Do you want to access a URL and pre-load the cache or maybe you want to login as a user and then measure a URL? We use the NodeJs version of Selenium, you can find the [API documentation here](http://seleniumhq.github.io/selenium/docs/api/javascript/index.html). ## Login example -Create a script where you login the user. This is an example to login the user at Wikipedia. Create a file login.js with the following. +Create a script where you login the user. The followiing is an example to login the user at Wikipedia. Start by creating a file login.js with the following. ~~~ bash module.exports = { @@ -56,7 +56,7 @@ module.exports = { }; ~~~ -Make sure to change the username & password first +Make sure to change the username & password {: .note .note-warning} Then run it like this: @@ -74,8 +74,7 @@ Checkout the magic row: var webdriver = context.webdriver; ~~~ -From the context object you get a hold of the Selenium [Webdriver object](http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index.html) so you easy can get hold of -the mechanisms for locating an element on the page. +From the context object you get a hold of the Selenium [Webdriver object](http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index.html) and the mechanisms for locating an element on the page. Note: Use the supplied *driver* object to go to a specific page. @@ -101,7 +100,7 @@ And then run it like this: $ sitespeed.io --preScript pre.js -b chrome https://www.sitespeed.io/documentation/ ~~~ -The browser will then first access https://www.sitespeed.io/, fill the cache and then go to https://www.sitespeed.io/documentation/ where we will collect all the metrics. +The browser will first access https://www.sitespeed.io/, this will fill the cache and then go to https://www.sitespeed.io/documentation/ where it will collect all the metrics. Firefox (and/or the HAR Export trigger) has a bug that reports requests in the HAR file as 200 not flagging that they are from the local browser cache. Follow the [bug here](https://github.com/sitespeedio/browsertime/issues/121). We recommend you use Chrome until this is fixed. {: .note .note-warning}