{"id":15046905,"url":"https://github.com/ackama/lighthouse-matchers","last_synced_at":"2025-08-20T22:31:57.830Z","repository":{"id":34901954,"uuid":"188334597","full_name":"ackama/lighthouse-matchers","owner":"ackama","description":"Provides RSpec matchers for executing and evaluating Google Chrome Lighthouse audit scores","archived":false,"fork":false,"pushed_at":"2024-10-28T22:09:53.000Z","size":158,"stargazers_count":15,"open_issues_count":6,"forks_count":1,"subscribers_count":19,"default_branch":"main","last_synced_at":"2024-12-06T20:58:06.600Z","etag":null,"topics":["ackama","lighthouse-audits","lighthouse-matchers","rspec","rspec-matchers","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ackama.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-24T01:55:33.000Z","updated_at":"2024-10-28T22:09:56.000Z","dependencies_parsed_at":"2024-11-16T17:23:55.936Z","dependency_job_id":null,"html_url":"https://github.com/ackama/lighthouse-matchers","commit_stats":{"total_commits":62,"total_committers":6,"mean_commits":"10.333333333333334","dds":0.6935483870967742,"last_synced_commit":"37275d99fb8dd5cabc5477ff0030901c4ee4deed"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Flighthouse-matchers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Flighthouse-matchers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Flighthouse-matchers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Flighthouse-matchers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ackama","download_url":"https://codeload.github.com/ackama/lighthouse-matchers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230078873,"owners_count":18169306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ackama","lighthouse-audits","lighthouse-matchers","rspec","rspec-matchers","ruby"],"created_at":"2024-09-24T20:53:43.826Z","updated_at":"2025-08-20T22:31:57.823Z","avatar_url":"https://github.com/ackama.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lighthouse Matchers [![Gem Version](https://badge.fury.io/rb/lighthouse-matchers.svg)](https://badge.fury.io/rb/lighthouse-matchers) [![Maintainability](https://api.codeclimate.com/v1/badges/2f1df198307f6a0489fc/maintainability)](https://codeclimate.com/github/ackama/lighthouse-matchers/maintainability) [![Build Status](https://github.com/ackama/lighthouse-matchers/actions/workflows/ci.yml/badge.svg)](https://github.com/ackama/lighthout-matchers/actions)\n\nLighthouse Matchers provides single-line RSpec matchers for\nexpectations against the result of [Lighthouse](https://developers.google.com/web/tools/lighthouse/)\naudit checks.\n\n## Getting Started\n\n### RSpec\n\nStart by including the gem in your Gemfile:\n\n``` ruby\ngroup :test do\n  gem 'lighthouse-matchers'\nend\n```\n\nNext, you need to require the matchers in your `spec_helper.rb` or `rails_helper.rb`:\n\n``` ruby\nrequire \"lighthouse/matchers/rspec\"\n```\n\nYou also need to have the `lighthouse` CLI tool available. The matchers will automatically pick up the tool\nif you have added it to your `$PATH`, or if you have installed the tool using:\n\n* `npm install --save-dev lighthouse`\n* `yarn add --dev lighthouse`\n\nIf you have the `lighthouse` CLI tool installed, but available elsewhere on your system, you can set the location manually.\nSee [Configuration](#configuration) for further instructions.\n\nThe matchers are now available to use. If you wish for your Lighthouse audits to use the same Chrome session\nas your system tests (e.g. the page requires a logged-in user), then you should\nchange the definition of your system test Chrome browser arguments to define a \"remote debugging port\". Without\ndefining this port, The `lighthouse` audit tool cannot connect to your existing Chrome session and will begin a new\none, clearing any session information.\n\nAn example of such a configuration is:\n\n``` ruby\n# spec/spec_helper.rb\n\nCapybara.register_driver :headless_chrome do |app|\n  capabilities = Selenium::WebDriver::Remote::Capabilities.chrome(\n    chromeOptions: { args: %w(headless remote-debugging-port=9222) }\n  )\n\n  Capybara::Selenium::Driver.new app,\n    browser: :chrome,\n    desired_capabilities: capabilities\nend\n\nCapybara.javascript_driver = :headless_chrome\nLighthouse::Matchers.remote_debugging_port = 9222\n```\n\n### Test::Unit\n\nTest::Unit support is planned and is coming soon!\n\n## Matchers\n\n### `pass_lighthouse_audit`\n\nThis matcher accepts an optional audit type, and minimum score.\nIf no audit type is passed in, then all audits are run. If a minimum score is not provided, then the score defined\nin `Lighthouse::Matchers.minimum_score` is used. The default value of this attribute is 100 - i.e. the audit must pass\nentirely.\n\n#### Examples\n\n* Assert that a URL fully passes all audits:\n  ```\n  it { expect(\"http://mysite.com\").to pass_lighthouse_audit }\n  ```\n* Assert that a Capybara page object passes a performance audit only:\n  ```\n  it { expect(page).to pass_lighthouse_audit(:performance) }\n  ```\n* Assert that a Capybara page object passes all audits with a minimum score of 60:\n  ```\n  it { expect(page).to pass_lighthouse_audit(score: 60) }\n  ```\n* Assert that a URL passes the PWA audit with a minimum score of 90:\n  ```\n  it { expect(\"http://pwa.mysite.com\").to pass_lighthouse_audit(:pwa, score: 90) }\n  ```\n\n## Configuration\n\nAll configuration keys are accessible against the `Lighthouse::Matchers` object. Configuration options include:\n\n* **`remote_debugging_port`:** If defined, Lighthouse will connect to this Chrome debugging port.\n  This allows the audit to run in the same context as the Chrome session that created the port\n  (for example, in Capybara, this would be the current state of the page under test). This setting is useful for\n  running a Lighthouse audit against the _current state_ of a page, rather than it's initial load state. This setting\n  must match up with the remote debugging port that has been configured for the Chrome browser instance if\n  Selenium webdrivers are being used.\n* **`lighthouse_cli`:** The path to the Lighthouse CLI tool. By default, we will check `$PATH` and `node_modules/.bin/`\n  for the CLI. This setting can be used if the Lighthouse tool is installed in a non-standard location.\n* **`minimum_score`:** The default minimum score that audits must meet for the matcher to pass.\n  The default value of this configuration setting is '100' - e.g. audits must fully comply to pass.\n* **`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`).\n* **`results_directory`:** Directory to write lighthouse results on failure\n  * Defaults to `\u003cRSpec.configuration.default_path\u003e/lighthouse` if `RSpec` is defined, otherwise a temporary directory prefixed with `lighthouse-matchers-`\n  * For Rails applications, we recommend setting this to `Rails.root.join('/tmp/lighthouse')` in your `rails_helper.rb`\n\n## Compatibility\n\n* Lighthouse Matchers is tested and supported against Ruby 2.0+ and RSpec 3.x.\n* The `lighthouse` CLI tool must be installed for these matchers to function.\n* The [`capybara`](https://rubygems.org/gems/capybara) gem is required to make assertions\n  by passing in a `Capybara::Session`.\n\n## Contributing\n\nContributions are welcome.\nPlease see the [contribution guidelines](https://github.com/ackama/lighthouse-matchers/blob/master/CONTRIBUTING.md)\nfor detailed instructions.\n\n## Versioning\n\nThis gem endeavours to follow Semantic Versioning 2.0 as defined at https://semver.org/.\n\n## Releasing\n\nReleases are done automatically by GitHub Actions when a new tag is pushed to the repository.\n\nTo 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.\n\n## License\n\nlighthouse-matchers is copyright © 2019 Ackama Group Ltd.\nIt is free software, and may be redistributed under the terms specified in the\n[LICENSE](https://github.com/ackama/lighthouse-matchers/blob/master/LICENSE.txt) file.\n\n\n## About Ackama\n\nLighthouse Matchers is created and maintained by Ackama Group using our investment time scheme.\nWe are passionate about using and contributing back to the open source community, and are available for hire.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fackama%2Flighthouse-matchers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fackama%2Flighthouse-matchers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fackama%2Flighthouse-matchers/lists"}