scarpe 0.2.1 → 0.3.0

data/lacci/test/test_shoes_errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class TestShoesErrors < NienteTest
+  def test_drawable_attr_error
+    run_test_niente_code(<<~SHOES_APP, app_test_code: <<~SHOES_SPEC)
+    Shoes.app do
+      button "OK" do
+        star 10, 25, "sammy"
+      end
+    end
+    SHOES_APP
+    assert_raises Shoes::Errors::InvalidAttributeValueError do
+      button().trigger_click
+    end
+    SHOES_SPEC
+  end
+
+  def test_too_many_instances_error
+    run_test_niente_code(<<~SHOES_APP, app_test_code: <<~SHOES_SPEC)
+    $ruby_main = self
+    Shoes.app do
+    end
+    SHOES_APP
+    assert_raises Shoes::Errors::TooManyInstancesError do
+      $ruby_main.instance_eval do
+        Shoes.app {}
+      end
+    end
+    SHOES_SPEC
+  end
+
+  def test_drawables_found_errors
+    run_test_niente_code(<<~SHOES_APP, app_test_code: <<~SHOES_SPEC)
+    Shoes.app do
+      button "OK"
+      button "Not OK"
+    end
+    SHOES_APP
+    assert_raises Shoes::Errors::MultipleDrawablesFoundError do
+      button()
+    end
+    assert_raises Shoes::Errors::NoDrawablesFoundError do
+      edit_line()
+    end
+    SHOES_SPEC
+  end
+end

data/lib/scarpe/cats_cradle.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "scarpe/components/unit_test_helpers"
+require "scarpe/evented_assertions"
+
+require "fiber"
+
+module Scarpe::Test
+  # We'd like something we can call Shoes drawable methods on, such as para.replace.
+  # But we'd also like to be able to grab the corresponding display drawable and
+  # call some of *those* methods.
+  class CCProxy
+    attr_reader :display
+    attr_reader :obj
+
+    def initialize(obj)
+      @obj = obj
+      # TODO: how to do this with Webview relay? Proxy object to send a message, maybe?
+      @display = ::Shoes::DisplayService.display_service.query_display_drawable_for(obj.linkable_id)
+    end
+
+    def method_missing(method, ...)
+      if @obj.respond_to?(method)
+        self.singleton_class.define_method(method) do |*args, **kwargs, &block|
+          @obj.send(method, *args, **kwargs, &block)
+        end
+        send(method, ...)
+      else
+        super # raise an exception
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @obj.respond_to_missing?(method_name, include_private)
+    end
+
+    def trigger(event_name, *args)
+      name = "#{@obj.linkable_id}-#{event_name}"
+      Scarpe::Webview::DisplayService.instance.app.handle_callback(name, *args)
+    end
+
+    [:click, :hover, :leave, :change].each do |ev|
+      define_method "trigger_#{ev}" do |*args|
+        trigger(ev, *args)
+      end
+    end
+  end
+
+  module DrawableFinders
+    # What to do about TextDrawables? Link, code, em, strong?
+    # Also, wait, what's up with span? What *is* that?
+    Shoes::Drawable.drawable_classes.each do |drawable_class|
+      finder_name = drawable_class.dsl_name
+
+      define_method(finder_name) do |*args|
+        app = Shoes::App.instance
+
+        drawables = app.find_drawables_by(drawable_class, *args)
+        raise Shoes::Errors::MultipleDrawablesFoundError, "Found more than one #{finder_name} matching #{args.inspect}!" if drawables.size > 1
+        raise Shoes::Errors::NoDrawablesFoundError, "Found no #{finder_name} matching #{args.inspect}!" if drawables.empty?
+
+        CCProxy.new(drawables[0])
+      end
+    end
+  end
+
+  # This class defines the CatsCradle DSL. It also holds a "bag of fibers"
+  # with promises for when they should next resume.
+  class CCInstance
+    include Shoes::Log
+    include Scarpe::Test::EventedAssertions
+    include Scarpe::Test::Helpers
+    include Scarpe::Test::DrawableFinders
+
+    def self.instance
+      @instance ||= CCInstance.new
+    end
+
+    def initialize
+      log_init("CatsCradle")
+
+      evented_assertions_initialize
+
+      @waiting_fibers = []
+      @event_promises = {}
+
+      @manager_fiber = Fiber.new do
+        loop do
+          # A fiber can run briefly and then exit. It can run and then block on an API call.
+          # These fibers return promises to indicate to CatsCradle when they can run again.
+          # A fiber that is no longer #alive? is assumed to be successfully finished.
+          @waiting_fibers.each do |fiber_data|
+            next unless fiber_data[:promise].fulfilled?
+
+            @log.debug("Resuming fiber with value #{fiber_data[:promise].returned_value.inspect}")
+            result = fiber_data[:fiber].transfer fiber_data[:promise].returned_value
+
+            # Dead fibers will be removed later, just leave it
+            next unless fiber_data[:fiber].alive?
+
+            case result
+            when ::Scarpe::Promise
+              fiber_data[:promise] = result
+            else
+              raise Scarpe::UnexpectedFiberTransferError, "Unexpected object returned from Fiber#transfer for still-living Fiber! #{result.inspect}"
+            end
+          end
+
+          # Throw out dead fibers or those that will never wake
+          @waiting_fibers.select! do |fiber_data|
+            fiber_data[:fiber].alive? && !fiber_data[:promise].rejected?
+          end
+
+          # Done with this iteration
+          Fiber.yield
+        end
+      end
+    end
+
+    # If we add "every" events, that's likely to complicate timing and event_promise handling.
+    EVENT_TYPES = [:init, :next_heartbeat, :next_redraw, :every_heartbeat, :every_redraw]
+
+    # This needs to be called after the basic display service objects exist
+    # and we can find the control interface.
+    def event_init
+      return if @cc_init_done
+
+      @cc_init_done = true
+
+      @control_interface = ::Shoes::DisplayService.display_service.control_interface
+      @wrangler = @control_interface.wrangler
+
+      cc_instance = self # ControlInterface#on_event does an instance eval. We'll reset self with another.
+
+      @control_interface.on_event(:every_heartbeat) do
+        cc_instance.instance_eval do
+          p = @event_promises.delete(:next_heartbeat)
+          p&.fulfilled!
+
+          p = @event_promises.delete(:every_heartbeat)
+          p&.fulfilled!
+
+          # Give every ready fiber a chance to run once.
+          @manager_fiber.resume
+        end
+      end
+
+      @control_interface.on_event(:every_redraw) do
+        cc_instance.instance_eval do
+          p = @event_promises.delete(:next_redraw)
+          p&.fulfilled!
+
+          p = @event_promises.delete(:every_redraw)
+          p&.fulfilled!
+
+          # Give every ready fiber a chance to run once.
+          @manager_fiber.resume
+        end
+      end
+    end
+
+    def event_promise(event)
+      @event_promises[event] ||= ::Scarpe::Promise.new
+    end
+
+    def on_event(event, &block)
+      raise Scarpe::UnknownEventTypeError, "Unknown event type: #{event.inspect}!" unless EVENT_TYPES.include?(event)
+
+      f = Fiber.new do
+        CCInstance.instance.instance_eval(&block)
+      end
+      @waiting_fibers << { promise: event_promise(event), fiber: f }
+    end
+
+    def proxy_for(shoes_drawable)
+      CCProxy.new(shoes_drawable)
+    end
+
+    def die_after(time)
+      t_start = Time.now
+      @die_after = [t_start, time]
+
+      @wrangler.periodic_code("scarpeTestTimeout") do |*_args|
+        t_delta = (Time.now - t_start).to_f
+        if t_delta > time
+          @did_time_out = true
+          @log.warn("die_after - timed out after #{t_delta.inspect} (threshold: #{time.inspect})")
+          return_results(false, "Timed out!")
+          ::Shoes::DisplayService.dispatch_event("destroy", nil)
+        end
+      end
+    end
+
+    def wait(promise)
+      raise(Scarpe::InvalidPromiseError, "Must supply a promise to wait!") unless promise.is_a?(::Scarpe::Promise)
+
+      # Wait until this promise is complete before running again
+      @manager_fiber.transfer(promise)
+    end
+
+    # This returns a promise, which can be waited on using wait()
+    def fully_updated
+      @wrangler.promise_dom_fully_updated
+    end
+
+    def dom_html(timeout: 1.0)
+      query_js_value("document.getElementById('wrapper-wvroot').innerHTML", timeout:)
+    end
+
+    def query_js_value(js_code, timeout: 1.0)
+      js_promise = @wrangler.eval_js_async(js_code, timeout:)
+
+      # This promise will return the string, so we can just pass it to #transfer
+      @manager_fiber.transfer(js_promise)
+    end
+
+    def query_js_promise(js_code, timeout: 1.0)
+      @wrangler.eval_js_async(js_code, timeout:)
+    end
+
+    def test_finished(return_results: true)
+      return_assertion_data if return_results
+
+      ::Shoes::DisplayService.dispatch_event("destroy", nil)
+    end
+
+    def test_finished_no_results
+      ::Shoes::DisplayService.dispatch_event("destroy", nil)
+    end
+  end
+
+  # "Cat's Cradle" is a children's game where they interlace string between
+  # their fingers to make beautiful complicated shapes. The interlacing
+  # of fibers made it a good name for a prototype.
+
+  # An attempt at an experimental Fiber-based testing system to deal with
+  # Shoes, Display and JS all at the same time.
+  #
+  # In general, we'll use Fiber.transfer to bounce control back and forth
+  # between the evented implementations (e.g. waiting for redraw) that
+  # need to return control to Webview, and the procedural test flows
+  # that look far better if we don't do that explicitly.
+  #
+  # Ruby Fiber basic docs: https://ruby-doc.org/core-3.0.0/Fiber.html
+  #
+  # This module is mixed into a test object if we're running CatsCradle-based tests
+  module CatsCradle
+    attr_reader :cc_instance
+
+    def event_init
+      @cc_instance ||= CCInstance.instance
+      @cc_instance.event_init
+    end
+
+    def on_heartbeat(&block)
+      @cc_instance.on_event(:next_heartbeat, &block)
+    end
+
+    def on_every_heartbeat(&block)
+      @cc_instance.on_event(:every_heartbeat, &block)
+    end
+
+    def on_init(&block)
+      @cc_instance.on_event(:init, &block)
+    end
+
+    def on_next_redraw(&block)
+      @cc_instance.on_event(:next_redraw, &block)
+    end
+  end
+end

data/lib/scarpe/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Scarpe
+  class UnknownShoesEventAPIError < Scarpe::Error; end
+
+  class UnknownShapeCommandError < Scarpe::Error; end
+
+  class UnknownBuiltinCommandError < Scarpe::Error; end
+
+  class UnknownEventTypeError < Scarpe::Error; end
+
+  class UnexpectedFiberTransferError < Scarpe::Error; end
+
+  class InvalidPromiseError < Scarpe::Error; end
+
+  class MissingAppError < Scarpe::Error; end
+
+  class MissingDocRootError < Scarpe::Error; end
+
+  class MissingWranglerError < Scarpe::Error; end
+
+  class IllegalSubscribeEventError < Scarpe::Error; end
+
+  class IllegalDispatchEventError < Scarpe::Error; end
+
+  class MissingBlockError < Scarpe::Error; end
+
+  class DuplicateCallbackError < Scarpe::Error; end
+
+  class JSBindingError < Scarpe::Error; end
+
+  class JSInitError < Scarpe::Error; end
+
+  class PeriodicHandlerSetupError < Scarpe::Error; end
+
+  class WebWranglerNotRunningError < Scarpe::Error; end
+
+  class NonexistentEvalResultError < Scarpe::Error; end
+
+  class JSRedrawError < Scarpe::Error; end
+
+  class ConnectionError < Scarpe::Error; end
+
+  class DatagramSendError < Scarpe::Error; end
+
+  class InvalidOperationError < Scarpe::Error; end
+
+  class MissingAttributeError < Scarpe::Error; end
+
+  # This error indicates a problem when running ConfirmedEval
+  class JSEvalError < Scarpe::Error
+    def initialize(data)
+      @data = data
+      super(data[:msg] || (self.class.name + "!"))
+    end
+  end
+
+  # An error running the supplied JS code string in confirmed_eval
+  class JSRuntimeError < JSEvalError; end
+
+  # The code timed out for some reason
+  class JSTimeoutError < JSEvalError; end
+
+  # We got weird or nonsensical results that seem like an error on WebWrangler's part
+  class JSInternalError < JSEvalError; end
+
+  # An error occurred which would normally be handled by shutting down the app
+  class AppShutdownError < Scarpe::Error; end
+
+  class InvalidClassError < Scarpe::Error; end
+
+  class MissingClassError < Scarpe::Error; end
+
+  class EmptyPageNotSetError < Scarpe::Error; end
+
+  class BadDisplayClassType < Scarpe::Error; end
+end

data/lib/scarpe/evented_assertions.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "json"
+require "fileutils"
+
+require "scarpe/components/unit_test_helpers"
+
+module Scarpe::Test; end
+
+# We need a separate assertion system for the kind of Scarpe
+# testing where we start a subprocess, perform the assertion
+# logic in the subprocess, and then run Minitest in the parent.
+# It's an unusual setup.
+module Scarpe::Test::EventedAssertions
+  include Scarpe::Test::HTMLAssertions
+
+  private
+
+  def evented_assertions_initialize
+    @assertion_data = []
+    @assertions_passed = 0
+    @assertions_failed = []
+  end
+
+  public
+
+  def assert(value, msg = nil)
+    msg ||= "Assertion #{value ? "succeeded" : "failed"}"
+    @assertion_data << [(value ? true : false), msg]
+    if value
+      @assertions_passed += 1
+    else
+      @assertions_failed << msg
+    end
+  end
+
+  def assert_equal(expected, actual, msg = nil)
+    msg ||= "Expected #{actual.inspect} to equal #{expected.inspect}!"
+    assert actual == expected, msg
+  end
+
+  def assertion_data_as_a_struct
+    {
+      still_pending: 0,
+      succeeded: @assertions_passed,
+      failed: @assertions_failed.size,
+      failures: @assertions_failed,
+    }
+  end
+
+  def test_metadata
+    {}
+  end
+
+  # Assert that `text` includes `subtext`.
+  #
+  # @param text [String] the longer text
+  # @param subtext [String] the text that is asserted to be included
+  # @param msg [String,nil] if supplied, the failure message for the assertion
+  # @return [void]
+  def assert_include(text, subtext, msg = nil)
+    msg ||= "Expected #{text.inspect} to include #{subtext.inspect}"
+    assert text.include?(subtext), msg
+  end
+
+  # Assert that `text` does not include `subtext`.
+  #
+  # @param text [String] the longer text
+  # @param subtext [String] the text that is asserted to not be included
+  # @param msg [String,nil] if supplied, the failure message for the assertion
+  # @return [void]
+  def assert_not_include(text, subtext, msg = nil)
+    msg ||= "Expected #{text.inspect} not to include #{subtext.inspect}"
+    assert !text.include?(subtext), msg
+  end
+
+  def return_assertion_data
+    if !@assertions_failed.empty?
+      return_results(false, "Assertions failed", assertion_data_as_a_struct)
+    elsif @assertions_passed > 0
+      return_results(true, "All assertions passed", assertion_data_as_a_struct)
+    else
+      return_results(true, "Test finished successfully")
+    end
+  end
+
+  # This does a final return of results. If it gets called
+  # multiple times with different results, the test fails because that's not allowed.
+  #
+  # @param result_bool [Boolean] true if the results are success, false if failure
+  # @param msg [String] the message included with the results
+  # @param data [Hash] any additional data to pass with the results
+  # @return void
+  def return_results(result_bool, msg, data = {})
+    result_file = ENV["SCARPE_TEST_RESULTS"] || "./scarpe_results.txt"
+
+    result_structs = [result_bool, msg, data.merge(test_metadata)]
+    if File.exist?(result_file)
+      results_returned = JSON.parse File.read(result_file)
+    end
+
+    # Multiple different sets of results is bad, even if both are passing.
+    if results_returned && results_returned[0..1] != result_structs[0..1]
+      # Just raising here doesn't reliably fail the test.
+      # See: https://github.com/scarpe-team/scarpe/issues/212
+      Shoes::Log.logger("Test Results").error("Writing multi-result failure file to #{result_file.inspect}!")
+
+      new_res_data = { first_result: results_returned, second_result: result_structs }.merge(test_metadata)
+      bad_result = [false, "Returned two sets of results!", new_res_data]
+      File.write(result_file, JSON.pretty_generate(bad_result))
+
+      return
+    elsif results_returned
+      Shoes::Log.logger("Test Results").warn "Returning identical results twice: #{results_returned.inspect}"
+    end
+
+    Shoes::Log.logger("Test Results").debug("Writing results file #{result_file.inspect} to disk!")
+    File.write(result_file, JSON.pretty_generate(result_structs))
+  end
+end

data/lib/scarpe/shoes_spec.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "scarpe/cats_cradle"
+require "scarpe/components/string_helpers"
+
+require "scarpe/components/unit_test_helpers"
+
+# Test framework code to allow Scarpe to execute Shoes-Spec test code.
+# This will run inside the exe/scarpe child process, then send
+# results back to the parent Minitest process.
+
+module Scarpe::Test
+  # Is it at all reasonable to define more than one test to run in the same Shoes run? Probably not.
+  # They'll leave in-memory residue.
+  def self.run_shoes_spec_test_code(code, class_name: nil, test_name: nil)
+    if @shoes_spec_init
+      raise Shoes::Errors::MultipleShoesSpecRunsError, "Scarpe-Webview can only run a single Shoes spec per process!"
+    end
+
+    @shoes_spec_init = true
+
+    require "scarpe/components/minitest_export_reporter"
+    Minitest::Reporters::ShoesExportReporter.activate!
+
+    class_name ||= ENV["SHOES_MINITEST_CLASS_NAME"] || "TestShoesSpecCode"
+    test_name ||= ENV["SHOES_MINITEST_METHOD_NAME"] || "test_shoes_spec"
+
+    require_relative "cats_cradle"
+
+    # We want Minitest assertions available in the test code.
+    # But this will normally run in a subprocess. So we need
+    # to run Minitest tests and then export the results.
+
+    # We create a test object based on CatsCradle, which will
+    # run the test as straight-line code, wait for appropriate
+    # events and generally make things well-behaved. But the
+    # test DSL isn't CatsCradle. It's based on Minitest and
+    # ShoesSpecTest (see below).
+    #
+    # Note that that means that using CatsCradle to "bounce"
+    # control back and forth for evented tricks isn't really
+    # an option. We may need to revisit all of this later...
+    test_obj = Object.new
+    class << test_obj
+      include Scarpe::Test::CatsCradle
+    end
+    Scarpe::ShoesSpecTest.test_obj = test_obj
+    test_obj.instance_eval do
+      event_init
+
+      on_heartbeat do
+        Minitest.run ARGV
+
+        test_finished_no_results
+        Scarpe::ShoesSpecTest.test_obj = nil
+      end
+    end
+
+    test_class = Class.new(Scarpe::ShoesSpecTest)
+    Object.const_set(Scarpe::Components::StringHelpers.camelize(class_name), test_class)
+    test_name = "test_" + test_name unless test_name.start_with?("test_")
+    test_class.define_method(test_name) do
+      eval(code)
+    end
+  end
+end
+
+# This is based on the CatsCradle proxies initially, but will diverge over time
+class Scarpe::ShoesSpecProxy
+  attr_reader :obj
+  attr_reader :linkable_id
+  attr_reader :display
+
+  JS_EVENTS = [:click, :hover, :leave, :change]
+
+  def initialize(obj)
+    @obj = obj
+    @linkable_id = obj.linkable_id
+    @display = ::Shoes::DisplayService.display_service.query_display_drawable_for(obj.linkable_id)
+
+    unless @display
+      raise "Can't find display widget for #{obj.inspect}!"
+    end
+  end
+
+  def method_missing(method, ...)
+    if @obj.respond_to?(method)
+      self.singleton_class.define_method(method) do |*args, **kwargs, &block|
+        @obj.send(method, *args, **kwargs, &block)
+      end
+      send(method, ...)
+    else
+      super # raise an exception
+    end
+  end
+
+  def trigger(event_name, *args)
+    name = "#{@linkable_id}-#{event_name}"
+    Scarpe::Webview::DisplayService.instance.app.handle_callback(name, *args)
+  end
+
+  JS_EVENTS.each do |ev|
+    define_method "trigger_#{ev}" do |*args|
+      trigger(ev, *args)
+    end
+  end
+
+  def respond_to_missing?(method_name, include_private = false)
+    @obj.respond_to_missing?(method_name, include_private)
+  end
+end
+
+# When running ShoesSpec tests, we create a parent class for all of them
+# with the appropriate convenience methods and accessors.
+class Scarpe::ShoesSpecTest < Minitest::Test
+  include Scarpe::Test::HTMLAssertions
+
+  class << self
+    attr_accessor :test_obj
+  end
+  Shoes::Drawable.drawable_classes.each do |drawable_class|
+    finder_name = drawable_class.dsl_name
+
+    define_method(finder_name) do |*args|
+      app = Shoes::App.instance
+
+      drawables = app.find_drawables_by(drawable_class, *args)
+      raise Shoes::Errors::MultipleDrawablesFoundError, "Found more than one #{finder_name} matching #{args.inspect}!" if drawables.size > 1
+      raise Shoes::Errors::NoDrawablesFoundError, "Found no #{finder_name} matching #{args.inspect}!" if drawables.empty?
+
+      Scarpe::ShoesSpecProxy.new(drawables[0])
+    end
+  end
+  def drawable(*specs)
+    drawables = app.find_drawables_by(*specs)
+    raise Scarpe::MultipleDrawablesFoundError, "Found more than one #{finder_name} matching #{args.inspect}!" if drawables.size > 1
+    raise Scarpe::NoDrawablesFoundError, "Found no #{finder_name} matching #{args.inspect}!" if drawables.empty?
+
+    Scarpe::ShoesSpecProxy.new(drawables[0])
+  end
+
+  def catscradle_dsl(&block)
+    Scarpe::Test::CCInstance.instance.instance_eval(&block)
+  end
+
+  def dom_html
+    catscradle_dsl do
+      wait fully_updated
+      dom_html
+    end
+  end
+
+  # This isn't working. Neither is calling die_after. Are the other fibers not
+  # running or something like that? Should run a test from the command line
+  # and see what's happening... Or check logfiles?
+  def timeout(t_timeout = 5.0, exit_code: -1)
+    catscradle_dsl do
+      t0 = Time.now
+      on_event(:every_heartbeat) do
+        if Time.now - t0 >= t_timeout
+          if exit_code == 0
+            @log.info "Timed out after #{t_timeout} seconds!"
+          else
+            @log.error "Timed out after #{t_timeout} seconds!"
+          end
+          exit exit_code
+        end
+      end
+    end
+  end
+
+  def exit_on_first_heartbeat(exit_code: 0)
+    catscradle_dsl do
+      on_event(:next_heartbeat) do
+        @log.info "Exiting on first heartbeat (exit code #{exit_code})"
+        exit exit_code
+      end
+    end
+  end
+end

data/lib/scarpe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-class Scarpe
-  VERSION = "0.2.1"
+module Scarpe
+  VERSION = "0.3.0"
 end