smartest 0.3.3.alpha4 → 0.5.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75e3f0538afd3f490c37121ae4eee497a4691f35926ff50201e035acb64d2314
-  data.tar.gz: 53fea3bdbbb788167d13c6a7b6c18a9258de42b971c4f2a1f36906176f75813a
+  metadata.gz: 967084d2b9e35152ef0f03e3ac524e92378e23b946dd919328d95f751553451a
+  data.tar.gz: b4df54be2c78b6a7341cedf0dc2b95bec0e52f6f51734fe3769bf005bfdfff00
 SHA512:
-  metadata.gz: ba646897bc5994e7caf30fc9b1127a1ad72f2545a4ed8734820c5eeeca3e5e1e7e0302394b38916fbc9d9c153dccfdae96496093dce1f23af172fa74a01cbd75
-  data.tar.gz: 5c12f0c3532da8eb44c3e832d28e479b1f8a54f5797a4c67c61c865bbbedf31e2225fe441c1f433d8de6ce3b2246c374de998d2aae9b2cfa8a7ea63f043ed949
+  metadata.gz: c0c2f5f9a2d79ae06e2391a8b1a8138337f175f0a36b25f3969d5cab2e1f05bf90dfd85c734fdf581fdf15c7110338d3e6af7f52550259d24b5650dd0eb553ce
+  data.tar.gz: 67b85ab5f35b8d9844efacad366b549abe2fab44505266e60f0e10c3495e36b6009581508da0e647cafddb5c03bc13c95884a709565ce26cb7ccc29e3b37d09e

data/CHANGELOG.md

@@ -1,19 +1,24 @@
 # Changelog
 
-## 0.1.0 - Unreleased
-
-- Add the initial Smartest test runner.
-- Support top-level `test` definitions.
-- Support class-based fixtures through `Smartest::Fixture`.
-- Support required keyword-argument fixture injection and fixture dependencies.
-- Support per-test fixture caching and cleanup.
-- Support suite-scoped fixtures through `suite_fixture`.
-- Support `eq`, `include`, `start_with`, `end_with`, `be_nil`, `raise_error`, and `change` 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/`.
-- Add gem packaging metadata and release tasks.
-- Add Docusaurus documentation.
-- Add `smartest --init-browser` with a Playwright init scaffold, fixture setup, matcher generation, and dependency installation.
+## 0.5.0 - Unreleased
+
+### Breaking Changes
+
+- Rename the fixture teardown registration API from `cleanup` to
+  `on_teardown`. The old `cleanup` method is no longer available.
+- Rename teardown failure output from cleanup terminology to teardown
+  terminology.
+
+## 0.4.0
+
+### New Features
+
+- Add fixture-scoped method stub helpers: `simple_stub_any_instance_of` and
+  `simple_stub`.
+- Add `with_stub_const` for block-scoped constant stubbing in test bodies,
+  `around_test`, and `around_suite`.
+- Support Ruby 2.7 and newer.
+
+## 0.1.0 - 0.3.2
+
+- Initial release.

data/DEVELOPMENT.md

@@ -13,7 +13,7 @@ Smartest is a Ruby test runner focused on:
 - top-level test definitions
 - class-based fixtures
 - explicit keyword-argument fixture dependencies
-- optional cleanup for fixtures that need teardown
+- optional teardown for fixtures that need teardown
 - suite-scoped fixtures for expensive shared resources
 - a small internal architecture that is easy to reason about
 
@@ -224,7 +224,7 @@ Responsibilities:
 - class-level `suite_fixture` DSL for suite-scoped fixtures
 - stores fixture definitions
 - supports inheritance
-- exposes `cleanup` to fixture blocks
+- exposes `on_teardown` to fixture blocks
 - optionally delegates helper methods to `ExecutionContext`
 - does not delegate `skip` or `pending` to fixture blocks
 
@@ -293,8 +293,8 @@ Responsibilities:
 - find fixture definitions
 - resolve fixture dependencies
 - cache fixture values for its scope
-- collect cleanup blocks
-- run cleanup blocks in reverse order
+- collect teardown blocks
+- run teardown blocks in reverse order
 - detect duplicate fixture names
 - detect circular dependencies
 
@@ -332,9 +332,9 @@ Responsibilities:
 - create a fresh `FixtureSet` per test
 - resolve test keyword fixtures
 - run test body
-- run cleanup in `ensure`
+- run teardown in `ensure`
 - track skipped and pending test state
-- run suite fixture cleanup after all tests
+- run suite fixture teardown after all tests
 - produce `TestResult`
 - notify reporter
 
@@ -373,7 +373,7 @@ rescue Exception => error
     TestResult.failed(test_case, error)
   end
 ensure
-  fixture_set&.run_cleanups
+  fixture_set&.run_teardowns
 end
 ```
 
@@ -424,7 +424,7 @@ end
 
 fixture :server do
   server = TestServer.start
-  cleanup { server.stop }
+  on_teardown { server.stop }
   server
 end
 
@@ -456,12 +456,12 @@ resolve :logged_in_client
   evaluate logged_in_client
   cache logged_in_client
 run test body
-run cleanup stack
+run teardown stack
 ```
 
-## Cleanup behavior
+## Teardown behavior
 
-Fixture cleanup is optional.
+Fixture teardown is optional.
 
 Fixture without teardown:
 
@@ -476,33 +476,33 @@ Fixture with teardown:
 ```ruby
 fixture :server do
   server = TestServer.start
-  cleanup { server.stop }
+  on_teardown { server.stop }
 
   server.wait_until_ready!
   server
 end
 ```
 
-`cleanup` should register a block on the current fixture set. Regular fixture
-cleanups run after the test. `suite_fixture` cleanups run after all tests.
+`on_teardown` should register a block on the current fixture set. Regular fixture
+teardown blocks run after the test. `suite_fixture` teardown blocks run after all tests.
 
-Cleanup blocks must run:
+Teardown blocks must run:
 
 - after the test body
 - after the suite for suite-scoped fixtures
 - after failed tests
-- after fixture setup errors, if cleanup was already registered
+- after fixture setup errors, if teardown was already registered
 - in reverse registration order
 
 Implementation:
 
 ```ruby
-def add_cleanup(&block)
-  @cleanups << block
+def add_teardown(&block)
+  @teardowns << block
 end
 
-def run_cleanups
-  @cleanups.reverse_each(&:call)
+def run_teardowns
+  @teardowns.reverse_each(&:call)
 end
 ```
 
@@ -621,17 +621,17 @@ A practical approach:
 - recursive fixture resolution
 - per-test caching
 
-### Phase 4: Cleanup
+### Phase 4: Teardown
 
-- `cleanup { ... }`
-- cleanup stack on `FixtureSet`
-- cleanup in `ensure`
+- `on_teardown { ... }`
+- teardown stack on `FixtureSet`
+- teardown in `ensure`
 
 ### Phase 5: Suite-scoped fixtures
 
 - `suite_fixture :name do ... end`
 - suite-level fixture cache
-- suite cleanup after all tests
+- suite teardown after all tests
 - test fixtures may depend on suite fixtures
 - suite fixtures may not depend on test fixtures
 
@@ -648,6 +648,10 @@ A practical approach:
 - `exe/smartest`
 - load files from ARGV
 - default glob `smartest/**/*_test.rb`
+- print scaffold guidance and exit 1 when the default run is requested before
+  `smartest/` exists
+- expand directory path arguments such as `smartest/` to `**/*_test.rb` files
+  under that directory
 - 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
@@ -658,14 +662,14 @@ A practical approach:
 
 - `around_suite do |suite| ... end`
 - run hooks around the full suite body
-- include suite fixture cleanup inside the wrapped body
+- include suite fixture teardown 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
+- run hooks around fixture setup, test body, and fixture teardown
 - expose `use_fixture` and `use_matcher` only inside hook contexts
 - make `around_test` registered from `around_suite` suite-wide
 
@@ -716,7 +720,7 @@ end
 ```
 
 ```ruby
-cleanup { ... }
+on_teardown { ... }
 ```
 
 ```ruby
@@ -839,6 +843,22 @@ Before releasing:
 - run a sample project against the installed gem
 - push the release tag
 
+### Changelog updates
+
+Update `CHANGELOG.md` from the actual diff between released versions, not from
+commit messages. For an already tagged release, compare the previous release tag
+to the release tag and inspect the code/docs changes, for example:
+
+```bash
+git diff --stat 0.4.0..0.5.0
+git diff 0.4.0..0.5.0
+```
+
+Before the new tag exists, compare the latest release tag to the release branch
+or working tree and inspect the same kind of diff. Only document breaking
+changes and notable new features. Do not copy every commit message or list
+documentation-only maintenance changes unless they materially affect users.
+
 Example commands:
 
 ```bash

data/README.md

@@ -1,7 +1,10 @@
-# Smartest introduces Pytest-style fixtures for Ruby
+# Smartest
 
-Smartest is a small Ruby test runner that brings pytest-style fixture
-injection, explicit fixture dependencies, and fixture cleanup to Ruby tests.
+[![Gem Version](https://badge.fury.io/rb/smartest.svg)](https://rubygems.org/gems/smartest)
+
+Smartest is a Ruby test runner that brings pytest-style fixtures to Ruby,
+with explicit fixture dependencies, automatic teardown, and Playwright-friendly
+browser testing.
 
 Tests request fixtures with Ruby keyword arguments. Fixtures define their own
 dependencies the same way:
@@ -10,7 +13,7 @@ dependencies the same way:
 class WebFixture < Smartest::Fixture
   fixture :server do
     server = TestServer.start
-    cleanup { server.stop }
+    on_teardown { server.stop }
     server
   end
 
@@ -45,7 +48,7 @@ idea: tests should explicitly declare their dependencies.
 RSpec `let` is useful when examples need lazy helper methods. Minitest `setup`
 is simple for xUnit-style setup. Rails fixtures and FactoryBot are great for
 test data. Smartest is aimed at tests where setup resources, dependency graphs,
-and cleanup should be visible in the test signature and fixture definitions.
+and teardown should be visible in the test signature and fixture definitions.
 
 ```ruby
 test("GET /me") do |logged_in_client:|
@@ -67,6 +70,9 @@ end
 
 Smartest requires Ruby 2.7 or newer.
 
+Smartest is published as the `smartest` RubyGem:
+[Smartest on RubyGems](https://rubygems.org/gems/smartest).
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -123,12 +129,34 @@ bundle exec smartest
 By default, Smartest loads `smartest/**/*_test.rb`, so a separate `test/`
 directory can remain available for Minitest.
 
+If `smartest/` does not exist yet and no explicit paths are passed, Smartest
+prints scaffold commands instead of attempting a default test run:
+
+```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
+```
+
 You can also pass explicit paths:
 
 ```bash
+bundle exec smartest smartest/suite1/
 bundle exec smartest smartest/**/*_test.rb
+bundle exec smartest smartest/user_test.rb
 ```
 
+A directory path is expanded to `**/*_test.rb` under that directory, so
+`bundle exec smartest smartest/suite1/` is equivalent to
+`bundle exec smartest smartest/suite1/**/*_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:
 
@@ -152,6 +180,18 @@ bundle exec smartest --help
 bundle exec smartest --version
 ```
 
+The help output lists common commands, including default runs, directory runs,
+single-file runs, line-filtered runs, and scaffold generation:
+
+```bash
+bundle exec smartest
+bundle exec smartest smartest/suite1/
+bundle exec smartest smartest/user_test.rb
+bundle exec smartest smartest/user_test.rb:12
+bundle exec smartest --init
+bundle exec smartest --init-browser
+```
+
 Output resembles:
 
 ```text
@@ -443,7 +483,7 @@ released after the full suite finishes:
 class BrowserFixture < Smartest::Fixture
   suite_fixture :browser do
     browser = Browser.launch
-    cleanup { browser.close }
+    on_teardown { browser.close }
     browser
   end
 
@@ -454,7 +494,7 @@ end
 ```
 
 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
+and teardown 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
@@ -470,8 +510,8 @@ 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.
+wraps every test, test-scoped fixture setup and teardown, suite fixture setup, and
+suite fixture teardown.
 
 Fixture and matcher registrations made before `suite.run` are applied to that
 run:
@@ -512,7 +552,7 @@ end
 ```
 
 The hook receives a run target and must call `test.run` exactly once. It wraps
-fixture setup, the test body, and fixture cleanup.
+fixture setup, the test body, and fixture teardown.
 
 `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
@@ -546,20 +586,20 @@ 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.
+instead so its cache and teardown 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`.
+Not every fixture needs teardown. For fixtures that do, use `on_teardown`.
 
 ```ruby
 class WebFixture < Smartest::Fixture
   fixture :server do
     server = TestServer.start
-    cleanup { server.stop }
+    on_teardown { server.stop }
 
     server.wait_until_ready!
     server
@@ -571,8 +611,8 @@ class WebFixture < Smartest::Fixture
 end
 ```
 
-`cleanup` blocks run after the fixture's scope finishes. For regular fixtures
-that means after the test. For `suite_fixture`, cleanup runs after the full
+`on_teardown` blocks run after the fixture's scope finishes. For regular fixtures
+that means after the test. For `suite_fixture`, teardown runs after the full
 suite.
 
 They are executed in reverse order of registration.
@@ -580,7 +620,7 @@ They are executed in reverse order of registration.
 ```ruby
 fixture :temp_dir do
   dir = Dir.mktmpdir
-  cleanup { FileUtils.rm_rf(dir) }
+  on_teardown { FileUtils.rm_rf(dir) }
 
   dir
 end
@@ -591,19 +631,19 @@ Recommended pattern:
 ```ruby
 fixture :server do
   server = TestServer.start
-  cleanup { server.stop }
+  on_teardown { server.stop }
 
   server.wait_until_ready!
   server
 end
 ```
 
-Register cleanup immediately after acquiring the resource, before later setup steps that may fail.
+Register teardown immediately after acquiring the resource, before later setup steps that may fail.
 
 ## Stubs
 
 Use simple stub helpers when a fixture needs to temporarily replace a Ruby
-method and reset it during cleanup:
+method and reset it during teardown:
 
 ```ruby
 class PaymentFixture < Smartest::Fixture
@@ -639,13 +679,13 @@ end
 Use `simple_stub(Time, :now) { fixed_time }` for singleton methods such as class
 methods.
 
-Use `simple_stub_const("AppConfig::PAYMENT_PROVIDER", "fake") { ... }` for
+Use `with_stub_const("AppConfig::PAYMENT_PROVIDER", "fake") { ... }` for
 constants in test bodies, `around_test`, or `around_suite`. Constant stubs are
 process-global; avoid concurrent tests that stub the same constant.
 
 The method stub helpers call `Smartest::SimpleStub` internally, apply the stub,
-register `cleanup { stub.reset }`, and return the stub object.
-`simple_stub_const` records the previous constant value, replaces it, yields to
+register `on_teardown { stub.reset }`, and return the stub object.
+`with_stub_const` records the previous constant value, replaces it, yields to
 the block, and restores or removes the constant with `ensure`.
 
 `Smartest::SimpleStub#apply` and `#reset` are idempotent in the current Fiber.
@@ -661,7 +701,7 @@ the current Fiber, and `reset!` raises
 class WebFixture < Smartest::Fixture
   fixture :server do
     server = TestServer.start
-    cleanup { server.stop }
+    on_teardown { server.stop }
 
     server.wait_until_ready!
     server
@@ -721,7 +761,7 @@ client setup
 user setup
 logged_in_client setup
 test body
-server cleanup
+server teardown
 ```
 
 ## Registering fixture classes
@@ -750,15 +790,15 @@ Fixture names must be unique across registered fixture classes.
 
 If two fixture classes define the same fixture name, Smartest raises an error.
 
-## Suite hooks and fixture cleanup
+## Suite hooks and fixture teardown
 
-Suite hooks are separate from fixture cleanup. Use fixture cleanup for
+Suite hooks are separate from fixture teardown. Use fixture teardown for
 resource-specific teardown:
 
 ```ruby
 fixture :server do
   server = TestServer.start
-  cleanup { server.stop }
+  on_teardown { server.stop }
   server
 end
 ```
@@ -815,7 +855,7 @@ Example:
 class WebFixture < Smartest::Fixture
   fixture :server do
     server = TestServer.start
-    cleanup { server.stop }
+    on_teardown { server.stop }
     server
   end
 
@@ -878,7 +918,7 @@ Smartest currently focuses on a small runner API:
 - class-based fixtures
 - keyword-argument fixture injection
 - fixture dependencies through keyword arguments
-- fixture cleanup
+- fixture teardown
 - suite-scoped fixtures through `suite_fixture`
 - fixture-scoped method stubs and block-scoped constant stubs
 - suite hooks with `around_suite`