cyperful 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e6cdf194b4606ed00df58d8b28820efb2bcf69f5a3f636ec5fed096fc8ce84e
-  data.tar.gz: 98ebee3f3b456c6d2fcaa905b19e1408503e1c2341926dd9d2b808c31287ef42
+  metadata.gz: c54a2f9266b145a049ddf720e90e50ec1250867ab51b51b046792ec36f57438a
+  data.tar.gz: a6dfac785f965f733c9b5fe41ea99c2437972f1a63dbbb346dfa822f6c2f187b
 SHA512:
-  metadata.gz: da33579e39387049c628a5d6a1d52dac4d56fffdc754671fd3928d22bb9cdf4149d597637beab80413e68eac719b6ee4607fc88acc39803568365240dac3f2b2
-  data.tar.gz: b5ee454173523ea078cf592aa2861541522514695bb50c7cdd0a42bb49c9b67359ef5493c55629cd1be2ff7ea3e40946f17e889be009cb27520803f6883ca637
+  metadata.gz: 79c77ab5eb6c05c9eb4531964b545ad2580e2a2e8a188835ec7bc5d261087eb05603faaa9ea7fbc16509f4c3e9675c1750bdf96e23c42716e2efcbae93715fab
+  data.tar.gz: 23bb98e1e7e6bb5f2939461ecfdf7b66bd5d04f06b449696c7ebacde7b8bf4b69396a48451fc3d3fe5e7aa5f199955bab4beaaadc6524c38c05003678998a0b7

data/lib/cyperful/driver.rb

@@ -0,0 +1,376 @@
+class Cyperful::Driver
+  attr_reader :steps, :pausing
+
+  SCREENSHOTS_DIR = File.join(Cyperful::ROOT_DIR, "public/screenshots")
+
+  def initialize
+    @step_pausing_queue = Queue.new
+
+    @session = Capybara.current_session
+    raise "Could not find Capybara session" unless @session
+
+    setup_api_server
+  end
+
+  def set_current_test(test_class, test_name)
+    @test_class = test_class
+    @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}")
+
+    reset_steps
+
+    print_steps
+
+    @session.visit(@cyperful_origin)
+    drive_iframe
+
+    # after we setup our UI, send the initialization data
+    notify_updated_steps
+
+    setup_tracing
+
+    setup_file_listener
+
+    # Sanity check
+    unless @step_pausing_queue.empty?
+      raise "step_pausing_queue is not empty during setup"
+    end
+
+    # Wait for the user to click "Start"
+    step_pausing_dequeue
+  end
+
+  def step_pausing_dequeue
+    command = @step_pausing_queue.deq
+    if command == :reset
+      raise Cyperful::ResetCommand
+    elsif command == :exit
+      raise Cyperful::ExitCommand
+    elsif command == :next
+      # just continue
+    else
+      raise "unknown command: #{command}"
+    end
+  end
+
+  def reset_steps
+    # TODO: memoize this when there's multiple tests per file
+    @steps =
+      Cyperful::TestParser.new(@test_class).steps_per_test.fetch(@test_name)
+
+    editor = "vscode" # TODO: support other editors?
+
+    @steps.each_with_index do |step, i|
+      step.merge!(
+        index: i,
+        status: "pending",
+        start_at: nil,
+        end_at: nil,
+        paused_at: nil,
+        permalink: "#{editor}://file/#{@source_filepath}:#{step.fetch(:line)}",
+      )
+    end
+
+    @step_per_line = @steps.index_by { |step| step[:line] }
+
+    @current_step = nil
+
+    @pause_at_step = true
+
+    @test_result = nil
+
+    # reset SCREENSHOTS_DIR
+    FileUtils.rm_rf(SCREENSHOTS_DIR)
+    FileUtils.mkdir_p(SCREENSHOTS_DIR)
+  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) }
+  end
+
+  # subscribe to the execution of each line of code in the test.
+  # this let's us notify the frontend of the line's status, and pause execution if needed.
+  def setup_tracing
+    @tracepoint&.disable
+
+    @tracepoint =
+      TracePoint.new(:line) do |tp|
+        next if @source_filepath.nil? || tp.path != @source_filepath
+
+        finish_current_step
+
+        step = @step_per_line[tp.lineno]
+        pause_on_step(step) if step
+      end
+    @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..."
+
+        @pause_at_step = true
+        @step_pausing_queue.enq(:reset)
+      end
+    @file_listener.start
+  end
+
+  def print_steps
+    puts "#{@steps.length} steps:"
+    @steps.each do |step|
+      puts "  #{step[:method]}: #{step[:line]}:#{step[:column]}"
+    end
+    puts
+  end
+
+  # pending (i.e. test hasn't started), paused, running, passed, failed
+  def test_status
+    return @test_result[:status] if @test_result # passed or failed
+
+    if @pause_at_step
+      return "running" if @steps.any? { |step| step[:status] == "running" }
+
+      return "pending" unless @current_step
+      return "paused"
+    end
+
+    "running"
+  end
+
+  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] }
+    return nil unless last_ended_step_i
+
+    end_at = @steps[last_ended_step_i][:end_at]
+
+    duration = end_at - start_at
+
+    @steps.each_with_index do |step, i|
+      next if i == 0 || i > last_ended_step_i
+      if step[:paused_at] && step[:start_at]
+        duration -= (step[:start_at] - step[:paused_at])
+      end
+    end
+
+    duration
+  end
+
+  def steps_updated_data
+    status = self.test_status
+    {
+      event: "steps_updated",
+      steps: @steps,
+      current_step_index: @current_step&.[](:index),
+      pause_at_step: @pause_at_step,
+      test_suite: @test_class.name,
+      test_name: @test_name,
+      test_status: status,
+      test_error: @test_result&.[](:error)&.to_s,
+      test_duration_ms: test_duration_ms,
+    }
+  end
+
+  private def notify_updated_steps
+    @ui_server.notify(steps_updated_data)
+  end
+
+  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"
+
+      # take screenshot after the step has finished
+      # path = File.join(SCREENSHOTS_DIR, "#{@current_step[:index]}.png")
+
+      # FIXME: this adds ~200ms to each step! disabling it for now
+      # @session.save_screenshot(path)
+
+      # this adds ~70ms to each step, but causes a weird flash on the screen
+      # @session.find(:css, "body").base.native.save_screenshot(path)
+
+      @current_step = nil
+    end
+
+    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
+
+  def drive_iframe
+    puts "Driving iframe..."
+
+    @session.switch_to_frame(
+      @session.find(:css, "iframe#scenario-frame"), # waits for the iframe to load
+    )
+    @driving_iframe = true
+  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)
+    base_uri =
+      ::Addressable::URI.parse(@session.config.app_host || @session.server_url)
+
+    if base_uri && [nil, "http", "https"].include?(visit_uri.scheme)
+      if visit_uri.relative?
+        visit_uri_parts = visit_uri.to_hash.compact
+
+        # Useful to people deploying to a subdirectory
+        # and/or single page apps where only the url fragment changes
+        visit_uri_parts[:path] = base_uri.path + visit_uri.path
+
+        visit_uri = base_uri.merge(visit_uri_parts)
+      end
+      # adjust_server_port(visit_uri)
+    end
+
+    abs_url = visit_uri.to_s
+
+    display_url = abs_url.sub(base_uri.to_s, "")
+
+    [abs_url, display_url]
+  end
+
+  WATCHER_JS = File.read(File.join(Cyperful::ROOT_DIR, "watcher.js"))
+
+  def internal_visit(url)
+    return false unless @driving_iframe
+
+    abs_url, display_url = make_absolute_url(url)
+
+    # show the actual `visit` url as soon as it's computed
+    if @current_step && @current_step[:method] == :visit
+      @current_step[:as_string] = "visit #{display_url.to_json}"
+      notify_updated_steps
+    end
+
+    @session.execute_script("window.location.href = #{abs_url.to_json}")
+
+    # inject the watcher 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
+
+    true
+  end
+
+  def internal_current_url
+    return nil unless @driving_iframe
+
+    @session.evaluate_script("window.location.href")
+  end
+
+  def setup_api_server
+    @ui_server = Cyperful::UiServer.new(port: 3004)
+
+    @cyperful_origin = @ui_server.url_origin
+
+    @ui_server.on_command do |command, params|
+      case command
+      when "start"
+        # one of: integer (index of a step), true (pause at every step), or nil (don't pause)
+        @pause_at_step = params["pause_at_step"]
+
+        continue_next_step
+      when "reset"
+        @pause_at_step = true
+        @step_pausing_queue.enq(:reset)
+      when "stop"
+        @pause_at_step = true # enable pausing
+      when "exit"
+        @pause_at_step = true
+
+        # instead of calling `exit` directly, we need to raise a Cyperful::ExitCommand error
+        # so Minitest can finish it's teardown e.g. to reset the database
+        @step_pausing_queue.enq(:exit)
+      else
+        raise "unknown command: #{command}"
+      end
+    end
+
+    @ui_server.start_async
+
+    # 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}"
+  end
+
+  def teardown(error = nil)
+    @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 ;)"
+
+      @ui_server.notify(nil) # `break` out of the `loop` (see `UiServer#socket_open`)
+
+      queue_reset
+      return
+    end
+
+    return if error&.is_a?(Cyperful::ExitCommand)
+
+    if error
+      # get the 4 lines following the first line that includes the source file
+      i = nil
+      backtrace =
+        error.backtrace.select do |s|
+          i ||= 0 if s.include?(@source_filepath)
+          i += 1 if i
+          break if i && i > 4
+          true
+        end
+
+      warn "\n\nTest failed with error:\n#{error.message}\n#{backtrace.join("\n")}"
+    end
+
+    @test_result = { status: error ? "failed" : "passed", error: error }
+
+    finish_current_step(error)
+
+    @ui_server.notify(nil) # `break` out of the `loop` (see `UiServer#socket_open`)
+
+    puts "Cyperful teardown complete. Waiting for command..."
+    command = @step_pausing_queue.deq
+    queue_reset if command == :reset
+  end
+end

data/lib/cyperful/framework_injections.rb

@@ -0,0 +1,52 @@
+# 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
+module PrependCapybaraSession
+  def visit(url)
+    return if Cyperful.current&.internal_visit(url)
+    super
+  end
+
+  def current_url
+    url = Cyperful.current&.internal_current_url
+    return url if url
+    super
+  end
+
+  def refresh
+    return if Cyperful.current&.internal_visit(current_url)
+    super
+  end
+end
+Capybara::Session.prepend(PrependCapybaraSession)
+
+# 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
+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")
+  end
+else
+  warn "Cyperful: Rails not detected, skipping content_security_policy fix.\nThe Cyperful UI may not work correctly."
+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/ui_server.rb

@@ -1,8 +1,8 @@
 require "webrick/websocket"
 
+# fix for: webrick-websocket incorrectly assumes `Upgrade` header is always present
 module FixWebrickWebsocketServer
   def service(req, res)
-    # fix for: webrick-websocket incorrectly assumes `Upgrade` header is always present
     req.header["upgrade"] = [""] if req["upgrade"].nil?
     super
   end
@@ -34,7 +34,7 @@ class Cyperful::UiServer
     @server =
       WEBrick::Websocket::HTTPServer.new(
         Port: @port,
-        DocumentRoot: File.expand_path("../../public", __dir__),
+        DocumentRoot: File.join(Cyperful::ROOT_DIR, "public"),
         Logger: WEBrick::Log.new("/dev/null"),
         AccessLog: [],
       )
@@ -53,7 +53,7 @@ class Cyperful::UiServer
           # at the moment it's not possible to have more than one client connected.
           # TODO: handle the client unexpectedly disconnecting e.g. user changes browser url
           if open_sockets.length > 0
-            warn "Warning: websockets already open: #{open_sockets}. You probably need to restart."
+            raise "websockets already open: #{open_sockets}. You probably need to restart."
           end
 
           sock_num = sock_num_counter