tryouts 2.4.1 → 3.0.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 975acb3a790344e059de10c8eafae0a58de04e407f89a42af031d7a76c082ca2
-  data.tar.gz: a9d77fe3c5f15d2080999b93b7b42c3d16a465fbe31397338f806cd6d67bb253
+  metadata.gz: 07be17b9ebef2d51f24a192dab9c292cf9613cf6ae32b42a98f47d34dea70045
+  data.tar.gz: 618e98529240a7a6df56667a1fa64a9f758d76c40ace4bd815275061894c176f
 SHA512:
-  metadata.gz: 4c70927fb871e78c28d44a1b996844e76b84eb944d57c9943f5603b5227f6f18d38bcdc836fa504b4e4b1220683c5d1b9c02a7af5636f884e393697927d8fc68
-  data.tar.gz: 7ccb05deaf71afdb6ff239e312c6bba8c7ef371a8fe746b15a47cf84cc81652502a62bff704ea8d33e345fa9350bcaec90d3055860c71973f9e2d8ffe618412d
+  metadata.gz: 8d8e493922bfd6c734466ec1f69becf5668f6b571b37e8367395e0f26aec8d19d5831e04169952b9acf2b1f04b3370fe33a163d50d776d42dcdfecc3aea1a0c6
+  data.tar.gz: 4aaac8820547f393a95dfb82f621aedef8142264298ef437beffe853b83a2fb61ee2687d5bf1cf0c74f852bc7192b49b963d133fcda5354a0250dfe309ec435c

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2011-2024 Delano Mandelbaum
+Copyright (c) 2011-2025 Delano Mandelbaum
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,109 +1,223 @@
-# Tryouts v2.4 (2024-07-20)
+# Tryouts v3.0.0-pre
 
 **Ruby tests that read like documentation.**
 
-A simple test framework for Ruby code that uses introspection to allow defining checks in comments.
+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 (`#=>`)
+- **Framework integration** with RSpec and Minitest translators
+- **Modern Ruby architecture** using Prism parser and pattern matching
+- **Immutable data structures** with `Data.define` classes
+- **Enhanced error reporting** with line numbers and context
 
 ## Installation
 
-One of:
-* In your Gemfile: `gem 'tryouts'`
-* As a gem: `gem install tryouts`
-* From source:
+Add to your Gemfile:
+```ruby
+gem 'tryouts', '~> 3.0.0-pre'
+```
+
+Or install directly:
+```bash
+gem install tryouts --pre
+```
 
+From source:
 ```bash
-  $ git clone git://github.com/tryouts/tryouts.git
+git clone https://github.com/delano/tryouts.git
+cd tryouts
+bundle install
 ```
 
+## Requirements
+
+- **Ruby >= 3.4.4** (for Prism parser and pattern matching)
+- **RSpec** or **Minitest** (optional, for framework integration)
+
 ## Usage
 
+### Basic Commands
+
 ```bash
-  # Run all tests accessible from the current directory (e.g. ./try, ./tryouts))
-  $ try
-
-  # Run a single test file
-  $ try try/10_utils_try.rb
-
-  # Command arguments
-  $ try -h
-  Usage: try [options]
-      -V, --version                    Display the version
-      -q, --quiet                      Run in quiet mode
-      -v, --verbose                    Run in verbose mode
-      -f, --fails                      Show only failing tryouts
-      -D, --debug                      Run in debug mode
-      -h, --help                       Display this help
+# Auto-discover and run all tests
+try
+
+# Run specific test file
+try try/step1_try.rb
+
+# Framework integration
+try --rspec try/step1_try.rb      # Run with RSpec
+try --minitest try/step1_try.rb   # Run with Minitest
+
+# Code generation only
+try --generate-rspec try/step1_try.rb
+try --generate-minitest try/step1_try.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
+### Exit Codes
 
-When all tests pass, try exits with a 0. An exit code of 1 or more indicates the number of failing tests.
+- `0`: All tests pass
+- `1+`: Number of failing tests
 
+## Writing Tests
 
-## Writing tests
+Tryouts use a unique comment-based expectation syntax:
 
 ```ruby
-  ## A very simple test
-  1 + 1
-  #=> 2
-
-  ## The test description can spread
-  ## across multiple lines. The same
-  ## is true for test definitions.
-  a = 'foo'
-  b = 'bar'
-  a + b
-  #=> 'foobar'
-
-  ## A test will pass when its return
-  ## value equals the expectation.
-  'foo'.class
-  #=> String
-
-  ## The expectations are evaluated as well.
-  81
-  #=> 9 * 9
-
-  ## Here's an example of testing errors
-  begin
-    raise RuntimeError
-  rescue RuntimeError
-    :success
-  end
-  #=> :success
+# Setup code runs before all tests
+puts 'Setup running'
+
+## Simple test with expectation
+a = 1 + 1
+#=> 2
+
+## Multi-line test with description
+## TEST: Addition works correctly
+a = 1
+b = 2
+a + b
+#=> 3
+
+## Testing object methods
+'hello'.upcase
+#=> 'HELLO'
+
+## Expressions are evaluated
+81
+#=> 9 * 9
+
+## Testing errors with rescue
+begin
+  raise RuntimeError, "test error"
+rescue RuntimeError
+  :caught
+end
+#=> :caught
+
+# Teardown runs after all tests
+puts 'Cleanup complete'
 ```
 
-For real world examples, see [Onetimesecret](https://github.com/onetimesecret/onetimesecret/) tryouts.
+### Test Structure
 
+- **Setup Section**: Code before first test case (accessible via instance variables)
+- **Test Cases**: Description lines (`##`), Ruby code, and expectations (`#=>`)
+- **Teardown Section**: Code after last test case
 
-### Test setup / cleanup
+## Framework Integration
 
-Put the setup code at the top of the file, and cleanup code at the bottom. Like this:
+Version 3.0 introduces framework translators that convert tryouts into established test frameworks:
 
-```ruby
-  # This is called before all tests
-  require 'gibbler'
-  Gibbler.digest_type = Digest::SHA256
+### RSpec Integration
+
+```bash
+try --rspec file_try.rb
+```
+
+Generates RSpec `describe/it` blocks with full RSpec ecosystem support including:
+- Mocking and stubbing
+- Custom matchers
+- Parallel execution
+- IDE integration
+
+### Minitest Integration
 
+```bash
+try --minitest file_try.rb
+```
 
-  ## This is a single testcase
-    :anything.gibbler
-  #=> '8574309'
+Creates Minitest classes with `test_*` methods for:
+- Standard assertions
+- Custom test cases
+- CI/CD integration
+- Debugging support
 
+### Direct Mode
 
-  # This will be called after all tests
-  Gibbler.digest_type = Digest::SHA1
+```bash
+try file_try.rb  # Original tryouts execution
 ```
 
-__
+Uses shared execution context with all tests running in the same environment.
+
+## File Discovery
+
+Auto-discovers test files matching these patterns:
+- `./try/*_try.rb`
+- `./tryouts/*_try.rb`
+- `./*_try.rb`
+
+Files are processed in lexical order.
+
+## Modern Architecture (v3.0)
+
+### 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
+
+### Ruby 3.4+ Features
+
+- **Pattern matching** throughout parsing and classification logic
+- **Prism native parser** (no external grammar compilation)
+- **Data.define classes** for immutable data structures
+- **Enhanced error context** with line numbers and suggestions
+
+## Development
+
+### Running Tests
+
+```bash
+# Test framework using itself
+try try/*_try.rb
+
+# With coverage
+COVERAGE=1 try try/*_try.rb
+```
+
+### Code Quality
+
+```bash
+bundle exec rubocop        # Check style
+bundle exec rubocop -A     # Auto-fix issues
+```
+
+## Migration from v2.x
+
+Version 3.0 represents a complete modernization:
+
+- **Parser**: Tree-sitter → Prism (native Ruby)
+- **Execution**: Custom runner → Framework delegation
+- **Data**: Traditional classes → `Data.define` immutable structures
+- **Syntax**: Standard Ruby → Pattern matching throughout
+- **Ruby**: 2.7+ → 3.4+ requirement
+
+## Examples
+
+For real-world usage examples, see:
+- [Onetimesecret tryouts](https://github.com/onetimesecret/onetimesecret/)
+- Test files in this repository: `try/*_try.rb` and `doc/`
 
+## AI Development Assistance
 
-## Thanks
+This version of Tryouts was developed with assistance from AI tools. The following tools provided significant help with architecture design, code generation, and documentation:
 
-* [cloudhead](https://github.com/cloudhead)
-* [mynyml](https://github.com/mynyml)
-* [Syntenic](https://syntenic.com/) for the hackfest venue.
-* [AlexPeuchert](https://www.rubypulse.com/) for the screencast.
-* Christian Michon for suggesting a better default output format.
+- **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
 
-*This collision was brought to you by Montreal.rb.*
+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.

data/exe/try

@@ -1,51 +1,27 @@
-#!/usr/bin/env ruby
+#!/usr/bin/env /Users/d/.rbenv/shims/ruby
 
-require 'optparse'
 require_relative '../lib/tryouts'
 
-# Adding local lib directories allows the test files
-# to require the ruby code they are testing without
-# needing even if the files use regular requires. It
-# skips the test files from having to muck with the
-# load path or use `require_relative` which is easy
-# to forget. This is a convenience feature.
-#
-# Here we're looking for directories relative to the
-# current working directory (i.e. where this script
-# is being run from.
+# Add development library paths
 lib_glob = File.join(Dir.pwd, '{lib,../lib,.}')
-Tryouts.update_load_path(lib_glob)
+Tryouts.update_load_path(lib_glob) if Tryouts.respond_to?(:update_load_path)
 
-# Parse command-line arguments
-OptionParser.new do |opts|
-  opts.on('-V', '--version', 'Display the version') do
-    puts "Tryouts: #{Tryouts::VERSION}"
-    exit
-  end
-  opts.on('-q', '--quiet', 'Run in quiet mode') { Tryouts.quiet = true }
-  opts.on('-v', '--verbose', 'Run in verbose mode') { Tryouts.noisy = true }
-  opts.on('-f', '--fails', 'Show only failing tryouts') { Tryouts.fails = true }
-  opts.on('-D', '--debug', 'Run in debug mode') { Tryouts.debug = true }
-  opts.on('-h', '--help', 'Display this help') do
-    puts opts
-    exit
-  end
-end.parse!
+# Parse args and run CLI
+begin
+  files, options = Tryouts::CLI.parse_args(ARGV)
 
-# Find tryouts path with a path glob unless thin
-# script was called with arguments in which case
-# we consume those as a list of paths.
-paths = if ARGV.empty?
-          Dir.glob(
-            ['./{try,tryouts/,.}/*_{try,tryouts}.rb'],
-            base: Dir.pwd
-          ).sort # deterministic order
-
-        else
-          ARGV
-        end
+  # Default file discovery if no files specified
+  if files.empty?
+    files = Dir.glob(
+      ['./{try,tryouts,.}/*_try.rb'],
+      base: Dir.pwd,
+    ).sort
+  end
 
-# Running the tryouts returns the number of
-# test failures so here we pass that value
-# through as the exit code for the script.
-exit Tryouts.run_all(*paths)
+  cli = Tryouts::CLI.new
+  exit cli.run(files, **options)
+rescue StandardError => ex
+  warn "Error: #{ex.message}"
+  warn ex.backtrace.join("\n") if options[:debug]
+  exit 1
+end

data/exe/tryouts

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
-# frozen_string_literal: true
+# exe/tryouts
 
-load File.expand_path("../try", __FILE__)
+load File.expand_path('try', __dir__)

data/lib/tryouts/cli/formatters/base.rb

@@ -0,0 +1,108 @@
+# lib/tryouts/cli/formatters/base.rb
+
+require_relative 'factory'
+require_relative 'output_manager'
+
+class Tryouts
+  class CLI
+    # Enhanced interface for all test output formatting
+    module FormatterInterface
+      # Phase-level output (major sections)
+      def phase_header(message, file_count = nil, level = 0)
+        raise NotImplementedError, "#{self.class} must implement #phase_header"
+      end
+
+      # File-level operations
+      def file_start(file_path, context_info = {})
+        raise NotImplementedError, "#{self.class} must implement #file_start"
+      end
+
+      def file_parsed(file_path, test_count, setup_present: false, teardown_present: false)
+        raise NotImplementedError, "#{self.class} must implement #file_parsed"
+      end
+
+      def file_execution_start(file_path, test_count, context_mode)
+        raise NotImplementedError, "#{self.class} must implement #file_execution_start"
+      end
+
+      def file_result(file_path, total_tests, failed_count, error_count, elapsed_time)
+        raise NotImplementedError, "#{self.class} must implement #file_result"
+      end
+
+      # Test-level operations
+      def test_start(test_case, index, total)
+        raise NotImplementedError, "#{self.class} must implement #test_start"
+      end
+
+      def test_result(test_case, result_status, actual_results = [], elapsed_time = nil)
+        raise NotImplementedError, "#{self.class} must implement #test_result"
+      end
+
+      def test_output(test_case, output_text)
+        raise NotImplementedError, "#{self.class} must implement #test_output"
+      end
+
+      # Setup/teardown operations
+      def setup_start(line_range)
+        raise NotImplementedError, "#{self.class} must implement #setup_start"
+      end
+
+      def setup_output(output_text)
+        raise NotImplementedError, "#{self.class} must implement #setup_output"
+      end
+
+      def teardown_start(line_range)
+        raise NotImplementedError, "#{self.class} must implement #teardown_start"
+      end
+
+      def teardown_output(output_text)
+        raise NotImplementedError, "#{self.class} must implement #teardown_output"
+      end
+
+      # Summary operations
+      def batch_summary(total_tests, failed_count, elapsed_time)
+        raise NotImplementedError, "#{self.class} must implement #batch_summary"
+      end
+
+      def grand_total(total_tests, failed_count, error_count, successful_files, total_files, elapsed_time)
+        raise NotImplementedError, "#{self.class} must implement #grand_total"
+      end
+
+      # Debug and diagnostic output
+      def debug_info(message, level = 0)
+        raise NotImplementedError, "#{self.class} must implement #debug_info"
+      end
+
+      def trace_info(message, level = 0)
+        raise NotImplementedError, "#{self.class} must implement #trace_info"
+      end
+
+      def error_message(message, details = nil)
+        raise NotImplementedError, "#{self.class} must implement #error_message"
+      end
+
+      # Utility methods
+      def raw_output(text)
+        raise NotImplementedError, "#{self.class} must implement #raw_output"
+      end
+
+      def separator(style = :light)
+        raise NotImplementedError, "#{self.class} must implement #separator"
+      end
+
+      def indent_text(text, level)
+        indent = '  ' * level
+        "#{indent}#{text}"
+      end
+
+      def with_indent(level)
+        old_indent      = @current_indent
+        @current_indent = level
+        yield
+      ensure
+        @current_indent = old_indent
+      end
+    end
+
+  end
+end