tryouts 3.3.2 → 3.5.0

data/lib/tryouts/cli/opts.rb

@@ -15,19 +15,72 @@ class Tryouts
         try --direct --shared-context test_try.rb # Explicit shared context
         try --generate-rspec test_try.rb         # Output RSpec code only
         try --inspect test_try.rb                # Inspect file structure and validation
-
-      File Format:
-        ## Test description       # Test case marker
-        code_to_test              # Ruby code
-        #=> expected_result       # Expectation (various types available)
+        try --agent test_try.rb                  # Agent-optimized structured output
+        try --agent --agent-limit 10000 tests/  # Agent mode with 10K token limit
+
+      Agent Output Modes:
+        --agent                                  # Structured, token-efficient output
+        --agent-focus summary                    # Show counts and problem files only
+        --agent-focus first-failure              # Show first failure per file
+        --agent-focus critical                   # Show errors/exceptions only
+        --agent-limit 1000                      # Limit output to 1000 tokens
+
+      File Naming & Organization:
+        Files must end with '_try.rb' or '.try.rb' (e.g., auth_service_try.rb, user_model.try.rb)
+        Auto-discovery searches: ./try/, ./tryouts/, ./*_try.rb, ./*.try.rb patterns
+        Organize by feature/module: try/models/, try/services/, try/api/
+
+      Testcase Structure (3 required parts)
+        ## This is the description
+        echo 'This is ruby code under test'
+        true
+        #=> true  # this is the expected result
+
+      File Structure (3 sections):
+        # Setup section (optional) - runs once before all tests
+        @shared_var = "available to all test cases"
+
+        ## TEST: Feature description
+        # Test case body with plain Ruby code
+        result = some_operation()
+        #=> expected_value
+
+        # Teardown section (optional) - runs once after all tests
+
+      Context Guidelines:
+        Shared Context (default): Instance variables persist across test cases
+          - Use for: Integration testing, stateful scenarios, realistic workflows
+          - Caution: Test order matters, state accumulates
+
+        Fresh Context (--rspec/--minitest): Each test gets isolated environment
+          - Use for: Unit testing, independent test cases
+          - Setup variables copied to each test, but changes don't persist
+
+      Writing Quality Tryouts:
+        - Use realistic, plain Ruby code (avoid mocks, test harnesses)
+        - Test descriptions start with ##, be specific about what's being tested
+        - One result per test case (last expression is the result)
+        - Use appropriate expectation types for clarity (#==> for boolean, #=:> for types)
+        - Keep tests focused and readable - they serve as documentation
 
       Great Expectations System:
-        Multiple expectation types are supported for different testing needs.
-
         #=>   Value equality        #==> Must be true         #=/=> Must be false
         #=|>  True OR false         #=!>  Must raise error    #=:>  Type matching
         #=~>  Regex matching        #=%>  Time constraints    #=*>  Non-nil result
         #=1>  STDOUT content        #=2>  STDERR content      #=<>  Intentional failure
+
+      Exception Testing:
+        # Method 1: Rescue and test exception
+        begin
+          risky_operation
+        rescue StandardError => e
+          e.class
+        end
+        #=> StandardError
+
+        # Method 2: Let it raise and test with #=!>
+        risky_operation
+        #=!> error.is_a?(StandardError)
     HELP
 
     class << self
@@ -70,6 +123,26 @@ class Tryouts
             options[:parallel_threads] = threads.to_i if threads && threads.to_i > 0
           end
 
+          opts.separator "\nParser Options:"
+          opts.on('--strict', 'Require explicit test descriptions (fail on unnamed tests)') { options[:strict] = true }
+          opts.on('--no-strict', 'Allow unnamed tests (legacy behavior)') { options[:strict] = false }
+          opts.on('-w', '--warnings', 'Show parser warnings (default: true)') { options[:warnings] = true }
+          opts.on('--no-warnings', 'Suppress parser warnings') { options[:warnings] = false }
+
+          opts.separator "\nAgent-Optimized Output:"
+          opts.on('-a', '--agent', 'Agent-optimized structured output for LLM context management') do
+            options[:agent] = true
+          end
+          opts.on('--agent-limit TOKENS', Integer, 'Limit total output to token budget (default: 5000)') do |limit|
+            options[:agent] = true
+            options[:agent_limit] = limit
+          end
+          opts.on('--agent-focus TYPE', %w[failures first-failure summary critical],
+                  'Focus mode: failures, first-failure, summary, critical (default: failures)') do |focus|
+            options[:agent] = true
+            options[:agent_focus] = focus.to_sym
+          end
+
           opts.separator "\nParser Options:"
           opts.on('--enhanced-parser', 'Use enhanced parser with inhouse comment extraction (default)') { options[:parser] = :enhanced }
           opts.on('--legacy-parser', 'Use legacy prism parser') { options[:parser] = :prism }

data/lib/tryouts/cli.rb

@@ -4,6 +4,7 @@ require 'optparse'
 
 require_relative 'cli/opts'
 require_relative 'cli/formatters'
+require_relative 'cli/line_spec_parser'
 require_relative 'test_runner'
 
 class Tryouts
@@ -13,6 +14,8 @@ class Tryouts
         framework: :direct,
         verbose: false,
         inspect: false,
+        strict: true,    # Default to strict mode for better UX
+        warnings: true,  # Default to showing warnings
       }
     end
 
@@ -22,11 +25,14 @@ class Tryouts
       output_manager = FormatterFactory.create_output_manager(@options)
 
       handle_version_flag(@options, output_manager)
-      validate_files_exist(files, output_manager)
+
+      # Parse line specs from file arguments
+      files_with_specs = parse_file_specs(files)
+      validate_files_exist(files_with_specs, output_manager)
 
       runner = TestRunner.new(
-        files: files,
-        options: @options,
+        files: files_with_specs.keys,
+        options: @options.merge(file_line_specs: files_with_specs),
         output_manager: output_manager,
       )
 
@@ -42,13 +48,24 @@ class Tryouts
       exit 0
     end
 
-    def validate_files_exist(files, output_manager)
-      missing_files = files.reject { |file| File.exist?(file) }
+    def validate_files_exist(files_with_specs, output_manager)
+      missing_files = files_with_specs.keys.reject { |file| File.exist?(file) }
 
       unless missing_files.empty?
         missing_files.each { |file| output_manager.error("File not found: #{file}") }
         exit 1
       end
     end
+
+    def parse_file_specs(files)
+      files_with_specs = {}
+
+      files.each do |file_arg|
+        filepath, line_spec = LineSpecParser.parse(file_arg)
+        files_with_specs[filepath] = line_spec
+      end
+
+      files_with_specs
+    end
   end
 end

data/lib/tryouts/file_processor.rb

@@ -20,8 +20,15 @@ class Tryouts
 
     def process
       testrun                     = create_parser(@file, @options).parse
+
+      # Apply line spec filtering before reporting test counts
+      if @options[:line_spec]
+        testrun = filter_testrun_by_line_spec(testrun)
+      end
+
       @global_tally[:aggregator].increment_total_files
       @output_manager.file_parsed(@file, testrun.total_tests)
+      @output_manager.parser_warnings(@file, warnings: testrun.warnings)
 
       if @options[:inspect]
         handle_inspect_mode(testrun)
@@ -38,6 +45,34 @@ class Tryouts
 
     private
 
+    def filter_testrun_by_line_spec(testrun)
+      require_relative 'cli/line_spec_parser'
+
+      line_spec = @options[:line_spec]
+
+      # Filter test cases to only those that match the line spec
+      filtered_cases = testrun.test_cases.select do |test_case|
+        Tryouts::CLI::LineSpecParser.matches?(test_case, line_spec)
+      end
+
+      # Check if any tests matched the line specification
+      if filtered_cases.empty?
+        @output_manager.file_failure(@file, "No test cases found matching line specification: #{line_spec}")
+        return testrun  # Return original testrun to avoid breaking the pipeline
+      end
+
+      # Create a new testrun with filtered cases
+      # We need to preserve the setup and teardown but only include matching tests
+      testrun.class.new(
+        setup: testrun.setup,
+        test_cases: filtered_cases,
+        teardown: testrun.teardown,
+        source_file: testrun.source_file,
+        metadata: testrun.metadata,
+        warnings: testrun.warnings
+      )
+    end
+
     def create_parser(file, options)
       parser_type = options[:parser] || :enhanced  # enhanced parser is now the default
 
@@ -47,9 +82,9 @@ class Tryouts
 
       case parser_type
       when :enhanced
-        EnhancedParser.new(file)
+        EnhancedParser.new(file, options)
       when :prism
-        PrismParser.new(file)
+        PrismParser.new(file, options)
       end
     end
 

data/lib/tryouts/parser_warning.rb

@@ -0,0 +1,26 @@
+# lib/tryouts/parser_warning.rb
+
+class Tryouts
+  # Data structure for parser warnings
+  ParserWarning = Data.define(:type, :message, :line_number, :context, :suggestion) do
+    def self.unnamed_test(line_number:, context:)
+      new(
+        type: :unnamed_test,
+        message: "Test case without explicit description",
+        line_number: line_number,
+        context: context,
+        suggestion: "Add a test description using '## Description' prefix"
+      )
+    end
+
+    def self.ambiguous_test_boundary(line_number:, context:)
+      new(
+        type: :ambiguous_boundary,
+        message: "Ambiguous test case boundary detected",
+        line_number: line_number,
+        context: context,
+        suggestion: "Use explicit '## Description' to clarify test structure"
+      )
+    end
+  end
+end

data/lib/tryouts/parsers/base_parser.rb

@@ -3,6 +3,7 @@
 require 'prism'
 
 require_relative 'shared_methods'
+require_relative '../parser_warning'
 
 class Tryouts
   # Fixed PrismParser with pattern matching for robust token filtering
@@ -10,12 +11,14 @@ class Tryouts
     class BaseParser
       include Tryouts::Parsers::SharedMethods
 
-      def initialize(source_path)
+      def initialize(source_path, options = {})
         @source_path  = source_path
         @source       = File.read(source_path)
         @lines        = @source.lines.map(&:chomp)
         @prism_result = Prism.parse(@source)
         @parsed_at    = Time.now
+        @options      = options
+        @warnings     = []
       end
 
     end

data/lib/tryouts/parsers/shared_methods.rb

@@ -1,5 +1,7 @@
 # lib/tryouts/parsers/shared_methods.rb
 
+require_relative '../parser_warning'
+
 class Tryouts
   module Parsers
     module SharedMethods
@@ -205,13 +207,19 @@ class Tryouts
         test_blocks     = classified_blocks.filter { |block| block[:type] == :test }
         teardown_blocks = classified_blocks.filter { |block| block[:type] == :teardown }
 
-        Testrun.new(
+        testrun = Testrun.new(
           setup: build_setup(setup_blocks),
           test_cases: test_blocks.map { |block| build_test_case(block) },
           teardown: build_teardown(teardown_blocks),
           source_file: @source_path,
           metadata: { parsed_at: @parsed_at, parser: parser_type },
+          warnings: warnings
         )
+
+        # Validate strict mode after collecting all warnings
+        validate_strict_mode(testrun)
+
+        testrun
       end
 
       def build_setup(setup_blocks)
@@ -354,6 +362,9 @@ class Tryouts
           start_line: Integer => start_line,
           end_line: Integer => end_line
         }
+          # Collect warning for unnamed test
+          collect_unnamed_test_warning(block)
+
           source_lines           = @lines[start_line..end_line]
           first_expectation_line = exp_tokens.empty? ? start_line : exp_tokens.first[:line]
 
@@ -411,6 +422,44 @@ class Tryouts
         :shared
       end
 
+      # Warning collection methods
+      def add_warning(warning)
+        @warnings ||= []
+        @warnings << warning
+      end
+
+      def warnings
+        @warnings ||= []
+      end
+
+      def collect_unnamed_test_warning(block)
+        return unless block[:type] == :test && block[:description].empty?
+
+        line_number = block[:start_line] + 1
+        context = @lines[block[:start_line]] || ''
+
+        add_warning(ParserWarning.unnamed_test(
+          line_number: line_number,
+          context: context.strip
+        ))
+      end
+
+      def validate_strict_mode(testrun)
+        return unless @options[:strict]
+
+        unnamed_test_warnings = warnings.select { |w| w.type == :unnamed_test }
+        return if unnamed_test_warnings.empty?
+
+        # In strict mode, fail with first unnamed test error
+        first_warning = unnamed_test_warnings.first
+        raise TryoutSyntaxError.new(
+          "Strict mode: #{first_warning.message} at line #{first_warning.line_number}. #{first_warning.suggestion}",
+          line_number: first_warning.line_number,
+          context: first_warning.context,
+          source_file: @source_path
+        )
+      end
+
     end
   end
 end

data/lib/tryouts/test_case.rb

@@ -67,7 +67,7 @@ class Tryouts
     end
   end
 
-  Testrun = Data.define(:setup, :test_cases, :teardown, :source_file, :metadata) do
+  Testrun = Data.define(:setup, :test_cases, :teardown, :source_file, :metadata, :warnings) do
     def total_tests
       test_cases.size
     end

data/lib/tryouts/test_executor.rb

@@ -11,6 +11,7 @@ class Tryouts
       @output_manager = output_manager
       @translator     = translator
       @global_tally   = global_tally
+
     end
 
     def execute
@@ -28,6 +29,7 @@ class Tryouts
 
     private
 
+
     def execute_direct_mode
       batch = TestBatch.new(
         @testrun,

data/lib/tryouts/test_runner.rb

@@ -29,6 +29,7 @@ class Tryouts
       @output_manager = output_manager
       @translator     = initialize_translator
       @global_tally   = initialize_global_tally
+      @file_line_specs = options[:file_line_specs] || {}
     end
 
     def run
@@ -37,8 +38,17 @@ class Tryouts
 
       result = process_files
       show_failure_summary
-      show_grand_total if @global_tally[:aggregator].get_file_counts[:total] > 1
-      result
+      # Always show grand total for agent mode to ensure output, otherwise only for multiple files
+      if @options[:agent] || @global_tally[:aggregator].get_file_counts[:total] > 1
+        show_grand_total
+      end
+
+      # For agent critical mode, only count errors as failures
+      if @options[:agent] && (@options[:agent_focus] == :critical || @options[:agent_focus] == 'critical')
+        @global_tally[:aggregator].get_display_counts[:errors]
+      else
+        result
+      end
     end
 
     private
@@ -107,7 +117,7 @@ class Tryouts
       executor = Concurrent::ThreadPoolExecutor.new(
         min_threads: 1,
         max_threads: pool_size,
-        max_queue: pool_size * 2, # Reasonable queue size
+        max_queue: @files.length, # Queue size must accommodate all files
         fallback_policy: :abort # Raise exception if pool and queue are exhausted
       )
 
@@ -142,10 +152,16 @@ class Tryouts
       failure_count
     end
 
-    def process_file(file_path)
+    def process_file(file)
+      # Pass line spec for this file if available
+      file_options = @options.dup
+      if @file_line_specs && @file_line_specs[file]
+        file_options[:line_spec] = @file_line_specs[file]
+      end
+
       processor = FileProcessor.new(
-        file: file_path,
-        options: @options,
+        file: file,
+        options: file_options,
         output_manager: @output_manager,
         translator: @translator,
         global_tally: @global_tally,
@@ -154,7 +170,7 @@ class Tryouts
     rescue StandardError => ex
       handle_file_error(ex)
       @global_tally[:aggregator].add_infrastructure_failure(
-        :file_processing, file_path, ex.message, ex
+        :file_processing, file, ex.message, ex
       )
       1
     end

data/lib/tryouts/version.rb

@@ -1,5 +1,5 @@
 # lib/tryouts/version.rb
 
 class Tryouts
-  VERSION = '3.3.2'
+  VERSION = '3.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tryouts
 version: !ruby/object:Gem::Version
-  version: 3.3.2
+  version: 3.5.0
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -137,6 +137,7 @@ files:
 - lib/tryouts.rb
 - lib/tryouts/cli.rb
 - lib/tryouts/cli/formatters.rb
+- lib/tryouts/cli/formatters/agent.rb
 - lib/tryouts/cli/formatters/base.rb
 - lib/tryouts/cli/formatters/compact.rb
 - lib/tryouts/cli/formatters/factory.rb
@@ -144,8 +145,10 @@ files:
 - lib/tryouts/cli/formatters/output_manager.rb
 - lib/tryouts/cli/formatters/quiet.rb
 - lib/tryouts/cli/formatters/test_run_state.rb
+- lib/tryouts/cli/formatters/token_budget.rb
 - lib/tryouts/cli/formatters/tty_status_display.rb
 - lib/tryouts/cli/formatters/verbose.rb
+- lib/tryouts/cli/line_spec_parser.rb
 - lib/tryouts/cli/modes/generate.rb
 - lib/tryouts/cli/modes/inspect.rb
 - lib/tryouts/cli/opts.rb
@@ -167,6 +170,7 @@ files:
 - lib/tryouts/expectation_evaluators/true.rb
 - lib/tryouts/failure_collector.rb
 - lib/tryouts/file_processor.rb
+- lib/tryouts/parser_warning.rb
 - lib/tryouts/parsers/base_parser.rb
 - lib/tryouts/parsers/enhanced_parser.rb
 - lib/tryouts/parsers/prism_parser.rb