Add docs

.rubocop.yml

@@ -10,10 +10,13 @@ inherit_mode:
     - Exclude
 
 AllCops:
+  NewCops: enable
   TargetRubyVersion: 2.7
   Exclude:
     - 'spec/dummy/config/**/*'
     - 'spec/dummy/app/**/*'
     - 'spec/dummy/bin/**/*'
     - 'vendor/**/*'
+    - 'gemfiles/vendor/**/*'
     - 'bin/rails'
+

.rubocop_todo.yml

@@ -1,27 +1,46 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2021-09-14 13:25:06 UTC using RuboCop version 1.20.0.
+# on 2024-07-02 19:48:59 UTC using RuboCop version 1.64.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 6
-# Configuration parameters: CountAsOne.
-RSpec/ExampleLength:
-  Max: 8
+# Offense count: 11
+# Configuration parameters: EnforcedStyle, AllowedGems, Include.
+# SupportedStyles: Gemfile, gems.rb, gemspec
+# Include: **/*.gemspec, **/Gemfile, **/gems.rb
+Gemspec/DevelopmentDependencies:
+  Exclude:
+    - 'rpi_auth.gemspec'
 
 # Offense count: 1
-# Configuration parameters: Include, CustomTransform, IgnoreMethods, SpecSuffixOnly.
-# Include: **/*_spec*rb*, **/spec/**/*
-RSpec/FilePath:
-  Exclude:
-    - 'spec/rpi_auth/models/authenticatable_spec.rb'
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 23
 
 # Offense count: 7
-RSpec/MultipleExpectations:
+# Configuration parameters: CountAsOne.
+RSpec/ExampleLength:
   Max: 8
 
-# Offense count: 1
-RSpec/NestedGroups:
+# Offense count: 20
+RSpec/MultipleExpectations:
   Max: 4
+
+# Offense count: 8
+# Configuration parameters: AllowSubject.
+RSpec/MultipleMemoizedHelpers:
+  Max: 6
+
+# Offense count: 10
+# Configuration parameters: AllowedGroups.
+RSpec/NestedGroups:
+  Max: 5
+
+# Offense count: 1
+# Configuration parameters: Include, CustomTransform, IgnoreMethods, IgnoreMetadata.
+# Include: **/*_spec.rb
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/rpi_auth/models/authenticatable_spec.rb'

README.md

@@ -194,7 +194,7 @@ There are some standardised test helpers in `RpiAuth::SpecHelpers` that can be u
 * `stub_auth_for(user:)` enables the Omniauth test mode, and makes sure any auth requests succeed, returning this user.
 * `log_in(user:)` goes through the log-in process for that user, either using Capybara-style `click_on` methods, or POST'ing directly to the auth endpoint.
 
-There is also a page at `/rpi_auth/test` that has log-in and sign-up buttons.
+There is also a page at `/rpi_auth/test` that has log-in and sign-up buttons which can be navigated to as part of the test suite to avoid having to render pages, or navigate into the shadow roots.
 
 ## Troubleshooting
 

lib/rpi_auth/spec_helpers.rb

@@ -2,13 +2,15 @@
 
 module RpiAuth
   module SpecHelpers
-    def stub_auth_for(user:, id_param: :user_id)
-      OmniAuth.config.test_mode = true
-
+    # This sets up the OmniAuth mock for the given user.  It assumes the User
+    # model has an `:user_id` method which returns the users ID, but this can
+    # be changed by setting the `id_param` option.
+    def stub_auth_for(user:, id_param: :user_id) # rubocop:disable Metrics/AbcSize
       expires_in = user.respond_to?(:expires_at) ? user.expires_at.to_i - Time.zone.now.to_i : 3600
       token = user.respond_to?(:access_token) ? user.access_token : SecureRandom.hex(16)
       refresh_token = user.respond_to?(:refresh_token) ? user.refresh_token : SecureRandom.hex(16)
 
+      OmniAuth.config.test_mode = true
       OmniAuth.config.add_mock(:rpi,
                                uid: user.send(id_param),
                                credentials: {
@@ -21,10 +23,10 @@ def stub_auth_for(user:, id_param: :user_id)
     # need to have visited the page with the "Log in" link before calling this.
     # In request specs, we just post directly to `/auth/rpi`, so this can be
     # called without any prep.
-    def sign_in(user:)
+    def log_in(user:)
       stub_auth_for(user: user)
 
-      # This is a bit grotty, but see if we can call `find_link` (from Capybara,
+      # This is a bit grotty, but see if we can call `click_on` (from Capybara,
       # i.e. system specs) first, and then if that fails fall back to using
       # `post` which is available in request specs.
       if respond_to?(:click_on)

spec/dummy/spec/requests/auth_request_spec.rb

@@ -36,7 +36,7 @@
 
   describe 'GET /rpi_auth/logout' do
     it 'clears the current session and redirects to profile' do
-      sign_in(user: user)
+      log_in(user: user)
       expect(session['current_user']).not_to be_nil
       previous_id = session.id
 
@@ -51,7 +51,7 @@
       let(:return_to) { '/next/page' }
 
       it 'redirects to the correct URL' do
-        sign_in(user: user)
+        log_in(user: user)
 
         get '/rpi_auth/logout', params: { returnTo: return_to }
 
@@ -62,7 +62,7 @@
         let(:return_to) { 'https://a.bad.actor.com/bad/page' }
 
         it 'redirects to the correct URL' do
-          sign_in(user: user)
+          log_in(user: user)
 
           get '/rpi_auth/logout', params: { returnTo: return_to }
 
@@ -92,7 +92,7 @@
         let(:return_to) { '/next/page' }
 
         it 'redirects to the correct URL' do
-          sign_in(user: user)
+          log_in(user: user)
 
           get '/rpi_auth/logout', params: { returnTo: return_to }
 

spec/dummy/spec/requests/home_request_spec.rb

@@ -22,7 +22,7 @@
 
     context 'when logged in' do
       before do
-        sign_in(user: user)
+        log_in(user: user)
       end
 
       it 'displays the user ID' do

spec/dummy/spec/requests/rpi_auth_test_request_spec.rb

@@ -22,7 +22,7 @@
 
     context 'when logged in' do
       before do
-        sign_in(user: user)
+        log_in(user: user)
       end
 
       it 'displays the user ID' do

spec/dummy/spec/system/login_flow_spec.rb

@@ -49,7 +49,7 @@
 
   describe 'Logging out' do
     before do
-      sign_in(user: user)
+      log_in(user: user)
     end
 
     it do

spec/spec_helper.rb

@@ -8,8 +8,8 @@
 
 require 'pry-byebug'
 
-require_relative './support/omniauth'
-require_relative './support/request_helpers'
+require_relative 'support/omniauth'
+require_relative 'support/request_helpers'
 require 'rpi_auth/spec_helpers'
 
 ENV['RAILS_ENV'] = 'test'