scarpe 0.2.1 → 0.3.0

data/scarpe-components/lib/scarpe/components/segmented_file_loader.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "scarpe/components/file_helpers"
+
+module Scarpe::Components
+  class SegmentedFileLoader
+    include Scarpe::Components::FileHelpers
+
+    # Add a new segment type (e.g. "catscradle") with a different
+    # file handler.
+    #
+    # @param type [String] the new name for this segment type
+    # @param handler [Object] an object that will be called as obj.call(filename) - often a proc
+    # @return <void>
+    def add_segment_type(type, handler)
+      if segment_type_hash.key?(type)
+        raise Shoes::Errors::InvalidAttributeValueError, "Segment type #{type.inspect} already exists!"
+      end
+
+      segment_type_hash[type] = handler
+    end
+
+    # Return an Array of segment type labels, such as "code" and "app_test".
+    #
+    # @return [Array<String>] the segment type labels
+    def segment_types
+      segment_type_hash.keys
+    end
+
+    # Normally a Shoes application will want to keep the default segment types,
+    # which allow loading a Shoes app and running a test inside. But sometimes
+    # the default handler will be wrong and a library will want to register
+    # its own "shoes" and "app_test" segment handlers, or not have any at all.
+    # For those applications, it makes sense to clear all segment types before
+    # registering its own.
+    #
+    # @return <void>
+    def remove_all_segment_types!
+      @segment_type_hash = {}
+    end
+
+    # Load a .sca file with an optional YAML frontmatter prefix and
+    # multiple file sections which can be treated differently.
+    #
+    # The file loader acts like a proc, being called with .call()
+    # and returning true or false for whether it has handled the
+    # file load. This allows chaining loaders in order and the
+    # first loader to recognise a file will run it.
+    #
+    # @param path [String] the file or directory to treat as a Scarpe app
+    # @return [Boolean] return true if the file is loaded as a segmented Scarpe app file
+    def call(path)
+      return false unless path.end_with?(".scas") || path.end_with?(".sspec")
+
+      file_load(path)
+      true
+    end
+
+    # Segment type handlers can call this to perform an operation after the load
+    # has completed. This is important for ordering, and because loading a Shoes
+    # app often doesn't return. So to have a later section (e.g. tests, additional
+    # data) do something that affects Shoes app loading (e.g. set an env var,
+    # affect the display service) it's important that app loading take place later
+    # in the sequence.
+    def after_load(&block)
+      @after_load ||= []
+      @after_load << block
+    end
+
+    def self.gen_name(segmap)
+      ctr = (1..10_000).detect { |i| !segmap.key?("%5d" % i) }
+      "%5d" % ctr
+    end
+
+    def self.front_matter_and_segments_from_file(contents)
+      require "yaml" # Only load when needed
+      require "English"
+
+      segments = contents.split(/\n-{5,}/)
+      front_matter = {}
+
+      # The very first segment can start with front matter, or with a divider, or with no divider.
+      if segments[0].start_with?("---\n") || segments[0] == "---"
+        # We have YAML front matter at the start. All later segments will have a divider.
+        front_matter = YAML.load segments[0]
+        front_matter ||= {} # If the front matter is just the three dashes it returns nil
+        segments = segments[1..-1]
+      elsif segments[0].start_with?("-----")
+        # We have a divider at the start. Great! We're already well set up for this case.
+      elsif segments.size == 1
+        # No front matter, no divider, a single unnamed segment. No more parsing needed.
+        return [{}, { "" => segments[0] }]
+      else
+        # No front matter, no divider before the first segment, multiple segments.
+        # We'll add an artificial divider to the first segment for uniformity.
+        segments = ["-----\n" + segments[0]] + segments[1..-1]
+      end
+
+      segmap = {}
+      segments.each do |segment|
+        if segment =~ /\A-* +(.*?)\n/
+          # named segment with separator
+          name = ::Regexp.last_match(1)
+
+          raise("Duplicate segment name: #{name.inspect}!") if segmap.key?(name)
+
+          segmap[name] = ::Regexp.last_match.post_match
+        elsif segment =~ /\A-* *\n/
+          # unnamed segment with separator
+          segmap[gen_name(segmap)] = ::Regexp.last_match.post_match
+        else
+          raise Scarpe::InternalError, "Internal error when parsing segments in segmented app file! seg: #{segment.inspect}"
+        end
+      end
+
+      [front_matter, segmap]
+    end
+
+    def file_load(path)
+      contents = File.read(path)
+
+      front_matter, segmap = self.class.front_matter_and_segments_from_file(contents)
+
+      if segmap.empty?
+        raise Scarpe::FileContentError, "Illegal segmented Scarpe file: must have at least one code segment, not just front matter!"
+      end
+
+      if front_matter[:segments]
+        if front_matter[:segments].size != segmap.size
+          raise Scarpe::FileContentError, "Number of front matter :segments must equal number of file segments!"
+        end
+      else
+        if segmap.size > 2
+          raise Scarpe::FileContentError, "Segmented files with more than two segments have to specify what they're for!"
+        end
+
+        # Set to default of shoes code only or shoes code and app test code.
+        front_matter[:segments] = segmap.size == 2 ? ["shoes", "app_test"] : ["shoes"]
+      end
+
+      # Match up front_matter[:segments] with the segments, or use the default of shoes and app_test.
+
+      sth = segment_type_hash
+      sv = segmap.values
+
+      tf_specs = []
+      front_matter[:segments].each.with_index do |seg_type, idx|
+        unless sth.key?(seg_type)
+          raise Scarpe::FileContentError, "Unrecognized segment type #{seg_type.inspect}! No matching segment type available!"
+        end
+
+        tf_specs << ["scarpe_#{seg_type}_segment_contents", sv[idx]]
+      end
+
+      with_tempfiles(tf_specs) do |filenames|
+        filenames.each.with_index do |filename, idx|
+          seg_name = front_matter[:segments][idx]
+          sth[seg_name].call(filename)
+        end
+
+        # Need to call @after_load hooks while tempfiles still exist
+        if @after_load && !@after_load.empty?
+          @after_load.each(&:call)
+          @after_load = []
+        end
+      end
+    end
+
+    # The hash of segment type labels mapped to handlers which will be called.
+    # This could be called by a display service, a test framework or similar
+    # code that wants to define a non-Scarpe-standard file format.
+    #
+    # @return [Hash<String, Object>] the name/handler pairs
+    def segment_type_hash
+      @segment_handlers ||= {
+        "shoes" => proc { |seg_file| after_load { load seg_file } },
+        "app_test" => proc do |seg_file|
+          ENV["SHOES_SPEC_TEST"] = seg_file
+          ENV["SHOES_MINITEST_EXPORT_FILE"] = "sspec.json"
+        end,
+      }
+    end
+  end
+end
+
+# You can add additional segment types to the segmented file loader
+# loader = Scarpe::Components::SegmentedFileLoader.new
+# loader.add_segment_type "capybara", proc { |seg_file| load_file_as_capybara(seg_file) }
+# Shoes.add_file_loader loader

data/scarpe-components/lib/scarpe/components/string_helpers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Scarpe; module Components; end; end
+module Scarpe::Components::StringHelpers
+  # Cut down from Rails camelize
+  def self.camelize(string)
+    string = string.sub(/^[a-z\d]*/, &:capitalize)
+    string.gsub(/(?:_|(\/))([a-z\d]*)/) { "#{::Regexp.last_match(1)}#{::Regexp.last_match(2).capitalize}" }
+  end
+end

data/scarpe-components/lib/scarpe/components/tiranti.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+# In Italian, tiranti are bootstraps -- the literal pull-on-a-boot kind, not a step to something better.
+# Tiranti.rb builds on calzini.rb, but renders a Bootstrap-decorated version of the HTML output.
+# You would ordinarily set either Calzini or Tiranti as the top-level HTML renderer, not both.
+# You'll include both if you use Tiranti, because it falls back to Calzini for a lot of its rendering.
+
+require "scarpe/components/calzini"
+
+# The Tiranti module expects to be included by a class defining
+# the following methods:
+#
+#     * html_id - the HTML ID for the specific rendered DOM object
+#     * handler_js_code(event_name) - the JS handler code for this DOM object and event name
+#     * (optional) display_properties - the display properties for this object, unless overridden in render()
+module Scarpe::Components::Tiranti
+  include Scarpe::Components::Calzini
+  extend self
+
+  # Currently we're using Bootswatch 5
+  BOOTSWATCH_THEMES = [
+    "cerulean",
+    "cosmo",
+    "cyborg",
+    "darkly",
+    "flatly",
+    "journal",
+    "litera",
+    "lumen",
+    "lux",
+    "materia",
+    "minty",
+    "morph",
+    "pulse",
+    "quartz",
+    "sandstone",
+    "simplex",
+    "sketchy",
+    "slate",
+    "solar",
+    "spacelab",
+    "superhero",
+    "united",
+    "vapor",
+    "yeti",
+    "zephyr",
+  ]
+
+  BOOTSWATCH_THEME = ENV["SCARPE_BOOTSTRAP_THEME"] || "sketchy"
+
+  def empty_page_element
+    <<~HTML
+      <html>
+        <head id='head-wvroot'>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+          <link rel="stylesheet" href="https://bootswatch.com/5/#{BOOTSWATCH_THEME}/bootstrap.css">
+          <link rel="stylesheet" href="https://bootswatch.com/_vendor/bootstrap-icons/font/bootstrap-icons.min.css">
+          <style id='style-wvroot'>
+            /** Style resets **/
+            body {
+              height: 100%;
+              overflow: hidden;
+            }
+          </style>
+        </head>
+        <body id='body-wvroot'>
+          <div id='wrapper-wvroot'></div>
+
+          <script src="https://bootswatch.com/_vendor/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
+        </body>
+      </html>
+    HTML
+  end
+
+  # def render_stack
+  # end
+  # def render_flow
+  # end
+
+  # How do we want to handle theme-specific colours and primary/secondary buttons in Bootstrap?
+  # "Disabled" could be checked in properties. Is there any way we can/should use "outline" buttons?
+  def button_element(props)
+    HTML.render do |h|
+      h.button(id: html_id, type: "button", class: "btn btn-primary", onclick: handler_js_code("click"), style: button_style(props)) do
+        props["text"]
+      end
+    end
+  end
+
+  private
+
+  def button_style(props)
+    styles = drawable_style(props)
+
+    styles[:"background-color"] = props["color"] if props["color"]
+    styles[:"padding-top"] = props["padding_top"] if props["padding_top"]
+    styles[:"padding-bottom"] = props["padding_bottom"] if props["padding_bottom"]
+    styles[:color] = props["text_color"] if props["text_color"]
+    styles[:width] = dimensions_length(props["width"]) if props["width"]
+    styles[:height] = dimensions_length(props["height"]) if props["height"]
+    styles[:"font-size"] = props["font_size"] if props["font_size"]
+
+    styles[:top] = dimensions_length(props["top"]) if props["top"]
+    styles[:left] = dimensions_length(props["left"]) if props["left"]
+    styles[:position] = "absolute" if props["top"] || props["left"]
+    styles[:"font-size"] = dimensions_length(text_size(props["size"])) if props["size"]
+    styles[:"font-family"] = props["font"] if props["font"]
+
+    styles
+  end
+
+  public
+
+  def alert_element(props)
+    onclick = handler_js_code(props["event_name"] || "click")
+
+    HTML.render do |h|
+      h.div(id: html_id, class: "modal", tabindex: -1, role: "dialog", style: alert_overlay_style(props)) do
+        h.div(class: "modal-dialog", role: "document") do
+          h.div(class: "modal-content", style: alert_modal_style) do
+            h.div(class: "modal-header") do
+              h.h5(class: "modal-title") { "Alert" }
+              h.button(type: "button", class: "close", data_dismiss: "modal", aria_label: "Close") do
+                h.span(aria_hidden: "true") { "&times;" }
+              end
+            end
+            h.div(class: "modal-body") do
+              h.p { props["text"] }
+            end
+            h.div(class: "modal-footer") do
+              h.button(type: "button", onclick:, class: "btn btn-primary") { "OK" }
+              #h.button(type: "button", class: "btn btn-secondary") { "Close" }
+            end
+          end
+        end
+      end
+    end
+  end
+
+  def check_element(props)
+    HTML.render do |h|
+      h.div class: "form-check" do
+        h.input type: :checkbox,
+          id: html_id,
+          class: "form-check-input",
+          onclick: handler_js_code("click"),
+          value: props["text"],
+          checked: props["checked"],
+          style: drawable_style(props)
+      end
+    end
+  end
+
+  def progress_element(props)
+    HTML.render do |h|
+      h.div(class: "progress", style: "width: 90%") do
+        pct = "%.1f" % ((props["fraction"] || 0.0) * 100.0)
+        h.div(
+          class: "progress-bar progress-bar-striped progress-bar-animated",
+          role: "progressbar",
+          "aria-valuenow": pct,
+          "aria-valuemin": 0,
+          "aria-valuemax": 100,
+          style: "width: #{pct}%",
+        )
+      end
+    end
+  end
+
+  # para_element is a bit of a hard one, since it does not-entirely-trivial
+  # mapping between display objects and IDs. But we don't want Calzini
+  # messing with the display service or display objects.
+  def para_element(props, &block)
+    tag, opts = para_elt_and_opts(props)
+
+    HTML.render do |h|
+      h.send(tag, **opts, &block)
+    end
+  end
+
+  private
+
+  ELT_AND_SIZE = {
+    inscription: [:p, 10],
+    ins: [:p, 10],
+    para: [:p, 12],
+    caption: [:p, 14],
+    tagline: [:p, 18],
+    subtitle: [:h3, 26],
+    title: [:h2, 34],
+    banner: [:h1, 48],
+  }.freeze
+
+  def para_elt_and_opts(props)
+    elt, size = para_elt_and_size(props)
+    size = dimensions_length(size)
+
+    para_style = drawable_style(props).merge({
+      color: rgb_to_hex(props["stroke"]),
+      "font-size": para_font_size(props),
+      "font-family": props["font"],
+    }.compact)
+
+    opts = (props["html_attributes"] || {}).merge(id: html_id, style: para_style)
+
+    [elt, opts]
+  end
+
+  def para_elt_and_size(props)
+    return [:p, nil] unless props["size"]
+
+    ps = props["size"].to_s.to_sym
+    if ELT_AND_SIZE.key?(ps)
+      ELT_AND_SIZE[ps]
+    else
+      sz = props["size"].to_i
+      if sz > 18
+        [:h2, sz]
+      else
+        [:p, sz]
+      end
+    end
+  end
+end

data/scarpe-components/lib/scarpe/components/unit_test_helpers.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "json"
+require "fileutils"
+
+require "scarpe/components/file_helpers"
+
+module Scarpe::Test; end
+
+# We want test failures set up once *total*, not per Minitest::Test. So an instance var
+# doesn't do it.
+ALREADY_SET_UP_LOGGED_TEST_FAILURES = { setup: false }
+
+# General helpers for general usage.
+# Helpers here should *not* use Webview-specific functionality.
+# The intention is that these are helpers for various Scarpe display
+# services that do *not* necessarily use Webview.
+
+module Scarpe::Test::Helpers
+  # Very useful for tests
+  include Scarpe::Components::FileHelpers
+
+  # Temporarily set env vars for the block of code inside. The old environment
+  # variable values will be restored after the block finishes.
+  #
+  # @param envs [Hash<String,String>] A hash of environment variable names and values
+  def with_env_vars(envs)
+    old_env = {}
+    envs.each do |k, v|
+      old_env[k] = ENV[k]
+      ENV[k] = v
+    end
+    yield
+  ensure
+    old_env.each { |k, v| ENV[k] = v }
+  end
+end
+
+# This test will save extensive logs in case of test failure.
+# Note that it defines setup/teardown methods. If you want
+# multiple setup/teardowns from multiple places to happen you
+# may need to explictly call (e.g. with logged_test_setup/teardown)
+# to ensure everything you want happens.
+module Scarpe::Test::LoggedTest
+  def self.included(includer)
+    class << includer
+      attr_accessor :logger_dir
+    end
+  end
+
+  def file_id
+    "#{self.class.name}_#{self.name}"
+  end
+
+  # This should be called by the test during setup to make sure that
+  # failure logs will be saved if this test fails. It makes sure the
+  # log config will save all logs from all sources, but keeps a copy
+  # of the old log config to restore after the test is finished.
+  #
+  # @return [void]
+  def logged_test_setup
+    # Make sure test failures will be saved at the end of the run.
+    # Delete stale test failures and logging only the *first* time this is called.
+    set_up_test_failures
+
+    @normal_log_config = Shoes::Log.current_log_config
+    Shoes::Log.configure_logger(log_config_for_test)
+
+    Shoes::Log.logger("LoggedScarpeTest").info("Test: #{self.class.name}##{self.name}")
+  end
+
+  # If you include this module and don't override setup/teardown, everything will
+  # work fine. But if you need more setup/teardown steps, you can do that too.
+  #
+  # The setup method guarantees that just including this module will do setup
+  # automatically. If you override it, be sure to call `super` or `logged_test_setup`.
+  #
+  # @return [void]
+  def setup
+    logged_test_setup
+  end
+
+  # After the test has finished, this will restore the old log configuration.
+  # It will also save the logfiles, but only if the test failed, not if it
+  # succeeded or was skipped.
+  #
+  # @return [void]
+  def logged_test_teardown
+    # Restore previous log config
+    Shoes::Log.configure_logger(@normal_log_config)
+
+    if self.failure
+      save_failure_logs
+    else
+      remove_unsaved_logs
+    end
+  end
+
+  # Make sure that, by default, #logged_test_teardown will be called for teardown.
+  # If a class overrides teardown, it should also call `super` or `logged_test_teardown`
+  # to make sure this still happens.
+  #
+  # @return [void]
+  def teardown
+    logged_test_teardown
+  end
+
+  # Set additional LoggedTest configuration for specific logs to separate or save.
+  # This is normally going to be display-service-specific log components.
+  # Note that this only really works with the modular logger or another logger
+  # that does something useful with the log config. The simple print logger
+  # doesn't do a lot with it.
+  def extra_log_config=(additional_log_config)
+    @additional_log_config = additional_log_config
+  end
+
+  # This is the log config that LoggedTests use. It makes sure all components keep all
+  # logs, but also splits the logs into several different files for later ease of scanning.
+  #
+  # TODO: this shouldn't directly include any Webview entries like WebviewAPI or
+  #     CatsCradle. Those should be overridden in Webview.
+  #
+  # @return [Hash] the log config
+  def log_config_for_test
+    {
+      "default" => ["debug", "logger/test_failure_#{file_id}.log"],
+      "DisplayService" => ["debug", "logger/test_failure_display_service_#{file_id}.log"],
+    }.merge(@additional_log_config || {})
+  end
+
+  # The list of logfiles that should be saved. Normally this is called internally by the
+  # class, not externally from elsewhere.
+  #
+  # This could be a lot simpler except I want to only update the file list in one place,
+  # log_config_for_test(). Having a single spot should (I hope) make it a lot friendlier to
+  # add more logfiles for different components, logged API objects, etc.
+  def saved_log_files
+    lc = log_config_for_test
+    log_outfiles = lc.values.map { |_level, loc| loc }
+    log_outfiles.select { |s| s.start_with?("logger/") }.map { |s| s.delete_prefix("logger/") }
+  end
+
+  # Make sure that test failure logs will be noticed, and a message will be printed,
+  # if any logged tests fail. This needs to be called at least once in any Minitest-enabled
+  # process using logged tests.
+  #
+  # @return [void]
+  def set_up_test_failures
+    return if ALREADY_SET_UP_LOGGED_TEST_FAILURES[:setup]
+
+    log_dir = self.class.logger_dir
+    raise(Scarpe::MustOverrideMethod, "Must set logger directory!") unless log_dir
+    raise(Scarpe::NoSuchFile, "Can't find logger directory!") unless File.directory?(log_dir)
+
+    ALREADY_SET_UP_LOGGED_TEST_FAILURES[:setup] = true
+    # Delete stale test failures, if any, before starting the first failure-logged test
+    Dir["#{log_dir}/test_failure*.log"].each { |fn| File.unlink(fn) }
+
+    Minitest.after_run do
+      # Print test failure notice to console
+      unless Dir["#{log_dir}/test_failure*.out.log"].empty?
+        puts "Some tests have failed! See #{log_dir}/test_failure*.out.log for test logs!"
+      end
+
+      # Remove un-saved test logs
+      Dir["#{log_dir}/test_failure*.log"].each do |f|
+        next if f.include?(".out.log")
+
+        File.unlink(f) if File.exist?(f)
+      end
+    end
+  end
+
+  # Failure log output location for a given file path. This is normally used internally to this
+  # class, not externally.
+  #
+  # @return [String] the output path
+  def logfail_out_loc(filepath)
+    # Add a .out prefix before final .log
+    out_loc = filepath.gsub(%r{.log\Z}, ".out.log")
+
+    if out_loc == filepath
+      raise Shoes::Errors::InvalidAttributeValueError, "Something is wrong! Could not figure out failure-log output path for #{filepath.inspect}!"
+    end
+
+    if File.exist?(out_loc)
+      raise Scarpe::DuplicateFileError, "Duplicate test file #{out_loc.inspect}? This file should *not* already exist!"
+    end
+
+    out_loc
+  end
+
+  # Save the failure logs in the appropriate place(s). This is normally used internally, not externally.
+  #
+  # @return [void]
+  def save_failure_logs
+    saved_log_files.each do |log_file|
+      full_loc = File.expand_path("#{self.class.logger_dir}/#{log_file}")
+      # TODO: we'd like to skip 0-length logfiles. But also Logging doesn't flush. For now, ignore.
+      next unless File.exist?(full_loc)
+
+      FileUtils.mv full_loc, logfail_out_loc(full_loc)
+    end
+  end
+
+  # Remove unsaved failure logs. This is normally used internally, not externally.
+  #
+  # @return [void]
+  def remove_unsaved_logs
+    Dir["#{self.class.logger_dir}/test_failure*.log"].each do |f|
+      next if f.include?(".out.log") # Don't delete saved logs
+
+      File.unlink(f)
+    end
+  end
+end
+
+module Scarpe::Test::HTMLAssertions
+  # Assert that `actual_html` is the same as `expected_tag` with `opts`.
+  # This uses Scarpe's HTML tag-based renderer to render the tag and options
+  # into text, and valides that the text is the same.
+  #
+  # @see Scarpe::Components::HTML.render
+  #
+  # @param actual_html [String] the html to compare to
+  # @param expected_tag [String,Symbol] the HTML tag, used to send a method call
+  # @param opts keyword options passed to the tag method call
+  # @yield block passed to the tag method call.
+  # @return [void]
+  def assert_html(actual_html, expected_tag, **opts, &block)
+    expected_html = Scarpe::Components::HTML.render do |h|
+      h.public_send(expected_tag, opts, &block)
+    end
+
+    assert_equal expected_html, actual_html
+  end
+
+  # Assert that `actual_html` includes `expected_tag` with `opts`.
+  # This uses Scarpe's HTML tag-based renderer to render the tag and options
+  # into text, and valides that the full HTML contains that tag.
+  #
+  # @see Scarpe::Components::HTML.render
+  #
+  # @param actual_html [String] the html to compare to
+  # @param expected_tag [String,Symbol] the HTML tag, used to send a method call
+  # @param opts keyword options passed to the tag method call
+  # @yield block passed to the tag method call.
+  # @return [void]
+  def assert_contains_html(actual_html, expected_tag, **opts, &block)
+    expected_html = Scarpe::Components::HTML.render do |h|
+      h.public_send(expected_tag, opts, &block)
+    end
+
+    assert actual_html.include?(expected_html), "Expected #{actual_html.inspect} to include #{expected_html.inspect}!"
+  end
+end

data/scarpe-components/lib/scarpe/components/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Scarpe
+  module Components
+    VERSION = "0.3.0"
+  end
+end