smartest 0.1.0.alpha1 → 0.1.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4b99c1edbf3ad101277d9c87de980708ffe37b5665a3b151be6f03803d4837a
-  data.tar.gz: 6c0d645bd34ccedc0df9ef4fdacb9c3b43133bee5a0f6172ab73c5d9b44c05d1
+  metadata.gz: c1ce8aea4b74c7ca0de7f3a2b1472b79ea86849be91801e11922883b6423afdf
+  data.tar.gz: be5f8e88c1bd93eb061eb0a854b46a6c6094627b36cd22f8778026e35161992a
 SHA512:
-  metadata.gz: 567e14909b4fd63fe70392014d5f41d964e078ac7f16c46ff64071ae6860eb0eabdad3b1c2c409e51b52ce440b487b2531897ceee40f4d6de5dc79a6eb6297a5
-  data.tar.gz: ca377cc64560272f1d75f5527ce10014771bf728500d8489abb6a68a6e285c30c1f587b4a24f47a871ead56033a8fb6b4225dbe60c226c6b1288a1d5cdc509fe
+  metadata.gz: 864cea53cff77bf90e73bdf6528c9e6ff7ba633c89c8edbf011bd50552d9bf1aea606c0a9e4af83352847f88b1ca8571433987d2f933d20b50270b2d2b81079d
+  data.tar.gz: d587ffbf743f4fe75d8977346ae653fe2616ab70e4480453442f4677f7d4d6a4f84166f64c17b50417616693232149ef36214c8c12d530de41a9ff5f36c75a51

data/CHANGELOG.md

@@ -9,6 +9,8 @@
 - Support per-test fixture caching and cleanup.
 - Support suite-scoped fixtures through `suite_fixture`.
 - Support `eq`, `include`, `be_nil`, and `raise_error` matchers.
+- Support custom matcher modules through `use_matcher`.
+- Generate an opt-in `PredicateMatcher` custom matcher for `be_<predicate>` calls.
 - Add the `smartest` CLI.
 - Add `--help` and `--version` CLI options.
 - Use `smartest/**/*_test.rb` as the default CLI glob so Smartest can coexist with Minitest files under `test/`.

data/DEVELOPMENT.md

@@ -126,6 +126,7 @@ Required methods:
 ```ruby
 test(name, **metadata, &block)
 use_fixture(klass)
+use_matcher(matcher_module)
 ```
 
 Possible later methods:
@@ -613,6 +614,8 @@ A practical approach:
 - `exe/smartest`
 - load files from ARGV
 - default glob `smartest/**/*_test.rb`
+- support `path:line` and `path:start-end` filters that run tests whose `test`
+  blocks contain or intersect the lines
 - add `smartest/` to the load path before loading tests
 - generate a `smartest/test_helper.rb` that loads `smartest/fixtures/**/*.rb`
 - exit code 0 on success, 1 on failure

data/README.md

@@ -59,6 +59,8 @@ This creates:
 ```text
 smartest/test_helper.rb
 smartest/fixtures/
+smartest/matchers/
+smartest/matchers/predicate_matcher.rb
 smartest/example_test.rb
 ```
 
@@ -88,6 +90,14 @@ You can also pass explicit paths:
 bundle exec smartest smartest/**/*_test.rb
 ```
 
+To run tests by line number, append `:line` or `:start-end` to the file path.
+Smartest runs tests whose `test` blocks contain or intersect the selected lines:
+
+```bash
+bundle exec smartest smartest/user_test.rb:12
+bundle exec smartest smartest/user_test.rb:3-12
+```
+
 CLI help and version output are available with:
 
 ```bash
@@ -163,6 +173,10 @@ be_nil
 raise_error(ErrorClass)
 ```
 
+Custom matcher modules can be registered with `use_matcher`. The generated
+scaffold includes a `PredicateMatcher` custom matcher for `be_<predicate>` calls.
+See [Matchers](documentation/docs/matchers.md).
+
 ## Fixtures
 
 Fixtures are defined in classes.
@@ -176,9 +190,17 @@ class AppFixture < Smartest::Fixture
     )
   end
 end
+```
 
+Register fixture classes from `smartest/test_helper.rb`:
+
+```ruby
 use_fixture AppFixture
+```
 
+Tests request fixtures by keyword:
+
+```ruby
 test("user") do |user:|
   expect(user.name).to eq("Alice")
 end
@@ -329,8 +351,16 @@ class WebFixture < Smartest::Fixture
     client
   end
 end
+```
 
+```ruby
+# smartest/test_helper.rb
 use_fixture WebFixture
+```
+
+```ruby
+# smartest/web_test.rb
+require "test_helper"
 
 test("GET /me") do |logged_in_client:|
   response = logged_in_client.get("/me")
@@ -361,7 +391,7 @@ server cleanup
 
 ## Registering fixture classes
 
-Use `use_fixture`:
+Use `use_fixture` from `smartest/test_helper.rb`:
 
 ```ruby
 use_fixture AppFixture
@@ -421,6 +451,9 @@ smartest/
   fixtures/
     app_fixture.rb
     web_fixture.rb
+  matchers/
+    predicate_matcher.rb
+    have_status_matcher.rb
   example_test.rb
 ```
 
@@ -431,10 +464,18 @@ require "smartest/autorun"
 Dir[File.join(__dir__, "fixtures", "**", "*.rb")].sort.each do |fixture_file|
   require fixture_file
 end
+
+Dir[File.join(__dir__, "matchers", "**", "*.rb")].sort.each do |matcher_file|
+  require matcher_file
+end
+
+use_fixture WebFixture
+use_matcher PredicateMatcher
 ```
 
-The generated helper loads Ruby files under `smartest/fixtures/` in sorted order.
-Test files still register the fixture classes they need with `use_fixture`.
+The generated helper loads Ruby files under `smartest/fixtures/` and
+`smartest/matchers/` in sorted order. Register fixture classes and matcher
+modules from the helper with `use_fixture` and `use_matcher`.
 
 Example:
 
@@ -457,8 +498,6 @@ end
 # smartest/example_test.rb
 require "test_helper"
 
-use_fixture WebFixture
-
 test("GET /health") do |client:|
   expect(client.get("/health").status).to eq(200)
 end

data/SMARTEST_DESIGN.md

@@ -294,7 +294,7 @@ context.instance_exec(**fixtures, &block)
 
 This keeps the top-level DSL small.
 
-Only `test`, `fixture`, and `use_fixture` need to be globally available when using `smartest/autorun`.
+Only `test`, `fixture`, `use_fixture`, and `use_matcher` need to be globally available when using `smartest/autorun`.
 
 ## Core architecture
 
@@ -794,15 +794,19 @@ CLI flow:
 ```ruby
 require "smartest"
 
-Kernel.include Smartest::DSL
+Smartest.disable_autorun!
+Kernel.prepend Smartest::DSL
 $LOAD_PATH.unshift File.expand_path("smartest", Dir.pwd)
 
-files = ARGV.empty? ? Dir["smartest/**/*_test.rb"] : ARGV
-files.each { |file| require File.expand_path(file) }
+arguments = Smartest::CLIArguments.new(ARGV)
+arguments.files.each { |file| load File.expand_path(file) }
 
-exit Smartest::Runner.new.run
+exit Smartest::Runner.new(tests: arguments.select_tests(Smartest.suite.tests)).run
 ```
 
+`Smartest::CLIArguments` should support file paths, shell globs, `path:line`,
+and `path:start-end` filters.
+
 `smartest/autorun` should use `at_exit`.
 
 ```ruby

data/exe/smartest

@@ -8,6 +8,7 @@ require "smartest"
 usage = <<~USAGE
   Usage:
     smartest [paths...]
+    smartest path/to/test_file.rb:line[-line]
     smartest --init
     smartest --version
     smartest --help
@@ -38,21 +39,13 @@ begin
   test_load_path = File.expand_path("smartest", Dir.pwd)
   $LOAD_PATH.unshift(test_load_path) if Dir.exist?(test_load_path) && !$LOAD_PATH.include?(test_load_path)
 
-  files =
-    if ARGV.empty?
-      Dir["smartest/**/*_test.rb"]
-    else
-      ARGV.flat_map do |pattern|
-        matches = Dir[pattern]
-        matches.empty? ? [pattern] : matches
-      end.uniq
-    end
-
-  files.each do |file|
+  arguments = Smartest::CLIArguments.new(ARGV)
+
+  arguments.files.each do |file|
     load File.expand_path(file)
   end
 
-  exit Smartest::Runner.new.run
+  exit Smartest::Runner.new(tests: arguments.select_tests(Smartest.suite.tests)).run
 rescue Exception => error
   raise if Smartest.fatal_exception?(error)
 

data/lib/smartest/cli_arguments.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Smartest
+  class CLIArguments
+    attr_reader :files, :line_filters
+
+    def initialize(argv)
+      @files = []
+      @whole_files = Set.new
+      @line_filters = Hash.new { |hash, key| hash[key] = Set.new }
+
+      parse(argv.empty? ? ["smartest/**/*_test.rb"] : argv)
+    end
+
+    def filter_tests?
+      @line_filters.any?
+    end
+
+    def select_tests(tests)
+      return tests unless filter_tests?
+
+      tests.select do |test_case|
+        next false unless test_case.location
+
+        path = File.expand_path(test_case.location.path)
+        @whole_files.include?(path) ||
+          @line_filters.fetch(path, []).any? { |line_filter| test_case.includes_line_range?(line_filter) }
+      end
+    end
+
+    private
+
+    def parse(argv)
+      argv.each do |argument|
+        pattern, line_filter = split_line_filter(argument)
+        matches = Dir[pattern]
+        files = matches.empty? ? [pattern] : matches
+
+        files.each do |file|
+          @files << file
+
+          path = File.expand_path(file)
+          if line_filter
+            @line_filters[path].add(line_filter)
+          else
+            @whole_files.add(path)
+          end
+        end
+      end
+
+      @files.uniq!
+    end
+
+    def split_line_filter(argument)
+      match = argument.match(/\A(.+):(\d+)(?:-(\d+))?\z/)
+      return [argument, nil] unless match
+
+      start_line = match[2].to_i
+      end_line = match[3] ? match[3].to_i : start_line
+
+      [match[1], start_line..end_line]
+    end
+  end
+end

data/lib/smartest/dsl.rb

@@ -17,6 +17,10 @@ module Smartest
       Smartest.suite.fixture_classes.add(klass)
     end
 
-    private :test, :use_fixture
+    def use_matcher(matcher_module)
+      Smartest.suite.matcher_modules.add(matcher_module)
+    end
+
+    private :test, :use_fixture, :use_matcher
   end
 end

data/lib/smartest/init_generator.rb

@@ -13,6 +13,66 @@ module Smartest
         Dir[File.join(__dir__, "fixtures", "**", "*.rb")].sort.each do |fixture_file|
           require fixture_file
         end
+
+        Dir[File.join(__dir__, "matchers", "**", "*.rb")].sort.each do |matcher_file|
+          require matcher_file
+        end
+
+        use_matcher PredicateMatcher
+      RUBY
+      "smartest/matchers/predicate_matcher.rb" => <<~RUBY,
+        # frozen_string_literal: true
+
+        module PredicateMatcher
+          def method_missing(name, *arguments, &block)
+            matcher_name = name.to_s
+            return super unless matcher_name.match?(/\\Abe_.+\\z/)
+
+            Matcher.new(matcher_name.delete_prefix("be_"), arguments, block)
+          end
+
+          def respond_to_missing?(name, include_private = false)
+            name.to_s.match?(/\\Abe_.+\\z/) || super
+          end
+
+          class Matcher
+            def initialize(predicate_name, arguments, block)
+              @predicate_name = predicate_name
+              @predicate = "\#{predicate_name}?"
+              @arguments = arguments
+              @block = block
+            end
+
+            def matches?(actual)
+              @actual = actual
+              return false unless actual.respond_to?(@predicate)
+
+              !!actual.public_send(@predicate, *@arguments, &@block)
+            end
+
+            def failure_message
+              return "expected \#{@actual.inspect} to respond to \#{@predicate}" unless @actual.respond_to?(@predicate)
+
+              "expected \#{@actual.inspect} to be \#{description}"
+            end
+
+            def negated_failure_message
+              "expected \#{@actual.inspect} not to be \#{description}"
+            end
+
+            private
+
+            def description
+              return @predicate_name if @arguments.empty?
+
+              "\#{@predicate_name} \#{argument_description}"
+            end
+
+            def argument_description
+              @arguments.map(&:inspect).join(", ")
+            end
+          end
+        end
       RUBY
       "smartest/example_test.rb" => <<~RUBY
         # frozen_string_literal: true
@@ -33,6 +93,7 @@ module Smartest
     def run
       create_directory("smartest")
       create_directory("smartest/fixtures")
+      create_directory("smartest/matchers")
       FILES.each { |path, contents| create_file(path, contents) }
 
       @output.puts

data/lib/smartest/matcher_registry.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Smartest
+  class MatcherRegistry
+    include Enumerable
+
+    def initialize
+      @matcher_modules = []
+    end
+
+    def add(matcher_module)
+      unless matcher_module.is_a?(Module) && !matcher_module.is_a?(Class)
+        raise ArgumentError, "matcher must be a module"
+      end
+
+      @matcher_modules << matcher_module unless @matcher_modules.include?(matcher_module)
+    end
+
+    def each(&block)
+      @matcher_modules.each(&block)
+    end
+
+    def to_a
+      @matcher_modules.dup
+    end
+  end
+end

data/lib/smartest/runner.rb

@@ -2,9 +2,10 @@
 
 module Smartest
   class Runner
-    def initialize(suite: Smartest.suite, reporter: Reporter.new)
+    def initialize(suite: Smartest.suite, reporter: Reporter.new, tests: nil)
       @suite = suite
       @reporter = reporter
+      @tests = tests || suite.tests
     end
 
     def run
@@ -12,10 +13,10 @@ module Smartest
       suite_cleanup_errors = []
       @suite_fixture_set = nil
 
-      @reporter.start(@suite.tests.count)
+      @reporter.start(@tests.count)
 
       begin
-        @suite.tests.each do |test_case|
+        @tests.each do |test_case|
           result = run_one(test_case)
           results << result
           @reporter.record(result)
@@ -34,7 +35,7 @@ module Smartest
 
     def run_one(test_case)
       started_at = now
-      context = ExecutionContext.new
+      context = build_context
       fixture_set = nil
       error = nil
       cleanup_errors = []
@@ -68,11 +69,17 @@ module Smartest
     def suite_fixture_set
       @suite_fixture_set ||= FixtureSet.new(
         @suite.fixture_classes,
-        context: ExecutionContext.new,
+        context: build_context,
         scope: :suite
       )
     end
 
+    def build_context
+      ExecutionContext.new.tap do |context|
+        @suite.matcher_modules.each { |matcher_module| context.extend(matcher_module) }
+      end
+    end
+
     def now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/smartest/suite.rb

@@ -2,11 +2,12 @@
 
 module Smartest
   class Suite
-    attr_reader :tests, :fixture_classes
+    attr_reader :tests, :fixture_classes, :matcher_modules
 
     def initialize
       @tests = TestRegistry.new
       @fixture_classes = FixtureClassRegistry.new
+      @matcher_modules = MatcherRegistry.new
     end
   end
 end

data/lib/smartest/test_case.rb

@@ -14,5 +14,51 @@ module Smartest
       @location = location
       @fixture_names = ParameterExtractor.required_keyword_names(block, usage: :test)
     end
+
+    def includes_line?(line)
+      includes_line_range?(line..line)
+    end
+
+    def includes_line_range?(range)
+      return false unless location
+
+      current_range = line_range
+      current_range.begin <= range.end && range.begin <= current_range.end
+    end
+
+    private
+
+    def line_range
+      location.lineno..end_lineno
+    end
+
+    def end_lineno
+      @end_lineno ||= inferred_end_lineno
+    end
+
+    def inferred_end_lineno
+      code_location = instruction_sequence_metadata[:code_location]
+      return code_location[2] if code_location&.length == 4
+
+      instruction_sequence_line_numbers.max || location.lineno
+    rescue StandardError
+      location.lineno
+    end
+
+    def instruction_sequence_metadata
+      return {} unless defined?(RubyVM::InstructionSequence)
+
+      sequence = RubyVM::InstructionSequence.of(block)
+      metadata = sequence&.to_a&.[](4)
+      metadata.is_a?(Hash) ? metadata : {}
+    end
+
+    def instruction_sequence_line_numbers
+      return [] unless defined?(RubyVM::InstructionSequence)
+
+      sequence = RubyVM::InstructionSequence.of(block)
+      body = sequence&.to_a&.last
+      body.is_a?(Array) ? body.select { |entry| entry.is_a?(Integer) } : []
+    end
   end
 end

data/lib/smartest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Smartest
-  VERSION = "0.1.0.alpha1"
+  VERSION = "0.1.0.alpha3"
 end

data/lib/smartest.rb

@@ -8,6 +8,7 @@ require_relative "smartest/test_registry"
 require_relative "smartest/fixture_definition"
 require_relative "smartest/fixture"
 require_relative "smartest/fixture_class_registry"
+require_relative "smartest/matcher_registry"
 require_relative "smartest/fixture_set"
 require_relative "smartest/suite"
 require_relative "smartest/expectations"
@@ -19,6 +20,7 @@ require_relative "smartest/test_result"
 require_relative "smartest/reporter"
 require_relative "smartest/runner"
 require_relative "smartest/init_generator"
+require_relative "smartest/cli_arguments"
 
 module Smartest
   class << self

data/smartest/smartest_test.rb

@@ -95,6 +95,58 @@ test("supports basic matchers") do
   expect(status).to eq(0)
 end
 
+test("registers matcher modules for suite execution contexts") do
+  status_matcher = Class.new do
+    def initialize(expected)
+      @expected = expected
+    end
+
+    def matches?(actual)
+      @actual = actual
+      actual.status == @expected
+    end
+
+    def failure_message
+      "expected #{@actual.inspect} to have status #{@expected.inspect}"
+    end
+
+    def negated_failure_message
+      "expected #{@actual.inspect} not to have status #{@expected.inspect}"
+    end
+  end
+
+  custom_matchers = Module.new do
+    define_method(:have_status) do |expected|
+      status_matcher.new(expected)
+    end
+  end
+
+  response = Struct.new(:status).new(200)
+  suite = Smartest::Suite.new
+  suite.matcher_modules.add(custom_matchers)
+  suite.tests.add(SmartestSelfTest.test_case("custom matcher", proc { expect(response).to have_status(200) }))
+
+  status, = SmartestSelfTest.run_suite(suite)
+
+  expect(status).to eq(0)
+end
+
+test("rejects non-module matcher registrations") do
+  error = SmartestSelfTest.capture_error(ArgumentError) do
+    Smartest::MatcherRegistry.new.add(Object.new)
+  end
+
+  expect(error.message).to include("matcher must be a module")
+end
+
+test("rejects class matcher registrations") do
+  error = SmartestSelfTest.capture_error(ArgumentError) do
+    Smartest::MatcherRegistry.new.add(Class.new)
+  end
+
+  expect(error.message).to include("matcher must be a module")
+end
+
 test("resolves keyword fixture dependencies per test") do
   calls = []
 
@@ -477,6 +529,157 @@ test("cli loads files and returns failure status") do
   end
 end
 
+test("cli loads matcher files registered in test helper") do
+  Dir.mktmpdir do |dir|
+    smartest_dir = File.join(dir, "smartest")
+    matchers_dir = File.join(smartest_dir, "matchers")
+    FileUtils.mkdir_p(matchers_dir)
+    File.write(File.join(smartest_dir, "test_helper.rb"), <<~RUBY)
+      require "smartest/autorun"
+
+      Dir[File.join(__dir__, "matchers", "**", "*.rb")].sort.each do |matcher_file|
+        require matcher_file
+      end
+
+      use_matcher HaveStatusMatcher
+    RUBY
+    File.write(File.join(matchers_dir, "have_status_matcher.rb"), <<~RUBY)
+      module HaveStatusMatcher
+        class MatcherImpl
+          def initialize(expected)
+            @expected = expected
+          end
+
+          def matches?(actual)
+            @actual = actual
+            actual.status == @expected
+          end
+
+          def failure_message
+            "expected \#{@actual.inspect} to have status \#{@expected.inspect}"
+          end
+
+          def negated_failure_message
+            "expected \#{@actual.inspect} not to have status \#{@expected.inspect}"
+          end
+        end
+
+        def have_status(expected)
+          MatcherImpl.new(expected)
+        end
+      end
+    RUBY
+
+    File.write(File.join(smartest_dir, "sample_test.rb"), <<~RUBY)
+      require "test_helper"
+
+      Response = Struct.new(:status)
+
+      test("custom matcher") do
+        expect(Response.new(200)).to have_status(200)
+      end
+    RUBY
+
+    stdout, stderr, status = Open3.capture3(
+      { "RUBYLIB" => File.expand_path("../lib", __dir__) },
+      "ruby",
+      File.expand_path("../exe/smartest", __dir__),
+      "smartest/sample_test.rb",
+      chdir: dir
+    )
+
+    expect(status.success?).to eq(true)
+    expect(stderr).to eq("")
+    expect(stdout).to include("custom matcher")
+    expect(stdout).to include("1 test, 1 passed, 0 failed")
+  end
+end
+
+test("cli runs tests matching a file line filter") do
+  Dir.mktmpdir do |dir|
+    smartest_dir = File.join(dir, "smartest")
+    FileUtils.mkdir_p(smartest_dir)
+    File.write(File.join(smartest_dir, "test_helper.rb"), <<~RUBY)
+      require "smartest/autorun"
+    RUBY
+
+    test_file = File.join(smartest_dir, "sample_test.rb")
+    File.write(test_file, <<~RUBY)
+      require "test_helper"
+
+      test("line one") do
+        expect(1).to eq(1)
+      end
+
+      test("line two") do
+        expect(2).to eq(2)
+      end
+    RUBY
+    line_number = File.readlines(test_file).find_index { |line| line.include?("expect(2)") } + 1
+
+    stdout, stderr, status = Open3.capture3(
+      { "RUBYLIB" => File.expand_path("../lib", __dir__) },
+      "ruby",
+      File.expand_path("../exe/smartest", __dir__),
+      "smartest/sample_test.rb:#{line_number}",
+      chdir: dir
+    )
+
+    expect(status.success?).to eq(true)
+    expect(stderr).to eq("")
+    expect(stdout).to include("Running 1 test")
+    expect(stdout).not_to include("line one")
+    expect(stdout).to include("line two")
+    expect(stdout).to include("1 test, 1 passed, 0 failed")
+  end
+end
+
+test("cli runs tests intersecting a file line range filter") do
+  Dir.mktmpdir do |dir|
+    smartest_dir = File.join(dir, "smartest")
+    FileUtils.mkdir_p(smartest_dir)
+    File.write(File.join(smartest_dir, "test_helper.rb"), <<~RUBY)
+      require "smartest/autorun"
+    RUBY
+
+    test_file = File.join(smartest_dir, "sample_test.rb")
+    File.write(test_file, <<~RUBY)
+      require "test_helper"
+
+      test("range one") do
+        expect(1).to eq(1)
+      end
+
+      test("range two") do
+        expect(2).to eq(2)
+      end
+
+      test("range three") do
+        expect(3).to eq(3)
+      end
+    RUBY
+    lines = File.readlines(test_file)
+    start_line = lines.find_index { |line| line.include?("expect(1)") } + 1
+    end_line = lines.find_index { |line| line.include?("expect(2)") } + 1
+
+    stdout, stderr, status = Open3.capture3(
+      { "RUBYLIB" => File.expand_path("../lib", __dir__) },
+      "ruby",
+      File.expand_path("../exe/smartest", __dir__),
+      "smartest/sample_test.rb:#{start_line}-#{end_line}",
+      chdir: dir
+    )
+
+    expect(status.success?).to eq(true)
+    expect(stderr).to eq("")
+    expect(stdout).to include("Running 2 tests")
+    expect(stdout).to include("range one")
+    expect(stdout).to include("range two")
+    expect(stdout).not_to include("range three")
+    expect(stdout).to include("2 tests, 2 passed, 0 failed")
+  end
+end
+
 test("cli default suite ignores minitest-style test directory") do
   Dir.mktmpdir do |dir|
     smartest_dir = File.join(dir, "smartest")
@@ -541,6 +744,7 @@ test("cli prints help") do
   expect(stderr).to eq("")
   expect(stdout).to include("Usage:")
   expect(stdout).to include("smartest [paths...]")
+  expect(stdout).to include("smartest path/to/test_file.rb:line[-line]")
   expect(stdout).to include("smartest --init")
   expect(stdout).to include("smartest/**/*_test.rb")
 end
@@ -559,11 +763,17 @@ test("cli initializes a runnable test scaffold") do
     expect(stderr).to eq("")
     expect(stdout).to include("create  smartest")
     expect(stdout).to include("create  smartest/fixtures")
+    expect(stdout).to include("create  smartest/matchers")
     expect(stdout).to include("create  smartest/test_helper.rb")
+    expect(stdout).to include("create  smartest/matchers/predicate_matcher.rb")
     expect(stdout).to include("create  smartest/example_test.rb")
     helper_contents = File.read(File.join(dir, "smartest/test_helper.rb"))
     expect(helper_contents).to include('require "smartest/autorun"')
     expect(helper_contents).to include('Dir[File.join(__dir__, "fixtures", "**", "*.rb")].sort.each')
+    expect(helper_contents).to include('Dir[File.join(__dir__, "matchers", "**", "*.rb")].sort.each')
+    expect(helper_contents).to include("use_matcher PredicateMatcher")
+    predicate_matcher_contents = File.read(File.join(dir, "smartest/matchers/predicate_matcher.rb"))
+    expect(predicate_matcher_contents).to include("module PredicateMatcher")
     expect(File.read(File.join(dir, "smartest/example_test.rb"))).to include('require "test_helper"')
 
     nested_fixtures_dir = File.join(dir, "smartest/fixtures/nested")
@@ -586,6 +796,54 @@ test("cli initializes a runnable test scaffold") do
       end
     RUBY
 
+    nested_matchers_dir = File.join(dir, "smartest/matchers/nested")
+    FileUtils.mkdir_p(nested_matchers_dir)
+    File.write(File.join(nested_matchers_dir, "auto_loaded_matcher.rb"), <<~RUBY)
+      module AutoLoadedMatcher
+        class Matcher
+          def initialize(expected)
+            @expected = expected
+          end
+
+          def matches?(actual)
+            @actual = actual
+            actual == @expected
+          end
+
+          def failure_message
+            "expected \#{@actual.inspect} to auto-eq \#{@expected.inspect}"
+          end
+
+          def negated_failure_message
+            "expected \#{@actual.inspect} not to auto-eq \#{@expected.inspect}"
+          end
+        end
+
+        def auto_eq(expected)
+          Matcher.new(expected)
+        end
+      end
+    RUBY
+
+    File.write(File.join(dir, "smartest/auto_loaded_matcher_test.rb"), <<~RUBY)
+      require "test_helper"
+
+      use_matcher AutoLoadedMatcher
+
+      test("auto-loaded matcher") do
+        expect("loaded from smartest/matchers").to auto_eq("loaded from smartest/matchers")
+      end
+    RUBY
+
+    File.write(File.join(dir, "smartest/predicate_matcher_test.rb"), <<~RUBY)
+      require "test_helper"
+
+      test("generated predicate matcher") do
+        expect("").to be_empty
+        expect(2).to be_between(1, 3)
+      end
+    RUBY
+
     run_stdout, run_stderr, run_status = Open3.capture3(
       { "RUBYLIB" => File.expand_path("../lib", __dir__) },
       "ruby",
@@ -597,7 +855,9 @@ test("cli initializes a runnable test scaffold") do
     expect(run_stderr).to eq("")
     expect(run_stdout).to include("example")
     expect(run_stdout).to include("auto-loaded fixture")
-    expect(run_stdout).to include("2 tests, 2 passed, 0 failed")
+    expect(run_stdout).to include("auto-loaded matcher")
+    expect(run_stdout).to include("generated predicate matcher")
+    expect(run_stdout).to include("4 tests, 4 passed, 0 failed")
   end
 end
 
@@ -605,13 +865,17 @@ test("cli init does not overwrite existing scaffold files") do
   Dir.mktmpdir do |dir|
     smartest_dir = File.join(dir, "smartest")
     fixture_dir = File.join(smartest_dir, "fixtures")
+    matcher_dir = File.join(smartest_dir, "matchers")
     FileUtils.mkdir_p(fixture_dir)
+    FileUtils.mkdir_p(matcher_dir)
     helper_path = File.join(smartest_dir, "test_helper.rb")
     example_path = File.join(smartest_dir, "example_test.rb")
     fixture_path = File.join(fixture_dir, "custom_fixture.rb")
+    matcher_path = File.join(matcher_dir, "predicate_matcher.rb")
     File.write(helper_path, "# custom helper\n")
     File.write(example_path, "# custom test\n")
     File.write(fixture_path, "# custom fixture\n")
+    File.write(matcher_path, "# custom matcher\n")
 
     stdout, stderr, status = Open3.capture3(
       { "RUBYLIB" => File.expand_path("../lib", __dir__) },
@@ -625,10 +889,13 @@ test("cli init does not overwrite existing scaffold files") do
     expect(stderr).to eq("")
     expect(stdout).to include("exist   smartest")
     expect(stdout).to include("exist   smartest/fixtures")
+    expect(stdout).to include("exist   smartest/matchers")
     expect(stdout).to include("exist   smartest/test_helper.rb")
+    expect(stdout).to include("exist   smartest/matchers/predicate_matcher.rb")
     expect(stdout).to include("exist   smartest/example_test.rb")
     expect(File.read(helper_path)).to eq("# custom helper\n")
     expect(File.read(example_path)).to eq("# custom test\n")
     expect(File.read(fixture_path)).to eq("# custom fixture\n")
+    expect(File.read(matcher_path)).to eq("# custom matcher\n")
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smartest
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha1
+  version: 0.1.0.alpha3
 platform: ruby
 authors:
 - Yusuke Iwaki
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-26 00:00:00.000000000 Z
+date: 2026-04-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -42,6 +42,7 @@ files:
 - exe/smartest
 - lib/smartest.rb
 - lib/smartest/autorun.rb
+- lib/smartest/cli_arguments.rb
 - lib/smartest/dsl.rb
 - lib/smartest/errors.rb
 - lib/smartest/execution_context.rb
@@ -52,6 +53,7 @@ files:
 - lib/smartest/fixture_definition.rb
 - lib/smartest/fixture_set.rb
 - lib/smartest/init_generator.rb
+- lib/smartest/matcher_registry.rb
 - lib/smartest/matchers.rb
 - lib/smartest/parameter_extractor.rb
 - lib/smartest/reporter.rb