with_clues 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9250314165c2529d8ac1a12ccc085a2abf2098f057b5778b1544c34dff21f9c
-  data.tar.gz: 9f737b4264d64955b17174ac44c9336d8dfa8fe79152b00cf96447b48ac15208
+  metadata.gz: 270e2b6f2af29d8d7871cba1103db16ec84efd97380acb4592b094729adfb994
+  data.tar.gz: 22de0039993571e0a491cbe9ec5d1b53021d184793d99bfc47ffb34d64ca833a
 SHA512:
-  metadata.gz: 9bf1631b167e606916d8d7e87bba3236bf829c0614c722b05fc5ac99c103cd96fb44f4c1e548bbcdbfcc71205e3661ba9d9d58f0a844cf7c004dc618174ab253
-  data.tar.gz: cdb5e7836e91a48764ad70afeeed9f1aeaf872b3cf748c4663431e522cfc7f4006a00045ab7a03b7fa905d9865f5442dba5621b0e47172fa3c18b4738d1022fe
+  metadata.gz: f019bd0a5354f762b4a7304d88509054fe53078528c188e8186aa8af134ff40d99042b0c3556ea2c2497317e0d899e764a6649e78f22ed1aea53e5301ee83c6f
+  data.tar.gz: d106562538a1cd625d422e1e500aa34564c5f1c97bfeea30fa6083c7e7f1b99d4addf59f7046c29575122f0b43a15c61b7efefc6fba16ef8a0aeec0107b15148

data/.circleci/config.yml

@@ -1,35 +1,98 @@
-version: 2.1
-orbs:
-  # See https://circleci.com/developer/orbs/orb/circleci/ruby
-  ruby: circleci/ruby@1.1.2
-jobs:                # keyword
-  test:              # my name for the job
-    parameters:      # keyword
-      ruby-version:  # my parameter name
-        type: string # type is a keyword
-    docker:          # keyword
-      - image: cimg/base:stable
-    steps:                                       # keyword
-      - checkout                                 # magic name
-      - ruby/install:                            # ruby/ is from the orb name, install is a command in that orb
-          version: << parameters.ruby-version >> # magic nonsense for param subst
-      - run:
-          command: "bin/setup"
-      - run:
-          name: "Create the test results directory because you can't just store_test_results with a file and if you do you do not get any sort of error because wtf is with this platform?"
-          command: mkdir -p /tmp/test-results
-      - run:
-          command: bin/ci /tmp/test-results/rspec_results.xml
-      - store_test_results:                      # store_test_results is magic from circle
-          path: /tmp/test-results                # path is a param to store_test_results and it must be a directory not a file
-      - store_artifacts:                         # store_artifacts is magic from circle
-          path: /tmp/test-results                # path is the param to store_artifacts
-workflows:              # keyword
-  all-rubies:           # my name for the workflow
-    jobs:               # keyword
-      - test:           # my name for the job
-          matrix:       # keyword
-            parameters: # keyword
-              # All rubies being maintained per this page:
-              # https://www.ruby-lang.org/en/downloads/branches/
-              ruby-version: [ "2.5", "2.6", "2.7", "3.0" ]
+# THIS IS GENERATED - DO NOT EDIT
+# regenerate with bin/mk_circle_config
+# You are very welcome
+---
+version: '2.1'
+jobs:
+  ruby__2_6:
+    docker:
+    - image: cimg/ruby:2.6
+    steps:
+    - checkout
+    - run:
+        name: Setup for build
+        command: bin/setup
+    - run:
+        name: Ensure bin/setup is idempotent
+        command: bin/setup
+    - run:
+        name: Create the test results dir
+        command: mkdir -p /tmp/test-results/2.6
+    - run:
+        name: Run all tests
+        command: bin/ci /tmp/test-results/2.6/rspec_results.xml
+    - store_test_results:
+        path: "/tmp/test-results/2.6"
+    - store_artifacts:
+        path: "/tmp/test-results/2.6"
+  ruby__2_7:
+    docker:
+    - image: cimg/ruby:2.7
+    steps:
+    - checkout
+    - run:
+        name: Setup for build
+        command: bin/setup
+    - run:
+        name: Ensure bin/setup is idempotent
+        command: bin/setup
+    - run:
+        name: Create the test results dir
+        command: mkdir -p /tmp/test-results/2.7
+    - run:
+        name: Run all tests
+        command: bin/ci /tmp/test-results/2.7/rspec_results.xml
+    - store_test_results:
+        path: "/tmp/test-results/2.7"
+    - store_artifacts:
+        path: "/tmp/test-results/2.7"
+  ruby__3_0:
+    docker:
+    - image: cimg/ruby:3.0
+    steps:
+    - checkout
+    - run:
+        name: Setup for build
+        command: bin/setup
+    - run:
+        name: Ensure bin/setup is idempotent
+        command: bin/setup
+    - run:
+        name: Create the test results dir
+        command: mkdir -p /tmp/test-results/3.0
+    - run:
+        name: Run all tests
+        command: bin/ci /tmp/test-results/3.0/rspec_results.xml
+    - store_test_results:
+        path: "/tmp/test-results/3.0"
+    - store_artifacts:
+        path: "/tmp/test-results/3.0"
+  ruby__3_1:
+    docker:
+    - image: cimg/ruby:3.1
+    steps:
+    - checkout
+    - run:
+        name: Setup for build
+        command: bin/setup
+    - run:
+        name: Ensure bin/setup is idempotent
+        command: bin/setup
+    - run:
+        name: Create the test results dir
+        command: mkdir -p /tmp/test-results/3.1
+    - run:
+        name: Run all tests
+        command: bin/ci /tmp/test-results/3.1/rspec_results.xml
+    - store_test_results:
+        path: "/tmp/test-results/3.1"
+    - store_artifacts:
+        path: "/tmp/test-results/3.1"
+workflows:
+  version: 2
+  all_rubies:
+    jobs:
+    - ruby__2_6
+    - ruby__2_7
+    - ruby__3_0
+    - ruby__3_1

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.1.0

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/bin/mk_circle_config

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+
+require "yaml"
+require "pathname"
+
+circle_config = {
+  "version" => "2.1",
+  "jobs" => {},
+  "workflows" => {
+    "version" => 2,
+    "all_rubies" => {
+      "jobs" => [
+      ],
+    },
+  }
+}
+
+supported_rubies = [
+  "2.6",
+  "2.7",
+  "3.0",
+  "3.1",
+]
+
+supported_rubies.each do |ruby_verison|
+
+  test_results_dir = "/tmp/test-results/#{ruby_verison}"
+  job_name = "ruby__#{ruby_verison.gsub(/\./,"_")}"
+
+  job = {
+    "docker" => [
+      {
+        "image" => "cimg/ruby:#{ruby_verison}",
+      }
+    ],
+    "steps" => [
+      "checkout",
+      {
+        "run" => {
+          "name" => "Setup for build",
+          "command" => "bin/setup",
+        }
+      },
+      {
+        "run" => {
+          "name" => "Ensure bin/setup is idempotent",
+          "command" => "bin/setup",
+        }
+      },
+      {
+        "run" => {
+          "name" => "Create the test results dir",
+          "command" => "mkdir -p #{test_results_dir}",
+        }
+      },
+      {
+        "run" => {
+          "name" => "Run all tests",
+          "command" => "bin/ci #{test_results_dir}/rspec_results.xml",
+        }
+      },
+      {
+        "store_test_results" => {
+          "path" => test_results_dir,
+        }
+      },
+      {
+        "store_artifacts" => {
+          "path" => test_results_dir,
+        }
+      },
+    ]
+  }
+  circle_config["jobs"][job_name] = job
+  circle_config["workflows"]["all_rubies"]["jobs"] << job_name
+end
+
+circle_config_file = (Pathname(__FILE__).dirname / ".." / ".circleci" / "config.yml").expand_path
+File.open(circle_config_file,"w") do |file|
+  file.puts "# THIS IS GENERATED - DO NOT EDIT"
+  file.puts "# regenerate with bin/mk_circle_config"
+  file.puts "# You are very welcome"
+  file.puts circle_config.to_yaml
+end

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/html.rb

@@ -1,14 +1,16 @@
 module WithClues
   class Html
     def dump(notifier, page:, context:)
-      if !page.respond_to?(:html)
-        notifier.notify "Something may be wrong. page (#{page.class}) does not respond to #html"
-        return
-      end
       notifier.blank_line
       notifier.notify "HTML {"
       notifier.blank_line
-      notifier.notify_raw page.html
+      if page.respond_to?(:html)
+        notifier.notify_raw page.html
+      elsif page.respond_to?(:native)
+        notifier.notify_raw page.native
+      else
+        notifier.notify "[!] Something may be wrong. page (#{page.class}) does not respond to #html or #native"
+      end
       notifier.blank_line
       notifier.notify "} END HTML"
     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.0.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.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Dave Copeland
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-03-20 00:00:00.000000000 Z
+date: 2022-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -76,6 +76,8 @@ files:
 - ".circleci/config.yml"
 - ".gitignore"
 - ".rspec"
+- ".tool-versions"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
@@ -84,6 +86,7 @@ files:
 - Rakefile
 - bin/ci
 - bin/console
+- bin/mk_circle_config
 - bin/mk_gem
 - bin/rake
 - bin/rspec
@@ -93,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
@@ -117,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
 summary: WTF does this do?