sus 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e9cdd2318c294d0d9cea4ae26b1b82635bdee10530302fc17c9fbbf66271e25
-  data.tar.gz: ae9c5b7311646e83acd88ad665126be152a8dc149db1e8a5156e0269f8a64b80
+  metadata.gz: e68f73a268f03439168f0ce3daec5a802174d6ada57de7e03d8362d2102eb3b2
+  data.tar.gz: 273c4098c1a760fa81525302d38f985f2f07ad630c2ddced74db4c1fd67ce030
 SHA512:
-  metadata.gz: da0963499c5f6b2aa2be21a5623a4ed1feb2f1889c6efcfb5fae927dbcf6bf33049a49ce849f622d4c87602ae353aa1476b89649bdc3de18a192dac495a97343
-  data.tar.gz: ddeb909536fdd63b90a1992fe7ba986320156fbd42d3c18bc2fdc82bdfd14879d61a3df0b4a7ffddb84bea8b0a5fb705b6730a4bbf05ff4083abaf2671042167
+  metadata.gz: c7f993c9daea1b833f4f34ec5e5c0cee6898fda975c0ea0850f907c45f325533b26ba6ddcda394125f33e03ea601cd4c7db8e42a09a38de3fee4ff4e7ba19b89
+  data.tar.gz: 7e8eb36690ba2e85686efa0b955755a5b587619803bb8f953b8b2c2ba11576733044d7b5255047d2ac3734ef9a5e84b86adf45c10a758bb2d22baf30661e3fa3

data/context/getting-started.md

@@ -47,3 +47,355 @@ Check out all the repositories in this organisation, including these notable exa
 
 - [sus/test](https://github.com/socketry/sus/tree/main/test/sus)
 - [async/test](https://github.com/socketry/async/tree/main/test)
+
+## Project Structure
+
+Here is an example structure for testing with Sus - the actual structure may vary based on your gem's organization, but aside from the `lib/` directory, sus expects the following structure:
+
+```
+my-gem/
+├── config/
+│   └── sus.rb                     # Sus configuration file
+├── lib/
+│   ├── my_gem.rb
+│   └── my_gem/
+│       └── my_thing.rb
+├── fixtures/
+│   └── my_gem/
+│       └── a_thing.rb               # Provides MyGem::AThing shared context
+└── test/
+    ├── my_gem.rb                    # Tests MyGem
+    └── my_gem/
+        └── my_thing.rb              # Tests MyGem::MyThing
+```
+
+### Configuration File
+
+Create `config/sus.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+# Use the covered gem for test coverage reporting:
+require "covered/sus"
+include Covered::Sus
+
+def before_tests(assertions, output: self.output)
+	# Starts the clock and sets up the test environment:
+	super
+end
+
+def after_tests(assertions, output: self.output)
+	# Stops the clock and prints the test results:
+	super
+end
+```
+
+### Fixtures Files
+
+`fixtures/` gets added to the `$LOAD_PATH` automatically, so you can require files from there without needing to specify the full path.
+
+### Test Files
+
+Sus runs all Ruby files in the `test/` directory by default. But you can also create tests in any file, and run them with the `sus my_tests.rb` command.
+
+## Test Syntax
+
+### `describe` - Test Groups
+
+Use `describe` to group related tests:
+
+```ruby
+describe MyThing do
+	# The subject will be whatever is described:
+	let(:my_thing) {subject.new}
+end
+```
+
+### `it` - Individual Tests
+
+Use `it` to define individual test cases:
+
+```ruby
+it "returns the expected value" do
+	expect(result).to be == "expected"
+end
+```
+
+You can use `it` blocks at the top level or within `describe` or `with` blocks.
+
+### `with` - Context Blocks
+
+Use `with` to create context-specific test groups:
+
+```ruby
+with "valid input" do
+	let(:input) {"valid input"}
+	it "succeeds" do
+		expect{my_thing.process(input)}.not.to raise_exception
+	end
+end
+
+# Non-lazy state can be provided as keyword arguments:
+with "invalid input", input: nil do
+	it "raises an error" do
+		expect{my_thing.process(input)}.to raise_exception(ArgumentError)
+	end
+end
+```
+
+When testing methods, use `with` to specify the method being tested:
+
+```ruby
+with "#my_method" do
+	it "returns a value" do
+		expect(my_thing.my_method).to be == 42
+	end
+end
+
+with ".my_class_method" do
+	it "returns a value" do
+		expect(MyThing.class_method).to be == "class value"
+	end
+end
+```
+
+### `let` - Lazy Variables
+
+Use `let` to define variables that are evaluated when first accessed:
+
+```ruby
+let(:helper) {subject.new}
+let(:test_data) {"test value"}
+
+it "uses the helper" do
+	expect(helper.process(test_data)).to be_truthy
+end
+```
+
+### `before` and `after` - Setup/Teardown
+
+Use `before` and `after` for setup and teardown logic:
+
+```ruby
+before do
+	# Setup logic.
+end
+
+after do
+	# Cleanup logic.
+end
+```
+
+Error handling in `after` allows you to perform cleanup even if the test fails with an exception (not a test failure).
+
+```ruby
+after do |error = nil|
+	if error
+		# The state of the test is unknown, so you may want to forcefully kill processes or clean up resources.
+		Process.kill(:KILL, @child_pid)
+	else
+		# Normal cleanup logic.
+		Process.kill(:TERM, @child_pid)
+	end
+	
+	Process.waitpid(@child_pid)
+end
+```
+
+### `around` - Setup/Teardown
+
+Use `around` for setup and teardown logic:
+
+```ruby
+around do |&block|
+	# Setup logic.
+	super() do
+		# Run the test.
+		block.call
+	end
+ensure
+	# Cleanup logic.
+end
+```
+
+Invoking `super()` calls any parent `around` block, allowing you to chain setup and teardown logic.
+
+## Assertions
+
+### Basic Assertions
+
+```ruby
+expect(value).to be == expected
+expect(value).to be >= 10
+expect(value).to be <= 100
+expect(value).to be > 0
+expect(value).to be < 1000
+expect(value).to be_truthy
+expect(value).to be_falsey
+expect(value).to be_nil
+expect(value).to be_equal(another_value)
+expect(value).to be_a(Class)
+```
+
+### Strings
+
+```ruby
+expect(string).to be(:start_with?, "prefix")
+expect(string).to be(:end_with?, "suffix")
+expect(string).to be(:match?, /pattern/)
+expect(string).to be(:include?, "substring")
+```
+
+### Ranges and Tolerance
+
+```ruby
+expect(value).to be_within(0.1).of(5.0)
+expect(value).to be_within(5).percent_of(100)
+```
+
+### Method Calls
+
+To call methods on the expected object:
+
+```ruby
+expect(array).to be(:include?, "value")
+expect(string).to be(:start_with?, "prefix")
+expect(object).to be(:respond_to?, :method_name)
+```
+
+### Collection Assertions
+
+```ruby
+expect(array).to have_attributes(length: be == 1)
+expect(array).to have_value(be > 1)
+
+expect(hash).to have_keys(:key1, "key2")
+expect(hash).to have_keys(key1: be == 1, "key2" => be == 2)
+```
+
+### Attribute Testing
+
+```ruby
+expect(user).to have_attributes(
+	name: be == "John",
+	age: be >= 18,
+	email: be(:include?, "@")
+)
+```
+
+### Exception Assertions
+
+```ruby
+expect do
+	risky_operation
+end.to raise_exception(RuntimeError, message: be =~ /expected error message/)
+```
+
+## Combining Predicates
+
+Predicates can be nested.
+
+```ruby
+expect(user).to have_attributes(
+	name: have_attributes(
+		first: be == "John",
+		last: be == "Doe"
+	),
+	comments: have_value(be =~ /test comment/),
+	created_at: be_within(1.minute).of(Time.now)
+)
+```
+
+### Logical Combinations
+
+```ruby
+expect(value).to (be > 10).and(be < 20)
+expect(value).to be_a(String).or(be_a(Symbol), be_a(Integer))
+```
+
+### Custom Predicates
+
+You can create custom predicates for more complex assertions:
+
+```ruby
+def be_small_prime
+	(be == 2).or(be == 3, be == 5, be == 7)
+end
+```
+
+## Block Expectations
+
+### Testing Blocks
+
+```ruby
+expect{operation}.to raise_exception(Error)
+expect{operation}.to have_duration(be < 1.0)
+```
+
+### Performance Testing
+
+You should generally avoid testing performance in unit tests, as it will be highly unstable and dependent on the environment. However, if you need to test performance, you can use:
+
+```ruby
+expect{slow_operation}.to have_duration(be < 2.0)
+expect{fast_operation}.to have_duration(be < 0.1)
+```
+
+- For less unstable performance tests, you can use the `sus-fixtures-time` gem which tries to compensate for the environment by measuring execution time.
+
+- For benchmarking, you can use the `sus-fixtures-benchmark` gem which measures a block of code multiple times and reports the execution time.
+
+## File Operations
+
+### Temporary Directories
+
+Use `Dir.mktmpdir` for isolated test environments:
+
+```ruby
+around do |block|
+	Dir.mktmpdir do |root|
+		@root = root
+		block.call
+	end
+end
+
+let(:test_path) {File.join(@root, "test.txt")}
+
+it "can create a file" do
+	File.write(test_path, "content")
+	expect(File).to be(:exist?, test_path)
+end
+```
+
+## Test Output
+
+In general, tests should not produce output unless there is an error or failure.
+
+### Informational Output
+
+You can use `inform` to print informational messages during tests:
+
+```ruby
+it "logs an informational message" do
+	rate = copy_data(source, destination)
+	inform "Copied data at #{rate}MB/s"
+	expect(rate).to be > 0
+end
+```
+
+This can be useful for debugging or providing context during test runs.
+
+### Console Output
+
+The `sus-fixtures-console` gem provides a way to suppress and capture console output during tests. If you are using code which generates console output, you can use this gem to capture it and assert on it.
+
+## Running Tests
+
+```bash
+# Run all tests
+bundle exec sus
+
+# Run specific test file
+bundle exec sus test/specific_test.rb
+```

data/context/index.yaml

@@ -11,3 +11,12 @@ files:
   title: Getting Started
   description: This guide explains how to use the `sus` gem to write tests for your
     Ruby projects.
+- path: mocking.md
+  title: Mocking
+  description: This guide explains how to use mocking in sus to isolate dependencies
+    and verify interactions in your tests.
+- path: shared-contexts.md
+  title: Shared Test Behaviors and Fixtures
+  description: This guide explains how to use shared test contexts and fixtures in
+    sus to reduce duplication and ensure consistent test behavior across your test
+    suite.

data/context/mocking.md

@@ -1,8 +1,20 @@
 # Mocking
 
-There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace method implementations or set up more complex behavior.
+This guide explains how to use mocking in sus to isolate dependencies and verify interactions in your tests.
 
-Mocking non-local objects permanently changes the object's ancestors, so it should be used with care. For local objects, you can use `let` to define the object and then mock it.
+## Overview
+
+When testing code that depends on external services, slow operations, or complex objects, you need a way to control those dependencies without actually invoking them. Mocking allows you to replace method implementations or set expectations on method calls, making your tests faster, more reliable, and easier to maintain.
+
+Use mocking when you need:
+- **Isolation**: Test your code without depending on external services (databases, APIs, file systems)
+- **Performance**: Avoid slow operations during testing
+- **Control**: Simulate error conditions or edge cases that are hard to reproduce
+- **Verification**: Ensure your code calls methods with the correct arguments
+
+Sus provides two types of mocking: `receive` for method call expectations and `mock` for replacing method implementations. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace method implementations or set up more complex behavior.
+
+**Important**: Mocking non-local objects permanently changes the object's ancestors, so it should be used with care. For local objects, you can use `let` to define the object and then mock it.
 
 Sus does not support the concept of test doubles, but you can use `receive` and `mock` to achieve similar functionality.
 
@@ -10,86 +22,144 @@ Sus does not support the concept of test doubles, but you can use `receive` and
 
 The `receive(:method)` expectation is used to set up an expectation that a method will be called on an object. You can also specify arguments and return values. However, `receive` is not sequenced, meaning it does not enforce the order of method calls. If you need to enforce the order, use `mock` instead.
 
+### Basic Usage
+
+Verify that a method is called:
+
 ```ruby
-describe MyThing do
-	let(:my_thing) {subject.new}
+describe PaymentProcessor do
+	let(:payment_processor) {subject.new}
+	let(:logger) {Object.new}
 	
-	it "calls the expected method" do
-		expect(my_thing).to receive(:my_method)
+	it "logs payment attempts" do
+		expect(logger).to receive(:info)
 		
-		expect(my_thing.my_method).to be == 42
+		payment_processor.process_payment(amount: 100, logger: logger)
 	end
 end
 ```
 
 ### With Arguments
 
+Verify method calls with specific arguments:
+
 ```ruby
-it "calls the method with arguments" do
-	expect(object).to receive(:method_name).with(arg1, arg2)
-	# or .with_arguments(be == [arg1, arg2])
-	# or .with_options(be == {option1: value1, option2: value2})
-	# or .with_block
+describe EmailService do
+	let(:email_service) {subject.new}
+	let(:smtp_client) {Object.new}
 	
-	object.method_name(arg1, arg2)
+	it "sends emails with correct recipient and subject" do
+		expect(smtp_client).to receive(:send).with("user@example.com", "Welcome!")
+		
+		email_service.send_welcome_email("user@example.com", smtp_client)
+	end
 end
 ```
 
+You can also use more flexible argument matching:
+- `.with_arguments(be == [arg1, arg2])` for positional arguments
+- `.with_options(be == {option1: value1})` for keyword arguments
+- `.with_block` to verify a block is passed
+
 ### Returning Values
 
+Set up return values for mocked methods:
+
 ```ruby
-it "returns a value" do
-	expect(object).to receive(:method_name).and_return("expected value")
-	result = object.method_name
-	expect(result).to be == "expected value"
+describe UserRepository do
+	let(:repository) {subject.new}
+	let(:database) {Object.new}
+	
+	it "retrieves user by ID" do
+		expected_user = {id: 1, name: "Alice"}
+		expect(database).to receive(:find_user).with(1).and_return(expected_user)
+		
+		user = repository.find(1, database)
+		expect(user).to be == expected_user
+	end
 end
 ```
 
 ### Raising Exceptions
 
+Simulate error conditions:
+
 ```ruby
-it "raises an exception" do
-	expect(object).to receive(:method_name).and_raise(StandardError, "error message")
+describe FileUploader do
+	let(:uploader) {subject.new}
+	let(:storage_service) {Object.new}
 	
-	expect{object.method_name}.to raise_exception(StandardError, message: "error message")
+	it "handles storage failures gracefully" do
+		expect(storage_service).to receive(:upload).and_raise(StandardError, "Storage unavailable")
+		
+		expect{uploader.upload_file("data.txt", storage_service)}.to raise_exception(StandardError, message: "Storage unavailable")
+	end
 end
 ```
 
 ### Multiple Calls
 
+Verify methods are called multiple times:
+
 ```ruby
-it "calls the method multiple times" do
-	expect(object).to receive(:method_name).twice.and_return("result")
-	# or .with_call_count(be == 2)
-	expect(object.method_name).to be == "result"
-	expect(object.method_name).to be == "result"
+describe CacheWarmer do
+	let(:warmer) {subject.new}
+	let(:cache) {Object.new}
+	
+	it "warms multiple cache entries" do
+		expect(cache).to receive(:set).twice.and_return(true)
+		
+		warmer.warm(["key1", "key2"], cache)
+	end
 end
 ```
 
+You can also use `.with_call_count(be == 2)` for more flexible call count expectations.
+
 ## Mock Objects
 
 Mock objects are used to replace method implementations or set up complex behavior. They can be used to intercept method calls, modify arguments, and control the flow of execution. They are thread-local, meaning they only affect the current thread, therefore are not suitable for use in tests that have multiple threads.
 
+### Replacing Method Implementations
+
+Replace methods to return controlled values:
+
 ```ruby
 describe ApiClient do
 	let(:http_client) {Object.new}
 	let(:client) {ApiClient.new(http_client)}
 	let(:users) {["Alice", "Bob"]}
 	
-	it "makes GET requests" do
+	it "fetches users from API" do
 		mock(http_client) do |mock|
 			mock.replace(:get) do |url, headers: {}|
 				expect(url).to be == "/api/users"
 				expect(headers).to be == {"accept" => "application/json"}
 				users.to_json
 			end
-			
-			# or mock.before {|...| ...}
-			# or mock.after {|...| ...}
-			# or mock.wrap(:new) {|original, ...| original.call(...)}
 		end
 		
 		expect(client.fetch_users).to be == users
 	end
 end
 ```
+
+### Advanced Mocking Patterns
+
+You can also use:
+- `mock.before {|...| ...}` to execute code before the original method
+- `mock.after {|...| ...}` to execute code after the original method
+- `mock.wrap(:method) {|original, ...| original.call(...)}` to wrap the original method
+
+## Best Practices
+
+1. **Prefer real objects**: Use mocks only when necessary (external services, slow operations, error conditions)
+2. **Use dependency injection**: Make dependencies explicit so they can be easily mocked
+3. **Mock at boundaries**: Mock external services, not internal implementation details
+4. **Keep mocks simple**: Complex mock setups indicate the code might need refactoring
+
+## Common Pitfalls
+
+1. **Over-mocking**: Mocking too much makes tests brittle and less valuable
+2. **Thread safety**: Mock objects are thread-local, don't use them in multi-threaded tests
+3. **Permanent changes**: Mocking non-local objects permanently changes their ancestors - use `let` for local objects instead

data/context/{shared.md → shared-contexts.md}

@@ -1,7 +1,17 @@
 # Shared Test Behaviors and Fixtures
 
+This guide explains how to use shared test contexts and fixtures in sus to reduce duplication and ensure consistent test behavior across your test suite.
+
 ## Overview
 
+When you have common test behaviors that need to be applied to multiple test files or multiple implementations of the same interface, shared contexts allow you to define those behaviors once and reuse them. This reduces duplication, ensures consistency, and makes it easier to maintain your tests.
+
+Use shared contexts when you need:
+- **Code reuse**: Apply the same test behavior to multiple classes or modules
+- **Consistency**: Ensure all implementations of an interface are tested the same way
+- **Maintainability**: Update test behavior in one place rather than many
+- **Parameterization**: Run the same tests with different inputs or configurations
+
 Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.
 
 When you have common test behaviors that you want to apply to multiple test files, add them to the `fixtures/` directory. When you have common test behaviors that you want to apply to multiple implementations of the same interface, within a single test file, you can define them as shared contexts within that file.
@@ -10,6 +20,8 @@ When you have common test behaviors that you want to apply to multiple test file
 
 ### Directory Structure
 
+Shared fixtures are stored in the `fixtures/` directory, which mirrors your project structure:
+
 ```
 my-gem/
 ├── lib/
@@ -25,6 +37,8 @@ my-gem/
         └── my_thing.rb
 ```
 
+The `fixtures/` directory is automatically added to the `$LOAD_PATH`, so you can require files from there without needing to specify the full path.
+
 ### Creating Shared Fixtures
 
 Create shared behaviors in the `fixtures/` directory using `Sus::Shared`:
@@ -65,7 +79,7 @@ Require and use shared fixtures in your test files:
 
 ```ruby
 # test/my_gem/user_manager.rb
-require 'my_gem/a_user'
+require "my_gem/a_user"
 
 describe MyGem::UserManager do
 	it_behaves_like MyGem::AUser, "manager"
@@ -108,7 +122,7 @@ Use specific shared fixtures:
 
 ```ruby
 # test/my_gem/authorization.rb
-require 'my_gem/users'
+require "my_gem/users"
 
 describe MyGem::Authorization do
 	with "standard user" do
@@ -183,3 +197,16 @@ end
 ```
 
 Note the use of `unique: adapter.name` to ensure each test is uniquely identified, which is useful for reporting and debugging - otherwise the same test line number would be used for all iterations, which can make it hard to identify which specific test failed.
+
+## Best Practices
+
+1. **Organize by domain**: Group related shared contexts together in modules
+2. **Keep contexts focused**: Each shared context should test one cohesive behavior
+3. **Use parameters**: Make shared contexts flexible by accepting parameters
+4. **Document intent**: Use clear names that explain what behavior is being tested
+
+## Common Pitfalls
+
+1. **Over-sharing**: Don't create shared contexts for behaviors that are only used once
+2. **Tight coupling**: Avoid shared contexts that depend on too many specific implementation details
+3. **Unclear names**: Use descriptive names that make it obvious what behavior is being tested