perfrunner

# Perfrunner [![Build Status](https://travis-ci.org/Drag13/perfrunner.svg?branch=master)](https://travis-ci.org/Drag13/perfrunner) Perfrunner - performance testing tool for websites and web applications. Tracks your application performance with Performance Events and visualize the progress. Supports various predefined network conditions, CPU throttling, cache. Supports different output - [HTML](#html), [CSV](#csv), [JSON](#json). Uses multiple reruns for better precision. Tracks: - First Contentful Paint - Largest Contentful Paint - Layout duration time - Script duration time - Resources size (js, css, img, fonts) - And much more! ## Example ```cmd npx perfrunner drag13.io ``` ![default-html-reporter-example-angular-react-vue](https://raw.githubusercontent.com/Drag13/perfrunner/master/packages/perfrunner-cli/docs/default-html-reporter-example-angular-react-vue.PNG) It's just an example, please don't consider to take framework depending on this chart :) ## Installation To save it into your project: ```cmd npm i perfrunner -D ``` For one-time usage: ```cmd npx perfrunner https://drag13.io ``` ## Default options - Network:**original**/ **fast3g** - Cache: **false** - Runs: **3** - Reporter: **html** - Throttling: **2** ## All options | Command | Alias | Description | Default value | IsRequired | | --------------------- | ----- | ---------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------- | | | | Run tests using perfrunner.json config file | | Optional | | --cache | -C | Using browser cahce. Mutliple values supported. <`true`/`false`> | `false` | Optional | | --chrome-args | - | Additional arguments to pass to the browser instance. Should be passed using camelCase style like: `"noSandbox"` | `undefined` | Optional | | --comment | - | Provide additional information about test. May be used from reporter | `undefined` | Optional | | --executable-path | -E | Sets path to the Chrome instance | `undefined` | Optional | | --ignore-default-args | - | Ignore defaultArgs for launching Chromium | `false` | Optional | | --init | - | Creates perfrunner.json config file, requires URL as a parameter | `undefined` | Optional | | --log-level | - | Setup log level: <`verbose`> | `undefined` | Optional | | --network | - | Setup network contions. Multiple values supported. <`online`/`regular4g`/`fast3g`/`hspa`/`slow3g`> | `online`,`fast3g` | Optional | | --no-headless | - | Disables headless mode | `false` | Optional | | --purge | - | Remove old data before the test run | `false` | Optional | | --reporter | - | Specify reporter | `html` | Optional | | --report-only | - | Skips profiling session and only generates report | `false` | Optional | | --runs | -R | Number of runs you want to be performed | `3` | Optional | | --test-name | - | Name of the test run. Will be used to name testRun folder and grouping results | `undefined` | Optional | | --throttling | -T | CPU slowdown multiplier | `2` | Optional | | --timeout | - | Set timeout for the single test run in miliseconds | `90_000` | Optional | | --url | - | Url to profile | This field is required | Required | | --wait-for | -W | Specify selector or time in miliseconds to wait | `undefined` | Optional | ## Reporters Supported reporters: - [HTML](#html) - renders basic metrics into HTML (FCP, LCP, DCL, Size, etc) - [MD](#md) - generates simple markdown report with First Contentful Paint and Largest Contentful Paint, DOM Interactive and some other metrics - [JSON](#json) - saves all data to json - [CSV](#csv) - saves all data to csv - [custom](#custom) - you can specify your own custom reporter To switch between reporters, use `--reporter` flag: ```cmd npx drag13.io --reporter json ``` ## HTML Generates output as an HTML file. Includes: - Performance events Chart (DOM Content Loaded, First Paint, First Contentful Paint, Largest Contentful Paint, DOM Interactive) - Default Performance Metrics Chart - Layout Duration, Recalculation Style Duration, Script Duration, Task duration - Resource Size Chart (JS, CSS ,IMG, Fonts, XHR) - Performance Marks Chart - shows performance marks from application Example: This is default reporter so you don't need to name it ```cmd npx perfrunner drag13.io ``` ## MD Generate simple markdown report, that includes: - Performance events - First Contentful Paint and Largest Contentful Paint - Performance metrics DOM Interactive, Script Duration, Layout Duration, Recalculate Style metrics. **Example:** ```cmd npx perfrunner drag13.io --reporter md ``` ## JSON Generates output as JSON file **Example:** ```cmd npx perfrunner drag13.io --reporter json ``` ## CSV Generates output as CSV file **Example:** ```cmd npx perfrunner drag13.io --reporter csv ``` ## Custom You also can use your own custom reporter ```cmd npx perfrunner https://drag13.io --reporter my-custom-reporter.js ``` where reporter should looks like: ```js module.exports = { generateReport: (data, args) => console.log(outputFolder, JSON.stringify(data), args), defaultReportName: 'reporter.txt', }; ``` ## Config file Config file supports additional features: - Testing multiple plages - Network customization - Executing post loading script ### OnAfterPageLoaded To run script after it was loaded, you need to: - Create new file on the root of the project using `module.exports = function` notation - Set `onAfterPageLoadedScript` property to "./YOUR-FILE-NAME.js" Example: ```js module.exports = async function () { console.log('start'); return new Promise((r) => setTimeout((x) => (console.log('end'), r()), 3000)); }; ``` The script will beexecuted after page loaded. If the script is async - page will wait till completion ## Troubleshooting Internally, perfrunner uses [puppeteer](https://github.com/puppeteer/puppeteer), so please check [this](https://github.com/puppeteer/puppeteer/blob/master/docs/troubleshooting.md) page for troubleshooting. Perfrunner supports passing chromeArgs and ignoreDefaults flags for better control from your side: ```cmd npx perfrunner https://drag13.io --ignore-default-args --chrome-args noSandbox ``` You also can use Perfrunner without headless mode ```cmd npx perfrunner https://drag13.io --no-headless ``` If nothing helps, try to use `--executable-path` option ```cmd npx perfrunner https://drag13.io -E "Path\To\chrome.exe" ``` ## What next For the next updates, please check the [project](https://github.com/Drag13/perfrunner/projects/1). It's not very well described but might give you an idea of what is planned. ## More details Here you can find an [introduction article about the Perfrunner](https://drag13.io/posts/perfrunner-intro/index.html).