https://github.com/fixrb/test_tube
A test tube to conduct software experiments 🧪
https://github.com/fixrb/test_tube
Last synced: 9 months ago
JSON representation
A test tube to conduct software experiments 🧪
- Host: GitHub
- URL: https://github.com/fixrb/test_tube
- Owner: fixrb
- License: mit
- Created: 2021-06-18T23:46:16.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-31T21:46:05.000Z (over 1 year ago)
- Last Synced: 2025-10-09T23:12:56.192Z (9 months ago)
- Language: Ruby
- Homepage:
- Size: 362 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Test Tube
[](https://github.com/fixrb/test_tube/tags)
[](https://rubydoc.info/github/fixrb/test_tube/main)
[](https://github.com/fixrb/test_tube/raw/main/LICENSE.md)
> A test tube to conduct software experiments safely 🧪
TestTube is a Ruby library designed to safely execute and evaluate code experiments. It provides:
- Complete exception handling (including SystemExit and other system-level exceptions)
- A flexible matcher-based testing approach
- Two distinct testing methods: code execution (`invoke`) and value testing (`pass`)
- Clear experiment results with actual values, errors, and matcher results
## Installation
Add this line to your application's Gemfile:
```ruby
gem "test_tube"
```
And then execute:
```sh
bundle install
```
Or install it yourself as:
```sh
gem install test_tube
```
## Usage
### Basic Usage
First, make TestTube available:
```ruby
require "test_tube"
```
TestTube provides two main ways to conduct experiments:
1. **Execute and test code** with `invoke`:
- Safely executes blocks of code
- Catches ALL exceptions, including system-level ones
- Perfect for testing potentially dangerous operations
2. **Test direct values** with `pass`:
- Tests pre-computed values
- Simpler and more direct approach
- Ideal when you already have the value to test
### Simple Example
Let's test if a value equals 42 using a custom matcher:
```ruby
class BeTheAnswer
def match?
42.equal?(yield)
end
end
# Using invoke to execute code
experiment = TestTube.invoke(matcher: BeTheAnswer.new, negate: false) do
"101010".to_i(2) # Converting binary to decimal
end
experiment.got # => true
experiment.actual # => 42
experiment.error # => nil
# Or using pass with a direct value
experiment = TestTube.pass(42, matcher: BeTheAnswer.new, negate: false)
experiment.got # => true
experiment.actual # => 42
experiment.error # => nil
```
### Integration with Matchi
TestTube works seamlessly with the [Matchi](https://github.com/fixrb/matchi/) matcher library:
```sh
gem install matchi
```
```ruby
require "matchi"
# Testing for exceptions
experiment = TestTube.invoke(
matcher: Matchi::RaiseException.new(:NoMethodError),
negate: false
) { "foo".blank? }
experiment.got # => true
experiment.actual # => #
# Testing floating-point arithmetic
experiment = TestTube.invoke(
matcher: Matchi::Be.new(0.3),
negate: false
) { 0.1 + 0.2 }
experiment.got # => false
experiment.actual # => 0.30000000000000004
# Handling errors gracefully
experiment = TestTube.invoke(
matcher: Matchi::Match.new(/^foo$/),
negate: false
) { BOOM }
experiment.got # => nil
experiment.error # => #
experiment.actual # => nil
```
## Key Features
- **Safe Execution**: Catches all exceptions, including system-level ones
- **Flexible Testing**: Support for custom matchers and the Matchi library
- **Clear Results**: Easy access to actual values, errors, and test results
- **Two Testing Modes**: Choose between code execution and direct value testing
- **Framework Friendly**: Perfect for building testing frameworks and tools
## Contact
* Source code: https://github.com/fixrb/test_tube
* Chinese blog post: https://ruby-china.org/topics/41390
* Japanese blog post: https://qiita.com/cyril/items/36174b619ff1852c80ec
## Versioning
Test Tube follows [Semantic Versioning 2.0](https://semver.org/).
## License
The [gem](https://rubygems.org/gems/test_tube) is available as open source under the terms of the [MIT License](https://github.com/fixrb/test_tube/raw/main/LICENSE.md).
## Sponsors
This project is sponsored by [Sashité](https://sashite.com/)