Sus Testing Framework

Shared fixtures allow you to define common test behaviors once and reuse them across multiple test files or multiple implementations of an interface. This is useful for code reuse, ensuring consistency across interface implementations, and parameterizing tests.

There are two main ways to organize shared behaviors:

1. Across multiple test files: Store these in the fixtures/ directory. The fixtures/ directory is automatically added to the $LOAD_PATH.
2. Within a single test file: Define them as shared contexts directly within that file to apply to different implementations of the same interface.

Shared fixtures are created using Sus::Shared and can accept parameters to make the tests flexible.

# Example of a shared fixture structure

# fixtures/my_gem/a_user.rb
module MyGem
  AUser = Sus::Shared("a user") do |role|
    let(:user) { { name: "Test", role: role } }
    it "has a role" do
      expect(user[:role]).to be_a(String)
    end
  end
end

# test/my_gem/user_manager.rb
require "my_gem/a_user"
describe MyGem::UserManager do
  it_behaves_like MyGem::AUser, "manager"
end

Sus provides two ways to reuse test logic depending on the scope of the reuse:

1. Shared Fixtures: Used for common behaviors applied across multiple test files. These are stored in the fixtures/ directory, which is automatically added to the $LOAD_PATH. They are typically defined using Sus::Shared and organized to mirror your project structure.

2. Shared Contexts: Used for common behaviors applied to multiple implementations of the same interface within a single test file. These are defined locally within the test file using Sus::Shared or via standard Ruby modules.

Both mechanisms allow you to reduce duplication, ensure consistency across implementations, and parameterize tests with different inputs.

# Example of the directory structure for shared fixtures
my-gem/
├── lib/
│   └── my_gem/
│       └── my_thing.rb
├── fixtures/
│   └── my_gem/
│       └── a_thing.rb               # Provides MyGem::AThing shared context
└── test/
    └── my_gem/
        └── my_thing.rb

The mock(object) { |mock| ... } block is used to replace method implementations or set up complex behaviors. Unlike receive, mock can be used to intercept calls and provide custom logic.

Important Constraints:

• Thread Safety: Mock objects are thread-local. They only affect the current thread and are not suitable for multi-threaded tests.

Replacing a method

Use mock.replace(:method_name) { |args| ... } to define a new implementation.

mock(http_client) do |mock|
  mock.replace(:get) do |url, headers: {}|
    # custom logic here
    "response_body"
  end
end

Advanced patterns

• mock.before { |...| ... }: Execute code before the original method.
• mock.after { |...| ... }: Execute code after the original method.
• mock.wrap(:method) { |original, ...| original.call(...) }: Wrap the original method implementation.

describe ApiClient do
	let(:http_client) {Object.new}
	let(:client) {ApiClient.new(http_client)}
	let(:users) {["Alice", "Bob"]}
	
	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
		end
		
		expect(client.fetch_users).to be == users
	end
end

Once a shared fixture is defined, you can use it in your describe blocks using two primary methods:

1. it_behaves_like: Used to apply the shared behavior and pass arguments to the fixture.
2. include_context: An alias for it_behaves_like.
3. include: Used within a with block when the shared fixture does not require arguments.

To use a fixture from the fixtures/ directory, you must first require it.

# Using it_behaves_like with arguments
require "my_gem/a_user"

describe MyGem::UserManager do
  it_behaves_like MyGem::AUser, "manager"
  # or
  # include_context MyGem::AUser, "manager"
end

# Using include within a 'with' block (no arguments)
require "my_gem/users"

describe MyGem::Authorization do
  with "standard user" do
    include MyGem::Users::AStandardUser
    
    it "denies admin access" do
      auth = subject.new
      expect(auth.can_admin?(user)).to be_falsey
    end
  end
end

To run the same set of shared tests against multiple different implementations (e.g., different database adapters), you can iterate over a collection of implementations and wrap the it_behaves_like call in a describe block.

Important: Use the unique: option in the describe block, passing a unique identifier (like the adapter name). This ensures that if a test fails, the error report points to the specific implementation that failed rather than showing the same line number for every iteration.

require "sus/shared"

ADatabaseAdapter = Sus::Shared("a database adapter") do |adapter|
	let(:database) {adapter.new}
	
	it "connects to the database" do
		expect(database.connect).to be_truthy
	end
end

# Enumerate the tests with different adapters
MyGem::DatabaseAdapters.each do |adapter|
	describe "with #{adapter}", unique: adapter.name do
		it_behaves_like ADatabaseAdapter, adapter
	end
end