CI
Using the Unlighthouse CI helps you to avoid regressions on your entire sites Google Lighthouse issues.
Install
Unlighthouse aims to keep the installation size small, for this reason it depends natively on your locally installed chrome.
To use Unlighthouse in a CI context, you'll need to install puppeteer alongside the cli.
npm install -g @unlighthouse/cli puppeteer
# yarn global add @unlighthouse/cli puppeteer
# pnpm install -g @unlighthouse/cli puppeteer
Usage
Reporting
You may want to generate reports that can be consumed by other tools. To do you can use the reporter options:
json
- A simple JSON report which contains the URL and top level scores. This is the default.jsonExpanded
- A full JSON report which contains the URL, score, metric and category breakdowns.csv
- A simple CSV report which contains the URL and score.csvExpanded
- A full CSV report which contains the URL, score, metric and category breakdowns.false
- Don't generate a report.
You can specify the reporter option with the --reporter
flag or the ci.reporter
config option.
# Run the CI with an expanded JSON report
unlighthouse-ci --site <your-site> --reporter jsonExpanded
export default {
ci: {
reporter: 'jsonExpanded'
}
}
Budget assertions
Unlighthouse simplifies budget assertions. You can provide a single budget number which will be used to validate all pages and on all selected categories.
# Run the CI with a budget, will fail if any pages report any category less than 50
unlighthouse-ci --site <your-site> --budget 50
Alternatively, you can provide a configuration file with a list of budgets for each category.
export default {
site: 'https://example.com',
ci: {
budget: {
'performance': 50,
'accessibility': 100,
'best-practices': 90,
'seo': 90,
}
}
}
# Run in the directory the unlighthouse.config.ts is in
unlighthouse-ci
Build static report
Examples
Pass the --build-static
flag to the binary to generate the static files needed to host the report.
# NPM
unlighthouse-ci --site harlanzw.com --debug --build-static
This will generate files in your outputPath
(.unlighthouse
by default).
You can upload the directory client
to a static host from there.
Configuration
Configuring the CLI can be done either through the CI arguments or through a config file.
CI Options
Options | |
---|---|
-v, --version | Display version number. |
--site <url> | Host URL to scan. |
--root <path> | Define the project root. |
--config-file <path> | Path to config file. |
--output-path <path> | Path to save the contents of the client and reports to. |
--budget <number> | Budget (1-100), the minimum score which can pass. |
--reporter <reporter> | Which reporter to use. Options are csv, json, csvExpanded, jsonExpanded. |
--build-static | Build a static website for the reports which can be uploaded. |
--cache | Enable the caching. |
--no-cache | Disable the caching. |
--throttle | Enable the throttling. |
--samples | Specify the amount of samples to run. |
--urls | Specify explicit relative URLs as a comma-separated list. |
--router-prefix | The URL path prefix for the client and API to run from. |
--enable-javascript | When inspecting the HTML wait for the javascript to execute. Useful for SPAs. |
--disable-javascript | When inspecting the HTML, don't wait for the javascript to execute. |
--enable-i18n-pages | Enable scanning pages which use x-default. |
--disable-i18n-pages | Disable scanning pages which use x-default. |
-d, --debug | Debug. Enable debugging in the logger. |
-h, --help | Display available CLI options |
Config File
If you want to configure Unlighthouse, you can create a unlighthouse.config.ts
file in your cwd.
export default {
site: 'example.com',
debug: true,
scanner: {
device: 'desktop'
}
}
See the Configuration section for more details and the guides.
Github Actions & Netlify Example
This example is for Github Actions and deploys a static client build to Netlify.
name: Assertions and static report
on:
workflow_dispatch:
jobs:
demo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Install Dependencies
run: npm install -g @unlighthouse/cli puppeteer netlify-cli
- name: Unlighthouse assertions and client
run: unlighthouse-ci --site <your-site> --budget 75 --build-static
- name: Deploy
run: netlify deploy --dir=.unlighthouse --prod --message="New Release Deploy from GitHub Actions"
env:
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}