smartest 0.3.3.alpha4 → 0.5.0.alpha1

data/SMARTEST_DESIGN.md

@@ -30,7 +30,7 @@ Fixture definitions:
 class WebFixture < Smartest::Fixture
   fixture :server do
     server = TestServer.start
-    cleanup { server.stop }
+    on_teardown { server.stop }
 
     server.wait_until_ready!
     server
@@ -195,12 +195,12 @@ server teardown
 
 This is especially complex when fixtures depend on other fixtures.
 
-Smartest instead chooses `cleanup` for the MVP:
+Smartest instead chooses `on_teardown` for the MVP:
 
 ```ruby
 fixture :server do
   server = TestServer.start
-  cleanup { server.stop }
+  on_teardown { server.stop }
 
   server.wait_until_ready!
   server
@@ -214,7 +214,7 @@ This has several advantages:
 - teardown is local to the fixture that owns the resource
 - implementation is simple
 - fixture dependencies remain ordinary recursive resolution
-- cleanup runs in `ensure`
+- teardown runs in `ensure`
 
 Not every fixture needs teardown, so teardown should not shape the entire fixture API.
 
@@ -236,12 +236,12 @@ fixture :article do |user:|
 end
 ```
 
-A fixture may register cleanup.
+A fixture may register teardown.
 
 ```ruby
 fixture :temp_dir do
   dir = Dir.mktmpdir
-  cleanup { FileUtils.rm_rf(dir) }
+  on_teardown { FileUtils.rm_rf(dir) }
   dir
 end
 ```
@@ -316,7 +316,7 @@ Runner
   ├── creates FixtureSet
   ├── resolves keyword fixtures
   ├── executes test body
-  ├── runs cleanup
+  ├── runs teardown
   └── reports TestResult
 ```
 
@@ -343,7 +343,7 @@ end
 
 fixture :server do
   server = TestServer.start
-  cleanup { server.stop }
+  on_teardown { server.stop }
   server
 end
 
@@ -363,7 +363,7 @@ resolve logged_in_client
       requires server
         resolve server
           evaluate server block
-          register cleanup
+          register teardown
           cache server
       evaluate client block with server:
       cache client
@@ -376,7 +376,7 @@ resolve logged_in_client
 
 execute test body with logged_in_client:
 
-run cleanup stack in reverse order
+run teardown stack in reverse order
 ```
 
 ## Fixture caching
@@ -397,33 +397,33 @@ shared for the runner lifetime.
 This keeps regular fixtures isolated while allowing explicit suite fixtures for
 expensive shared resources.
 
-## Cleanup stack
+## Teardown stack
 
-`FixtureSet` owns a cleanup stack for one fixture scope.
+`FixtureSet` owns a teardown stack for one fixture scope.
 
 ```ruby
-@cleanups = []
+@teardowns = []
 ```
 
 Fixture blocks can call:
 
 ```ruby
-cleanup { resource.close }
+on_teardown { resource.close }
 ```
 
 This delegates to:
 
 ```ruby
-fixture_set.add_cleanup(&block)
+fixture_set.add_teardown(&block)
 ```
 
-For test-scoped fixtures, cleanup runs after the test in reverse order:
+For test-scoped fixtures, teardown runs after the test in reverse order:
 
 ```ruby
-@cleanups.reverse_each(&:call)
+@teardowns.reverse_each(&:call)
 ```
 
-For suite-scoped fixtures, cleanup runs after all tests. Reverse order matters
+For suite-scoped fixtures, teardown runs after all tests. Reverse order matters
 because later resources may depend on earlier ones.
 
 Example:
@@ -431,18 +431,18 @@ Example:
 ```ruby
 fixture :server do
   server = TestServer.start
-  cleanup { server.stop }
+  on_teardown { server.stop }
   server
 end
 
 fixture :browser do |server:|
   browser = Browser.launch(server.url)
-  cleanup { browser.close }
+  on_teardown { browser.close }
   browser
 end
 ```
 
-Cleanup should run:
+Teardown should run:
 
 ```text
 browser.close
@@ -669,7 +669,7 @@ Fixture block execution happens on the fixture instance:
 fixture_instance.instance_exec(**dependencies, &definition.block)
 ```
 
-This allows fixture helper methods and `cleanup` to be private instance methods.
+This allows fixture helper methods and `on_teardown` to be private instance methods.
 
 ## Helper methods in fixtures
 
@@ -856,7 +856,24 @@ If no paths are given:
 bundle exec smartest
 ```
 
-should default to:
+should default to `smartest/**/*_test.rb` when `smartest/` exists. If the
+directory does not exist, the CLI should print scaffold guidance and exit with
+status `1`:
+
+```text
+No smartest/ directory found.
+
+To create a Smartest test scaffold:
+  bundle exec smartest --init
+
+For browser tests:
+  bundle exec smartest --init-browser
+
+See all commands:
+  bundle exec smartest --help
+```
+
+Default paths:
 
 ```text
 smartest/**/*_test.rb
@@ -877,8 +894,8 @@ arguments.files.each { |file| load File.expand_path(file) }
 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::CLIArguments` should support file paths, directory paths, shell
+globs, `path:line`, and `path:start-end` filters.
 
 `smartest/autorun` should use `at_exit`.
 
@@ -947,7 +964,7 @@ end
 ```
 
 `around_suite` wraps the full suite body, including all tests and suite fixture
-cleanup. The hook receives a run target and must call `suite.run` exactly once.
+teardown. The hook receives a run target and must call `suite.run` exactly once.
 Multiple hooks compose in registration order, with the first hook as the
 outermost wrapper.
 
@@ -996,7 +1013,7 @@ For `around_test`, those registrations are test-run local and must happen before
 `test.run`.
 
 Fixture classes registered from `around_test` must not define `suite_fixture`.
-Suite-scoped fixtures need suite-level cache and cleanup ownership, so classes
+Suite-scoped fixtures need suite-level cache and teardown ownership, so classes
 with suite-scoped fixtures must be registered from `around_suite`.
 
 Potential simpler per-test API:
@@ -1019,7 +1036,7 @@ Order:
 before hooks
 fixture setup
 test body
-fixture cleanup
+fixture teardown
 after hooks
 ```
 
@@ -1030,12 +1047,12 @@ fixture setup
 before hooks
 test body
 after hooks
-fixture cleanup
+fixture teardown
 ```
 
 This needs a final decision later.
 
-Fixture cleanup already handles resource-specific teardown.
+Fixture teardown already handles resource-specific teardown.
 
 ### Around-test parallelism note
 
@@ -1069,7 +1086,7 @@ Expensive shared resources can use `suite_fixture`:
 ```ruby
 suite_fixture :server do
   server = TestServer.start
-  cleanup { server.stop }
+  on_teardown { server.stop }
   server
 end
 ```
@@ -1082,7 +1099,7 @@ Supported scopes:
 `fixture :name do ... end` creates a test-scoped fixture.
 
 `suite_fixture :name do ... end` creates a suite-scoped fixture. It is lazy:
-setup runs the first time a test requests it, and cleanup runs after all tests.
+setup runs the first time a test requests it, and teardown runs after all tests.
 
 Test-scoped fixtures may depend on suite-scoped fixtures. Suite-scoped fixtures
 may depend only on other suite-scoped fixtures.
@@ -1119,7 +1136,7 @@ Benefits:
 - reusable fixture modules
 - clearer organization
 - fewer global definitions
-- natural place for cleanup helper
+- natural place for teardown helper
 
 Example:
 
@@ -1180,7 +1197,7 @@ Pros:
 - easy dependency extraction
 - easy duplicate detection
 - easy source locations
-- easy cleanup integration
+- easy teardown integration
 
 ### `fixture def user`
 
@@ -1224,7 +1241,7 @@ Reason:
 
 - requires around-chain execution
 - complicates dependency handling
-- not needed if `cleanup` exists
+- not needed if `on_teardown` exists
 - makes fixture API more complex
 
 Could be added later as advanced API.
@@ -1254,7 +1271,7 @@ class AppFixture < Smartest::Fixture
 
   fixture :server do
     server = TestServer.start
-    cleanup { server.stop }
+    on_teardown { server.stop }
     server
   end
 

data/exe/smartest

@@ -7,18 +7,51 @@ require "smartest"
 
 usage = <<~USAGE
   Usage:
-    smartest [--profile N] [paths...]
-    smartest [--profile N] path/to/test_file.rb:line[-line]
-    smartest --init
-    smartest --init-browser
-    smartest --version
-    smartest --help
-
-  When no paths are given, Smartest loads smartest/**/*_test.rb.
-  Smartest prints the 5 slowest tests after the run by default.
-  Use --profile N to choose how many slowest tests are printed.
+    bundle exec smartest [options] [paths...]
+
+  Common commands:
+    bundle exec smartest
+        Run tests under smartest/**/*_test.rb
+
+    bundle exec smartest smartest/suite1/
+        Run test files matching smartest/suite1/**/*_test.rb
+
+    bundle exec smartest smartest/user_test.rb
+        Run one test file
+
+    bundle exec smartest smartest/user_test.rb:12
+        Run tests around line 12
+
+    bundle exec smartest --init
+        Generate a basic Smartest scaffold
+
+    bundle exec smartest --init-browser
+        Generate a Playwright browser-test scaffold
+
+  Options:
+    --profile N
+        Print the N slowest tests. Defaults to 5.
+
+    --version, -v
+        Print the installed Smartest version.
+
+    --help, -h
+        Print this help.
 USAGE
 
+missing_smartest_directory_message = <<~MESSAGE
+  No smartest/ directory found.
+
+  To create a Smartest test scaffold:
+    bundle exec smartest --init
+
+  For browser tests:
+    bundle exec smartest --init-browser
+
+  See all commands:
+    bundle exec smartest --help
+MESSAGE
+
 command = :run
 
 begin
@@ -45,10 +78,16 @@ begin
   Smartest.disable_autorun!
   Smartest.install_dsl!
   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)
 
   arguments = Smartest::CLIArguments.new(ARGV)
 
+  if arguments.default_paths? && !Dir.exist?(test_load_path)
+    puts missing_smartest_directory_message
+    exit 1
+  end
+
+  $LOAD_PATH.unshift(test_load_path) if Dir.exist?(test_load_path) && !$LOAD_PATH.include?(test_load_path)
+
   arguments.files.each do |file|
     load File.expand_path(file)
   end

data/lib/smartest/cli_arguments.rb

@@ -5,6 +5,7 @@ require "set"
 module Smartest
   class CLIArguments
     DEFAULT_PROFILE_COUNT = 5
+    DEFAULT_PATHS = ["smartest/**/*_test.rb"].freeze
 
     attr_reader :files, :line_filters, :profile_count
 
@@ -13,15 +14,25 @@ module Smartest
       @whole_files = Set.new
       @line_filters = Hash.new { |hash, key| hash[key] = Set.new }
       @profile_count = DEFAULT_PROFILE_COUNT
+      @default_paths = false
 
       paths = extract_options(argv)
-      parse_paths(paths.empty? ? ["smartest/**/*_test.rb"] : paths)
+      if paths.empty?
+        @default_paths = true
+        paths = DEFAULT_PATHS
+      end
+
+      parse_paths(paths)
     end
 
     def filter_tests?
       @line_filters.any?
     end
 
+    def default_paths?
+      @default_paths
+    end
+
     def select_tests(tests)
       return tests unless filter_tests?
 
@@ -64,8 +75,7 @@ module Smartest
     def parse_paths(paths)
       paths.each do |argument|
         pattern, line_filter = split_line_filter(argument)
-        matches = Dir[pattern]
-        files = matches.empty? ? [pattern] : matches
+        files = expand_path_pattern(pattern)
 
         files.each do |file|
           @files << file
@@ -82,6 +92,19 @@ module Smartest
       @files.uniq!
     end
 
+    def expand_path_pattern(pattern)
+      matches = Dir[pattern]
+      return [pattern] if matches.empty?
+
+      matches.flat_map do |match|
+        if File.directory?(match)
+          Dir[File.join(match, "**", "*_test.rb")]
+        else
+          match
+        end
+      end
+    end
+
     def split_line_filter(argument)
       match = argument.match(/\A(.+):(\d+)(?:-(\d+))?\z/)
       return [argument, nil] unless match

data/lib/smartest/constant_stub_helpers.rb

@@ -4,10 +4,10 @@ module Smartest
   module ConstantStubHelpers
     private
 
-    def simple_stub_const(constant_path, value)
-      raise ArgumentError, "simple_stub_const block is required" unless block_given?
+    def with_stub_const(constant_path, value)
+      raise ArgumentError, "with_stub_const block is required" unless block_given?
 
-      owner, constant_name = resolve_simple_stub_constant(constant_path)
+      owner, constant_name = resolve_with_stub_constant(constant_path)
       original_defined = owner.const_defined?(constant_name, false)
       original_value = owner.const_get(constant_name, false) if original_defined
 
@@ -22,7 +22,7 @@ module Smartest
       end
     end
 
-    def resolve_simple_stub_constant(constant_path)
+    def resolve_with_stub_constant(constant_path)
       unless constant_path.is_a?(String) || constant_path.is_a?(Symbol)
         raise ArgumentError, "constant path must be a String or Symbol"
       end

data/lib/smartest/fixture.rb

@@ -2,7 +2,7 @@
 
 module Smartest
   class Fixture
-    RESERVED_CONTEXT_METHODS = %i[skip pending simple_stub_const].freeze
+    RESERVED_CONTEXT_METHODS = %i[skip pending with_stub_const].freeze
 
     class << self
       def fixture(name, scope: :test, &block)
@@ -59,10 +59,10 @@ module Smartest
 
     private
 
-    def cleanup(&block)
-      raise ArgumentError, "cleanup block is required" unless block
+    def on_teardown(&block)
+      raise ArgumentError, "on_teardown block is required" unless block
 
-      @fixture_set.add_cleanup(&block)
+      @fixture_set.add_teardown(&block)
     end
 
     def simple_stub_any_instance_of(klass, method_name, &block)
@@ -75,7 +75,7 @@ module Smartest
 
     def apply_simple_stub(stub)
       stub.apply!
-      cleanup { stub.reset }
+      on_teardown { stub.reset }
       stub
     end
 

data/lib/smartest/fixture_set.rb

@@ -9,7 +9,7 @@ module Smartest
       @parent = parent
       @cache = {}
       @setup_errors = {}
-      @cleanups = []
+      @teardowns = []
       @resolving = []
 
       build_fixture_index
@@ -49,17 +49,17 @@ module Smartest
       @resolving.pop if @resolving.last == symbol_name
     end
 
-    def add_cleanup(&block)
-      raise ArgumentError, "cleanup block is required" unless block
+    def add_teardown(&block)
+      raise ArgumentError, "on_teardown block is required" unless block
 
-      @cleanups << block
+      @teardowns << block
     end
 
-    def run_cleanups
+    def run_teardowns
       errors = []
 
-      @cleanups.reverse_each do |cleanup|
-        cleanup.call
+      @teardowns.reverse_each do |teardown|
+        teardown.call
       rescue Exception => error
         raise if Smartest.fatal_exception?(error)
 

data/lib/smartest/init_browser_generator.rb

@@ -14,7 +14,7 @@ module Smartest
           runtime = Playwright.create(
             playwright_cli_executable_path: "./node_modules/.bin/playwright",
           )
-          cleanup { runtime.stop }
+          on_teardown { runtime.stop }
           runtime.playwright
         end
 
@@ -35,13 +35,13 @@ module Smartest
           end
 
           browser = playwright.send(browser_type).launch(**launch_options)
-          cleanup { browser.close }
+          on_teardown { browser.close }
           browser
         end
 
         fixture :page do |browser:|
           context = browser.new_context
-          cleanup { context.close }
+          on_teardown { context.close }
           context.new_page
         end
       end

data/lib/smartest/reporter.rb

@@ -21,14 +21,14 @@ module Smartest
       @io.puts record_line(result)
     end
 
-    def finish(results, suite_cleanup_errors: [], suite_errors: [])
+    def finish(results, suite_teardown_errors: [], suite_errors: [])
       failures = results.select(&:failed?)
       skipped = results.select(&:skipped?)
       pending = results.select(&:pending?)
 
       report_failures(failures) if failures.any?
       report_suite_errors(suite_errors) if suite_errors.any?
-      report_suite_cleanup_errors(suite_cleanup_errors) if suite_cleanup_errors.any?
+      report_suite_teardown_errors(suite_teardown_errors) if suite_teardown_errors.any?
       report_profile(results) if @profile_count && @profile_count.positive?
 
       @io.puts
@@ -39,9 +39,9 @@ module Smartest
         suite_label = suite_errors.count == 1 ? "suite failure" : "suite failures"
         summary = "#{summary}, #{suite_errors.count} #{suite_label}"
       end
-      if suite_cleanup_errors.any?
-        cleanup_label = suite_cleanup_errors.count == 1 ? "suite cleanup" : "suite cleanups"
-        summary = "#{summary}, #{suite_cleanup_errors.count} #{cleanup_label} failed"
+      if suite_teardown_errors.any?
+        teardown_label = suite_teardown_errors.count == 1 ? "suite teardown" : "suite teardowns"
+        summary = "#{summary}, #{suite_teardown_errors.count} #{teardown_label} failed"
       end
       @io.puts summary
     end
@@ -72,7 +72,7 @@ module Smartest
         @io.puts "#{index + 1}) #{result.test_case.name}"
         report_location(result.test_case.location)
         report_error(result.error) if result.error
-        result.cleanup_errors.each { |error| report_cleanup_error(error) }
+        result.teardown_errors.each { |error| report_teardown_error(error) }
         @io.puts
       end
     end
@@ -89,14 +89,14 @@ module Smartest
       end
     end
 
-    def report_suite_cleanup_errors(errors)
+    def report_suite_teardown_errors(errors)
       @io.puts
-      @io.puts "Suite cleanup failures:"
+      @io.puts "Suite teardown failures:"
       @io.puts
 
       errors.each_with_index do |error, index|
-        @io.puts "#{index + 1}) suite cleanup"
-        report_cleanup_error(error)
+        @io.puts "#{index + 1}) suite teardown"
+        report_teardown_error(error)
         @io.puts
       end
     end
@@ -148,8 +148,8 @@ module Smartest
       report_backtrace(error)
     end
 
-    def report_cleanup_error(error)
-      @io.puts "   cleanup failed: #{error.class}: #{error.message}"
+    def report_teardown_error(error)
+      @io.puts "   teardown failed: #{error.class}: #{error.message}"
       report_backtrace(error)
     end