with_clues 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e8a1a2ede55c2de31c9a7a7e53a576b4a52dd08001b87a9406e8b9a16fa5495
-  data.tar.gz: 7e75e12ebe1d192c74813521f4800d2e70dd2641e1c8e70f5cda563fea700100
+  metadata.gz: 270e2b6f2af29d8d7871cba1103db16ec84efd97380acb4592b094729adfb994
+  data.tar.gz: 22de0039993571e0a491cbe9ec5d1b53021d184793d99bfc47ffb34d64ca833a
 SHA512:
-  metadata.gz: 2c3722af382010534c4020a70b17ff7c6907c101fc0f6159758193a8152b30850a0b208dcfd6a94d1128275b8026c524bad9a2e4cac55bd292cb4c4bc9dc0645
-  data.tar.gz: c90b2558520118f6617db83b2a3a48317ee51a03bfd01fc3eec9a726f6e4b5aea34fccc03cae5d74c03aed117eefdf8b39942084f59eed2ecadcb3784954907a
+  metadata.gz: f019bd0a5354f762b4a7304d88509054fe53078528c188e8186aa8af134ff40d99042b0c3556ea2c2497317e0d899e764a6649e78f22ed1aea53e5301ee83c6f
+  data.tar.gz: d106562538a1cd625d422e1e500aa34564c5f1c97bfeea30fa6083c7e7f1b99d4addf59f7046c29575122f0b43a15c61b7efefc6fba16ef8a0aeec0107b15148

data/CHANGELOG.md

@@ -0,0 +1 @@
+See [https://github.com/sustainable-rails/with\_clues/releases](https://github.com/sustainable-rails/with_clues/releases)

data/README.md

@@ -107,13 +107,15 @@ There are three clues included:
 `with_clues` is intended as a diagnostic tool you can develop and enhance over time.  As your team writes more code or develops
 more conventions, you can develop diagnostics as well.
 
-To add one, create a class that implements `dump(notifier, context:)`:
+To add one, create a class that implements `dump(notifier, context:)` or `dump(notifier, context:, page:)`:
 
 * `notifier` is a `WithClues::Notifier` that you should use to produce output:
   * `notify` - output text, preceded with `[ with_clues ]` (this is so you can tell output from your code vs from `with_clues`)
   * `blank_line` - a blank line (no prefix)
   * `notify_raw` - output text without a prefix, useful for removing ambiguity about what is being output
 * `context:` the context passed into `with_clues` (nil if it was omitted)
+* `page:` If `dump` requires this keyword, your clue will only be used in a browser context when the Capybara `page` object is available.
+In that case, that is what is passed in.
 
 For example, suppose you want to output information about an Active Record like so:
 
@@ -153,6 +155,9 @@ WithClues::Method.use_custom_clue ActiveRecordClues
 
 You can use multiple clues by repeatedly calling `use_custom_clue`
 
+Note that if your clue implements the three-arg version of `dump` ( `dump(notifier, context:, page:)` ), it will *only* be used when in
+a context where Capybara's `page` element in in play.
+
 ## Developing
 
 * Get set up with `bin/setup`

data/lib/with_clues/browser_logs.rb

@@ -6,24 +6,35 @@ module WithClues
         return
       end
       if page.driver.respond_to?(:browser)
-        if page.driver.browser.respond_to?(:manage)
-          if page.driver.browser.manage.respond_to?(:logs)
-            logs = page.driver.browser.manage.logs
-            browser_logs = logs.get(:browser)
-            notifier.notify "BROWSER LOGS {"
-            browser_logs.each do |log|
-              notifier.notify_raw log.message
-            end
-            notifier.notify "} END BROWSER LOGS"
-          else
-            notifier.notify "NO BROWSER LOGS: page.driver.browser.manage #{page.driver.browser.manage.class} does not respond to #logs"
+        logs = locate_logs(page.driver.browser, notifier: notifier)
+        if !logs.nil?
+          browser_logs = logs.get(:browser)
+          notifier.notify "BROWSER LOGS {"
+          browser_logs.each do |log|
+            notifier.notify_raw log.message
           end
-        else
-          notifier.notify "NO BROWSER LOGS: page.driver.browser #{page.driver.browser.class} does not respond to #manage"
+          notifier.notify "} END BROWSER LOGS"
         end
       else
-        notifier.notify "NO BROWSER LOGS: page.driver #{page.driver.class} does not respond to #browser"
+        notifier.notify "[with_clues: #{self.class}] NO BROWSER LOGS: page.driver #{page.driver.class} does not respond to #browser"
       end
     end
+
+  private
+
+    def locate_logs(browser, notifier:)
+      if browser.respond_to?(:logs)
+        return browser.logs
+      elsif browser.respond_to?(:manage)
+        if browser.manage.respond_to?(:logs)
+          return browser.manage.logs
+        end
+        notifier.notify "[with_clues: #{self.class}] NO BROWSER LOGS: page.driver.browser.manage #{browser.manage.class} does not respond to #logs"
+      else
+        notifier.notify "[with_clues: #{self.class}] NO BROWSER LOGS: page.driver.browser #{browser.class} does not respond to #manage or #logs"
+      end
+      nil
+    end
+
   end
 end

data/lib/with_clues/method.rb

@@ -1,6 +1,7 @@
 require_relative "html"
 require_relative "browser_logs"
 require_relative "notifier"
+require_relative "private/custom_clue_method_analysis"
 
 module WithClues
   module Method
@@ -23,18 +24,25 @@ module WithClues
       @@clue_classes[:custom].each do |klass|
         klass.new.dump(notifier, context: context)
       end
-      if !defined?(page)
-        raise ex
-      end
-      notifier.notify "Test failed: #{ex.message}"
-      @@clue_classes[:require_page].each do |klass|
-        klass.new.dump(notifier, context: context, page: page)
+      if defined?(page)
+        notifier.notify "Test failed: #{ex.message}"
+        @@clue_classes[:require_page].each do |klass|
+          klass.new.dump(notifier, context: context, page: page)
+        end
       end
       raise ex
     end
 
     def self.use_custom_clue(klass)
-      @@clue_classes[:custom] << klass
+      dump_method = klass.instance_method(:dump)
+      analysis = WithClues::Private::CustomClueMethodAnalysis.from_method(dump_method)
+      if analysis.standard_implementation?
+        @@clue_classes[:custom] << klass
+      elsif analysis.requires_page_object?
+        @@clue_classes[:require_page] << klass
+      else
+        analysis.raise_exception!
+      end
     end
   end
 end

data/lib/with_clues/private/custom_clue_method_analysis.rb

@@ -0,0 +1,139 @@
+module WithClues
+  module Private
+    class CustomClueMethodAnalysis
+
+      def self.from_method(unbound_method)
+
+        params = unbound_method.parameters.map { |param_array| Param.new(param_array) }
+
+        if params.size == 2
+          two_arg_method = TwoArgMethod.new(params)
+          if two_arg_method.valid?
+            return StandardImplementation.new
+          end
+
+          return BadParams.new(two_arg_method.errors)
+
+        elsif params.size == 3
+          three_arg_method = ThreeArgMethod.new(params)
+          if three_arg_method.valid?
+            return RequiresPageObject.new
+          end
+          return BadParams.new(three_arg_method.errors)
+        end
+
+        BadParams.new([])
+      end
+
+      def standard_implementation?
+        false
+      end
+
+      def requires_page_object?
+        false
+      end
+
+      def raise_exception!
+        raise StandardError.new("Unimplemented condition found inside #from_method")
+      end
+
+      class Param
+
+        def initialize(method_param_array)
+          @type = method_param_array[0]
+          @name = method_param_array[1]
+
+        end
+
+        def required?
+          @type == :req
+        end
+        def keyword_required?
+          @type == :keyreq
+        end
+
+        def named?(*allowed_names)
+          allowed_names.include?(@name)
+        end
+        def name
+          if self.keyword_required?
+            "#{@name}:"
+          else
+            @name
+          end
+        end
+      end
+
+      class TwoArgMethod
+        attr_reader :errors
+        def initialize(params)
+          @errors = []
+          if !params[0].required?
+            @errors << "Param 1, #{params[0].name}, is not required"
+          end
+          require_keyword(2,params[1])
+        end
+
+        def valid?
+          @errors.empty?
+        end
+      private
+
+        def require_keyword(param_number, param)
+          if !param.keyword_required?
+            @errors << "Param #{param_number}, #{param.name}, is not a required keyword param"
+          end
+          if !param.named?(*allowed_names)
+            @errors << "Param #{param_number}, #{param.name}, should be named context:"
+          end
+        end
+
+        def allowed_names
+          [ :context ]
+        end
+      end
+
+      class ThreeArgMethod < TwoArgMethod
+        def initialize(params)
+          super(params)
+          require_keyword(3,params[2])
+        end
+      private
+        def allowed_names
+          [ :context, :page ]
+        end
+      end
+
+    end
+
+    class GoodParams < CustomClueMethodAnalysis
+      def raise_exception!
+        raise StandardError.new("You should not have called .exception on a #{self.class.name}")
+      end
+    end
+
+    class RequiresPageObject < CustomClueMethodAnalysis
+      def requires_page_object?
+        true
+      end
+    end
+
+    class StandardImplementation < CustomClueMethodAnalysis
+      def standard_implementation?
+        true
+      end
+    end
+
+    class BadParams < CustomClueMethodAnalysis
+      def initialize(errors)
+        @message = errors.empty? ? DEFAULT_ERROR : errors.join(", ")
+      end
+
+      DEFAULT_ERROR = "dump must take one required param, one keyword param named context: and an optional keyword param named page:"
+
+      def raise_exception!
+        raise NameError.new(@message)
+      end
+    end
+  end
+end

data/lib/with_clues/version.rb

@@ -1,3 +1,3 @@
 module WithClues
-  VERSION="1.1.0"
+  VERSION="1.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: with_clues
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Dave Copeland
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-04 00:00:00.000000000 Z
+date: 2022-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -77,6 +77,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".tool-versions"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
@@ -95,6 +96,7 @@ files:
 - lib/with_clues/html.rb
 - lib/with_clues/method.rb
 - lib/with_clues/notifier.rb
+- lib/with_clues/private/custom_clue_method_analysis.rb
 - lib/with_clues/version.rb
 - with_clues.gemspec
 homepage: https://sustainable-rails.com