Tryouts v3.1

Ruby tests that read like documentation.

A modern test framework for Ruby that uses comments to define expectations. Tryouts are meant to double as documentation, so the Ruby code should be plain and reminiscent of real code.

> [!WARNING]
> Version 3.0+ uses Ruby’s Prism parser and pattern matching, requiring Ruby 3.4+

Key Features

Documentation-style tests using comment-based expectations (#=>)
Great expectation syntax for more expressive assertions (#==> for true, #=/=> for false, #=:> for class/module)
Framework integration write with tryouts syntax, run with RSpec or Minitest
Enhanced error reporting with line numbers and context

Installation

# Add to your Gemfile:
gem 'tryouts'

# Or install directly:
$ gem install tryouts

Usage

# Auto-discover and run all tests
try

# Run specific test file
try try/core/basic_syntax_try.rb

Writing Tests

Tryouts use a comment-based syntax for expecations:

# Setup code runs before all tests
puts 'Setup running'

## Simple test with expectation
a = 1 + 1
#=&gt; 2

## Multi-line test with description
## TEST: Addition works correctly
a = 1
b = 2
a + b
#=&gt; 3

## Testing object methods
'hello'.upcase
#=&gt; 'HELLO'

## Expressions are evaluated
81
#=&gt; 9 * 9

## Testing errors with rescue
begin
  raise RuntimeError, "test error"
rescue RuntimeError
  :caught
end
#=&gt; :caught

# Teardown runs after all tests
puts 'Cleanup complete'

Test Structure

Each test file is made up of three sections:

Setup: Code before first test case
Test Cases: Description lines (##), Ruby code, and expectations (#=>)
Teardown: Code after last test case

Great Expectations System

| Syntax | Description | Example | Context |
|——–|—————————-|————————————-|—————|
| #=> | Traditional value equality | #=> [1, 2, 3] | result, _ |
| #==> | Must be exactly true | #==> result.include?(2) | result, _ |
| #=/=>| Must be exactly false | #=/=> _.empty? | result, _ |
| #=\|> | Must be true OR false | #=\|> 0.positive? | result, _ |
| #=!> | Must raise an exception | #=!> error.is_a?(ZeroDivisionError) | error |
| #=:> | Must match result type | #=:> String | result, _ |
| #=~> | Must match regex pattern | #=~> /^[^@]+@[^@]+\.[^@]+$/ | result, _ |
| #=%> | Must complete within time | #=%> 2000 # in milliseconds | result, _ |
| #=1> | Match content in STDOUT | #=1> "You have great success" | result, _ |
| #=2> | Match content in STDERR | #=2> /[a-zA-Z0-9]+-?[0-9]{1,5} | result, _ |
| #=<> | Fails on purpose | #==<> result.include?(4) | result, _ |

Using other test runners

Version 3 introduces framework translators that convert tryouts into the equivalent tests in popular test tools, like RSpec and Minitest.

# Framework integration
try --rspec try/core/basic_syntax_try.rb      # Run with RSpec
try --minitest try/core/basic_syntax_try.rb   # Run with Minitest

# Code generation only
try --generate-rspec try/core/basic_syntax_try.rb &gt; spec/basic_syntax_spec.rb
try --generate-minitest try/core/basic_syntax_try.rb &gt; test/basic_syntax_test.rb

# Output options
try -v    # verbose (includes source code and return values)
try -q    # quiet mode
try -f    # show failures only
try -D    # debug mode

Exit Codes

0: All tests pass
1+: Number of failing tests

Requirements

Ruby >= 3.2+ (for Prism parser and pattern matching)
RSpec or Minitest (optional, for framework integration)

Modern Architecture (v3+)

Core Components

Prism Parser: Native Ruby parsing with pattern matching for line classification
Data Structures: Immutable Data.define classes for test representation
Framework Translators: Convert tryouts to RSpec/Minitest format
CLI: Modern command-line interface with framework selection

Live Examples

For real-world usage examples, see:

AI Development Assistance

This version of Tryouts was developed with assistance from AI tools. The following tools provided significant help with architecture design, code generation, and documentation:

Claude Sonnet 4 - Architecture design, code generation, and documentation
Claude Desktop & Claude Code - Interactive development sessions and debugging
GitHub Copilot - Code completion and refactoring assistance
Qodo Merge Pro - Code review and quality improvements

I remain responsible for all design decisions and the final code. I believe in being transparent about development tools, especially as AI becomes more integrated into our workflows as developers.

Modules

Classes