Getting Started

This guide explains how to use the sus gem to write tests for your Ruby projects.

Installation

Add the gem to your project:

$ bundle add sus

Write Some Tests

Create a test file in your project test/my_project/my_class.rb:

describe MyProject::MyClass do
	let(:instance) {subject.new}
	
	it "instantiates an object" do
		expect(instance).to be_a(Object)
	end
end

Run Your Tests

Run your tests with the sus command:

$ sus
1 passed out of 1 total (1 assertions)
🏁 Finished in 47.0µs; 21272.535 assertions per second.
🐇 No slow tests found! Well done!

You can also run your tests in parallel:

$ sus-parallel

More Examples

Check out all the repositories in this organisation, including these notable examples:

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:

# 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:

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:

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:

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:

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:

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:

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).

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:

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

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

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

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:

expect(array).to be(:include?, "value")
expect(string).to be(:start_with?, "prefix")
expect(object).to be(:respond_to?, :method_name)

Collection Assertions

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

expect(user).to have_attributes(
	name: be == "John",
	age: be >= 18,
	email: be(:include?, "@")
)

Exception Assertions

expect do
	risky_operation
end.to raise_exception(RuntimeError, message: be =~ /expected error message/)

Combining Predicates

Predicates can be nested.

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

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:

def be_small_prime
	(be == 2).or(be == 3, be == 5, be == 7)
end

Block Expectations

Testing Blocks

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:

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:

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:

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

# Run all tests
bundle exec sus

# Run specific test file
bundle exec sus test/specific_test.rb