polyrun 2.2.9 → 3.0.0

data/lib/polyrun/partition/paths.rb

@@ -2,18 +2,24 @@ module Polyrun
   module Partition
     # Shared spec path listing for run-shards, queue init, and plan helpers.
     module Paths
+      SUS_CONFIG_REL = "config/sus.rb"
+      SUS_TEST_GLOB = "test/**/*.rb"
+
       module_function
 
       def read_lines(path)
         File.read(File.expand_path(path.to_s, Dir.pwd)).split("\n").map(&:strip).reject(&:empty?)
       end
 
-      # Prefer +spec/+ RSpec files, then +test/+ Minitest, then Polyrun Quick files (same globs as +polyrun quick+).
-      # Order avoids running the broader Quick glob when RSpec or Minitest files already exist.
+      # Prefer +spec/+ RSpec files, then Sus (+config/sus.rb+ + +test/**/*.rb+), then +test/+ Minitest,
+      # then Polyrun Quick files (same globs as +polyrun quick+).
       def detect_auto_suite(cwd = Dir.pwd)
         base = File.expand_path(cwd)
         return :rspec if Dir.glob(File.join(base, "spec/**/*_spec.rb")).any?
 
+        sus = sus_test_paths(base)
+        return :sus if sus_configured?(base) && sus.any?
+
         return :minitest if Dir.glob(File.join(base, "test/**/*_test.rb")).any?
 
         quick = quick_parallel_default_paths(base)
@@ -22,32 +28,25 @@ module Polyrun
         nil
       end
 
-      # Infer parallel suite from explicit paths (+_spec.rb+ vs +_test.rb+ vs Polyrun quick-style +.rb+).
+      # Infer parallel suite from explicit paths.
       # Recognizes RSpec-style +path:line+ locators (strips a trailing numeric locator before classifying).
-      # Returns +:rspec+, +:minitest+, +:quick+, +:invalid+ (mixed spec and test), or +nil+ (empty).
+      # Returns +:rspec+, +:minitest+, +:sus+, +:quick+, +:invalid+ (mixed families), or +nil+ (empty).
       def infer_suite_from_paths(paths)
-        paths = Array(paths).map { |p| suite_classify_path(p) }
-        return nil if paths.empty?
-
-        specs = paths.count { |p| File.basename(p).end_with?("_spec.rb") }
-        tests = paths.count { |p| File.basename(p).end_with?("_test.rb") }
-        return :invalid if specs.positive? && tests.positive?
-
-        return :rspec if specs.positive?
-        return :minitest if tests.positive?
+        families = Array(paths).map { |p| suite_family_for_path(p) }.compact
+        return nil if families.empty?
 
-        others = paths.size - specs - tests
-        return :quick if others.positive?
+        uniq = families.uniq
+        return :invalid if uniq.size > 1
 
-        nil
+        uniq.first
       end
 
       # When +paths_file+ is set but missing, returns +{ error: "..." }+.
       # Otherwise returns +{ items:, source: }+ (human-readable source label).
       #
-      # +partition.suite+ (optional): +auto+ (default), +rspec+, +minitest+, +quick+ — used when resolving
+      # +partition.suite+ (optional): +auto+ (default), +rspec+, +minitest+, +sus+, +quick+ — used when resolving
       # from globs. Legacy +spec/spec_paths.txt+ is used only for +auto+/+rspec+ (RSpec-oriented); an
-      # explicit +minitest+/+quick+ suite skips it and globs instead. Bare +polyrun+ suite selection is
+      # explicit +minitest+/+sus+/+quick+ suite skips it and globs instead. Bare +polyrun+ suite selection is
       # {Suite.resolve_default} (explicit suite → paths_file inference → {detect_auto_suite}).
       def resolve_run_shard_items(paths_file: nil, cwd: Dir.pwd, partition: {})
         if paths_file
@@ -64,50 +63,88 @@ module Polyrun
       end
 
       def resolve_run_shard_items_glob(cwd:, partition: {})
-        suite = (partition["suite"] || partition[:suite] || "auto").to_s.downcase
-        suite = "auto" if suite.empty?
+        suite = partition_suite_name(partition)
+        catalogs = shard_path_catalogs(File.expand_path(cwd))
+        case suite
+        when "rspec", "minitest", "sus", "quick"
+          resolve_named_suite_items(suite, catalogs)
+        when "auto"
+          resolve_auto_suite_items(catalogs)
+        else
+          {error: "unknown partition.suite: #{suite.inspect} (expected auto, rspec, minitest, sus, quick)"}
+        end
+      end
 
-        base = File.expand_path(cwd)
-        spec = Dir.glob(File.join(base, "spec/**/*_spec.rb")).sort
-        test = Dir.glob(File.join(base, "test/**/*_test.rb")).sort
-        quick = quick_parallel_default_paths(base)
+      def partition_suite_name(partition)
+        suite = (partition["suite"] || partition[:suite] || "auto").to_s.downcase
+        suite.empty? ? "auto" : suite
+      end
+      private_class_method :partition_suite_name
+
+      def shard_path_catalogs(base)
+        {
+          base: base,
+          spec: Dir.glob(File.join(base, "spec/**/*_spec.rb")).sort,
+          test: Dir.glob(File.join(base, "test/**/*_test.rb")).sort,
+          sus: sus_test_paths(base),
+          quick: quick_parallel_default_paths(base)
+        }
+      end
+      private_class_method :shard_path_catalogs
 
+      def resolve_named_suite_items(suite, catalogs)
         case suite
         when "rspec"
-          return {error: "partition.suite is rspec but no spec/**/*_spec.rb files"} if spec.empty?
+          return {error: "partition.suite is rspec but no spec/**/*_spec.rb files"} if catalogs[:spec].empty?
 
-          {items: spec, source: "spec/**/*_spec.rb glob"}
+          {items: catalogs[:spec], source: "spec/**/*_spec.rb glob"}
         when "minitest"
-          return {error: "partition.suite is minitest but no test/**/*_test.rb files"} if test.empty?
+          return {error: "partition.suite is minitest but no test/**/*_test.rb files"} if catalogs[:test].empty?
 
-          {items: test, source: "test/**/*_test.rb glob"}
-        when "quick"
-          return {error: "partition.suite is quick but no Polyrun quick files under spec/ or test/"} if quick.empty?
+          {items: catalogs[:test], source: "test/**/*_test.rb glob"}
+        when "sus"
+          return {error: "partition.suite is sus but no test/**/*.rb files"} if catalogs[:sus].empty?
 
-          {items: quick, source: "Polyrun quick glob"}
-        when "auto"
-          if spec.any?
-            {items: spec, source: "spec/**/*_spec.rb glob"}
-          elsif test.any?
-            {items: test, source: "test/**/*_test.rb glob"}
-          elsif quick.any?
-            {items: quick, source: "Polyrun quick glob"}
-          else
-            {
-              error: "no spec paths (spec/spec_paths.txt, partition.paths_file, or spec/**/*_spec.rb); " \
-                     "no test/**/*_test.rb; no Polyrun quick files"
-            }
-          end
+          {items: catalogs[:sus], source: "test/**/*.rb glob (sus)"}
+        else
+          return {error: "partition.suite is quick but no Polyrun quick files under spec/ or test/"} if catalogs[:quick].empty?
+
+          {items: catalogs[:quick], source: "Polyrun quick glob"}
+        end
+      end
+      private_class_method :resolve_named_suite_items
+
+      def resolve_auto_suite_items(catalogs)
+        if catalogs[:spec].any?
+          {items: catalogs[:spec], source: "spec/**/*_spec.rb glob"}
+        elsif sus_configured?(catalogs[:base]) && catalogs[:sus].any?
+          {items: catalogs[:sus], source: "test/**/*.rb glob (sus)"}
+        elsif catalogs[:test].any?
+          {items: catalogs[:test], source: "test/**/*_test.rb glob"}
+        elsif catalogs[:quick].any?
+          {items: catalogs[:quick], source: "Polyrun quick glob"}
         else
-          {error: "unknown partition.suite: #{suite.inspect} (expected auto, rspec, minitest, quick)"}
+          {
+            error: "no spec paths (spec/spec_paths.txt, partition.paths_file, or spec/**/*_spec.rb); " \
+                   "no Sus test/**/*.rb (with config/sus.rb); no test/**/*_test.rb; no Polyrun quick files"
+          }
         end
       end
+      private_class_method :resolve_auto_suite_items
 
       def quick_parallel_default_paths(base)
         require_relative "../quick/runner"
         Polyrun::Quick::Runner.parallel_default_paths(base)
       end
 
+      def sus_configured?(base)
+        File.file?(File.join(base, SUS_CONFIG_REL))
+      end
+
+      def sus_test_paths(base)
+        Dir.glob(File.join(base, SUS_TEST_GLOB)).sort
+      end
+
       # Strip trailing numeric locators (+path:line+ or +path:line:column+), then expand.
       def suite_classify_path(path)
         raw = path.to_s.sub(/(?::\d+)+\z/, "")
@@ -115,12 +152,22 @@ module Polyrun
       end
       private_class_method :suite_classify_path
 
+      def suite_family_for_path(path)
+        abs = suite_classify_path(path)
+        base = File.basename(abs)
+        return :rspec if base.end_with?("_spec.rb")
+        return :minitest if base.end_with?("_test.rb")
+        return :quick if abs.include?("polyrun_quick")
+        return :sus if abs.match?(%r{(?:^|/)test/})
+
+        :quick
+      end
+      private_class_method :suite_family_for_path
+
       def use_legacy_spec_paths?(cwd, partition)
         return false unless File.file?(File.join(cwd, "spec", "spec_paths.txt"))
 
-        suite = (partition["suite"] || partition[:suite] || "auto").to_s.downcase
-        suite = "auto" if suite.empty?
-        %w[auto rspec].include?(suite)
+        %w[auto rspec].include?(partition_suite_name(partition))
       end
       private_class_method :use_legacy_spec_paths?
     end

data/lib/polyrun/partition/suite.rb

@@ -2,15 +2,17 @@ module Polyrun
   module Partition
     # Chooses the parallel runner suite for bare +polyrun+ and validates command vs path lists.
     module Suite
+      ALLOWED = %w[auto rspec minitest sus quick].freeze
+
       module_function
 
       # Resolve suite for default CLI dispatch.
       # Order: explicit +partition.suite+ (not auto) → infer from +paths_file+ → +detect_auto_suite+.
-      # Returns +{ suite: :rspec|:minitest|:quick }+ or +{ error: "..." }+.
+      # Returns +{ suite: :rspec|:minitest|:sus|:quick }+ or +{ error: "..." }+.
       def resolve_default(cwd: Dir.pwd, partition: {})
         configured = configured_suite(partition)
-        return {error: "unknown partition.suite: #{configured.inspect} (expected auto, rspec, minitest, quick)"} unless
-          %w[auto rspec minitest quick].include?(configured)
+        return {error: "unknown partition.suite: #{configured.inspect} (expected auto, rspec, minitest, sus, quick)"} unless
+          ALLOWED.include?(configured)
 
         inferred = infer_from_paths_file(cwd, partition)
         return inferred if inferred.is_a?(Hash) && inferred[:error]
@@ -32,7 +34,8 @@ module Polyrun
         return {suite: auto} if auto
 
         {
-          error: "no tests found (spec/**/*_spec.rb, test/**/*_test.rb, or Polyrun quick files). See polyrun help."
+          error: "no tests found (spec/**/*_spec.rb, Sus config/sus.rb + test/**/*.rb, " \
+                 "test/**/*_test.rb, or Polyrun quick files). See polyrun help."
         }
       end
 
@@ -41,6 +44,7 @@ module Polyrun
         return nil if tokens.empty?
 
         return :rspec if tokens.any? { |t| File.basename(t) == "rspec" }
+        return :sus if tokens.any? { |t| %w[sus sus-parallel].include?(File.basename(t)) }
         return :quick if tokens.include?("quick") && tokens.any? { |t| File.basename(t).include?("polyrun") }
         return :minitest if minitest_command?(tokens)
 
@@ -54,7 +58,7 @@ module Polyrun
         if path_suite == :invalid
           return nil unless cmd_suite
 
-          return "mixing _spec.rb and _test.rb paths is not supported with a #{cmd_suite} command " \
+          return "mixing path families is not supported with a #{cmd_suite} command " \
                  "(use a suite-agnostic custom command, or split the path list)"
         end
 
@@ -81,7 +85,7 @@ module Polyrun
 
         items = Paths.read_lines(abs)
         inferred = Paths.infer_suite_from_paths(items)
-        return {error: "paths_file mixes _spec.rb and _test.rb (not supported in one run)"} if inferred == :invalid
+        return {error: "paths_file mixes path families (not supported in one run)"} if inferred == :invalid
 
         inferred
       end

data/lib/polyrun/quick/config.rb

@@ -0,0 +1,56 @@
+module Polyrun
+  module Quick
+    # Optional host file +config/polyrun_quick.rb+ evaluated before Quick examples run.
+    class Config
+      PATH = "config/polyrun_quick.rb"
+
+      attr_reader :before_suite_hooks, :after_suite_hooks, :load_paths
+
+      def self.load!(root: Dir.pwd)
+        cfg = new
+        path = File.join(File.expand_path(root), PATH)
+        return cfg unless File.file?(path)
+
+        cfg.instance_eval(File.read(path), path)
+        cfg
+      end
+
+      def initialize
+        @before_suite_hooks = []
+        @after_suite_hooks = []
+        @load_paths = []
+      end
+
+      def before_suite(&block)
+        @before_suite_hooks << block if block
+      end
+
+      def after_suite(&block)
+        @after_suite_hooks << block if block
+      end
+
+      def add_load_path(path)
+        @load_paths << path.to_s
+      end
+
+      def apply_load_paths!(root:)
+        base = File.expand_path(root)
+        @load_paths.each do |rel|
+          abs = File.expand_path(rel, base)
+          next unless File.directory?(abs)
+          next if $LOAD_PATH.include?(abs)
+
+          $LOAD_PATH.unshift(abs)
+        end
+      end
+
+      def run_before_suite!
+        @before_suite_hooks.each(&:call)
+      end
+
+      def run_after_suite!(status)
+        @after_suite_hooks.each { |h| h.call(status) }
+      end
+    end
+  end
+end

data/lib/polyrun/quick/example_group.rb

@@ -1,18 +1,22 @@
 module Polyrun
   module Quick
-    # One +describe+ block (possibly nested). Holds +it+ / +test+ examples and hooks.
+    # One +describe+ / +with+ block (possibly nested). Holds examples and hooks.
     class ExampleGroup
-      attr_reader :name, :parent, :children, :examples, :before_hooks, :after_hooks, :lets, :let_bang_order
+      attr_reader :name, :parent, :children, :examples, :before_hooks, :after_hooks, :around_hooks,
+        :lets, :let_bang_order, :described_target
 
-      def initialize(name, parent: nil)
-        @name = name.to_s
+      def initialize(name, parent: nil, described_target: nil)
+        @name = name_label(name)
+        @described_target = described_target.nil? ? infer_described_target(name) : described_target
         @parent = parent
         @children = []
         @examples = []
         @before_hooks = []
         @after_hooks = []
+        @around_hooks = []
         @lets = {}
         @let_bang_order = []
+        maybe_default_subject!
       end
 
       def full_name
@@ -28,6 +32,8 @@ module Polyrun
         child
       end
 
+      alias_method :with, :describe
+
       def it(description, &block)
         @examples << [description.to_s, block]
       end
@@ -42,6 +48,10 @@ module Polyrun
         @after_hooks << block
       end
 
+      def around(&block)
+        @around_hooks << block
+      end
+
       def let(name, &block)
         @lets[name.to_sym] = block
       end
@@ -52,6 +62,15 @@ module Polyrun
         @let_bang_order << sym
       end
 
+      def subject(&block)
+        if block
+          let(:subject, &block)
+        else
+          # Used from examples via ExampleRunner method; group-level call without block is invalid.
+          raise ArgumentError, "subject requires a block at describe time"
+        end
+      end
+
       def each_example_with_ancestors(ancestors = [], &visitor)
         chain = ancestors + [self]
         @examples.each do |desc, block|
@@ -61,6 +80,32 @@ module Polyrun
           child.each_example_with_ancestors(chain, &visitor)
         end
       end
+
+      private
+
+      def name_label(name)
+        return name.to_s unless name.is_a?(Module)
+
+        name.name || name.to_s
+      end
+
+      def infer_described_target(name)
+        name.is_a?(Module) ? name : nil
+      end
+
+      def maybe_default_subject!
+        return unless @described_target
+        return if @lets.key?(:subject)
+
+        target = @described_target
+        @lets[:subject] = -> {
+          if target.respond_to?(:new)
+            target.new
+          else
+            target
+          end
+        }
+      end
     end
   end
 end

data/lib/polyrun/quick/example_runner.rb

@@ -26,17 +26,21 @@ module Polyrun
         qloc = quick_example_location(block)
         Polyrun::WorkerPing.ping!(location: qloc)
         Polyrun::SpecQuality.start_example!(location: qloc) if Polyrun::SpecQuality.started?
+        error = nil
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         begin
           run_before_hooks_from_chain(ancestor_chain)
-          instance_eval(&block)
-          @reporter.pass(group_name, description)
+          invoke_arounds(ancestor_chain.flat_map(&:around_hooks), 0) { instance_eval(&block) }
+          @reporter.pass(group_name, description, duration_seconds: elapsed_since(started))
         rescue AssertionFailed => e
-          @reporter.fail(group_name, description, e)
+          error = e
+          @reporter.fail(group_name, description, e, duration_seconds: elapsed_since(started))
         rescue => e
-          @reporter.error(group_name, description, e)
+          error = e
+          @reporter.error(group_name, description, e, duration_seconds: elapsed_since(started))
         ensure
           Polyrun::SpecQuality.finish_example!(location: qloc) if Polyrun::SpecQuality.started?
-          run_after_hooks_from_chain(ancestor_chain)
+          run_after_hooks_from_chain(ancestor_chain, error: error)
           reset_capybara_if_enabled!
           @_let_cache = {}
           Polyrun::WorkerPing.ping!(location: qloc)
@@ -45,6 +49,10 @@ module Polyrun
 
       private
 
+      def elapsed_since(started)
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      end
+
       def quick_example_location(block)
         loc = block&.source_location
         loc ? "#{loc[0]}:#{loc[1]}" : nil
@@ -79,10 +87,25 @@ module Polyrun
         end
       end
 
-      def run_after_hooks_from_chain(ancestor_chain)
+      def run_after_hooks_from_chain(ancestor_chain, error: nil)
         ancestor_chain.reverse_each do |g|
-          g.after_hooks.reverse_each { |h| instance_eval(&h) }
+          g.after_hooks.reverse_each { |h| instance_exec(error, &h) }
+        end
+      end
+
+      def invoke_arounds(arounds, index, &body)
+        if index >= arounds.size
+          body.call
+          return
         end
+
+        called = false
+        run = lambda {
+          called = true
+          invoke_arounds(arounds, index + 1, &body)
+        }
+        instance_exec(run, &arounds[index])
+        raise AssertionFailed, "around hook did not run the example" unless called
       end
 
       def extend_capybara_if_enabled!

data/lib/polyrun/quick/matchers.rb

@@ -1,8 +1,9 @@
 require_relative "errors"
+require_relative "matchers_predicates"
 
 module Polyrun
   module Quick
-    # Minimal +expect(x).to …+ chain (RSpec-ish) without RSpec.
+    # Minimal +expect(x).to …+ / +expect { }.to …+ chain without external gems.
     class Expectation
       def initialize(actual)
         @actual = actual
@@ -22,8 +23,10 @@ module Polyrun
     end
 
     module Matchers
-      def expect(actual)
-        Expectation.new(actual)
+      include MatchersPredicates
+
+      def expect(actual = nil, &block)
+        Expectation.new(block_given? ? block : actual)
       end
 
       def eq(expected)

data/lib/polyrun/quick/matchers_predicates.rb

@@ -0,0 +1,122 @@
+module Polyrun
+  module Quick
+    # Predicate-style matchers (+be ==+, +be_a+, +raise_exception+) for Quick expectations.
+    module MatchersPredicates
+      def be
+        BeMatcher.new
+      end
+
+      def be_a(klass)
+        BeAMatcher.new(klass)
+      end
+
+      alias_method :be_kind_of, :be_a
+
+      def raise_exception(exception_class = StandardError, message: nil)
+        RaiseExceptionMatcher.new(exception_class, message: message)
+      end
+    end
+
+    class BeMatcher
+      def ==(other)
+        EqMatcher.new(other)
+      end
+
+      def >(other)
+        CompareMatcher.new(:>, other)
+      end
+
+      def >=(other)
+        CompareMatcher.new(:>=, other)
+      end
+
+      def <(other)
+        CompareMatcher.new(:<, other)
+      end
+
+      def <=(other)
+        CompareMatcher.new(:<=, other)
+      end
+    end
+
+    class CompareMatcher
+      def initialize(op, expected)
+        @op = op
+        @expected = expected
+      end
+
+      def matches?(actual)
+        actual.public_send(@op, @expected)
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message(actual)
+        "expected #{actual.inspect} #{@op} #{@expected.inspect}"
+      end
+
+      def failure_message_when_negated(actual)
+        "expected #{actual.inspect} not #{@op} #{@expected.inspect}"
+      end
+    end
+
+    class BeAMatcher
+      def initialize(klass)
+        @klass = klass
+      end
+
+      def matches?(actual)
+        actual.is_a?(@klass)
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message(actual)
+        "expected #{actual.inspect} to be a #{@klass}"
+      end
+
+      def failure_message_when_negated(actual)
+        "expected #{actual.inspect} not to be a #{@klass}"
+      end
+    end
+
+    class RaiseExceptionMatcher
+      def initialize(exception_class, message: nil)
+        @exception_class = exception_class
+        @message = message
+      end
+
+      def matches?(actual)
+        return false unless actual.respond_to?(:call)
+
+        begin
+          actual.call
+          false
+        rescue @exception_class => e
+          return true if @message.nil?
+          return true if @message.is_a?(Regexp) && @message.match?(e.message)
+
+          e.message == @message.to_s
+        rescue
+          false
+        end
+      end
+
+      def does_not_match?(actual)
+        !matches?(actual)
+      end
+
+      def failure_message(actual)
+        "expected block to raise #{@exception_class}"
+      end
+
+      def failure_message_when_negated(actual)
+        "expected block not to raise #{@exception_class}"
+      end
+    end
+  end
+end