Friday, July 31, 2020

Generate Google Lighthouse Reports with Docker using PowerShell

While browsing Docker Hub, I came across this nifty Google Lighthouse Docker image (by Jay Moulin) which allows you to execute a Lighthouse audit against a given URL in a containerized application - made possible by the Google Chrome Headless Docker base image.  From a practical standpoint, this feels more reliable than running Lighthouse in the Chrome browser where extensions and other variables can easily interfere with the results of the audit. 

You can check out the Dockerfile for this image here: 

Consuming it is pretty straightforward.  With Docker installed and running while switched to Linux containers, two commands are all you need:

Additional options for the Lighthouse audit, like controlling the emulated device form factor (mobile vs. desktop), controlling the throttling method (devtools, provided, simulate), or defining specific categories (Accessibility, Best Practices, Performance, PWA, or SEO) can be included after the URL.
However, that's quite a bit of text to remember, and memorizing a bunch of Lighthouse CLI options are not something I see myself doing.  πŸ˜‹ 

BUT - we can make this tool more approachable by wrapping it in a PowerShell script. 😍

The name of the game is simplicity: execute .\LighthouseReport.ps1 from a PowerShell terminal, pass in a URL/standard Lighthouse options, and let it run. 

πŸ‘¨‍πŸ’» A Little PowerShell

In a new PowerShell file, we'll add a mandatory string parameter called $Url
We'll also include non-mandatory string parameters:
  • $FormFactor
    • Valid options for the '--emulated-form-factor=' flag are 'none', 'desktop', or 'mobile'. 

    • Default value when no parameter is provided will be 'desktop'

  • $Throttling
    • Valid options for the '--throttling-method=' flag are 'devtools', 'provided', or 'simulate'. 

    • Default value when no parameter is provided will be 'provided.'

  • $Categories (array of strings)
    • Valid options for the '--only-categories=' flag are 'accessibility', 'best-practices', 'performance', 'pwa', 'seo'. 

    • Default value when no parameter is provided will a comma-delimited string of all applicable categories 'accessibility,best-practices,performance,pwa,seo'

  • $DestinationPath
    • The local path to where the report will be 'dropped.' (used as a volume mapping to the container's '/home/chrome/reports' directory)

    • Default value when no parameter is provided will be "C:/lighthouse"

We'll add the docker pull command for femtopixel/google-lighthouse first.  During the initial execution of the script,  all required images will be downloaded from Docker Hub.  If your image becomes stale or a newer version is available, this will automatically update the image. 

Then add the docker run command with the -v flag to mount a volume to map the local $DestinationPath to the /home/chrome/reports directory on the container. Include the $URL parameter at the end, and all options following:

When the docker run command is executed, Docker will take over, and Lighthouse will begin to execute on the container. Once completed, a .html file will be available in the $DestinationPath

To take it a step further, we can open the $DestinationPath in Windows Explorer by using an Invoke-Item command:

If we want to open the .html report, we can set the PowerShell location to the $DestinationPath, followed by an Invoke-Item where we pass in Get-ChildItem latest .html file.

Simple - yet effective!

🏁 Final Script

⌨ Example Usage

Desktop form factor auditing all categories:

Desktop form factor auditing Best Practices, Performance and SEO only:

Mobile form factor auditing Performance only:


πŸ’‘ TIP: When setting a parameter (-FormFactor, -Throttling, -Categories), you can use Ctrl+Space to display valid options and hit enter to select it.

πŸ‘ Result

πŸ™Œ Feel free to grab a copy and modify it to your liking.


Post a Comment