cyperful 0.1.3 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0cc8a2ac49a7d7223268f31ec69e960e1fa5bf48fa98a92a5f3adc7b14776f7
-  data.tar.gz: 73be4bde0f5750a4366814527e890a9425764b885c4c72e5bea3717a9dfb6fa6
+  metadata.gz: 83254b2335dc0d99b443c2aad2260adc7c4f56bebaf32847a9e4ce151c03c6bc
+  data.tar.gz: 5a444d60e56c014569604e91162943aed5d6cb4f21655aaff8405be62d67b622
 SHA512:
-  metadata.gz: 3b67bf8da9159ff69167d5397a6e87f04980df7504cd46946710d8f28e3ead1a2ccf43738060c38552542d841ae76c6df70bda92d0e20fb9d5f9fc3395551f08
-  data.tar.gz: 5c3cdef286ca10f0f609f3cfd550c138747fa71af31ed9a8ed73006f8b422d46d1b75492383d6f1be83bf6c8ab196e4584522bbeacffa5f9a385920ece28ca06
+  metadata.gz: 945bad502b63c646fd55f43a997fbb2442d27866600aaac1aeda1aabd2c218841f51a81a000ecb0ede704097bd0e53d4ad67d9b8aa9c5b501ce62dc445d1c3cf
+  data.tar.gz: 32ce9c41a512ebc499b1852d5cf584fdf9b86015906da4c154706f056a5c385cd341aa174388c2b3171b82c1a17f23bd012ccaa62f6382d86c070a7f91dbd467

data/lib/cyperful/commands.rb

@@ -0,0 +1,19 @@
+module Cyperful
+  # @abstract
+  class AbstractCommand < StandardError
+    # don't print normal error/backtrace
+    def to_s
+      command_name =
+        self.class.name.split("::").last.chomp("Command").underscore
+      "(Captured cyperful command: #{command_name})"
+    end
+    def backtrace
+      []
+    end
+  end
+
+  class ResetCommand < AbstractCommand
+  end
+  class ExitCommand < AbstractCommand
+  end
+end

data/lib/cyperful/driver.rb

@@ -18,7 +18,7 @@ class Cyperful::Driver
 
     @source_filepath =
       Object.const_source_location(test_class.name).first ||
-        (raise "Could not find source file for #{test_class.name}")
+        raise("Could not find source file for #{test_class.name}")
 
     reset_steps
 
@@ -36,11 +36,11 @@ class Cyperful::Driver
 
     # Sanity check
     unless @step_pausing_queue.empty?
-      raise "step_pausing_queue is not empty during setup"
+      raise "Unexpected: step_pausing_queue must be empty during setup"
     end
 
     # Wait for the user to click "Start"
-    step_pausing_dequeue
+    step_pausing_dequeue if @pause_at_step == true
   end
 
   def step_pausing_dequeue
@@ -74,12 +74,18 @@ class Cyperful::Driver
       )
     end
 
+    # NOTE: there can be multiple steps per line, this takes the last instance
     @step_per_line = @steps.index_by { |step| step[:line] }
 
     @current_step = nil
 
     @pause_at_step = true
 
+    run_options = self.class.pop_run_options!
+    if run_options.key?(:pause_at_step)
+      @pause_at_step = run_options[:pause_at_step]
+    end
+
     @test_result = nil
 
     # reset SCREENSHOTS_DIR
@@ -87,10 +93,39 @@ class Cyperful::Driver
     FileUtils.mkdir_p(SCREENSHOTS_DIR)
   end
 
+  @next_run_options = {}
+  def self.next_run_options=(options)
+    @next_run_options = options
+  end
+  def self.pop_run_options!
+    opts = @next_run_options
+    @next_run_options = {}
+    opts
+  end
+
+  private def reload_const(class_name, source_path)
+    Object.send(:remove_const, class_name) if Object.const_defined?(class_name)
+    load(source_path) # reload the file
+    unless Object.const_defined?(class_name)
+      raise "Failed to reload test class: #{class_name}"
+    end
+    Object.const_get(class_name)
+  end
+
   def queue_reset
-    # FIXME: there may be other tests that are "queued" to run `at_exit`,
-    # so they'll run before this test restarts.
-    at_exit { Minitest.run_one_method(@test_class, @test_name) }
+    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)
+    end
   end
 
   # subscribe to the execution of each line of code in the test.
@@ -110,27 +145,41 @@ class Cyperful::Driver
     @tracepoint.enable
   end
 
-  # Every time a file changes the `test/` directory,
-  # reset this test
-  # TODO: add an option to auto-run
-  def setup_file_listener
-    test_dir = @source_filepath.match(%r{^/.+/(test|spec)\b})[0]
-
-    @file_listener&.stop
-    @file_listener =
-      Listen.to(test_dir) do |_modified, _added, _removed|
-        puts "Test files changed, resetting test..."
+  private def test_directory
+    @source_filepath.match(%r{^/.+/(?:test|spec)\b})&.[](0) ||
+      raise("Could not determine test directory for #{@source_filepath}")
+  end
 
-        @pause_at_step = true
-        @step_pausing_queue.enq(:reset)
-      end
-    @file_listener.start
+  # Every time a file changes the `test/` directory, reset this test
+  # TODO: add an option to auto-run on reload
+  def setup_file_listener
+    # TODO
+    # if Cyperful.config.reload_source_files
+    #   @source_file_listener = Listen.to(rails_directory) ...
+    # end
+
+    if Cyperful.config.reload_test_files
+      @file_listener&.stop
+      @file_listener =
+        Listen.to(test_directory) do |_modified, _added, _removed|
+          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 }
+
+          @pause_at_step = true # pause current test immediately
+          @step_pausing_queue.enq(:reset)
+        end
+      @file_listener.start
+    end
   end
 
   def print_steps
-    puts "#{@steps.length} steps:"
-    @steps.each do |step|
-      puts "  #{step[:method]}: #{step[:line]}:#{step[:column]}"
+    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]}"
     end
     puts
   end
@@ -149,7 +198,7 @@ class Cyperful::Driver
     "running"
   end
 
-  def test_duration_ms
+  private def test_duration_ms
     start_at = @steps.first&.[](:start_at)
     return nil unless start_at
     last_ended_step_i = @steps.rindex { |step| step[:end_at] }
@@ -188,11 +237,39 @@ class Cyperful::Driver
     @ui_server.notify(steps_updated_data)
   end
 
+  # called at the start of each step
+  def pause_on_step(step)
+    @current_step = step
+
+    # using `print` so we can append the step's status (see `finish_current_step`)
+    print("STEP #{(step[:index] + 1).to_s.rjust(2)}: #{step[:as_string]}")
+
+    if @pause_at_step == true || @pause_at_step == step[:index]
+      @current_step[:paused_at] = (Time.now.to_f * 1000.0).to_i
+      @current_step[:status] = "paused"
+      notify_updated_steps
+
+      # async wait for `continue_next_step`
+      step_pausing_dequeue
+    end
+
+    @current_step[:status] = "running"
+    @current_step[:start_at] = (Time.now.to_f * 1000.0).to_i
+    notify_updated_steps
+  end
+
+  # called at the end of each step
   private def finish_current_step(error = nil)
     if @current_step
       @current_step[:end_at] = (Time.now.to_f * 1000.0).to_i
       @current_step[:status] = !error ? "passed" : "failed"
 
+      puts(
+        " (#{@current_step[:end_at] - @current_step[:start_at]}ms)#{
+          error ? " FAILED" : ""
+        }",
+      )
+
       # take screenshot after the step has finished
       # path = File.join(SCREENSHOTS_DIR, "#{@current_step[:index]}.png")
 
@@ -208,25 +285,6 @@ class Cyperful::Driver
     notify_updated_steps
   end
 
-  def pause_on_step(step)
-    @current_step = step
-
-    puts "STEP: #{step[:as_string]}"
-
-    if @pause_at_step == true || @pause_at_step == step[:index]
-      @current_step[:paused_at] = (Time.now.to_f * 1000.0).to_i
-      @current_step[:status] = "paused"
-      notify_updated_steps
-
-      # async wait for `continue_next_step`
-      step_pausing_dequeue
-    end
-
-    @current_step[:status] = "running"
-    @current_step[:start_at] = (Time.now.to_f * 1000.0).to_i
-    notify_updated_steps
-  end
-
   private def continue_next_step
     @step_pausing_queue.enq(:next)
   end
@@ -234,12 +292,27 @@ class Cyperful::Driver
   def drive_iframe
     puts "Driving iframe..."
 
-    @session.switch_to_frame(
-      @session.find(:css, "iframe#scenario-frame"), # waits for the iframe to load
-    )
+    # make sure a `within` block doesn't affect these commands
+    without_finder_scopes do
+      @session.switch_to_frame(
+        # `find` waits for the iframe to load
+        @session.find(:css, "iframe#scenario-frame"),
+      )
+    end
+
     @driving_iframe = true
   end
 
+  private def without_finder_scopes(&block)
+    scopes = @session.send(:scopes)
+    before_scopes = scopes.dup
+    scopes.reject! { |el| el.is_a?(Capybara::Node::Element) }
+    block.call
+  ensure
+    scopes.clear
+    scopes.push(*before_scopes)
+  end
+
   # forked from: https://github.com/teamcapybara/capybara/blob/master/lib/capybara/session.rb#L264
   private def make_absolute_url(visit_uri)
     visit_uri = ::Addressable::URI.parse(visit_uri.to_s)
@@ -266,10 +339,27 @@ class Cyperful::Driver
     [abs_url, display_url]
   end
 
-  WATCHER_JS = File.read(File.join(Cyperful::ROOT_DIR, "watcher.js"))
+  def self.load_frame_agent_js
+    return @frame_agent_js if defined?(@frame_agent_js)
+
+    @frame_agent_js =
+      File.read(File.join(Cyperful::ROOT_DIR, "public/frame-agent.js")).sub(
+        "__CYPERFUL_CONFIG__",
+        { CYPERFUL_ORIGIN: "http://localhost:#{Cyperful.config.port}" }.to_json,
+      )
+  end
+
+  private def skip_multi_sessions
+    unless Capybara.current_session == @session
+      warn "Skipped Cyperful setup in non-default session: #{Capybara.session_name}"
+      return true
+    end
+    false
+  end
 
   def internal_visit(url)
     return false unless @driving_iframe
+    return false if skip_multi_sessions
 
     abs_url, display_url = make_absolute_url(url)
 
@@ -281,22 +371,23 @@ class Cyperful::Driver
 
     @session.execute_script("window.location.href = #{abs_url.to_json}")
 
-    # inject the watcher script into the page being tested.
+    # inject the frame-agent script into the page being tested.
     # this script will notify the Cyperful UI for events like:
     # console logs, network requests, client navigations, errors, etc.
-    @session.execute_script(WATCHER_JS) # ~9ms empirically
+    @session.execute_script(Cyperful::Driver.load_frame_agent_js) # ~9ms empirically
 
     true
   end
 
   def internal_current_url
     return nil unless @driving_iframe
+    return nil if skip_multi_sessions
 
     @session.evaluate_script("window.location.href")
   end
 
   def setup_api_server
-    @ui_server = Cyperful::UiServer.new(port: 3004)
+    @ui_server = Cyperful::UiServer.new(port: Cyperful.config.port)
 
     @cyperful_origin = @ui_server.url_origin
 
@@ -335,11 +426,8 @@ class Cyperful::Driver
     @tracepoint&.disable
     @tracepoint = nil
 
-    @file_listener&.stop
-    @file_listener = nil
-
     if error&.is_a?(Cyperful::ResetCommand)
-      puts "\nPlease ignore the error, we're just resetting the test ;)"
+      puts "\nResetting test (ignore any error logs)..."
 
       @ui_server.notify(nil) # `break` out of the `loop` (see `UiServer#socket_open`)
 
@@ -355,9 +443,10 @@ class Cyperful::Driver
       backtrace = []
       error.backtrace.each do |s|
         i ||= 0 if s.include?(@source_filepath)
-        i += 1 if i
-        break if i && i > 4
+        next unless i
+        i += 1
         backtrace << s
+        break if i >= 6
       end
 
       warn "\n\nTest failed with error:\n#{error.message}\n#{backtrace.join("\n")}"
@@ -370,7 +459,11 @@ 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
     command = @step_pausing_queue.deq
     queue_reset if command == :reset
+  ensure
+    @file_listener&.stop
+    @file_listener = nil
   end
 end

data/lib/cyperful/framework_injections.rb

@@ -1,3 +1,5 @@
+require "action_dispatch/system_testing/driver"
+
 # 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
@@ -17,9 +19,24 @@ module PrependCapybaraSession
     return if Cyperful.current&.internal_visit(current_url)
     super
   end
+
+  def go_back
+    super
+    Cyperful.current&.drive_iframe
+  end
 end
 Capybara::Session.prepend(PrependCapybaraSession)
 
+module PrependCapybaraWindow
+  # this solves a bug in Capybara where it doesn't
+  # return to driving the iframe after a call to `Window#close`
+  def close
+    super
+    Cyperful.current&.drive_iframe
+  end
+end
+Capybara::Window.prepend(PrependCapybaraWindow)
+
 # The Minitest test helper.
 # TODO: support other test frameworks like RSpec
 module Cyperful::SystemTestHelper
@@ -36,13 +53,48 @@ module Cyperful::SystemTestHelper
     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
 
+module PrependSystemTestingDriver
+  def initialize(...)
+    super(...)
+
+    prev_capabilities = @capabilities
+    @capabilities =
+      proc do |driver_opts|
+        prev_capabilities&.call(driver_opts)
+
+        next unless driver_opts.respond_to?(:add_argument)
+
+        # this assumes Selenium and Chrome:
+
+        # 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")
+
+        # make sure we're not in headless mode
+        driver_opts.args.delete("--headless")
+        driver_opts.args.delete("--headless=new")
+      end
+  end
+end
+ActionDispatch::SystemTesting::Driver.prepend(PrependSystemTestingDriver)
+
+# if defined?(Minitest::Test)
+#   Minitest::Test::PASSTHROUGH_EXCEPTIONS << Cyperful::AbstractCommand
+# end
+
 # we need to allow the iframe to be embedded in the cyperful server
 # TODO: use Rack middleware instead to support non-Rails apps
 if defined?(Rails)
   Rails.application.config.content_security_policy do |policy|
-    policy.frame_ancestors(:self, "localhost:3004")
+    policy.frame_ancestors(:self, "localhost:#{Cyperful.config.port}")
   end
 else
   warn "Cyperful: Rails not detected, skipping content_security_policy fix.\nThe Cyperful UI may not work correctly."

data/lib/cyperful/test_parser.rb

@@ -1,6 +1,41 @@
 require "parser/current"
+require "capybara/minitest"
 
 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) -
+      # exclude methods that don't have side-effects i.e. don't modify the page:
+      %i[
+        body
+        html
+        source
+        current_url
+        current_host
+        current_path
+        current_scope
+        status_code
+        response_headers
+      ]
+
+  def self.step_at_methods
+    @step_at_methods
+  end
+  def self.add_step_at_methods(*mods_or_methods)
+    mods_or_methods.each do |mod_or_method|
+      case mod_or_method
+      when Module
+        @step_at_methods +=
+          mod_or_method.methods(false) + mod_or_method.instance_methods(false)
+      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}"
+      end
+    end
+  end
+
   def initialize(test_class)
     @test_class = test_class
     @source_filepath = Object.const_source_location(test_class.name).first
@@ -24,14 +59,14 @@ class Cyperful::TestParser
     end
 
     (
-        # the children of the `class` node are either:
-        # - a `begin` node if there's more than 1 child node
-        # - or the one 0 or 1 child node
-        system_test_class
-          .children
-          .find { |node| node.type == :begin }
-          &.children || [system_test_class.children[2]].compact
-      )
+      # the children of the `class` node are either:
+      # - a `begin` node if there's more than 1 child node
+      # - or the one 0 or 1 child node
+      system_test_class
+        .children
+        .find { |node| node.type == :begin }
+        &.children || [system_test_class.children[2]].compact
+    )
       .map do |node|
         # e.g. `test "my test" do ... end`
         if node.type == :block && node.children[0].type == :send &&
@@ -39,7 +74,7 @@ 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+/, "_")}".to_sym
+          test_method = :"test_#{test_string.gsub(/\s+/, "_")}"
 
           block_node = node.children[2]
           [test_method, block_node]
@@ -50,29 +85,48 @@ class Cyperful::TestParser
       end
       .compact
       .to_h do |test_method, block_node|
-        [
-          test_method,
-          find_test_steps(block_node)
-            # sanity check:
-            .uniq { |step| step[:line] },
-        ]
+        out = []
+        block_node.children.each { |child| find_test_steps(child, out) }
+
+        [test_method, out]
       end
   end
 
-  private def find_test_steps(ast, out = [])
+  private def find_test_steps(ast, out = [], depth = 0)
     return out unless ast&.is_a?(Parser::AST::Node)
 
-    if ast.type == :send && Cyperful.step_at_methods.include?(ast.children[1])
-      out << {
-        method: ast.children[1],
-        line: ast.loc.line,
-        column: ast.loc.column,
-        as_string: ast.loc.expression.source,
-      }
-    end
+    if ast.type == :send
+      add_node(ast, out, depth)
+      ast.children.each { |child| find_test_steps(child, out, depth) }
+    elsif ast.type == :block
+      method, _args, child = ast.children
 
-    ast.children.each { |child| find_test_steps(child, out) }
+      children = child.type == :begin ? child.children : [child]
+
+      if method.type == :send
+        depth += 1 if add_node(method, out, depth)
+        method.children.each { |child| find_test_steps(child, out, depth) }
+      end
+
+      children.each { |child| find_test_steps(child, out, depth) }
+    end
 
     out
   end
+
+  private def add_node(node, out, depth)
+    unless Cyperful::TestParser.step_at_methods.include?(node.children[1])
+      return false
+    end
+
+    out << {
+      method: node.children[1],
+      line: node.loc.line,
+      column: node.loc.column,
+      as_string: node.loc.expression.source,
+      block_depth: depth,
+    }
+
+    true
+  end
 end

data/lib/cyperful/ui_server.rb

@@ -106,6 +106,18 @@ class Cyperful::UiServer
 
       res.status = 204
     end
+
+    @server.mount_proc("/api/config") do |req, res|
+      if req.request_method != "GET"
+        res.body = "Only POST allowed"
+        res.status = 405
+        next
+      end
+
+      res.body = Cyperful.config.to_h.to_json
+      res["Content-Type"] = "application/json"
+      res.status = 200
+    end
   end
 
   def start_async

data/lib/cyperful.rb

@@ -6,6 +6,27 @@ module Cyperful
 
   @current = nil
 
+  class Config < Struct.new(
+    :port,
+    :auto_run_on_reload,
+    :reload_test_files,
+    # :reload_source_files, # not implemented yet
+    :history_recording, # EXPERIMENTAL
+    keyword_init: true,
+  )
+    def initialize
+      super(
+        port: 3004,
+        auto_run_on_reload: true,
+        reload_test_files: true,
+        history_recording: true,
+      )
+    end
+  end
+  def self.config
+    @config ||= Config.new
+  end
+
   def self.current
     @current
   end
@@ -29,33 +50,12 @@ module Cyperful
     @current&.teardown(error)
   end
 
-  # more potential methods: https://www.rubydoc.info/github/jnicklas/capybara/Capybara/Session
-  @step_at_methods = [*Capybara::Session::NODE_METHODS, :visit, :refresh]
-  def self.step_at_methods
-    @step_at_methods
-  end
   def self.add_step_at_methods(*mods_or_methods)
-    mods_or_methods.each do |mod_or_method|
-      case mod_or_method
-      when Module
-        @step_at_methods +=
-          mod_or_method.methods(false) + mod_or_method.instance_methods(false)
-      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}"
-      end
-    end
+    Cyperful::TestParser.add_step_at_methods(*mods_or_methods)
   end
 end
 
-class Cyperful::AbstractCommand < StandardError
-end
-class Cyperful::ResetCommand < Cyperful::AbstractCommand
-end
-class Cyperful::ExitCommand < Cyperful::AbstractCommand
-end
-
+require "cyperful/commands"
 require "cyperful/test_parser"
 require "cyperful/ui_server"
 require "cyperful/driver"