cyperful 0.1.10 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f340215ffcef3e16c1738d36eb2b71461bbd32e2011598d000793326f806b6d4
-  data.tar.gz: 545e19084294a2d481a7e9d156f6ba5e4758fb52332c17dc2e2574be820b2256
+  metadata.gz: 928af50672505bb877c08f2ef62533dee16149822b591eb0d854b28235fcd207
+  data.tar.gz: 8b3974789ec4d679fd6413fd5a8ac09b770e038487741871249da41815faeb1a
 SHA512:
-  metadata.gz: 524bbb91d707a457adfa888bc8db5a2d97886714dedc026d8647d2f243f8ff381f46a47af8cffe3fb4d46242aacfd515f2dda1b2a794252f758b5899ca312e9a
-  data.tar.gz: e20223308f8c0df25df5aab64d97f24d4ef6f0b57bb530106e82a3234f5701f1ca434afa87dad9b50155f73043aef6b1afbe328ebb99aed35ad53fac29dc5ef9
+  metadata.gz: '08d44698ee7d2e39c0b6cc36395d359983348e24378fa0f71a13c029d26cdeded6283828054498e524db52f39564214a33bb8f860ad857accaa4d22edd8c6a02'
+  data.tar.gz: a3aa8baf3c5d3a12747e316aeff713b834cc0ef8ac1a784ab24ffc2c405fb4f60908f8109b2b0a24a504e8d66a3d71e620ad6cd02c11b53c9734b04e005f8b12

data/lib/cyperful/driver.rb

@@ -1,6 +1,14 @@
 class Cyperful::Driver
   attr_reader :steps, :pausing
 
+  # delegate
+  private def logger
+    Cyperful.logger
+  end
+  private def config
+    Cyperful.config
+  end
+
   SCREENSHOTS_DIR = File.join(Cyperful::ROOT_DIR, "public/screenshots")
 
   def initialize
@@ -8,6 +16,12 @@ class Cyperful::Driver
 
     @session = Capybara.current_session
     raise "Could not find Capybara session" unless @session
+    unless @session.driver.is_a?(Capybara::Selenium::Driver)
+      raise "Cyperful only supports Selenium, got: #{@session.driver}"
+    end
+    unless @session.driver.browser.browser == :chrome
+      raise "Cyperful only supports Chrome, got: #{@session.driver.browser.browser}"
+    end
 
     setup_api_server
   end
@@ -17,8 +31,11 @@ class Cyperful::Driver
     @test_name = test_name.to_sym
 
     @source_filepath =
-      Object.const_source_location(test_class.name).first ||
-        raise("Could not find source file for #{test_class.name}")
+      if Cyperful.rspec?
+        test_class.metadata.fetch(:absolute_file_path)
+      else
+        Object.const_source_location(test_class.name).first
+      end || raise("Could not find source file for #{test_class.name}")
 
     reset_steps
 
@@ -61,7 +78,9 @@ class Cyperful::Driver
     @steps =
       Cyperful::TestParser.new(@test_class).steps_per_test.fetch(@test_name)
 
-    editor_scheme = Cyperful.config.editor_scheme
+    raise "No steps found in #{@test_class}:#{@test_name}" if @steps.blank?
+
+    editor_scheme = config.editor_scheme
 
     @steps.each_with_index do |step, i|
       step.merge!(
@@ -115,19 +134,29 @@ class Cyperful::Driver
     Object.const_get(class_name)
   end
 
-  def queue_reset
+  def enqueue_reset
     at_exit do
-      # reload test-suite code on reset (for `setup_file_listener`)
-      # TODO: also reload dependent files
-      # NOTE: run_on_method will fail if test_name also changed
-      @test_class = reload_const(@test_class.name, @source_filepath)
-
-      # TODO
-      # if Cyperful.config.reload_source_files && defined?(Rails)
-      #   Rails.application.reloader.reload!
-      # end
-
-      Minitest.run_one_method(@test_class, @test_name)
+      case Cyperful.test_framework
+      when :rspec
+        RSpec.configuration.reset # private API. this resets the test reporter
+        RSpec.configuration.start_time = RSpec::Core::Time.now # this needs to be reset
+        RSpec.world.reset # private API. this unloads constants and clears examples
+        RSpec::Core::Runner.invoke # this reloads and starts the test suite
+      when :minitest
+        # reload test-suite code on reset (for `setup_file_listener`)
+        # TODO: also reload dependent files
+        # NOTE: run_on_method will fail if test_name also changed
+        @test_class = reload_const(@test_class.name, @source_filepath)
+
+        # TODO
+        # if Cyperful.config.reload_source_files && defined?(Rails)
+        #   Rails.application.reloader.reload!
+        # end
+
+        Minitest.run_one_method(@test_class, @test_name)
+      else
+        raise "Unsupported test framework: #{Cyperful.test_framework}"
+      end
     end
   end
 
@@ -161,11 +190,11 @@ class Cyperful::Driver
     #   @source_file_listener = Listen.to(rails_directory) ...
     # end
 
-    if Cyperful.config.reload_test_files
+    if config.reload_test_files
       @file_listener&.stop
       @file_listener =
         Listen.to(test_directory) do |_modified, _added, _removed|
-          puts "Test files changed, resetting test..."
+          logger.puts "Test files changed, resetting test..."
 
           # keep the same pause state after the reload
           self.class.next_run_options = { pause_at_step: @pause_at_step }
@@ -178,13 +207,15 @@ class Cyperful::Driver
   end
 
   def print_steps
-    puts "Found #{@steps.length} steps:"
+    logger.puts("found #{@steps.length} steps:")
     @steps.each_with_index do |step, i|
-      puts " #{
-             (i + 1).to_s.rjust(2)
-           }.  #{step[:method]}: #{step[:line]}:#{step[:column]}"
+      logger.plain(
+        " #{
+          (i + 1).to_s.rjust(2)
+        }.  #{step[:method]}: #{step[:line]}:#{step[:column]}",
+      )
     end
-    puts
+    logger.plain
   end
 
   # pending (i.e. test hasn't started), paused, running, passed, failed
@@ -267,7 +298,7 @@ class Cyperful::Driver
       @current_step[:end_at] = (Time.now.to_f * 1000.0).to_i
       @current_step[:status] = !error ? "passed" : "failed"
 
-      puts(
+      logger.plain(
         " (#{@current_step[:end_at] - @current_step[:start_at]}ms)#{
           error ? " FAILED" : ""
         }",
@@ -293,7 +324,7 @@ class Cyperful::Driver
   end
 
   def drive_iframe
-    puts "Driving iframe..."
+    logger.puts "Driving iframe..."
 
     # make sure a `within` block doesn't affect these commands
     without_finder_scopes do
@@ -353,8 +384,13 @@ class Cyperful::Driver
   end
 
   private def skip_multi_sessions
-    unless Capybara.current_session == @session
-      warn "Skipped Cyperful setup in non-default session: #{Capybara.session_name}"
+    if Capybara.current_session != @session
+      logger.warn "Skipped setup in non-default session"
+      # for debugging: {
+      #   "current_session.mode": Capybara.current_session.mode,
+      #   "session.mode": @session.mode,
+      #   current_driver: Capybara.current_driver,
+      # }.to_json
       return true
     end
     false
@@ -390,7 +426,7 @@ class Cyperful::Driver
   end
 
   def setup_api_server
-    @ui_server = Cyperful::UiServer.new(port: Cyperful.config.port)
+    @ui_server = Cyperful::UiServer.new(port: config.port)
 
     @cyperful_origin = @ui_server.url_origin
 
@@ -422,7 +458,7 @@ class Cyperful::Driver
     # The server appears to always stop on it's own,
     # so we don't need to stop it within an `at_exit` or `Minitest.after_run`
 
-    puts "Cyperful server started: #{@cyperful_origin}"
+    logger.puts "server started: #{@cyperful_origin}"
   end
 
   def teardown(error = nil)
@@ -430,11 +466,11 @@ class Cyperful::Driver
     @tracepoint = nil
 
     if error&.is_a?(Cyperful::ResetCommand)
-      puts "\nResetting test (ignore any error logs)..."
+      logger.puts "Resetting test (ignore any error logs)..."
 
       @ui_server.notify(nil) # `break` out of the `loop` (see `UiServer#socket_open`)
 
-      queue_reset
+      enqueue_reset
       return
     end
 
@@ -461,10 +497,12 @@ class Cyperful::Driver
 
     @ui_server.notify(nil) # `break` out of the `loop` (see `UiServer#socket_open`)
 
-    puts "Cyperful teardown complete. Waiting for command..."
-    # NOTE: this will raise an `Interrupt` if the user Ctrl+C's here
+    logger.puts "teardown complete. Waiting for command..."
+
+    # NOTE: MiniTest will raise an `Interrupt` if the user Ctrl+C's here
+    # TODO: can't seem to capture Rspec Ctrl+C's :(
     command = @step_pausing_queue.deq
-    queue_reset if command == :reset
+    enqueue_reset if command == :reset
   ensure
     @file_listener&.stop
     @file_listener = nil

data/lib/cyperful/framework_helper.rb

@@ -0,0 +1,7 @@
+module Cyperful::FrameworkHelper
+  # Disable default screenshot on failure b/c we handle them ourselves.
+  # https://github.com/rails/rails/blob/v7.0.1/actionpack/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb#L156
+  def take_failed_screenshot
+    nil
+  end
+end

data/lib/cyperful/framework_injections.rb

@@ -1,29 +1,5 @@
 require "action_dispatch/system_testing/driver"
 
-# The Minitest test helper.
-# TODO: support other test frameworks like RSpec
-module Cyperful::SystemTestHelper
-  def setup
-    Cyperful.setup(self.class, self.method_name)
-    super
-  end
-
-  def teardown
-    error = passed? ? nil : failure
-
-    error = error.error if error.is_a?(Minitest::UnexpectedError)
-
-    Cyperful.teardown(error)
-    super
-  end
-
-  # Disable default screenshot on failure b/c we handle them ourselves.
-  # https://github.com/rails/rails/blob/main/actionpack/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb#L156
-  def take_failed_screenshot
-    nil
-  end
-end
-
 # we need to override the some Capybara::Session methods because they
 # control the top-level browser window, but we want them
 # to control the iframe instead
@@ -78,10 +54,32 @@ module PrependSystemTestingDriver
 
         # this assumes Selenium and Chrome:
 
+        # all chrome flags: https://peter.sh/experiments/chromium-command-line-switches
+        # chrome flags for tooling: https://github.com/GoogleChrome/chrome-launcher/blob/main/docs/chrome-flags-for-tools.md
+
+        # set the min flags to make cyperful functional:
+
         # so user isn't prompted when we start recording video w/ MediaStream
         driver_opts.add_argument("--auto-accept-this-tab-capture")
         driver_opts.add_argument("--use-fake-ui-for-media-stream")
 
+        if driver_opts.args.none? { |arg| arg.include?("--disable-features=") }
+          # credit: https://github.com/krausest/js-framework-benchmark/discussions/1682
+          disabled_features = %w[
+            InterestFeedContentSuggestions
+            IPH_DemoMode
+            BackForwardCache
+            OptimizationHints
+            OptimizationHintsFetching
+            OptimizationTargetPrediction
+            PrivacySandboxSettings4
+            Translate
+          ]
+          driver_opts.add_argument(
+            "--flag-switches-begin --disable-features=#{disabled_features.join(",")} --flag-switches-end",
+          )
+        end
+
         # make sure we're not in headless mode
         driver_opts.args.delete("--headless")
         driver_opts.args.delete("--headless=new")
@@ -94,9 +92,5 @@ module PrependSystemTestingDriver
 end
 ActionDispatch::SystemTesting::Driver.prepend(PrependSystemTestingDriver)
 
-# if defined?(Minitest::Test)
-#   Minitest::Test::PASSTHROUGH_EXCEPTIONS << Cyperful::AbstractCommand
-# end
-
 # fix for: Set-Cookie (SameSite=Lax) doesn't work when within an iframe with host 127.0.0.1
 Capybara.server_host = "localhost"

data/lib/cyperful/logger.rb

@@ -0,0 +1,14 @@
+class Cyperful::Logger
+  def puts(message = nil)
+    # call puts method from Kernel module
+    Kernel.puts("[cyperful] #{message}")
+  end
+
+  def warn(message = nil)
+    Kernel.warn("[cyperful] #{message}")
+  end
+
+  def plain(message = nil)
+    Kernel.puts(message)
+  end
+end

data/lib/cyperful/minitest.rb

@@ -0,0 +1,30 @@
+require "cyperful"
+require "capybara/minitest"
+
+module Cyperful::Minitest # rubocop:disable Style/ClassAndModuleChildren
+  module SystemTestHelper
+    include Cyperful::FrameworkHelper
+
+    def setup
+      Cyperful.setup(self.class, self.method_name)
+      super
+    end
+
+    def teardown
+      error = passed? ? nil : failure
+
+      error = error.error if error.is_a?(Minitest::UnexpectedError)
+
+      Cyperful.teardown(error)
+      super
+    end
+  end
+end
+
+Cyperful.add_step_at_methods(
+  Capybara::Minitest::Assertions.instance_methods(false),
+)
+
+# if defined?(Minitest::Test)
+#   Minitest::Test::PASSTHROUGH_EXCEPTIONS << Cyperful::AbstractCommand
+# end

data/lib/cyperful/rspec.rb

@@ -0,0 +1,24 @@
+require "cyperful"
+
+RSpec.configure do |rspec_conf|
+  rspec_conf.include(Cyperful::FrameworkHelper)
+
+  rspec_conf.before(:example, type: :system) do
+    # e.g. class = `RSpec::ExampleGroups::MyTest`
+    # e.g. full_description = "my_test can visit root"
+    example = RSpec.current_example
+    Cyperful.setup(self.class, example.full_description)
+  end
+
+  rspec_conf.after(:example, type: :system) do
+    example = RSpec.current_example
+    error = example.exception # RSpec::Expectations::ExpectationNotMetError | nil
+
+    Cyperful.teardown(error)
+  end
+end
+
+Cyperful.add_step_at_methods(
+  Capybara::RSpecMatchers.instance_methods(false),
+  # Capybara::RSpecMatcherProxies.instance_methods(false),
+)

data/lib/cyperful/test_parser.rb

@@ -1,11 +1,9 @@
-require "parser/current"
-require "capybara/minitest"
+require "parser/current" # TODO: switch to Prism?
 
 class Cyperful::TestParser
   # see docs for methods: https://www.rubydoc.info/github/jnicklas/capybara/Capybara/Session
   @step_at_methods =
-    Capybara::Session::DSL_METHODS.to_set +
-      Capybara::Minitest::Assertions.instance_methods(false) -
+    Capybara::Session::DSL_METHODS -
       # exclude methods that don't have side-effects i.e. don't modify the page:
       %i[
         body
@@ -25,7 +23,7 @@ class Cyperful::TestParser
     @step_at_methods_set ||= @step_at_methods.to_set
   end
   def self.add_step_at_methods(*mods_or_methods)
-    mods_or_methods.each do |mod_or_method|
+    mods_or_methods.flatten.each do |mod_or_method|
       case mod_or_method
       when Module
         @step_at_methods +=
@@ -33,17 +31,81 @@ class Cyperful::TestParser
       when String, Symbol
         @step_at_methods << mod_or_method.to_sym
       else
-        raise "Expected Module or Array of strings/symbols, got #{mod_or_method.class}"
+        raise "Expected Module or string/symbol, got: #{mod_or_method.class.name}"
       end
     end
   end
 
   def initialize(test_class)
     @test_class = test_class
-    @source_filepath = Object.const_source_location(test_class.name).first
+
+    @source_filepath =
+      if Cyperful.rspec?
+        test_class.metadata.fetch(:absolute_file_path)
+      else
+        Object.const_source_location(test_class.name).first
+      end
   end
 
   def steps_per_test
+    case Cyperful.test_framework
+    when :rspec
+      rspec_steps_per_test
+    when :minitest
+      minitest_steps_per_test
+    else
+      raise "Unsupported test framework: #{Cyperful.test_framework}"
+    end
+  end
+
+  private def rspec_steps_per_test
+    ast = Parser::CurrentRuby.parse(File.read(@source_filepath))
+
+    example_per_line =
+      @test_class.examples.to_h do |example|
+        # file_path = example.metadata.fetch(:absolute_file_path)
+        [example.metadata.fetch(:line_number) || -1, example]
+      end
+
+    example_asts =
+      search_nodes(ast) do |node|
+        next nil unless node.type == :block
+
+        # assumption: the block is on the same line as the example, and there's at most one example per line
+        example = example_per_line[node.loc.begin.line]
+        next nil unless example
+
+        # "#{@test_class.name} #{example.description} #{}"
+
+        [example, node]
+      end
+
+    example_asts.to_h do |(example, block_node)|
+      out = []
+      block_node.children.each { |child| find_test_steps(child, out) }
+
+      # de-duplicate steps by line number
+      # TODO: support multiple steps on the same line. `step_per_line = ...` needs to be refactored
+      out = out.reverse.uniq { |step| step[:line] }.reverse
+
+      [example.full_description.to_sym, out]
+    end
+  end
+
+  private def search_nodes(parent, out = [], &block)
+    parent.children.each do |node|
+      next unless node.is_a?(Parser::AST::Node)
+      if (ret = block.call(node))
+        #
+        out << ret
+      else
+        search_nodes(node, out, &block)
+      end
+    end
+    out
+  end
+
+  private def minitest_steps_per_test
     ast = Parser::CurrentRuby.parse(File.read(@source_filepath))
 
     test_class_name = @test_class.name.to_sym
@@ -57,7 +119,7 @@ class Cyperful::TestParser
         end
       end
     unless system_test_class
-      raise "Could not find class #{test_class.name} in #{@source_filepath}"
+      raise "Could not find class #{@test_class.name} in #{@source_filepath}"
     end
 
     (
@@ -76,21 +138,21 @@ class Cyperful::TestParser
           test_string = node.children[0].children[2].children[0]
 
           # https://github.com/rails/rails/blob/66676ce499a32e4c62220bd05f8ee2cdf0e15f0c/activesupport/lib/active_support/testing/declarative.rb#L14C23-L14C61
-          test_method = :"test_#{test_string.gsub(/\s+/, "_")}"
+          test_name = :"test_#{test_string.gsub(/\s+/, "_")}"
 
           block_node = node.children[2]
-          [test_method, block_node]
+          [test_name, block_node]
 
           # e.g. `def test_my_test; ... end`
         elsif node.type == :def && node.children[0].to_s.start_with?("test_")
-          test_method = node.children[0]
+          test_name = node.children[0]
 
           block_node = node.children[2]
-          [test_method, block_node]
+          [test_name, block_node]
         end
       end
       .compact
-      .to_h do |test_method, block_node|
+      .to_h do |test_name, block_node|
         out = []
         block_node.children.each { |child| find_test_steps(child, out) }
 
@@ -98,7 +160,7 @@ class Cyperful::TestParser
         # TODO: support multiple steps on the same line. `step_per_line = ...` needs to be refactored
         out = out.reverse.uniq { |step| step[:line] }.reverse
 
-        [test_method, out]
+        [test_name, out]
       end
   end
 
@@ -122,6 +184,8 @@ class Cyperful::TestParser
       end
 
       children.each { |child| find_test_steps(child, out, depth) }
+    elsif ast.type == :begin || ast.type == :kwbegin || ast.type == :ensure
+      ast.children.each { |child| find_test_steps(child, out, depth) }
     end
 
     out

data/lib/cyperful/ui_server.rb

@@ -1,15 +1,6 @@
 require "webrick/websocket"
 require "webrick/httpproxy"
 
-# fix for: webrick-websocket incorrectly assumes `Upgrade` header is always present
-module FixWebrickWebsocketServer
-  def service(req, res)
-    req.header["upgrade"] = [""] if req["upgrade"].nil?
-    super
-  end
-end
-WEBrick::Websocket::HTTPServer.prepend(FixWebrickWebsocketServer)
-
 class Cyperful::UiServer
   def initialize(port:)
     @port = port

data/lib/cyperful.rb

@@ -33,11 +33,36 @@ module Cyperful
     @config ||= Config.new
   end
 
+  def self.logger
+    @logger ||= Cyperful::Logger.new
+  end
+
+  def self.test_framework
+    @test_framework || raise("Cyperful not set up yet")
+  end
+  def self.rspec?
+    @test_framework == :rspec
+  end
+  def self.minitest?
+    @test_framework == :minitest
+  end
+
   def self.current
     @current
   end
   def self.setup(test_class, test_name)
-    puts "Setting up Cyperful for: #{test_class}##{test_name}"
+    @test_framework =
+      if defined?(RSpec::Core::ExampleGroup) &&
+           test_class < RSpec::Core::ExampleGroup
+        :rspec
+      elsif defined?(ActiveSupport::TestCase) &&
+            test_class < ActiveSupport::TestCase
+        :minitest
+      else
+        raise "Unsupported test framework for class: #{test_class.name}"
+      end
+
+    logger.puts "init test: \"#{rspec? ? test_name : "#{test_class}##{test_name}"}\""
 
     # must set `Cyperful.current` before calling `async_setup`
     @current ||= Cyperful::Driver.new
@@ -62,8 +87,10 @@ module Cyperful
 end
 
 require "cyperful/commands"
+require "cyperful/logger"
 require "cyperful/test_parser"
 require "cyperful/ui_server"
 require "cyperful/driver"
+require "cyperful/framework_helper"
 require "cyperful/framework_injections"
 require "cyperful/railtie" if defined?(Rails::Railtie)