brut 0.0.20 → 0.0.22

data/lib/brut/spec_support/component_support.rb

@@ -8,15 +8,23 @@ module Brut::SpecSupport::ComponentSupport
   include Brut::SpecSupport::FlashSupport
   include Brut::SpecSupport::SessionSupport
   include Brut::SpecSupport::ClockSupport
-  include Brut::I18n::BaseMethods
+  include Brut::I18n::ForBackEnd # XXX: Maybe need a "ForSpecs"?
 
-  # Render a component into its text representation.  This mimics what happens when a component is used
-  # inside a template.  You typically don't want this, but should use {#render_and_parse}, since that will
-  # parse the HTML.
-  def render(component,&block)
+  # Generate a component or page into its text representation.  This mimics what happens when Brut generates
+  # the page or component.  Note that pages don't always return Strings, for example if `before_generate`
+  # returns a redirect.
+  #
+  # When testing a component, call {#generate_and_parse} instead of this. When testing a page that will
+  # always generate HTML, again call {#generate_and_parse}.
+  #
+  # When using this, there are some matchers that can help assert what the page has done:
+  #
+  # * `have_redirected_to` to check that the page redirected elsewhere, instead of generating HTML.
+  # * `have_returned_http_status` to check that the page returned an HTTP status instead of generating HTML.
+  def generate_result(component,&block)
     if component.kind_of?(Brut::FrontEnd::Page)
       if !block.nil?
-        raise "pages do not accept blocks - do not pass one to render_and_parse"
+        raise "pages do not accept blocks - do not pass one to generate_result or generate_and_parse"
       end
       component.handle!
     else
@@ -30,34 +38,40 @@ module Brut::SpecSupport::ComponentSupport
     end
   end
 
-  # Render a component and parse it into a Nokogiri Node for examination.
+  # Render a component or page and parse it into a Nokogiri Node for examination.  There are several matchers
+  # you can use with the return value of this method:
+  #
+  # * `have_html_attribute` to check if a node has a value for an HTML attribute.
+  # * `have_i18n_string` to check if the text of a node is exactly an i18n string you have set up.
+  # * `have_link_to` to check that a node contains a link to a page or page routing
+  #
   #
   # @example
   #
-  #   result = render_and_parse(HeaderComponent.new(title: "Hello!")
+  #   result = generate_and_parse(HeaderComponent.new(title: "Hello!")
   #   expect(result.e!("h1").text).to eq("Hello!")
   #
   # @example Using context
-  #   result = render_and_parse(TableRow.new([ "one", "two" ]), context: "tbody")
+  #   result = generate_and_parse(TableRow.new([ "one", "two" ]), context: "tbody")
   #
-  # @param [Brut::FrontEnd::Component] component the component instance you wish to render. This should be set up to simulate the test
+  # @param [Brut::FrontEnd::Component] component the component instance you wish to generate. This should be set up to simulate the test
   # you are running.
   # @yield if the component requires or accepts a yielded block, this is how you do that in the test.
   # @return [Brut::SpecSupport::EnhancedNode] a wrapper around a Nokogiri node to provide convienience methods.
-  def render_and_parse(component,&block)
-    rendered_text = render(component,&block)
+  def generate_and_parse(component,&block)
+    rendered_text = generate_result(component,&block)
     if !rendered_text.kind_of?(String)
       if rendered_text.kind_of?(URI::Generic)
-        raise "#{component.class} redirected to #{rendered_text} instead of rendering"
+        raise "#{component.class} redirected to #{rendered_text} instead of generating HTML"
       else
-        raise "#{component.class} returned a #{rendered_text.class} - you should not attempt to parse this.  Instead, call render(component)"
+        raise "#{component.class} returned a #{rendered_text.class} - you should not attempt to parse this.  Instead, call generate(component)"
       end
     end
     nokogiri_node = Nokogiri::HTML5(rendered_text)
     if !component.kind_of?(Brut::FrontEnd::Page)
       nokogiri_node = Nokogiri::HTML5.fragment(rendered_text.to_s.chomp, max_errors: 100, context: "template")
       if nokogiri_node.errors.any?
-        raise "#{component.class} render invalid HTML:\n\n#{rendered_text}\n\nErrors: #{nokogiri_node.errors.join(", ")}"
+        raise "#{component.class} generated invalid HTML:\n\n#{rendered_text}\n\nErrors: #{nokogiri_node.errors.join(", ")}"
       end
 
       non_blank_text_elements = nokogiri_node.children.select { |element|
@@ -70,7 +84,7 @@ module Brut::SpecSupport::ComponentSupport
       }
 
       if non_blank_text_elements.size != 1
-        raise "#{component.class} rendered #{non_blank_text_elements.size} elements other than blank text:\n\n#{non_blank_text_elements.map(&:name)}. Components should render a single element:\n#{rendered_text}"
+        raise "#{component.class} generated #{non_blank_text_elements.size} elements other than blank text:\n\n#{non_blank_text_elements.map(&:name)}. Components should generate a single element:\n#{rendered_text}"
       end
       nokogiri_node = non_blank_text_elements[0]
     end

data/lib/brut/spec_support/e2e_support.rb

@@ -1,4 +1,4 @@
 # Convienience methods for writing E2E tests
 module Brut::SpecSupport::E2eSupport
-  include Brut::I18n::BaseMethods
+  include Brut::I18n::ForBackEnd
 end

data/lib/brut/spec_support/e2e_test_server.rb

@@ -1,3 +1,6 @@
+require "socket"
+require "timeout"
+
 # Manages running the app in test mode for the purposes of running End-to-End tests against it.
 class Brut::SpecSupport::E2ETestServer
   include SemanticLogger::Loggable

data/lib/brut/spec_support/general_support.rb

@@ -5,6 +5,9 @@ module Brut::SpecSupport::GeneralSupport
   end
 
   module ClassMethods
+    # Used to indicate that a test does need to be written, but that
+    # its implementation can wait until a given date before causing
+    # `bin/ci` to fail the test suite.
     def implementation_is_needed(check_again_at:)
       check_again_at = if check_again_at.kind_of?(Time)
                          check_again_at

data/lib/brut/spec_support/handler_support.rb

@@ -2,7 +2,12 @@ require_relative "flash_support"
 require_relative "clock_support"
 require_relative "session_support"
 
-# Convienience methods for testing handlers.
+# Convienience methods for testing handlers.  When testing handlers, the following matchers may be useful:
+#
+#
+# * `have_redirected_to` to check that the handler redirected to a give URI
+# * `have_rendered` to check that the handler rendered a specific page
+# * `have_returned_http_status` to check that the handler returned an HTTP status
 module Brut::SpecSupport::HandlerSupport
   include Brut::SpecSupport::FlashSupport
   include Brut::SpecSupport::ClockSupport

data/lib/brut/spec_support/matcher.rb

@@ -10,4 +10,5 @@ require_relative "matchers/have_i18n_string"
 require_relative "matchers/have_redirected_to"
 require_relative "matchers/have_rendered"
 require_relative "matchers/have_returned_http_status"
+require_relative "matchers/have_returned_rack_response"
 require_relative "matchers/have_link_to"

data/lib/brut/spec_support/matchers/be_page_for.rb

@@ -1,3 +1,4 @@
+# E2E
 RSpec::Matchers.define :be_page_for do |klass|
   match do |page|
     meta = page.locator("meta[name='class']")

data/lib/brut/spec_support/matchers/have_html_attribute.rb

@@ -1,3 +1,4 @@
+# Component/Page
 RSpec::Matchers.define :have_html_attribute do |attribute|
   if attribute.kind_of?(Hash)
     if attribute.keys.length != 1

data/lib/brut/spec_support/matchers/have_i18n_string.rb

@@ -1,9 +1,6 @@
+# Component/Page
 RSpec::Matchers.define :have_i18n_string do |key,**args|
-  include Brut::I18n::ForHTML
-
-  # XXX: Figure out how to not have to do this
-  def safe(x) = x
-  def capture(&block) = block.()
+  include Brut::I18n::ForBackEnd
 
   match do |nokogiri_node|
 

data/lib/brut/spec_support/matchers/have_link_to.rb

@@ -1,3 +1,4 @@
+# Component/Page
 RSpec::Matchers.define :have_link_to do |page_klass,**args|
   match do |node|
     node.css("a[href='#{page_klass.routing(**args)}']").any?

data/lib/brut/spec_support/matchers/have_redirected_to.rb

@@ -1,3 +1,4 @@
+# Page
 RSpec::Matchers.define :have_redirected_to do |page_or_uri,**page_params|
   match do |result|
     if page_or_uri.kind_of?(URI)

data/lib/brut/spec_support/matchers/have_rendered.rb

@@ -1,3 +1,4 @@
+# Handler
 RSpec::Matchers.define :have_rendered do |component_or_page|
   match do |result|
     result.class.ancestors.include?(component_or_page)

data/lib/brut/spec_support/matchers/have_returned_rack_response.rb

@@ -0,0 +1,44 @@
+# Handler
+RSpec::Matchers.define :have_returned_rack_response do |http_status: :any, headers: :any, body: :any|
+  match do |result|
+    case result
+    in [ response_status, response_headers, response_body ]
+      http_status_match = http_status == :any || response_status == http_status
+      headers_match     = headers == :any || response_headers == headers
+      body_match        = body == :any || response_body == body
+
+      http_status_match && headers_match && body_match
+    else
+      false
+    end
+  end
+
+  failure_message do |result|
+    case result
+    in [ response_status, response_headers, response_body ]
+      http_status_match = http_status == :any || response_status == http_status
+      headers_match     = headers == :any || response_headers == headers
+      body_match        = body == :any || response_body == body
+      errors = [
+        http_status_match ? nil : "HTTP status #{response_status} did not match #{http_status}",
+        headers_match     ? nil : "Headers #{response_headers} did not match #{headers}",
+        body_match        ? nil : "Body #{response_body} did not match #{body}",
+      ].compact.join(", ")
+    else
+      if result.kind_of?(Array)
+        "Response was a #{result.class} of length #{result.length}, which could not be interpreted as a Rack response."
+      else
+        "Response was a #{result.class}, which could not be interpreted as a Rack response."
+      end
+    end
+  end
+  failure_message_when_negated do |result|
+    case result
+    in [ response_status, response_headers, response_body ]
+      "Response was a Rack response and/or array of size 3"
+    else
+      "failure_message_when_negated encounterd a code-path for a non-Rack response, which should not have happened when have_returned_rack_response was negated"
+    end
+  end
+
+end

data/lib/brut/spec_support.rb

@@ -1,7 +1,7 @@
 module Brut
   # Spec Support holds various matchers and helpers useful when writing tests with RSpec.
   # Note that this module and it's contents aren't loaded by default when you `require "brut"`.
-  # Your app's `spec_helper.rb` should require these properly.
+  # Your app's `spec_helper.rb` should require these explicitly.
   module SpecSupport
   end
 end

data/lib/brut/version.rb

@@ -1,4 +1,4 @@
 module Brut
   # @!visibility private
-  VERSION = "0.0.20"
+  VERSION = "0.0.22"
 end

data/lib/brut.rb

@@ -1,10 +1,11 @@
 require_relative "brut/framework"
 
-# Brut is a way to make web apps with Ruby. It focuses on web standards, object-orientation, and other fundamentals. Brut seeks to
-# minimize abstractions where possible.
+# Brut is a way to make web apps with Ruby. It focuses on web standards, object-orientation, and other
+# fundamentals. Brut seeks to minimize abstractions where possible.
 #
-# Brut encourages the use of the browser's technology and encourages you to build a web app based on good practices that are set up by
-# default.  Brut may not look easy, but it aims to be simple.  It attempts to minimize dependencies and complexity, while leveraging
+# Brut encourages the use of the browser's technology and encourages you to build a web app based
+# on good practices that are set up by default.  Brut may not look easy, but it aims to be simple.
+# It attempts to minimize dependencies and complexity, while leveraging
 # common tested Ruby libraries related to web development.
 #
 # Have fun!

data/lib/sequel/extensions/brut_migrations.rb

@@ -23,7 +23,7 @@ module Sequel
             run %{
               comment on table #{args.first} is #{literal args.last[:comment]}
             }
-          else
+          elsif args.first != "schema_info"
             raise ArgumentError, "Table #{args.first} must have a comment"
           end
           if args.last[:external_id]