Property-Based Testing in Ruby
An experimental property-based testing tool for Ruby that allows you to run test cases in parallel.
PBT stands for Property-Based Testing.
What's Property-Based Testing?
Property-Based Testing is a testing methodology that focuses on the properties a system should always satisfy, rather than checking individual examples. Instead of writing tests for predefined inputs and outputs, PBT allows you to specify the general characteristics that your code should adhere to and then automatically generates a wide range of inputs to verify these properties.
The key benefits of property-based testing include the ability to cover more edge cases and the potential to discover bugs that traditional example-based tests might miss. It's particularly useful for identifying unexpected behaviors in your code by testing it against a vast set of inputs, including those you might not have considered.
For a more in-depth understanding of Property-Based Testing, please refer to external resources.
- Original ideas
- Rather new introductory resources
Installation
Add this line to your application's Gemfile and run bundle install
.
gem 'pbt'
If you want to use multi-processes or multi-threads (other than Ractor) as workers to run tests, install the parallel gem.
gem 'parallel'
Off course you can install with gem intstall pbt
.
Basic Usage
Simple property
# Let's say you have a method that returns just a multiplicative inverse.
def multiplicative_inverse(number)
Rational(1, number)
end
Pbt.assert do
# The given block is executed 100 times with different random numbers.
# Besides, the block runs in parallel by Ractor.
Pbt.property(Pbt.integer) do |number|
result = multiplicative_inverse(number)
raise "Result should be the multiplicative inverse of the number" if result * number != 1
end
end
# If the function has a bug, the test fails with a counterexample.
# For example, the multiplicative_inverse method doesn't work for 0 regardless of the behavior is intended or not.
#
# Pbt::PropertyFailure:
# Property failed after 23 test(s)
# { seed: 11001296583699917659214176011685741769 }
# Counterexample: 0
# Shrunk 3 time(s)
# Got ZeroDivisionError: divided by 0
Explain The Snippet
The above snippet is very simple but contains the basic components.
Runner
Pbt.assert
is the runner. The runner interprets and executes the given property. Pbt.assert
takes a property and runs it multiple times. If the property fails, it tries to shrink the input that caused the failure.
Property
The snippet above declared a property by calling Pbt.property
. The property describes the following:
- What the user wants to evaluate. This corresponds to the block (let's call this
predicate
) enclosed bydo
end
- How to generate inputs for the predicate — using
Arbitrary
The predicate
block is a function that directly asserts, taking values generated by Arbitrary
as input.
Arbitrary
Arbitrary generates random values. It is also responsible for shrinking those values if asked to shrink a failed value as input.
Here, we used only one type of arbitrary, Pbt.integer
. There are many other built-in arbitraries, and you can create a variety of inputs by combining existing ones.
Shrink
In PBT, If a test fails, it attempts to shrink the case that caused the failure into a form that is easier for humans to understand. In other words, instead of stopping the test itself the first time it fails and reporting the failed value, it tries to find the minimal value that causes the error.
When there is a test that fails when given an even number, a counterexample of 2
is simpler and easier to understand than 432743417662
.
Arbitrary
There are many built-in arbitraries in Pbt
. You can use them to generate random values for your tests. Here are some representative arbitraries.
Primitives
rng = Random.new(
Pbt.integer.generate(rng) # => 42
Pbt.integer(min: -1, max: 8).generate(rng) # => Integer between -1 and 8
Pbt.symbol.generate(rng) # => :atq
Pbt.ascii_char.generate(rng) # => "a"
Pbt.ascii_string.generate(rng) # => "aagjZfao"
Pbt.boolean.generate(rng) # => true or false
Pbt.constant(42).generate(rng) # => 42 always
Composites
rng = Random.new
Pbt.array(Pbt.integer).generate(rng) # => [121, -13141, 9825]
Pbt.array(Pbt.integer, max: 1, empty: true).generate(rng) # => [] or [42] etc.
Pbt.tuple(Pbt.symbol, Pbt.integer).generate(rng) # => [:atq, 42]
Pbt.fixed_hash(x: Pbt.symbol, y: Pbt.integer).generate(rng) # => {x: :atq, y: 42}
Pbt.hash(Pbt.symbol, Pbt.integer).generate(rng) # => {atq: 121, ygab: -1142}
Pbt.one_of(:a, 1, 0.1).generate(rng) # => :a or 1 or 0.1
See ArbitraryMethods module for more details.
Configuration
You can configure Pbt
by calling Pbt.configure
before running tests.
Pbt.configure do |config|
# Whether to print verbose output. Default is `false`.
config.verbose = 100
# The concurrency method to use. :ractor`, `:thread`, `:process` and `:none` are supported. Default is `:ractor`.
config.worker = :ractor
# The number of runs to perform. Default is `100`.
config.num_runs = 100
# The seed to use for random number generation.
# It's useful to reproduce failed test with the seed you'd pick up from failure messages. Default is a random seed.
config.seed = 42
# Whether to report exceptions in threads.
# It's useful to suppress error logs on Ractor that reports many errors. Default is `false`.
config.thread_report_on_exception = false
end
Or, you can pass the configuration to Pbt.assert
as an argument.
Pbt.assert(num_runs: 100, seed: 42) do
# ...
end
Concurrent methods
One of the key features of Pbt
is its ability to rapidly execute test cases in parallel or concurrently, using a large number of values (by default, 100
) generated by Arbitrary
.
For concurrent processing, you can specify any of the three workers—:ractor
, :process
, or :thread
—using the worker
option. Alternatively, choose :none
for serial execution.
Pbt
supports 3 concurrency methods and 1 sequential one. You can choose one of them by setting the worker
option.
Ractor
Pbt.assert(worker: :ractor) do
Pbt.property(Pbt.integer) do |n|
# ...
end
end
Limitation
Please note that Ractor support is an experimental feature of this gem. Due to Ractor's limitations, you may encounter some issues when using it.
For example, you cannot access anything out of block.
a = 1
Pbt.assert(worker: :ractor) do
Pbt.property(Pbt.integer) do |n|
# You cannot access `a` here because this block is executed in a Ractor and it doesn't allow implicit sharing of objects.
a + n # => Ractor::RemoteError (can not share object between ractors)
end
end
You cannot use any methods provided by test frameworks like expect
or assert
because they are not available in a Ractor.
it do
Pbt.assert(worker: :ractor) do
Pbt.property(Pbt.integer) do |n|
# This is not possible because `self` if a Ractor here.
expect(n).to be_an(Integer) # => Ractor::RemoteError (cause by NoMethodError for `expect` or `be_an`)
end
end
end
Process
Pbt.assert(worker: :process) do
Pbt.property(Pbt.integer) do |n|
# ...
end
end
Thread
Pbt.assert(worker: :thread) do
Pbt.property(Pbt.integer) do |n|
# ...
end
end
None
Pbt.assert(worker: :none) do
Pbt.property(Pbt.integer) do |n|
# ...
end
end
TODOs
Once this project finishes the following, we will release v1.0.0.
- [x] Implement basic primitive arbitraries
- [x] Implement composite arbitraries
- [x] Support shrinking
- [x] Support multiple concurrency methods
- [x] Ractor
- [x] Process
- [x] Thread
- [x] None (Run tests sequentially)
- [x] Documentation
- [x] Add better examples
- [x] Arbitrary usage
- [x] Configuration
- [ ] Rich report like verbose mode
- [ ] Allow to use expectations and matchers provided by test framework in Ractor if possible.
- It'd be so hard to pass assertions like
expect
,assert
to a Ractor.
- It'd be so hard to pass assertions like
- [ ] Benchmark
- [ ] More parallelism or faster execution if possible
Development
Setup
bin/setup
bundle exec rake # Run tests and lint at once
Test
bundle exec rspec
Lint
bundle exec rake standard:fix
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/ohbarye/pbt. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Credits
This project draws a lot of inspiration from other testing tools, namely
Code of Conduct
Everyone interacting in the Pbt project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.