constable-rails 0.1.0 → 1.1.0

data/lib/constable/matchers.rb

@@ -33,7 +33,7 @@ module Constable
       not_found: 404, method_not_allowed: 405, not_acceptable: 406,
       request_timeout: 408, conflict: 409, gone: 410, precondition_failed: 412,
       payload_too_large: 413, unsupported_media_type: 415, im_a_teapot: 418,
-      unprocessable_entity: 422, locked: 423, too_many_requests: 429,
+      unprocessable_entity: 422, unprocessable_content: 422, locked: 423, too_many_requests: 429,
       internal_server_error: 500, not_implemented: 501, bad_gateway: 502,
       service_unavailable: 503, gateway_timeout: 504
     }.freeze
@@ -44,6 +44,22 @@ module Constable
       error: (500..599), server_error: (500..599)
     }.freeze
 
+    # Rack renames statuses -- 422 became :unprocessable_content in Rack 3.1, and Rails
+    # 8.1 deprecates the old spelling -- so the table above is a floor, not the whole
+    # truth. Anything Rack knows is accepted, which means a rename costs no release here.
+    def self.rack_status_codes
+      return @rack_status_codes if defined?(@rack_status_codes)
+
+      @rack_status_codes =
+        if defined?(::Rack::Utils::SYMBOL_TO_STATUS_CODE)
+          ::Rack::Utils::SYMBOL_TO_STATUS_CODE.transform_keys(&:to_sym)
+        else
+          {}
+        end
+    rescue StandardError
+      @rack_status_codes = {}
+    end
+
     MAX_INSPECT = 200
     MAX_BODY    = 800
 
@@ -222,7 +238,9 @@ module Constable
         case expected
         when Integer then expected
         when /\A\d+\z/ then expected.to_i
-        else HTTP_STATUS_CODES[expected.to_s.to_sym]
+        else
+          name = expected.to_s.to_sym
+          HTTP_STATUS_CODES[name] || Matchers.rack_status_codes[name]
         end
       end
 
@@ -345,6 +363,104 @@ module Constable
       end
     end
 
+    # `be_within(0.5).of(10)` -- a matcher spelled across two calls, so it has to survive
+    # the first one and collect its subject on the second.
+    #
+    # Registering it matters for a second reason: without an entry, `be_within` fell
+    # through to the be_*/have_* predicate fallback, which happily built a
+    # PredicateDeferred and then blew up on `.of` with a NoMethodError naming an internal
+    # class rather than the matcher the author actually wrote.
+    class WithinDeferred < Deferred
+      def of(expected)
+        @expected = expected
+        @expected_set = true
+        self
+      end
+
+      def matches?(actual)
+        unless @expected_set
+          return [false, "be_within(#{@args.first.inspect}) is incomplete -- it needs .of: " \
+                         "attest(value).to be_within(0.5).of(10)", nil]
+        end
+
+        delta = @args.first
+        difference = (actual - @expected).abs
+        return true if difference <= delta
+
+        [false, "expected #{Matchers.describe(actual)} to be within #{delta.inspect} of " \
+                "#{Matchers.describe(@expected)}, but it differed by #{difference}", nil]
+      rescue NoMethodError, TypeError, ArgumentError
+        [false, "expected #{Matchers.describe(actual)} to be within #{delta.inspect} of " \
+                "#{Matchers.describe(@expected)}, but a #{actual.class} cannot be subtracted", nil]
+      end
+
+      def description
+        return "be within #{@args.first.inspect} of #{Matchers.describe(@expected)}" if @expected_set
+
+        "be within #{@args.first.inspect} of (nothing -- .of was never called)"
+      end
+    end
+
+    # `be`, in its three RSpec spellings:
+    #
+    #   attest(x).to be(other)   identity -- the same object, not merely equal
+    #   attest(x).to be >= 0     an operator comparison
+    #   attest(x).to be          truthiness
+    #
+    # `==` is deliberately not among the operators. Defining it on a matcher object
+    # breaks equality everywhere the object is compared, and `eq` already says it.
+    class BeDeferred < Deferred
+      COMPARISONS = %i[< <= > >=].freeze
+
+      COMPARISONS.each do |operator|
+        define_method(operator) do |operand|
+          @operator = operator
+          @operand  = operand
+          self
+        end
+      end
+
+      def matches?(actual)
+        return compare(actual) if @operator
+        # `.empty?`, not `.any?`: `[nil].any?` is false, which would send `be(nil)` down
+        # the truthiness branch and assert the opposite of what was written.
+        return identity(actual) unless @args.empty?
+        return true if actual
+
+        [false, "expected a truthy value, but got #{actual.inspect}", nil]
+      end
+
+      def description
+        return "be #{@operator} #{Matchers.describe(@operand)}" if @operator
+        return "be #{Matchers.describe(@args.first)}" unless @args.empty?
+
+        "be truthy"
+      end
+
+      private
+
+      def compare(actual)
+        return true if actual.public_send(@operator, @operand)
+
+        [false, "expected #{Matchers.describe(actual)} to be #{@operator} " \
+                "#{Matchers.describe(@operand)}", nil]
+      rescue NoMethodError, ArgumentError, TypeError
+        [false, "expected #{Matchers.describe(actual)} to be #{@operator} " \
+                "#{Matchers.describe(@operand)}, but a #{actual.class} cannot be compared", nil]
+      end
+
+      # `be` is identity, not equality -- that distinction is the only reason to reach for
+      # it over `eq`, so the failure message says which one failed.
+      def identity(actual)
+        expected = @args.first
+        return true if actual.equal?(expected)
+
+        hint = actual == expected ? " (they are equal, but not the same object)" : ""
+        [false, "expected #{Matchers.describe(actual)} to be the same object as " \
+                "#{Matchers.describe(expected)}#{hint}", nil]
+      end
+    end
+
     # The be_*/have_* fallback: with no matcher registered under the name, the name itself
     # is the assertion -- `be_created` asks the actual whether it is `created?`.
     class PredicateDeferred < Deferred
@@ -795,6 +911,94 @@ module Constable
       raise Constable::Error, "change is only usable through attest { ... }.to change { ... }"
     end
 
+    # Order-independent collection equality. `modernize` converts
+    # `expect(x).to contain_exactly(a, b)` verbatim, so not having it turned every
+    # converted spec that used it into a NoMethodError.
+    define_builtin(:contain_exactly) do |actual, *expected|
+      unless actual.respond_to?(:to_a)
+        next [false, "expected #{Matchers.describe(actual)} to be a collection, " \
+                     "but a #{actual.class} does not respond to #to_a", nil]
+      end
+
+      items = actual.to_a
+      missing = expected.dup
+      extra   = []
+      items.each do |item|
+        index = missing.index { |candidate| candidate == item }
+        index ? missing.delete_at(index) : extra << item
+      end
+      next true if missing.empty? && extra.empty?
+
+      parts = []
+      parts << "missing #{Matchers.describe(missing)}" unless missing.empty?
+      parts << "unexpected #{Matchers.describe(extra)}" unless extra.empty?
+      [false, "expected the collection to contain exactly #{expected.size} " \
+              "#{expected.size == 1 ? "item" : "items"}: #{parts.join(", ")}",
+       { "Actual" => Matchers.describe(items) }]
+    end
+    # Not an alias: RSpec's match_array takes one array where contain_exactly takes
+    # varargs, so aliasing them makes match_array([1, 2]) assert that the collection
+    # holds a single element which is itself the array [1, 2].
+    define_builtin(:match_array) do |actual, expected|
+      unless expected.respond_to?(:to_a)
+        next [false, "match_array takes an array: attest(list).to match_array([1, 2])", nil]
+      end
+
+      Matchers.matcher_for(:contain_exactly).block.call(actual, *expected.to_a)
+    end
+
+    define_builtin(:start_with) do |actual, prefix|
+      unless actual.respond_to?(:start_with?) || actual.respond_to?(:first)
+        next [false, "expected #{Matchers.describe(actual)} to start with " \
+                     "#{Matchers.describe(prefix)}, but a #{actual.class} cannot say", nil]
+      end
+      passed = if actual.respond_to?(:start_with?)
+                 actual.start_with?(prefix)
+               else
+                 actual.first(Array(prefix).size) == Array(prefix)
+               end
+      next true if passed
+
+      [false, "expected #{Matchers.describe(actual)} to start with #{Matchers.describe(prefix)}", nil]
+    end
+
+    define_builtin(:end_with) do |actual, suffix|
+      unless actual.respond_to?(:end_with?) || actual.respond_to?(:last)
+        next [false, "expected #{Matchers.describe(actual)} to end with " \
+                     "#{Matchers.describe(suffix)}, but a #{actual.class} cannot say", nil]
+      end
+      passed = if actual.respond_to?(:end_with?)
+                 actual.end_with?(suffix)
+               else
+                 actual.last(Array(suffix).size) == Array(suffix)
+               end
+      next true if passed
+
+      [false, "expected #{Matchers.describe(actual)} to end with #{Matchers.describe(suffix)}", nil]
+    end
+
+    define_builtin(:be_between) do |actual, low, high|
+      next true if actual.between?(low, high)
+
+      [false, "expected #{Matchers.describe(actual)} to be between " \
+              "#{Matchers.describe(low)} and #{Matchers.describe(high)}", nil]
+    end
+
+    define_builtin(:satisfy) do |actual, &block|
+      next [false, "satisfy needs a block: attest(x).to satisfy { |value| ... }", nil] unless block
+      next true if block.call(actual)
+
+      [false, "expected #{Matchers.describe(actual)} to satisfy the block", nil]
+    end
+
+    define_builtin(:be_within, deferred_class: WithinDeferred) do |_actual, *_args|
+      raise Constable::Error, "be_within needs .of: attest(value).to be_within(0.5).of(10)"
+    end
+
+    define_builtin(:be, deferred_class: BeDeferred) do |_actual, *_args|
+      raise Constable::Error, "be is handled by BeDeferred and should never invoke its block"
+    end
+
     define_builtin(:be_a) do |actual, klass|
       next true if actual.is_a?(klass)
 

data/lib/constable/registry.rb

@@ -42,6 +42,30 @@ module Constable
       @cases.find { |klass| klass.constable_display_name == name.to_s || klass.name == name.to_s }
     end
 
+    # Re-keys any investigations that share a body with another, so the blotter never
+    # treats two tests as one. Runs once, after the whole suite is loaded -- a collision
+    # is invisible until every case file has been seen.
+    #
+    # Returns the groups it re-keyed, so a caller can report them if it wants to.
+    def disambiguate_identities!
+      collisions = investigations.group_by(&:identity).select { |_key, group| group.size > 1 }
+      return [] if collisions.empty?
+
+      collisions.each_value { |group| group.each(&:disambiguate!) }
+
+      # Class and description are usually enough to tell two identical bodies apart. When
+      # they are not -- a copy-pasted `investigate` with the same name and the same body
+      # in the same case -- fall back to position, which is the only thing left that
+      # differs. History for those resets whenever the file is reordered, which is the
+      # honest cost of two tests that are indistinguishable by anything a human wrote.
+      still_colliding = investigations.group_by(&:identity).select { |_key, group| group.size > 1 }
+      still_colliding.each_value do |group|
+        group.each_with_index { |investigation, index| investigation.disambiguate!(ordinal: index) }
+      end
+
+      collisions.values
+    end
+
     def each(&) = @cases.each(&)
 
     def size    = @cases.size

data/lib/constable/reporter.rb

@@ -46,6 +46,11 @@ module Constable
 
     DEFAULT_SLOWEST = 5
 
+    # Column the expanded stream right-aligns durations into. Descriptions are never
+    # truncated to fit it -- a clipped test name is not something you can grep for --
+    # so a long one simply pushes its own stamp out past the column.
+    EXPANDED_STAMP_COLUMN = 56
+
     # Result::GLYPHS covers statuses. These four are summary vocabulary, not statuses:
     # supervision and coverage are properties of a test, not outcomes of one.
     GLYPHS = Result::GLYPHS.merge(
@@ -97,11 +102,14 @@ module Constable
 
     attr_reader :io, :config, :seed, :total
 
-    def initialize(io: $stdout, config: nil, color: nil, slowest: DEFAULT_SLOWEST)
+    def initialize(io: $stdout, config: nil, color: nil, slowest: DEFAULT_SLOWEST, mode: nil)
       @io      = io
       @config  = config || Constable.config
       @color   = resolve_color(color)
       @slowest = slowest.to_i
+      # Resolved lazily: the reporter is built before case_helper.rb has run, so reading
+      # the config now would miss anything Constable.configure sets.
+      @requested_mode = mode
       @io.set_encoding(Encoding::UTF_8) if @io.respond_to?(:set_encoding)
 
       reset_stream!
@@ -141,6 +149,14 @@ module Constable
     def flush!
       return self unless streaming?
 
+      # The expanded stream never buffers -- every line was written as it happened, so
+      # there is nothing left to emit, only a blank line before the summary.
+      if expanded?
+        reset_stream!
+        writeln
+        return self
+      end
+
       close_stream_line
       pending_case_names.each { |name| open_stream_line(name) && close_stream_line }
       writeln
@@ -169,6 +185,9 @@ module Constable
 
       section_parole_violations(results)
       section_failures(results)
+      section_warrants(results)
+      section_jailed(results)
+      section_parole(results)
       section_warnings(warnings)
       section_slowest(results)
       rename_suggestions(suggestions)
@@ -193,6 +212,8 @@ module Constable
     def failed?  = !success?
     def color?   = @color
     def finished? = @finished
+    def mode      = @mode ||= resolve_mode(@requested_mode)
+    def expanded? = mode == :expanded
 
     private
 
@@ -211,6 +232,8 @@ module Constable
     end
 
     def stream(result)
+      return stream_expanded(result) if expanded?
+
       name = result.case_name.to_s
       name = "(anonymous)" if name.empty?
       glyph = paint(result.glyph, COLORS[result.status])
@@ -263,6 +286,77 @@ module Constable
     # Glyphs may carry escape codes; count only the visible ones.
     def count_glyphs(string) = strip_ansi(string).length
 
+    # --- expanded stream -----------------------------------------------------------
+    #
+    # One line per test instead of one glyph. The trade is deliberate: concise keeps a
+    # thousand-test suite on one screen, expanded tells you which test is hanging while
+    # it hangs, without waiting for the summary.
+    #
+    # Workers interleave, so a case can come back after another has spoken. It gets a
+    # second header rather than having its later tests silently appended under the
+    # wrong one -- the same honesty rule the concise stream follows.
+    def stream_expanded(result)
+      name = result.case_name.to_s
+      name = "(anonymous)" if name.empty?
+
+      if @stream_case != name
+        writeln if @stream_case
+        writeln(INDENT + paint(name, :bold))
+        @stream_case = name
+        @stream_open = true
+      end
+
+      writeln(expanded_line(result))
+    end
+
+    def expanded_line(result)
+      glyph = paint(result.glyph, COLORS[result.status])
+      line  = "#{ENTRY_INDENT}#{glyph} #{expanded_description(result)}"
+
+      stamp = expanded_duration(result)
+      return line if stamp.nil?
+
+      # Pad to a column so the durations line up, but never truncate a description --
+      # a clipped test name is not something you can grep for.
+      visible = strip_ansi(line).length
+      gap = [EXPANDED_STAMP_COLUMN - visible, 1].max
+      "#{line}#{" " * gap}#{paint(stamp, :dim)}"
+    end
+
+    def expanded_description(result)
+      description = result.description.to_s
+      description = "(no description)" if description.empty?
+      # A jailed test never ran its body, so say why rather than implying it passed.
+      return "#{description} #{paint("— #{result.jail_reason}", :dim)}" if jail_reason_worth_showing?(result)
+
+      description
+    end
+
+    def jail_reason_worth_showing?(result)
+      result.status == :jailed && !result.jail_reason.to_s.strip.empty?
+    end
+
+    # Only real, measured time. A jailed test never ran, and "0ms" would be a claim
+    # about a body that was skipped.
+    def expanded_duration(result)
+      return nil if result.status == :jailed
+      return nil unless result.duration.to_f.positive?
+
+      format_test_duration(result.duration)
+    end
+
+    # The summary's durations are run-scale, where "12.4s" is the useful unit. One test
+    # is usually sub-second, and "0.0s" against every line says nothing at all -- so the
+    # expanded stream counts milliseconds until a test is slow enough for seconds to mean
+    # something.
+    def format_test_duration(seconds)
+      seconds = seconds.to_f
+      return format_duration(seconds) if seconds >= 1
+
+      milliseconds = (seconds * 1000).round
+      milliseconds.zero? ? "<1ms" : "#{milliseconds}ms"
+    end
+
     # --- header and headline -------------------------------------------------------
 
     def header_line(results, duration)
@@ -359,8 +453,12 @@ module Constable
       each_entry(violations) do |result|
         writeln(INDENT + paint("#{GLYPHS[:parole_violation]} #{result.case_name}", COLORS[:parole_violation]))
         writeln(ENTRY_INDENT + paint(%("#{result.description}"), :dim))
+        writeln(ENTRY_INDENT + paint(result.location, :dim))
         writeln(ENTRY_INDENT + parole_violation_sentence(result))
       end
+      hint("Somebody trusted this test again and it let them down, so it is back on the " \
+           "docket. Fix it before the next constable jail parole — a second violation " \
+           "is the signal that the test, not the flake, is the problem.")
     end
 
     def parole_violation_sentence(result)
@@ -369,6 +467,95 @@ module Constable
       sentence
     end
 
+    # A section says what happened; a hint says what to do about it. One dim sentence,
+    # and only where there is a real next step -- a tip printed on every run stops being
+    # read on the second one.
+    def hint(text)
+      writeln
+      lines = wrap(text, width: RULE_WIDTH - INDENT.length - 2, indent: "  ")
+      writeln(INDENT + paint("→ #{lines.first}", :dim))
+      lines.drop(1).each { |line| writeln(INDENT + paint(line, :dim)) }
+    end
+
+    # Every test currently under a warrant: it failed, then passed when rerun in
+    # isolation, so it is flaky rather than broken. Loud, but not build-blocking.
+    def section_warrants(results)
+      warranted = results.select(&:warranted?)
+      return if warranted.empty?
+
+      section("WARRANTS")
+      each_entry(warranted) do |result|
+        writeln(INDENT + paint("#{GLYPHS[:warrant]} #{result.case_name}", COLORS[:warranted]))
+        writeln(ENTRY_INDENT + paint(%("#{result.description}"), :dim))
+        writeln(ENTRY_INDENT + paint(result.location, :dim))
+        writeln(ENTRY_INDENT + warrant_sentence(result))
+      end
+      hint("A warrant is \"not reproducible\", not \"not a problem\" — it stops blocking the " \
+           "build and stays visible until someone deals with it. " \
+           "Fixed the flake? constable warrants release PATH:LINE")
+    end
+
+    def warrant_sentence(result)
+      statuses = Array(result.retries).map(&:to_sym)
+      return "Failed once, then passed on retry." if statuses.empty?
+
+      passed = statuses.count(:passed)
+      "Failed, then passed #{passed} of #{statuses.size} #{pluralize(statuses.size, "retry")} " \
+        "run in isolation."
+    end
+
+    # The docket. These never ran their bodies, so they are neither passing nor failing --
+    # which is exactly why they get their own category rather than being folded into
+    # either one.
+    def section_jailed(results)
+      jailed = results.select { |result| result.status == :jailed }
+      return if jailed.empty?
+
+      section("JAILED")
+      each_entry(jailed) do |result|
+        writeln(INDENT + paint("#{GLYPHS[:jailed]} #{result.case_name}", COLORS[:jailed]))
+        writeln(ENTRY_INDENT + paint(%("#{result.description}"), :dim))
+        writeln(ENTRY_INDENT + paint(result.location, :dim))
+        writeln(ENTRY_INDENT + jailed_sentence(result))
+      end
+      hint("Jailed means skipped and tracked, not passing. Think one is fixed? " \
+           "constable jail parole PATH:LINE runs it for real again — " \
+           "#{@config.parole_period} clean runs and it releases itself.")
+    end
+
+    def jailed_sentence(result)
+      reason   = result.jail_reason.to_s.strip
+      sentence = reason.empty? ? "Body skipped; setup still ran." : "#{reason.capitalize}."
+      sentence += " Its #{ordinalize(result.times_jailed)} time in jail." if result.times_jailed.to_i > 1
+      sentence
+    end
+
+    # Out on parole and behaving. Worth naming every run, because the count only means
+    # something if you can see it moving.
+    def section_parole(results)
+      paroled = results.select { |result| result.parole_day && !result.parole_violation? }
+      return if paroled.empty?
+
+      section("ON PAROLE")
+      each_entry(paroled) do |result|
+        writeln(INDENT + paint("#{GLYPHS[:parole]} #{result.case_name}", COLORS[:parole]))
+        writeln(ENTRY_INDENT + paint(%("#{result.description}"), :dim))
+        writeln(ENTRY_INDENT + paint(result.location, :dim))
+        writeln(ENTRY_INDENT + parole_progress_sentence(result))
+      end
+      hint("A paroled test runs for real and is watched: one failure sends it straight " \
+           "back to jail. constable watchlist shows everything under supervision.")
+    end
+
+    def parole_progress_sentence(result)
+      day       = result.parole_day.to_i
+      period    = @config.parole_period
+      remaining = [period - day, 0].max
+      return "Day #{day} of #{period} — releases after this run." if remaining.zero?
+
+      "Day #{day} of #{period} — #{remaining} #{pluralize(remaining, "clean run")} to go."
+    end
+
     def section_failures(results)
       failures = results.select(&:failed?)
       return if failures.empty?
@@ -432,11 +619,21 @@ module Constable
           writeln(INDENT + paint("#{GLYPHS[:warning]} #{message}", COLORS[:warning]))
         else
           writeln(INDENT + paint("#{GLYPHS[:warning]} #{location}", COLORS[:warning]))
-          message.each_line { |line| writeln(ENTRY_INDENT + line.chomp) }
+          warning_message_lines(message).each { |line| writeln(ENTRY_INDENT + line) }
         end
       end
     end
 
+    # A warning carries the author's own words -- an unsafe block's reason, a cold case's
+    # count -- and those are easily ninety columns. Wrapped to the frame, but respecting
+    # any line breaks the message already chose.
+    def warning_message_lines(message)
+      message.to_s.lines.flat_map do |line|
+        text = line.chomp
+        text.empty? ? [""] : wrap(text, width: RULE_WIDTH - ENTRY_INDENT.length, indent: "")
+      end
+    end
+
     def section_slowest(results)
       # A jailed test never ran its body, so it has no honest duration. A parole
       # violation did run -- and failing slowly is still worth seeing.
@@ -551,7 +748,28 @@ module Constable
     end
 
     def pluralize(count, word)
-      count.to_i == 1 ? word : "#{word}s"
+      return word if count.to_i == 1
+      # "retry" -> "retries". Only the consonant-y rule earns a special case; every other
+      # word this reporter pluralizes takes a plain "s".
+      return "#{word[0..-2]}ies" if word.end_with?("y") && !"aeiou".include?(word[-2].to_s)
+
+      "#{word}s"
+    end
+
+    # Hints are prose, and prose that runs past the frame reads as a mistake. Wrapped to
+    # the same 60 columns the rules use, with continuation lines aligned under the arrow.
+    def wrap(text, width:, indent:)
+      words = text.split
+      lines = [+""]
+      words.each do |word|
+        candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
+        if candidate.length <= width || lines.last.empty?
+          lines[-1] = candidate
+        else
+          lines << +word
+        end
+      end
+      lines.each_with_index.map { |line, i| i.zero? ? line : indent + line }
     end
 
     def format_duration(seconds)
@@ -571,6 +789,17 @@ module Constable
 
     # Colour is a nicety; correctness is not. NO_COLOR, a pipe, a dumb terminal or an
     # explicit --no-color all fall back to plain text with identical layout.
+    # An explicit argument (the --expanded / --concise flags) beats the config file, which
+    # beats the default. An unrecognized value falls back rather than raising: a typo in
+    # config.yml should not stop a suite from running.
+    def resolve_mode(mode)
+      configured = @config.respond_to?(:output_mode) ? @config.output_mode : :concise
+      return configured if mode.nil?
+
+      mode = mode.to_s.strip.downcase.to_sym
+      Config::OUTPUT_MODES.include?(mode) ? mode : configured
+    end
+
     def resolve_color(color)
       return !!color unless color.nil?
       return false if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?