topoisomerase 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b85e0899515e89773ce6a546b58fab50d4fb802d8752ca7f7836c254ea072dd5
-  data.tar.gz: 0773b1feacf0423d6e14b8793e8dee8074bfb0e4e355611a2902a9e58d7b24b8
+  metadata.gz: cf5043b7dcc2f4ba70d7a034d42683de8975d67a0d2a92d51cab289b4f0b1996
+  data.tar.gz: 8d3ceca3787dbb577e9fb3e994a4180e5d5706c7cbc7ffd37c8238a7249131ab
 SHA512:
-  metadata.gz: c3323e825f54fcb67243e7d763743ecd2337635a7c0e3a2d132e1264b7bba2c5f2c5ac21c9da1198bd8b49d3c913f6fdeb69d7697736666b0f43610e86258da8
-  data.tar.gz: d00d0ff0f245067be77d161e66e2255364993777aa878eb107057b6ea98ca4146bb427450687f4278d45352f7e75ef974e5d30076245900e85e304ef03deacd3
+  metadata.gz: b8b8ad151f546440ee8d9a64122680d0a4177fec31536d944f1c4cbefb76d4f7e79f8c2d7fe2735768dccb6c3d9867893b5d9fc3e37d704e56e2253a9eb11bff
+  data.tar.gz: f3ed5723e43bb23279e084f5efec789c6352fb610bad3eb6b6024ea730e0798ceba8df0f1738e8c6bdb8ebff059a2be836a501bd5a152770c5900b8fe291cd3e

data/.gitignore

@@ -8,6 +8,7 @@
 /tmp/
 /.idea/
 /stub/
+Gemfile.lock
 
 # rspec failure tracking
 .rspec_status

data/ChangeLog

@@ -0,0 +1,4 @@
+Version 0.1.1
+  * Use 'comments_added' to add comments matching a regular expression
+Version 0.1.0
+  * Initial working of the gem making basic stubs for dynamic methods objects inheriting from a class

data/README.md

@@ -34,7 +34,29 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+To create a stub file for a class, call the `create_stubs_for` passing that class.
+
+E.g:
+```ruby
+Topoisomerase.create_stubs_for BasicClass 
+```
+
+By default stubs will be created in the `stubs` folder. 
+This can be changed by setting the `stub_folder` variable. 
+
+```ruby
+Topoisomerase.stub_folder = 'custom_folder'
+```
+
+Note that this will by default attempt to instantiate the class with ClassName.new. If parameters are
+needed pass a block to the `create_stubs_for` as shown below. The result of the block will be the 
+instance of the class used in creating stubs.
+
+```ruby
+Topoisomerase.create_stubs_for ParameterizedClass do
+  ParameterizedClass.new 5
+end
+```
 
 ## Development
 

data/lib/topoisomerase.rb

@@ -2,49 +2,92 @@ require 'topoisomerase/version'
 require 'method_source'
 require 'fileutils'
 require 'topoisomerase/core_ext/string'
+require 'topoisomerase/comment_adder'
 
-# USE PRY instead
+# Module for parsing and creating stubs for dynamic methods
 module Topoisomerase
   @stub_folder = 'stub'
+  @comments_added = {}
+  # @return [Object] Class to create stubs for
+  @class_name = nil
 
+  # For errors raised related to Topoisomerase
   class Error < StandardError; end
-  # Your code goes here...
   class << self
     # @return [String] Folder where stubs are stored
     attr_accessor :stub_folder
+    # @todo Use custom object for this
+    # @return [Hash] Comments added to stubs generated grouped by inheriting class and then by
+    #   message, matcher patterns
+    attr_accessor :comments_added
 
+    # @todo This is only covering 'define_method'. More methods will be added later
+    # @return [Boolean] Whether method is defined dynamically
     def dynamic_method?(method)
       source_code = method.source
       source_code.strip.start_with? 'define_method'
     end
 
     # @param [Object] class_name Class to retrieve dynamic methods for
-    # @return [Hash]
+    # @return [Hash] Hash with dynamic methods as keys and values being the source, comment
+    #   and location
     def dynamic_instance_methods(class_name)
-      class_instance = if block_given?
-                         yield
-                       else
-                         class_name.new
-                       end
+      class_instance = block_given? ? yield(class_name) : class_name.new
       methods_hash = {}
       (class_instance.public_methods - Object.public_methods).each do |method|
         method_obj = class_instance.method(method)
-        if dynamic_method? class_instance.method(method)
-          methods_hash.merge!(method => { source: method_obj.source, comment: method_obj.comment,
-                                          location: method_obj.source_location })
-        end
+        next unless dynamic_method? class_instance.method(method)
+
+        methods_hash.merge!(method => { source: method_obj.source, comment: method_obj.comment,
+                                        location: method_obj.source_location,
+                                        parameters: method_obj.parameters.collect { |p| p.last.to_s } })
+        # TODO: May be worth checking required parameters and documenting non-required differently
+        # receiver - Shows object that will call method
+        # owner - shows class from which method belongs to
+        # parameters - Array with params and :req
       end
-      # methods.each do |method|
-      #   method_obj = class_instance.method(method)
-      #   methods_hash.merge(method => { source: method_obj.source, comment: method_obj.comment,
-      #                                  location: method_obj.source_location })
-      # end
       methods_hash
     end
 
+    # @return [String] Comment extracted from dynamic element
+    def extracted_comment(method_data)
+      method_data[:comment].strip.empty? ? '' : "Extracted comment #{method_data[:comment].strip}"
+    end
+
+    # @return [Boolean]
+    def match?(value_to_test, matcher_value)
+      value_to_test = value_to_test.to_s
+      case matcher_value
+      when Regexp then !value_to_test[matcher_value].nil?
+      when String then value_to_test == matcher_value
+      else
+        raise "Unknown matcher type for #{value_to_test}, value of #{matcher_value}"
+      end
+    end
+
+    # Reads from 'comments_added' variable if no comment added above dynamic method
+    # @return [String] Comment defined by 'comments_added'
+    def comment_for(method_to_stub, method_data)
+      return extracted_comment(method_data) unless comments_added[@inheriting_class]
+
+      comments_added[@inheriting_class].each do |comment_matcher|
+        matchers = comment_matcher[:matchers]
+        return ERB.new(comment_matcher[:message]).result(binding) if matchers.all? do |matcher_type, matcher_value|
+          extracted_match = case matcher_type
+                            when :method_name then match?(method_to_stub, matcher_value)
+                            when :source then match? method_data[:source], matcher_value
+                            else
+                              raise Topoisomerase::Error, "Undefined matcher #{matcher_type}"
+                            end
+          extracted_match
+        end
+      end
+      ''
+    end
+
     # Create stub file for passed in class
     # @param [Object] class_name Object to create stub file for
-    def create_stubs_for(class_name)
+    def create_stubs_for(class_name, inner_folder = nil)
       template = File.join(File.dirname(__FILE__), 'topoisomerase', 'stub_template.rb.erb')
       @class_name = class_name
       @class_instance = if block_given?
@@ -55,8 +98,9 @@ module Topoisomerase
       @dynamic_methods = dynamic_instance_methods(class_name) do
         @class_instance
       end
-      FileUtils.mkdir_p stub_folder
-      filename = File.join(stub_folder, "#{class_name.to_s.snakecase}.rb")
+      class_folder = inner_folder ? File.join(stub_folder, inner_folder) : stub_folder
+      FileUtils.mkdir_p class_folder
+      filename = File.join(class_folder, "#{class_name.to_s.snakecase}.rb")
       IO.write filename, ERB.new(File.read(template)).result(binding)
       `rubocop -a #{filename}`
     end
@@ -64,12 +108,13 @@ module Topoisomerase
     # Create stub files for each class that inherits from passed in class
     # @param [Object] inheriting_class Object to check for inheriting classes for
     def create_stubs_based_on(inheriting_class)
+      @inheriting_class = inheriting_class
       classes = ObjectSpace.each_object(Class).select { |class_name| class_name < inheriting_class }.reject do |class_name|
         class_name.to_s.split(':')[0] == inheriting_class.to_s
       end
       classes.each do |class_name|
         @class_instance = block_given? ? yield(class_name) : class_name.new
-        create_stubs_for(class_name) { @class_instance }
+        create_stubs_for(class_name, inheriting_class.to_s.snakecase) { @class_instance }
       end
     end
   end

data/lib/topoisomerase/comment_adder.rb

@@ -0,0 +1,40 @@
+module Topoisomerase
+  # Class to set up comments that will be added to stubs for dynamic methods
+  class Comments
+    class << self
+      # @return [Object]  Class for which stubs will be created from and for
+      #   which rules to add comments for are defined
+      attr_accessor :inheriting_class
+
+      # Add a comment that is returned if ALL matchers are true
+      # @example Match a method ending with '_element' and include it's name without the '_element'
+      #   comment "@return [Object] The '<%= method_to_stub.to_s.gsub('_element', '') %>' element",
+      #           method_name: /_element$/
+      # @param [String] comment Comment to add above class
+      def comment(comment, matchers)
+        Topoisomerase.comments_added[inheriting_class] << {
+          message: comment,
+          matchers: matchers
+        }
+      end
+
+      # Add comments according to matchers for an inheriting class
+      #
+      # The order in which they are added is the order in which matching will occur.
+      # The first comment that has a match will be used.
+      # If several matchers are used on 1 comment, all must be true to be considered a match
+      #
+      # @example Add a comment where method name ends with '=' and source contains '.text'
+      #   Comments.add_for_class PageObject do
+      #     comment 'Comment to add', method_name: /=$/, source: /.text/
+      #   end
+      #
+      # @param [Object] inheriting_class Class for which stubs will be created from and for
+      #   which rules to add comments for are defined
+      def add_for_class(inheriting_class, &script)
+        self.inheriting_class = inheriting_class
+        instance_eval(&script)
+      end
+    end
+  end
+end

data/lib/topoisomerase/stub_template.rb.erb

@@ -2,13 +2,12 @@ require 'topoisomerase'
 # Stub for <%= @class_name %> created by 'topoisomerase'
 class <%= @class_name %>
   <% @dynamic_methods.each do |method_to_stub, method_data| %>
-  # Defined at <%=  method_data[:location] %>
-  # Extracted comment <%=  method_data[:comment].strip %>
-  def <%= method_to_stub %>
-    raise Topoisomerase::Error, "Method '<%= method_to_stub %>' called when it
+  # <%= comment_for(method_to_stub, method_data) %>
+  def <%= method_to_stub %> <%= method_data[:parameters].join(',') %>
+    # Defined at <%=  method_data[:location] %>
+    raise Topoisomerase::Error, "Method '<%= method_to_stub %>' called with when it
     should not have been. Don't require stub files"
-    # This is merely a stub
-    # Contents is below
+    # This is merely a stub. Contents is below
 <%= method_data[:source] %>
   end
   <% end %>

data/lib/topoisomerase/template/page_object.rb

@@ -0,0 +1,69 @@
+# Load comments for page_object and create stubs for classes inheriting from it
+
+# This blocks shows the manual addition of comments to the comments_added accessor
+# Preferred way is to Topoisomerase::Comments.add_for_class
+#
+# Topoisomerase.comments_added[PageObject] = [
+#   {
+#     message: "@return [PageObject::Elements::Element] An object representing the '<%= method_to_stub.to_s.gsub('_element', '') %>' element",
+#     matchers: { method_name: /_element$/ } # If either matcher matches, result returned
+#   },
+#   {
+#     message: "@return [Boolean] Whether the '<%= method_to_stub.to_s.gsub('?', '') %>' element is present",
+#     matchers: { method_name: /\?$/ }
+#   },
+#   # Testing whether 2 matchers use AND
+#   {
+#     message: "Set the text of the '<%= method_to_stub.to_s.gsub('?', '') %>' text field\n # @param [String] _value Value to set",
+#     matchers: { method_name: /=$/, source: /text_field_value_set/ }
+#   },
+#   {
+#     message: "Set the value of '<%= method_to_stub.to_s.gsub('?', '') %>' element\n # @param [String] _value Value to set",
+#     matchers: { method_name: /=$/ }
+#   },
+#   {
+#     message: "@return [String] The text of the '<%= method_to_stub.to_s.gsub('?', '') %>' element",
+#     matchers: { source: /\.text/ }
+#   },
+#   {
+#     message: "Click the '<%= method_to_stub.to_s.gsub('?', '') %>' element",
+#     matchers: { source: /\.click/ }
+#   }
+# ]
+
+
+#     message: "@return [Watir::Elements::Element] An object representing the '<%= method_to_stub.to_s.gsub('_element', '') %>' element",
+#     matchers: { method_name: /_element$/ } # If either matcher matches, result returned
+#   },
+
+Topoisomerase::Comments.add_for_class PageObject do
+  comment "Url of the page. Used by 'goto' method and when using 'visit'", method_name: 'page_url_value'
+  comment 'Open the page on the browser', method_name: 'goto'
+  comment "@return [PageObject::Elements::Element] An object representing the '<%= method_to_stub.to_s.gsub('_element', '') %>' element",
+          method_name: /_element$/
+end
+
+# This block demonstrates how a real browser could be used to create stubs.
+# This however should not be necessary and be resorted to only if the MockBrowser does not
+# work
+#
+# @return [Array] List of Selenium options
+# def options
+#   [args: %w[--disable-popup-blocking
+#             --no-sandbox --disable-dev-shm-usage],
+#    headless: true]
+# end
+#
+# require 'watir'
+# browser = Watir::Browser.new :chrome, *options
+# browser.close
+
+# Mock class just to make instantiating a page object with a browser happy
+class MockBrowser
+  # Called by PageObject though not needed for documentation
+  def bridge; end
+end
+
+Topoisomerase.create_stubs_based_on PageObject do |inheriting_class|
+  inheriting_class.new(MockBrowser.new, false)
+end

data/lib/topoisomerase/version.rb

@@ -1,3 +1,4 @@
 module Topoisomerase
-  VERSION = '0.1.0'.freeze
+  # @return [String] Version of the gem
+  VERSION = '0.1.1'.freeze
 end

data/todo.md

@@ -0,0 +1,4 @@
+* Handle other ways of dynamically defining methods 
+  * define_singleton_method
+  * instance_eval
+  * etc

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: topoisomerase
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Samuel Garratt
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-05-08 00:00:00.000000000 Z
+date: 2019-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: method_source
@@ -135,8 +135,8 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CODE_OF_CONDUCT.md
+- ChangeLog
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -144,10 +144,12 @@ files:
 - bin/setup
 - exe/topoisomerase
 - lib/topoisomerase.rb
+- lib/topoisomerase/comment_adder.rb
 - lib/topoisomerase/core_ext/string.rb
-- lib/topoisomerase/override_define.rb
 - lib/topoisomerase/stub_template.rb.erb
+- lib/topoisomerase/template/page_object.rb
 - lib/topoisomerase/version.rb
+- todo.md
 - topoisomerase.gemspec
 homepage: https://gitlab.com/samuel-garratt/topoisomerase
 licenses:

data/Gemfile.lock

@@ -1,93 +0,0 @@
-PATH
-  remote: .
-  specs:
-    topoisomerase (0.1.0)
-      method_source
-      rubocop
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    ast (2.4.0)
-    childprocess (1.0.1)
-      rake (< 13.0)
-    concurrent-ruby (1.1.5)
-    data_magic (1.2)
-      faker (>= 1.1.2)
-      yml_reader (>= 0.6)
-    diff-lcs (1.3)
-    faker (1.9.3)
-      i18n (>= 0.7)
-    i18n (1.6.0)
-      concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.2)
-    method_source (0.9.2)
-    mini_portile2 (2.4.0)
-    nokogiri (1.10.3)
-      mini_portile2 (~> 2.4.0)
-    page-object (2.2.5)
-      page_navigation (>= 0.10)
-      selenium-webdriver (~> 3.0)
-      watir (~> 6.8)
-    page_navigation (0.10)
-      data_magic (>= 0.22)
-    parallel (1.17.0)
-    parser (2.6.0.0)
-      ast (~> 2.4.0)
-    powerpack (0.1.2)
-    psych (3.1.0)
-    rainbow (3.0.0)
-    rake (10.5.0)
-    regexp_parser (1.3.0)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.0)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.3)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
-    rubocop (0.65.0)
-      jaro_winkler (~> 1.5.1)
-      parallel (~> 1.10)
-      parser (>= 2.5, != 2.5.1.1)
-      powerpack (~> 0.1)
-      psych (>= 3.1.0)
-      rainbow (>= 2.2.2, < 4.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (~> 1.4.0)
-    ruby-progressbar (1.10.0)
-    rubyzip (1.2.2)
-    selenium-webdriver (3.142.0)
-      childprocess (>= 0.5, < 2.0)
-      rubyzip (~> 1.2, >= 1.2.2)
-    unicode-display_width (1.4.1)
-    watir (6.16.5)
-      regexp_parser (~> 1.2)
-      selenium-webdriver (~> 3.6)
-    webdrivers (3.8.0)
-      nokogiri (~> 1.6)
-      rubyzip (~> 1.0)
-      selenium-webdriver (~> 3.0)
-    yard (0.9.19)
-    yml_reader (0.7)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 2.0)
-  page-object
-  rake
-  rspec (~> 3.0)
-  topoisomerase!
-  webdrivers
-  yard
-
-BUNDLED WITH
-   2.0.1

data/lib/topoisomerase/override_define.rb

@@ -1,13 +0,0 @@
-# This is very dangerous. Overriding define_method.
-# Only to be used for specific task of documenting dynamic methods used
-class Object
-  def self.define_method(method_name)
-    Topoisomerase.dynamic_methods[self] = method_name
-  end
-
-  # I don't think I should include this. Safer and makes sense
-  # just to focus on definitions in custom classes
-  # def define_method(method_name)
-  #   Topoisomerase.dynamic_methods[self] = method_name
-  # end
-end