smartest 0.1.0.alpha3 → 0.2.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1ce8aea4b74c7ca0de7f3a2b1472b79ea86849be91801e11922883b6423afdf
-  data.tar.gz: be5f8e88c1bd93eb061eb0a854b46a6c6094627b36cd22f8778026e35161992a
+  metadata.gz: ee5c1b7be401fa3dc4a8d88a25a241fc2b0bad486e8a3163a83c6c2340ae7c3c
+  data.tar.gz: f063204cd31bcd99b4654c26bb8591d566dcd424a2a312d9a7c9cbbea4292b01
 SHA512:
-  metadata.gz: 864cea53cff77bf90e73bdf6528c9e6ff7ba633c89c8edbf011bd50552d9bf1aea606c0a9e4af83352847f88b1ca8571433987d2f933d20b50270b2d2b81079d
-  data.tar.gz: d587ffbf743f4fe75d8977346ae653fe2616ab70e4480453442f4677f7d4d6a4f84166f64c17b50417616693232149ef36214c8c12d530de41a9ff5f36c75a51
+  metadata.gz: 18f117d867c86f47ff3d517729c0e7cbae4af5933b7432fa96ad30b1aea58a76b48e7ae4d3c129e72594598d19297751513d49501e5481c9ef07259a5350dafb
+  data.tar.gz: '085a5a10a7d5248d7888fd6267edae7c4dd88077f5b413d45385d4c05245b0eae771975ab67a50befc8ca14d8acb3d148d9718d94b431caf9800d2a2daa78627'

data/DEVELOPMENT.md

@@ -102,7 +102,8 @@ Responsibilities:
 
 - test registry
 - fixture class registry
-- hook registry, if hooks are implemented later
+- matcher registry
+- `around_suite` hook registry
 
 Example shape:
 
@@ -125,10 +126,14 @@ Required methods:
 
 ```ruby
 test(name, **metadata, &block)
-use_fixture(klass)
-use_matcher(matcher_module)
+around_suite(&block)
+around_test(&block)
 ```
 
+`use_fixture(klass)` and `use_matcher(matcher_module)` are not top-level DSL
+methods. They are available only from hook execution contexts: `around_suite`
+and `around_test`.
+
 Possible later methods:
 
 ```ruby
@@ -263,7 +268,10 @@ Responsibilities:
 Example:
 
 ```ruby
-use_fixture AppFixture
+around_suite do |suite|
+  use_fixture AppFixture
+  suite.run
+end
 ```
 
 should register `AppFixture`.
@@ -314,6 +322,7 @@ Runs tests.
 Responsibilities:
 
 - iterate over registered test cases
+- run registered `around_suite` hooks around the suite body
 - create a lazy suite-scoped `FixtureSet`
 - create a fresh `ExecutionContext` per test
 - create a fresh `FixtureSet` per test
@@ -324,6 +333,11 @@ Responsibilities:
 - produce `TestResult`
 - notify reporter
 
+`around_suite` hooks receive a run target and must call `suite.run` exactly once.
+Registered hooks compose in registration order, so the first hook is the
+outermost wrapper. If a hook raises or does not call `suite.run`, the runner
+reports a suite failure and exits with status `1`.
+
 Pseudo-code:
 
 ```ruby
@@ -577,7 +591,7 @@ A practical approach:
 
 - `Smartest::Fixture`
 - `fixture :name do ... end`
-- `use_fixture`
+- `use_fixture` from a hook context
 - test block keyword fixture resolution
 
 ### Phase 3: Fixture dependencies
@@ -620,6 +634,21 @@ A practical approach:
 - generate a `smartest/test_helper.rb` that loads `smartest/fixtures/**/*.rb`
 - exit code 0 on success, 1 on failure
 
+### Phase 7: Suite hooks
+
+- `around_suite do |suite| ... end`
+- run hooks around the full suite body
+- include suite fixture cleanup inside the wrapped body
+- report hook failures as suite failures
+
+### Phase 8: Test hooks
+
+- `around_test do |test| ... end`
+- snapshot file-local hooks when each test is registered
+- run hooks around fixture setup, test body, and fixture cleanup
+- expose `use_fixture` and `use_matcher` only inside hook contexts
+- make `around_test` registered from `around_suite` suite-wide
+
 ## MVP API rules
 
 Supported:
@@ -648,6 +677,18 @@ end
 cleanup { ... }
 ```
 
+```ruby
+around_suite do |suite|
+  suite.run
+end
+```
+
+```ruby
+around_test do |test|
+  test.run
+end
+```
+
 Not supported in MVP:
 
 ```ruby

data/README.md

@@ -173,9 +173,9 @@ 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).
+Custom matcher modules can be registered from `around_suite` or `around_test`
+with `use_matcher`. The generated scaffold includes a `PredicateMatcher` custom
+matcher for `be_<predicate>` calls. See [Matchers](documentation/docs/matchers.md).
 
 ## Fixtures
 
@@ -192,10 +192,13 @@ class AppFixture < Smartest::Fixture
 end
 ```
 
-Register fixture classes from `smartest/test_helper.rb`:
+Register fixture classes from `around_suite` in `smartest/test_helper.rb`:
 
 ```ruby
-use_fixture AppFixture
+around_suite do |suite|
+  use_fixture AppFixture
+  suite.run
+end
 ```
 
 Tests request fixtures by keyword:
@@ -274,6 +277,100 @@ Suite fixtures are lazy: setup runs the first time a test requests the fixture,
 and cleanup runs once after all tests finish. Test-scoped fixtures can depend on
 suite fixtures, but suite fixtures cannot depend on test-scoped fixtures.
 
+## Suite hooks
+
+Use `around_suite` when the full test run must execute inside another block:
+
+```ruby
+around_suite do |suite|
+  Async do
+    suite.run
+  end
+end
+```
+
+The hook receives a run target and must call `suite.run` exactly once. The block
+wraps every test, test-scoped fixture setup and cleanup, suite fixture setup, and
+suite fixture cleanup.
+
+Fixture and matcher registrations made before `suite.run` are applied to that
+run:
+
+```ruby
+around_suite do |suite|
+  use_fixture GlobalFixture
+  suite.run
+end
+```
+
+Multiple `around_suite` hooks run in registration order. The first hook is the
+outermost wrapper:
+
+```ruby
+around_suite do |suite|
+  with_outer_resource { suite.run }
+end
+
+around_suite do |suite|
+  with_inner_resource { suite.run }
+end
+```
+
+If an `around_suite` hook raises or does not call `suite.run`, Smartest reports a
+suite failure and exits with status `1`.
+
+## Test hooks
+
+Use `around_test` when each test needs to run inside another block:
+
+```ruby
+around_test do |test|
+  SomeAutoCloseResource.new do
+    test.run
+  end
+end
+```
+
+The hook receives a run target and must call `test.run` exactly once. It wraps
+fixture setup, the test body, and fixture cleanup.
+
+`around_test` is file-scoped when it is written directly in a test file. Smartest
+copies the current file's `around_test` hooks when each `test` is registered, so
+hooks apply to tests defined later in the same file.
+
+Define `around_test` inside `around_suite` when the hook should apply to the
+whole run:
+
+```ruby
+around_suite do |suite|
+  around_test do |test|
+    with_some_resource do
+      test.run
+    end
+  end
+
+  suite.run
+end
+```
+
+`around_test` can also register fixture classes or matcher modules for that test
+run:
+
+```ruby
+around_test do |test|
+  use_fixture LocalFixture
+  use_matcher LocalMatcher
+  test.run
+end
+```
+
+Fixture classes registered from `around_test` must define only test-scoped
+fixtures. If a class defines `suite_fixture`, register it from `around_suite`
+instead so its cache and cleanup belong to the suite lifecycle.
+
+`use_fixture` and `use_matcher` are only available inside `around_suite` or
+`around_test` blocks. They are not top-level DSL methods.
+
 ## Fixtures with teardown
 
 Not every fixture needs teardown. For fixtures that do, use `cleanup`.
@@ -355,7 +452,10 @@ end
 
 ```ruby
 # smartest/test_helper.rb
-use_fixture WebFixture
+around_suite do |suite|
+  use_fixture WebFixture
+  suite.run
+end
 ```
 
 ```ruby
@@ -391,41 +491,34 @@ server cleanup
 
 ## Registering fixture classes
 
-Use `use_fixture` from `smartest/test_helper.rb`:
+Use `use_fixture` inside `around_suite` from `smartest/test_helper.rb`:
 
 ```ruby
-use_fixture AppFixture
+around_suite do |suite|
+  use_fixture AppFixture
+  suite.run
+end
 ```
 
 Multiple fixture classes can be registered:
 
 ```ruby
-use_fixture UserFixture
-use_fixture WebFixture
-use_fixture ApiFixture
+around_suite do |suite|
+  use_fixture UserFixture
+  use_fixture WebFixture
+  use_fixture ApiFixture
+  suite.run
+end
 ```
 
 Fixture names must be unique across registered fixture classes.
 
 If two fixture classes define the same fixture name, Smartest raises an error.
 
-## Hooks
-
-Smartest may support simple hooks:
-
-```ruby
-before do
-  DatabaseCleaner.start
-end
+## Suite hooks and fixture cleanup
 
-after do
-  DatabaseCleaner.clean
-end
-```
-
-Hooks are separate from fixture cleanup.
-
-Use fixture cleanup for resource-specific teardown:
+Suite hooks are separate from fixture cleanup. Use fixture cleanup for
+resource-specific teardown:
 
 ```ruby
 fixture :server do
@@ -435,11 +528,11 @@ fixture :server do
 end
 ```
 
-Use hooks for broad test-level behavior:
+Use `around_suite` for broad suite-level execution context:
 
 ```ruby
-before do
-  reset_global_state
+around_suite do |suite|
+  Async { suite.run }
 end
 ```
 
@@ -469,13 +562,16 @@ Dir[File.join(__dir__, "matchers", "**", "*.rb")].sort.each do |matcher_file|
   require matcher_file
 end
 
-use_fixture WebFixture
-use_matcher PredicateMatcher
+around_suite do |suite|
+  use_fixture WebFixture
+  use_matcher PredicateMatcher
+  suite.run
+end
 ```
 
 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`.
+`smartest/matchers/` in sorted order. Register suite-wide fixture classes and
+matcher modules from `around_suite` with `use_fixture` and `use_matcher`.
 
 Example:
 
@@ -550,6 +646,8 @@ The intended MVP includes:
 - keyword-argument fixture injection
 - fixture dependencies through keyword arguments
 - fixture cleanup
+- suite hooks with `around_suite`
+- test hooks with `around_test`
 - `expect(...).to eq(...)`
 - console reporter
 - CLI runner

data/SMARTEST_DESIGN.md

@@ -50,7 +50,10 @@ class WebFixture < Smartest::Fixture
   end
 end
 
-use_fixture WebFixture
+around_suite do |suite|
+  use_fixture WebFixture
+  suite.run
+end
 ```
 
 The core decision is:
@@ -294,7 +297,9 @@ context.instance_exec(**fixtures, &block)
 
 This keeps the top-level DSL small.
 
-Only `test`, `fixture`, `use_fixture`, and `use_matcher` need to be globally available when using `smartest/autorun`.
+Only `test`, `around_suite`, and `around_test` should be globally available when
+using `smartest/autorun`. `use_fixture` and `use_matcher` are available only
+inside hook execution contexts.
 
 ## Core architecture
 
@@ -543,8 +548,11 @@ class AdminFixture < Smartest::Fixture
   end
 end
 
-use_fixture UserFixture
-use_fixture AdminFixture
+around_suite do |suite|
+  use_fixture UserFixture
+  use_fixture AdminFixture
+  suite.run
+end
 ```
 
 Error:
@@ -853,7 +861,70 @@ Useful metadata later:
 
 Hooks are separate from fixtures.
 
-Potential API:
+Supported suite API:
+
+```ruby
+around_suite do |suite|
+  Async do
+    suite.run
+  end
+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.
+Multiple hooks compose in registration order, with the first hook as the
+outermost wrapper.
+
+Supported per-test API:
+
+```ruby
+around_test do |test|
+  SomeAutoCloseResource.new do
+    test.run
+  end
+end
+```
+
+When `around_test` is written directly in a test file, Smartest treats it as
+file-scoped by snapshotting the file's current around-test hooks into each
+`TestCase` at test registration time. Hooks defined later in the file apply only
+to later tests.
+
+`around_test` can also be registered inside `around_suite`. In that case the hook
+is suite-wide and applies when `suite.run` executes:
+
+```ruby
+around_suite do |suite|
+  around_test do |test|
+    TestServer.run do
+      test.run
+    end
+  end
+
+  suite.run
+end
+```
+
+`use_fixture` and `use_matcher` are not top-level DSL methods. They are available
+inside `around_suite` and `around_test` contexts:
+
+```ruby
+around_test do |test|
+  use_fixture LocalFixture
+  use_matcher LocalMatcher
+  test.run
+end
+```
+
+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
+with suite-scoped fixtures must be registered from `around_suite`.
+
+Potential simpler per-test API:
 
 ```ruby
 before do
@@ -889,10 +960,29 @@ fixture cleanup
 
 This needs a final decision later.
 
-For MVP, hooks can be omitted.
-
 Fixture cleanup already handles resource-specific teardown.
 
+### Around-test parallelism note
+
+The file-scoped `around_test` design is intended to remain compatible with
+future parallel execution if it is hardened in these directions:
+
+- keep registration protected by a `Mutex` when tests may be loaded from
+  multiple threads
+- use copy-on-write arrays for `around_test` hooks by file
+- snapshot the current file-local hook stack into each `TestCase` at registration
+  time
+- treat `TestCase` as immutable after registration
+- expose `use_fixture` and `use_matcher` through a per-run `TestRun` object, not
+  by mutating the global suite registry during test execution
+- snapshot the suite's fixture classes and matcher modules before a test starts
+- keep test-run fixture and matcher additions local to that run
+
+That shape lets multiple tests execute concurrently by reading immutable
+`TestCase` state and using per-test fixture/matcher registries. The current
+implementation can be simpler, but it should not rely on refinements or global
+method rewriting for file-local behavior.
+
 ## Scoping
 
 Fixtures are test-scoped by default.
@@ -1073,6 +1163,11 @@ require "smartest/autorun"
 Dir[File.join(__dir__, "fixtures", "**", "*.rb")].sort.each do |fixture_file|
   require fixture_file
 end
+
+around_suite do |suite|
+  use_fixture AppFixture
+  suite.run
+end
 ```
 
 ```ruby
@@ -1098,8 +1193,6 @@ end
 # smartest/example_test.rb
 require "test_helper"
 
-use_fixture AppFixture
-
 test("GET /health") do |client:|
   expect(client.get("/health").status).to eq(200)
 end
@@ -1117,7 +1210,6 @@ Possible future features:
 - richer matchers
 - block expectations
 - `raise_error`
-- hooks
 - file-scoped fixtures
 - parallel execution
 - watch mode

data/lib/smartest/dsl.rb

@@ -3,24 +3,31 @@
 module Smartest
   module DSL
     def test(name, **metadata, &block)
+      location = caller_locations(1, 1).first
+
       Smartest.suite.tests.add(
         TestCase.new(
           name: name,
           metadata: metadata,
           block: block,
-          location: caller_locations(1, 1).first
+          location: location,
+          around_test_hooks: Smartest.suite.around_test_hooks_for(location)
         )
       )
     end
 
-    def use_fixture(klass)
-      Smartest.suite.fixture_classes.add(klass)
+    def around_suite(&block)
+      raise ArgumentError, "around_suite block is required" unless block
+
+      Smartest.suite.around_suite_hooks << block
     end
 
-    def use_matcher(matcher_module)
-      Smartest.suite.matcher_modules.add(matcher_module)
+    def around_test(&block)
+      raise ArgumentError, "around_test block is required" unless block
+
+      Smartest.suite.add_around_test_hook(caller_locations(1, 1).first, block)
     end
 
-    private :test, :use_fixture, :use_matcher
+    private :test, :around_suite, :around_test
   end
 end

data/lib/smartest/errors.rb

@@ -48,5 +48,21 @@ module Smartest
 
   class InvalidFixtureParameterError < Error; end
 
+  class AroundSuiteRunError < Error; end
+
+  class AroundTestFixtureScopeError < Error
+    def initialize(fixture_class, fixture_names)
+      class_name = fixture_class.name || fixture_class.inspect
+      names = fixture_names.map { |fixture_name| ":#{fixture_name}" }.join(", ")
+
+      super(
+        "#{class_name} cannot be registered from around_test because it defines suite-scoped fixtures: #{names}. " \
+        "Register fixture classes with suite_fixture from around_suite instead."
+      )
+    end
+  end
+
+  class AroundTestRunError < Error; end
+
   class AssertionFailed < Error; end
 end

data/lib/smartest/hook_contexts.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Smartest
+  class AroundSuiteContext
+    def initialize(suite)
+      @suite = suite
+    end
+
+    def call(hook, suite_run)
+      @suite.around_suite_hook do
+        instance_exec(suite_run, &hook)
+      end
+    end
+
+    private
+
+    def use_fixture(klass)
+      @suite.fixture_classes.add(klass)
+    end
+
+    def use_matcher(matcher_module)
+      @suite.matcher_modules.add(matcher_module)
+    end
+
+    def around_test(&block)
+      raise ArgumentError, "around_test block is required" unless block
+
+      @suite.add_around_test_hook(caller_locations(1, 1).first, block)
+    end
+  end
+
+  class AroundTestContext
+    def initialize(test_run)
+      @test_run = test_run
+    end
+
+    def call(hook, run_target = @test_run)
+      instance_exec(run_target, &hook)
+    end
+
+    private
+
+    def use_fixture(klass)
+      @test_run.add_fixture_class(klass)
+    end
+
+    def use_matcher(matcher_module)
+      @test_run.add_matcher_module(matcher_module)
+    end
+  end
+end

data/lib/smartest/init_generator.rb

@@ -18,7 +18,10 @@ module Smartest
           require matcher_file
         end
 
-        use_matcher PredicateMatcher
+        around_suite do |suite|
+          use_matcher PredicateMatcher
+          suite.run
+        end
       RUBY
       "smartest/matchers/predicate_matcher.rb" => <<~RUBY,
         # frozen_string_literal: true

data/lib/smartest/reporter.rb

@@ -19,14 +19,19 @@ module Smartest
       @io.puts "#{mark} #{result.test_case.name}"
     end
 
-    def finish(results, suite_cleanup_errors: [])
+    def finish(results, suite_cleanup_errors: [], suite_errors: [])
       failures = results.select(&:failed?)
 
       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?
 
       @io.puts
       summary = "#{results.count} #{results.count == 1 ? 'test' : 'tests'}, #{results.count(&:passed?)} passed, #{failures.count} failed"
+      if suite_errors.any?
+        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"
@@ -50,6 +55,18 @@ module Smartest
       end
     end
 
+    def report_suite_errors(errors)
+      @io.puts
+      @io.puts "Suite failures:"
+      @io.puts
+
+      errors.each_with_index do |error, index|
+        @io.puts "#{index + 1}) suite"
+        report_error(error)
+        @io.puts
+      end
+    end
+
     def report_suite_cleanup_errors(errors)
       @io.puts
       @io.puts "Suite cleanup failures:"