lighthouse-matchers 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d59475b53e41779753dc20a7d0775dc4300494da79af101d2671b235d9952192
-  data.tar.gz: 41d0d01d7494075bc18d6dc3bca107f5de9ec3400cf89eac689c8834fd24efdd
+  metadata.gz: e47d9c8b9ac4ff8fe209317f9054fafd3c5d7c81f1f241cb61be6035940ea50a
+  data.tar.gz: 6627e960001bad68703a9a0d5eb2a20691f97f137b8293fcd24f70813c1df6d9
 SHA512:
-  metadata.gz: 201ae5239f163fc312f4edb460b7e9a5969757c06b7093792b7f0ff8cff7e5baccf9ec8aa8c5ac612d537bb6a371fb605c6099d833ca7b5ed918abbde2932ede
-  data.tar.gz: 2879723cd480d9e67e2578c5e89f78e6251350cd01702a3cd7150705fdf2e3245ed9319a44b929280e65d8640a4d6508b876065f9dbb5e1bbc434149e96bfe4a
+  metadata.gz: 2628e449c6d825aea0eed45bfbd2a3e9f3c63d925495033003f4c3eae649a6a4686f72ca90e388e61131aacd893a491733ed23b4762698b21bfd8c31ef7cbb04
+  data.tar.gz: 6da50b69d8d31d21ab669c3b7e1de4d74f731af703d9bae63ee8082836fa6be0a92d53bf1a64bef0bcf21c2598edaef58f6b153f3c716da3fe3a45f753f78a26

data/.github/workflows/ci.yml

@@ -22,24 +22,35 @@ permissions:
   contents: read # to fetch code (actions/checkout)
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.2'
+        bundler-cache: true
+    - run: bundle exec rubocop
   test:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['2.5', '2.6', '2.7', '3.0', '3.1']
+        ruby-version: ['2.5', '2.6', '2.7', '3.0', '3.1', '3.2', '3.3']
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         persist-credentials: false
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with:
         cache: 'npm'
     - run: npm ci
-    - run: npm test
+    - run: bundle exec rake spec
       env:
         CI_CHROME_FLAGS: "--headless"

data/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - v*
+
+permissions:
+  contents: read # to fetch code (actions/checkout)
+
+jobs:
+  push:
+    permissions:
+      contents: write
+      id-token: write
+    if: github.repository == 'ackama/lighthouse-matchers'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@v2
+        with:
+          egress-policy: audit
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+      - uses: rubygems/release-gem@v1

data/CHANGELOG.md

@@ -6,6 +6,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2025-08-13
+### Added
+- Write audit results to disk on failure so they can be viewed using the browser viewer ([#68](https://github.com/ackama/lighthouse-matchers/pull/68))
+
+### Changed
+- Prefix warnings with the full example description ([#69](https://github.com/ackama/lighthouse-matchers/pull/69))
+
+## [1.2.0] - 2024-07-13
+### Changed
+- Raise an explict error when the audit category is not found ([#56](https://github.com/ackama/lighthouse-matchers/pull/56))
+- Print run warnings from Lighthouse ([#55](https://github.com/ackama/lighthouse-matchers/pull/55))
+
 ## [1.1.0] - 2023-08-27
 ### Changed
 - Only run audits for categories that are requested to improve performance ([#28](https://github.com/ackama/lighthouse-matchers/pull/28))

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lighthouse-matchers (1.1.0)
+    lighthouse-matchers (1.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -14,7 +14,7 @@ GEM
     rainbow (3.0.0)
     rake (13.0.1)
     regexp_parser (2.2.0)
-    rexml (3.2.5)
+    rexml (3.3.9)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
@@ -43,7 +43,7 @@ GEM
       parser (>= 3.0.1.1)
     ruby-progressbar (1.11.0)
     unicode-display_width (2.1.0)
-    webrick (1.7.0)
+    webrick (1.8.2)
 
 PLATFORMS
   ruby

data/README.md

@@ -103,6 +103,9 @@ All configuration keys are accessible against the `Lighthouse::Matchers` object.
 * **`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`).
+* **`results_directory`:** Directory to write lighthouse results on failure
+  * Defaults to `<RSpec.configuration.default_path>/lighthouse` if `RSpec` is defined, otherwise a temporary directory prefixed with `lighthouse-matchers-`
+  * For Rails applications, we recommend setting this to `Rails.root.join('/tmp/lighthouse')` in your `rails_helper.rb`
 
 ## Compatibility
 
@@ -121,6 +124,12 @@ for detailed instructions.
 
 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
 
 lighthouse-matchers is copyright © 2019 Ackama Group Ltd.

data/lib/lighthouse/audit_service.rb

@@ -5,6 +5,8 @@ require 'stringio'
 
 # Compares a url's actual score to the expected score.
 class AuditService
+  class Error < StandardError; end
+
   def initialize(url, audit, score)
     @url = url
     @audit = audit
@@ -20,11 +22,29 @@ class AuditService
   end
 
   def measured_score
-    results.dig('categories', @audit.to_s, 'score') * 100
+    category['score'] * 100
+  end
+
+  def run_warnings
+    results['runWarnings']
+  end
+
+  def results
+    @results ||= JSON.parse(output)
   end
 
   private
 
+  def category
+    category = results.dig('categories', @audit.to_s)
+
+    if category.nil?
+      raise Error, "Category '#{@audit}' not found in Lighthouse results - maybe it was removed?"
+    end
+
+    category
+  end
+
   def opts
     "'#{@url}'".tap do |builder|
       builder << ' --quiet'
@@ -38,8 +58,4 @@ class AuditService
   def output
     @output ||= @runner.call("#{@cmd} #{opts}")
   end
-
-  def results
-    JSON.parse(output)
-  end
 end

data/lib/lighthouse/matchers/rspec.rb

@@ -4,22 +4,35 @@ require 'rspec/expectations'
 require 'lighthouse/matchers'
 require 'lighthouse/audit_service'
 require 'json'
+require 'digest'
+require 'fileutils'
 
-RSpec::Matchers.define :pass_lighthouse_audit do |audit, args = {}|
+RSpec::Matchers.define :pass_lighthouse_audit do |audit, args = {}| # rubocop:disable Metrics/BlockLength
   score ||= args.fetch(:score, Lighthouse::Matchers.minimum_score)
 
   match do |target|
-    audit_service = AuditService.new(url(target), audit, score)
+    @audit_service = AuditService.new(url(target), audit, score)
 
-    @measured_score = audit_service.measured_score
+    @audit_service.run_warnings.each do |warning|
+      RSpec.configuration.reporter.message(
+        "#{RSpec.current_example.full_description}: [lighthouse] #{warning}"
+      )
+    end
 
-    audit_service.passing_score?
+    @measured_score = @audit_service.measured_score
+
+    @audit_service.passing_score?
   end
 
   failure_message do |target|
     <<~FAIL
       expected #{url(target)} to pass Lighthouse #{audit} audit
       with a minimum score of #{score}, but only scored #{@measured_score.to_i}
+
+      Full report:
+       #{save_audit_results}
+
+       To view this report, load this file into https://googlechrome.github.io/lighthouse/viewer/
     FAIL
   end
 
@@ -28,4 +41,15 @@ RSpec::Matchers.define :pass_lighthouse_audit do |audit, args = {}|
   def url(target)
     target.respond_to?(:current_url) ? target.current_url : target
   end
+
+  def save_audit_results
+    body = JSON.pretty_generate(@audit_service.results)
+
+    path = File.join(Lighthouse::Matchers.results_directory, "#{Digest::SHA1.hexdigest(body)}.json")
+
+    FileUtils.mkdir_p(Lighthouse::Matchers.results_directory)
+    File.write(path, body)
+
+    path
+  end
 end

data/lib/lighthouse/matchers/version.rb

@@ -2,6 +2,6 @@
 
 module Lighthouse
   module Matchers
-    VERSION = '1.1.0'
+    VERSION = '1.3.0'
   end
 end

data/lib/lighthouse/matchers.rb

@@ -9,7 +9,7 @@ module Lighthouse
   module Matchers # rubocop:disable Style/Documentation
     class Error < StandardError; end
     class << self
-      attr_writer :minimum_score, :lighthouse_cli, :runner, :chrome_flags
+      attr_writer :minimum_score, :lighthouse_cli, :runner, :chrome_flags, :results_directory
       attr_accessor :remote_debugging_port
 
       def minimum_score
@@ -31,6 +31,14 @@ module Lighthouse
         @chrome_flags.map { |f| "--#{f}" }.join(' ')
       end
 
+      def results_directory
+        @results_directory ||= if defined?(RSpec)
+                                 File.join(RSpec.configuration.default_path, 'lighthouse')
+                               else
+                                 Dir.mktmpdir('lighthouse-matchers-')
+                               end
+      end
+
       private
 
       def guess_lighthouse_cli