Lighthouse Matchers

Lighthouse Matchers provides single-line RSpec matchers for expectations against the result of Lighthouse audit checks.

Getting Started

RSpec

Start by including the gem in your Gemfile:

group :test do
  gem 'lighthouse-matchers'
end

Next, you need to require the matchers in your spec_helper.rb or rails_helper.rb:

require "lighthouse/matchers/rspec"

You also need to have the lighthouse CLI tool available. The matchers will automatically pick up the tool if you have added it to your $PATH, or if you have installed the tool using:

npm install --save-dev lighthouse
yarn add --dev lighthouse

If you have the lighthouse CLI tool installed, but available elsewhere on your system, you can set the location manually. See Configuration for further instructions.

The matchers are now available to use. If you wish for your Lighthouse audits to use the same Chrome session as your system tests (e.g. the page requires a logged-in user), then you should change the definition of your system test Chrome browser arguments to define a "remote debugging port". Without defining this port, The lighthouse audit tool cannot connect to your existing Chrome session and will begin a new one, clearing any session information.

An example of such a configuration is:

# spec/spec_helper.rb

Capybara.register_driver :headless_chrome do |app|
  capabilities = Selenium::WebDriver::Remote::Capabilities.chrome(
    chromeOptions: { args: %w(headless remote-debugging-port=9222) }
  )

  Capybara::Selenium::Driver.new app,
    browser: :chrome,
    desired_capabilities: capabilities
end

Capybara.javascript_driver = :headless_chrome
Lighthouse::Matchers.remote_debugging_port = 9222

Test::Unit

Test::Unit support is planned and is coming soon!

Matchers

`pass_lighthouse_audit`

This matcher accepts an optional audit type, and minimum score. If no audit type is passed in, then all audits are run. If a minimum score is not provided, then the score defined in Lighthouse::Matchers.minimum_score is used. The default value of this attribute is 100 - i.e. the audit must pass entirely.

Examples

Assert that a URL fully passes all audits: it { expect("http://mysite.com").to pass_lighthouse_audit }
Assert that a Capybara page object passes a performance audit only: it { expect(page).to pass_lighthouse_audit(:performance) }
Assert that a Capybara page object passes all audits with a minimum score of 60: it { expect(page).to pass_lighthouse_audit(score: 60) }
Assert that a URL passes the PWA audit with a minimum score of 90: it { expect("http://pwa.mysite.com").to pass_lighthouse_audit(:pwa, score: 90) }

Configuration

All configuration keys are accessible against the Lighthouse::Matchers object. Configuration options include:

remote_debugging_port: If defined, Lighthouse will connect to this Chrome debugging port. This allows the audit to run in the same context as the Chrome session that created the port (for example, in Capybara, this would be the current state of the page under test). This setting is useful for running a Lighthouse audit against the current state of a page, rather than it's initial load state. This setting must match up with the remote debugging port that has been configured for the Chrome browser instance if Selenium webdrivers are being used.
lighthouse_cli: The path to the Lighthouse CLI tool. By default, we will check $PATH and node_modules/.bin/ for the CLI. This setting can be used if the Lighthouse tool is installed in a non-standard location.
minimum_score: The default minimum score that audits must meet for the matcher to pass. The default value of this configuration setting is '100' - e.g. audits must fully comply to pass.
chrome_flags: Any additional flags that should be passed to Chrome when Lighthouse launches a browser instance. As an example, running Lighthouse in Docker requires the normal headless Chrome flags (--headless, --no-sandbox) for Chrome to successfully start. Chrome flags can either be specified as an array (["headless", "no-sandbox"]) or as a string (--headless --no-sandbox).

Compatibility

Lighthouse Matchers is tested and supported against Ruby 2.0+ and RSpec 3.x.
The lighthouse CLI tool must be installed for these matchers to function.
The capybara gem is required to make assertions by passing in a Capybara::Session.

Contributing

Contributions are welcome. Please see the contribution guidelines for detailed instructions.

Versioning

This gem endeavours to follow Semantic Versioning 2.0 as defined at https://semver.org/.

Releasing

Releases are done automatically by GitHub Actions when a new tag is pushed to the repository.

To release a new version, create a pull request updating the "Unreleased" section of CHANGELOG.md file to reflect the upcoming version and expected release date, and to update the version number in lib/lighthouse/matchers/version.rb. Once the pull request is merged, create a new tag in the format vX.Y.Z, which will trigger GitHub Actions to publish the new version to RubyGems.

License

About Ackama

Lighthouse Matchers is created and maintained by Ackama Group using our investment time scheme. We are passionate about using and contributing back to the open source community, and are available for hire.