tryouts 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b0f0a0ca7de83a58c4e822d127a963bb1fb08523d9146b24c8b33f8a2c12ff2
-  data.tar.gz: 2f4e61611e23176da42cc9bbf82a92a2cc1e9d6049943fd4d4827dcd2b34c84f
+  metadata.gz: 7b692cc3a63ac86e060b52e77c246305be0f209dbf06b31b1b08deefbc06434a
+  data.tar.gz: 156e86aa4bde377aa2158f3a059983a6fe5f58796f71545c9895a9b57668b126
 SHA512:
-  metadata.gz: 1505d26c47b4fb3fb75675425e6aaac3e1ba81b6f39ac8ae47622ae43acd0c19a13a16e82486663de0201f21bf7b997281744fc6d69cae6116e67065803b4a39
-  data.tar.gz: ca57f3c38348023c57f5e382fe8b45e29877393fae155a718c921550b4a2200b0fe37c1c31be4f41dcbc934527d8c6b53e74fbe88fcc574c53cbc3d765bb3534
+  metadata.gz: d289a9b5ccd6694bd63fe4ca2a0c8aaf610d702e74380bf4975ae78ffaf377d0f82a9ec481dbc51105de9f3b07681c32eaa8a1c3566a1eebd0a861796eaff1e3
+  data.tar.gz: a0db3ebf76b5a291e6ea9d81f1f6e268a95320d28040a10f2225171b221f04bb2ed525bae3f79785d50f4269eb7c9be1dec242012bbca0a6d4588ac9e7fdd362

data/README.md

@@ -1,4 +1,4 @@
-# Tryouts v3
+# Tryouts - A Ruby Testing Framework
 
 **Ruby tests that read like documentation.**
 
@@ -130,6 +130,21 @@ try --agent --agent-focus critical       # show only errors/exceptions
 try --agent --agent-limit 1000          # limit output to 1000 tokens
 ```
 
+#### Why Not Pipe Test Output Directly to AI?
+
+Raw test output creates several problems when working with AI assistants:
+
+- **Token bloat**: Verbose formatting wastes 60-80% of your context window on styling
+- **Signal vs noise**: Important failures get buried in passing test details and framework boilerplate
+- **Inconsistent parsing**: AI struggles with varying output formats across different test runs
+- **Context overflow**: Large test suites exceed AI token limits, truncating critical information
+
+#### TOPA: A Better Approach
+
+Tryouts' `--agent` mode inspired the development of **TOPA (Test Output Protocol for AI)** - a standardized format optimized for AI analysis. The [tpane](https://github.com/delano/tpane) tool implements this protocol, transforming any test framework's output into structured, token-efficient formats.
+
+Instead of overwhelming AI with raw output, TOPA provides clean semantic data focusing on what actually needs attention - failures, errors, and actionable context.
+
 ### Exit Codes
 
 - `0`: All tests pass
@@ -162,8 +177,8 @@ For real-world usage examples, see:
 
 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
+- **Claude Sonnet 4, Opus 4.1** - Architecture design, code generation, and documentation
+- **Claude Desktop & Claude Code (Max plan)** - Interactive development sessions and debugging
 - **GitHub Copilot** - Code completion and refactoring assistance
 - **Qodo Merge Pro** - Code review and quality improvements
 

data/exe/try

@@ -42,15 +42,18 @@ Tryouts.update_load_path(lib_glob) if Tryouts.respond_to?(:update_load_path)
 begin
   files, options = Tryouts::CLI.parse_args(ARGV)
 
-  # Expand files if directories are given
+  # Expand files if directories are given, preserving line specs
   expanded_files = []
   files.each do |file_or_dir|
-    if File.directory?(file_or_dir)
+    # Parse line spec from the argument
+    path_part, line_spec = Tryouts::CLI::LineSpecParser.parse(file_or_dir)
+
+    if File.directory?(path_part)
       # If it's a directory, find all *_try.rb and *.try.rb files within it
-      dir_files = Dir.glob(['**/*_try.rb', '**/*.try.rb'], base: file_or_dir)
-      expanded_files.concat(dir_files.map { |f| File.join(file_or_dir, f) })
+      dir_files = Dir.glob(['**/*_try.rb', '**/*.try.rb'], base: path_part)
+      expanded_files.concat(dir_files.map { |f| File.join(path_part, f) })
     else
-      # If it's a file, add it as-is
+      # If it's a file, add it as-is (with line spec if present)
       expanded_files << file_or_dir
     end
   end

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

@@ -22,6 +22,9 @@ class Tryouts
         @current_file_data = nil
         @total_stats = { files: 0, tests: 0, failures: 0, errors: 0, elapsed: 0 }
         @output_rendered = false
+        @options = options  # Store all options for execution context display
+        @all_warnings = []  # Store warnings globally for execution details
+        @syntax_errors = []  # Store syntax errors for execution details
 
         # No colors in agent mode for cleaner parsing
         @use_colors = false
@@ -42,7 +45,8 @@ class Tryouts
           tests: 0,
           failures: [],
           errors: [],
-          passed: 0
+          passed: 0,
+          context_info: context_info  # Store context info for later display
         }
       end
 
@@ -56,19 +60,47 @@ class Tryouts
       end
 
       def file_parsed(_file_path, test_count:, setup_present: false, teardown_present: false)
-        @current_file_data[:tests] = test_count if @current_file_data
+        if @current_file_data
+          @current_file_data[:tests] = test_count
+        end
         @total_stats[:tests] += test_count
       end
 
-      def file_result(_file_path, total_tests:, failed_count:, error_count:, elapsed_time: nil)
+      def parser_warnings(file_path, warnings:)
+        return if warnings.empty? || !@options.fetch(:warnings, true)
+
+        # Store warnings globally for execution details and per-file
+        warnings.each do |warning|
+          warning_data = {
+            type: warning.type.to_s,
+            message: warning.message,
+            line: warning.line_number,
+            suggestion: warning.suggestion,
+            file: relative_path(file_path)
+          }
+          @all_warnings << warning_data
+        end
+
+        # Also store in current file data for potential future use
+        if @current_file_data
+          @current_file_data[:warnings] = @all_warnings.select { |w| w[:file] == relative_path(file_path) }
+        end
+      end
+
+      def file_result(file_path, total_tests:, failed_count:, error_count:, elapsed_time: nil)
         # Always update global totals
         @total_stats[:failures] += failed_count
         @total_stats[:errors] += error_count
         @total_stats[:elapsed] += elapsed_time if elapsed_time
 
-        # Update per-file data when available
-        if @current_file_data
-          @current_file_data[:passed] = total_tests - failed_count - error_count
+        # Update per-file data - file_result is called AFTER file_end, so data is in @collected_files
+        relative_file_path = relative_path(file_path)
+        file_data = @collected_files.find { |f| f[:path] == relative_file_path }
+
+        if file_data
+          file_data[:passed] = total_tests - failed_count - error_count
+          # Also ensure tests count is correct if it wasn't set properly earlier
+          file_data[:tests] ||= total_tests
         end
       end
 
@@ -135,6 +167,14 @@ class Tryouts
         @output_rendered = true
       end
 
+      def error_message(message, backtrace: nil)
+        # Store syntax errors for display in execution details
+        @syntax_errors << {
+          message: message,
+          backtrace: backtrace
+        }
+      end
+
       # Override live status - not needed for agent mode
       def live_status_capabilities
         {
@@ -209,50 +249,71 @@ class Tryouts
       def render_summary_only
         output = []
 
+        # Add execution context header for agent clarity
+        output << render_execution_context
+        output << ""
+
         # Count failures manually from collected file data (same as other render methods)
         failed_count = @collected_files.sum { |f| f[:failures].size }
         error_count = @collected_files.sum { |f| f[:errors].size }
         issues_count = failed_count + error_count
         passed_count = [@total_stats[:tests] - issues_count, 0].max
 
+        status_parts = []
         if issues_count > 0
-          status = "FAIL: #{issues_count}/#{@total_stats[:tests]} tests"
           details = []
           details << "#{failed_count} failed" if failed_count > 0
           details << "#{error_count} errors" if error_count > 0
-          status += " (#{details.join(', ')}, #{passed_count} passed)"
+          status_parts << "FAIL: #{issues_count}/#{@total_stats[:tests]} tests (#{details.join(', ')}, #{passed_count} passed)"
         else
-          status = "PASS: #{@total_stats[:tests]} tests passed"
+          # Agent doesn't need output in the positive case (i.e. for passing
+          # tests). It just fills out the context window.
         end
 
-        status += " (#{format_time(@total_stats[:elapsed])})" if @total_stats[:elapsed]
+        status_parts << "(#{format_time(@total_stats[:elapsed])})" if @total_stats[:elapsed]
 
-        output << status
+        output << status_parts.join(" ")
+
+        # Always show file information for agent context
+        output << ""
 
-        # Show which files had failures
         files_with_issues = @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
         if files_with_issues.any?
-          output << ""
-          output << "Files with issues:"
+          output << "Files:"
           files_with_issues.each do |file_data|
             issue_count = file_data[:failures].size + file_data[:errors].size
             output << "  #{file_data[:path]}: #{issue_count} issue#{'s' if issue_count != 1}"
           end
+        elsif @collected_files.any?
+          # Show files that were processed successfully
+          output << "Files:"
+          @collected_files.each do |file_data|
+            # Use the passed count from file_result if available, otherwise calculate
+            passed_tests = file_data[:passed] ||
+                          ((file_data[:tests] || 0) - file_data[:failures].size - file_data[:errors].size)
+            output << "  #{file_data[:path]}: #{passed_tests} test#{'s' if passed_tests != 1} passed"
+          end
         end
 
-        puts output.join("\n")
+        puts output.join("\n") if output.any?
       end
 
       def render_critical_only
         # Only show errors (exceptions), skip assertion failures
         critical_files = @collected_files.select { |f| f[:errors].any? }
 
+        output = []
+
+        # Add execution context header for agent clarity
+        output << render_execution_context
+        output << ""
+
         if critical_files.empty?
-          puts "No critical errors found"
+          output << "No critical errors found"
+          puts output.join("\n")
           return
         end
 
-        output = []
         output << "CRITICAL: #{critical_files.size} file#{'s' if critical_files.size != 1} with errors"
         output << ""
 
@@ -283,39 +344,21 @@ class Tryouts
       def render_full_structured
         output = []
 
-        # Header with overall stats
-        issues_count = @total_stats[:failures] + @total_stats[:errors]
-        passed_count = [@total_stats[:tests] - issues_count, 0].max
-
-        files_count = if @total_stats[:files].to_i > 0
-          @total_stats[:files]
-        else
-          @total_stats[:total_files] || @collected_files.size
-        end
-
-        if issues_count > 0
-          status_line = "FAIL: #{issues_count}/#{@total_stats[:tests]} tests (#{files_count} files, #{format_time(@total_stats[:elapsed])})"
-        else
-          status_line = "PASS: #{@total_stats[:tests]} tests (#{files_count} files, #{format_time(@total_stats[:elapsed])})"
-        end
-
-        # Always include status line
-        output << status_line
-        @budget.force_consume(status_line)
+        # Add execution context header for agent clarity
+        output << render_execution_context
+        output << ""
 
-        # Only show files with issues (unless focus is different)
-        files_to_show = case @focus_mode
-        when :failures, :first_failure
-          @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
-        else
-          @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
-        end
+        # Count actual failures from collected data
+        failed_count = @collected_files.sum { |f| f[:failures].size }
+        error_count = @collected_files.sum { |f| f[:errors].size }
+        issues_count = failed_count + error_count
+        passed_count = [@total_stats[:tests] - issues_count, 0].max
 
-        if files_to_show.any?
-          output << ""
-          @budget.consume("\n")
+        # Show files with issues only
+        files_with_issues = @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
 
-          files_to_show.each do |file_data|
+        if files_with_issues.any?
+          files_with_issues.each do |file_data|
             break unless @budget.has_budget?
 
             file_section = render_file_section(file_data)
@@ -329,14 +372,15 @@ class Tryouts
               @budget.consume(file_section)
             end
           end
+          output << ""
         end
 
         # Final summary line
-        summary = "Summary: #{passed_count} passed, #{@total_stats[:failures]} failed"
-        summary += ", #{@total_stats[:errors]} errors" if @total_stats[:errors] > 0
+        summary = "Summary: \n"
+        summary += "#{passed_count} testcases passed, #{failed_count} failed"
+        summary += ", #{error_count} errors" if error_count > 0
         summary += " in #{@total_stats[:files]} files"
 
-        output << ""
         output << summary
 
         puts output.join("\n")
@@ -348,6 +392,20 @@ class Tryouts
         # File header
         lines << "#{file_data[:path]}:"
 
+        # Check if file has any issues
+        has_issues = file_data[:failures].any? || file_data[:errors].any?
+
+        # If no issues, show success summary
+        if !has_issues
+          # Use the passed count from file_result if available, otherwise calculate
+          passed_tests = file_data[:passed] ||
+                        ((file_data[:tests] || 0) - file_data[:failures].size - file_data[:errors].size)
+
+
+          lines << "  ✓ #{passed_tests} test#{'s' if passed_tests != 1} passed"
+          return lines.join("\n")
+        end
+
         # For first-failure mode, only show first error or failure
         if @focus_mode == :first_failure || @focus_mode == :'first-failure'
           shown_count = 0
@@ -445,6 +503,74 @@ class Tryouts
           "#{seconds.round(2)}s"
         end
       end
+
+      def render_execution_context
+        context_lines = []
+        context_lines << "EXECUTION DETAILS:"
+
+        # Framework and context mode
+        framework = @options[:framework] || :direct
+        shared_context = if @options.key?(:shared_context)
+          @options[:shared_context]
+        else
+          # Apply framework defaults
+          case framework
+          when :rspec, :minitest
+            false
+          else
+            true  # direct/tryouts defaults to shared
+          end
+        end
+
+        context_lines << "  Framework: #{framework}"
+        context_lines << "  Context mode: #{shared_context ? 'shared (variables persist across test cases)' : 'fresh (each test case isolated)'}"
+
+        # Parser type
+        parser = @options[:parser] || :enhanced
+        context_lines << "  Parser: #{parser}"
+
+        # Other relevant flags
+        flags = []
+        flags << "verbose" if @options[:verbose]
+        flags << "fails-only" if @options[:fails_only]
+        flags << "debug" if @options[:debug]
+        flags << "stack-traces" if @options[:stack_traces]
+        flags << "parallel(#{@options[:parallel_threads] || 'auto'})" if @options[:parallel]
+        flags << "line-spec" if @options[:line_spec]
+
+        context_lines << "  Flags: #{flags.any? ? flags.join(', ') : 'none'}" if flags.any?
+
+        # Agent-specific settings
+        context_lines << "  Agent mode: focus=#{@focus_mode}, limit=#{@budget.limit} tokens"
+
+        # Add syntax errors if any (these prevent test execution)
+        if @syntax_errors.any?
+          context_lines << ""
+          context_lines << "Syntax Errors:"
+          @syntax_errors.each do |error|
+            # Clean up the error message to remove redundant prefixes
+            clean_message = error[:message].gsub(/^ERROR:\s*/i, '').strip
+            context_lines << "  #{clean_message}"
+            if error[:backtrace] && @options[:debug]
+              error[:backtrace].first(3).each do |trace|
+                context_lines << "    #{trace}"
+              end
+            end
+          end
+        end
+
+        # Add warnings if any
+        if @all_warnings.any? && @options.fetch(:warnings, true)
+          context_lines << ""
+          context_lines << "Parser Warnings:"
+          @all_warnings.each do |warning|
+            context_lines << "  #{warning[:file]}:#{warning[:line]}: #{warning[:message]}"
+            context_lines << "    #{warning[:suggestion]}" if warning[:suggestion]
+          end
+        end
+
+        context_lines.join("\n")
+      end
     end
   end
 end

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

@@ -33,6 +33,10 @@ class Tryouts
         # Default: no output
       end
 
+      def parser_warnings(file_path, warnings:)
+        # Default: no output - override in specific formatters
+      end
+
       def file_execution_start(file_path, test_count:, context_mode:)
         # Default: no output
       end
@@ -151,7 +155,7 @@ class Tryouts
       end
 
       def separator(style = :light)
-        width = @options.fetch(:line_width, 70)
+        width = @options.fetch(:line_width, 60)
         case style
         when :heavy
           '=' * width

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

@@ -44,9 +44,20 @@ class Tryouts
         @stderr.puts indent_text("Parsed #{test_count} tests#{suffix}", 1)
       end
 
+      def parser_warnings(file_path, warnings:)
+        return if warnings.empty? || !@options.fetch(:warnings, true)
+
+        @stderr.puts
+        @stderr.puts Console.color(:yellow, "Warnings:")
+        warnings.each do |warning|
+          @stderr.puts "  #{Console.pretty_path(file_path)}:#{warning.line_number}: #{warning.message}"
+        end
+      end
+
       def file_execution_start(file_path, test_count:, context_mode:)
         pretty_path = Console.pretty_path(file_path)
-        @stderr.puts "#{pretty_path}: #{test_count} tests"
+        puts
+        puts "#{pretty_path}: #{test_count} tests"
       end
 
       # Summary operations - show failure summary
@@ -204,7 +215,6 @@ class Tryouts
 
       def grand_total(total_tests:, failed_count:, error_count:, successful_files:, total_files:, elapsed_time:)
         @stderr.puts
-        @stderr.puts '=' * 50
 
         issues_count = failed_count + error_count
         if issues_count > 0
@@ -219,8 +229,8 @@ class Tryouts
 
         time_str = format_timing(elapsed_time)
 
-        @stderr.puts "Total: #{result}#{time_str}"
-        @stderr.puts "Files: #{successful_files} of #{total_files} successful"
+        @stderr.puts "#{result}#{time_str}"
+        @stderr.puts "#{successful_files} of #{total_files} files passed"
       end
 
       # Debug and diagnostic output - minimal in compact mode

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

@@ -57,6 +57,10 @@ class Tryouts
         )
       end
 
+      def parser_warnings(file_path, warnings:)
+        @formatter.parser_warnings(file_path, warnings: warnings)
+      end
+
       def file_execution_start(file_path, test_count, context_mode)
         @formatter.file_execution_start(
           file_path,

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

@@ -19,12 +19,7 @@ class Tryouts
       def phase_header(message, file_count: nil)
         return if message.include?('EXECUTING') # Skip execution phase headers
 
-        header_line = message.center(@line_width)
-        separator_line = '=' * @line_width
-
-        puts(separator_line)
-        puts(header_line)
-        puts(separator_line)
+        puts("=== #{message} ===")
       end
 
       # File-level operations
@@ -40,12 +35,25 @@ class Tryouts
         extras << 'teardown' if teardown_present
         message += " (#{extras.join(', ')})" unless extras.empty?
 
-        puts(indent_text(message, 2))
+        puts(indent_text(message, 1))
+      end
+
+      def parser_warnings(file_path, warnings:)
+        return if warnings.empty? || !@options.fetch(:warnings, true)
+
+        puts
+        puts Console.color(:yellow, "Parser Warnings:")
+        warnings.each do |warning|
+          puts "  #{Console.color(:yellow, 'WARNING')}: #{warning.message} (line #{warning.line_number})"
+          puts "    #{Console.color(:dim, warning.context)}" unless warning.context.empty?
+          puts "    #{Console.color(:blue, warning.suggestion)}"
+        end
+        puts
       end
 
       def file_execution_start(_file_path, test_count:, context_mode:)
         message = "Running #{test_count} tests with #{context_mode} context"
-        puts(indent_text(message, 1))
+        puts(indent_text(message, 0))
       end
 
       # Summary operations - show detailed failure summary
@@ -53,9 +61,7 @@ class Tryouts
         return unless failure_collector.any_failures?
 
         puts
-        write '=' * 50
-        puts
-        puts Console.color(:red, 'Failed Tests:')
+        write '=== FAILURES ==='
 
         # Number failures sequentially across all files instead of per-file
         failure_number = 1
@@ -73,16 +79,14 @@ class Tryouts
             puts
             puts Console.color(:yellow, location)
             puts "  #{failure_number}) #{failure.description}"
-            puts "     #{Console.color(:red, 'Failure:')} #{failure.failure_reason}"
+            puts "     #{Console.color(:red, failure.failure_reason)}"
 
-            # Show source context in verbose mode
+            # Show source context in compact format
             if failure.source_context.any?
-              puts "     #{Console.color(:cyan, 'Source:')}"
               failure.source_context.each do |line|
                 puts "       #{line.strip}"
               end
             end
-            puts
             failure_number += 1
           end
         end
@@ -102,25 +106,27 @@ class Tryouts
 
           time_str = elapsed_time ? " (#{elapsed_time.round(2)}s)" : ''
           message = "✗ Out of #{total_tests} tests: #{details_str}#{time_str}"
-          puts indent_text(Console.color(color, message), 2)
+          puts indent_text(Console.color(color, message), 1)
         else
           message = "#{total_tests} tests passed"
           color = :green
-          puts indent_text(Console.color(color, "✓ #{message}"), 2)
+          puts indent_text(Console.color(color, "✓ #{message}"), 1)
         end
 
         return unless elapsed_time
 
         time_msg = "Completed in #{format_timing(elapsed_time).strip.tr('()', '')}"
-        puts indent_text(Console.color(:dim, time_msg), 2)
+        puts indent_text(Console.color(:dim, time_msg), 1)
       end
 
       # Test-level operations
       def test_start(test_case:, index:, total:)
+        return unless @show_passed
+
         desc = test_case.description.to_s
         desc = 'Unnamed test' if desc.empty?
         message = "Test #{index}/#{total}: #{desc}"
-        puts indent_text(Console.color(:dim, message), 2)
+        puts indent_text(Console.color(:dim, message), 1)
       end
 
       def test_result(result_packet)
@@ -143,7 +149,7 @@ class Tryouts
         test_case = result_packet.test_case
         location = "#{Console.pretty_path(test_case.path)}:#{test_case.first_expectation_line + 1}"
         puts
-        puts indent_text("#{status_line} @ #{location}", 2)
+        puts indent_text("#{status_line} @ #{location}", 1)
 
         # Show source code for verbose mode
         show_test_source_code(test_case)
@@ -160,21 +166,22 @@ class Tryouts
       def test_output(test_case:, output_text:, result_packet:)
         return if output_text.nil? || output_text.strip.empty?
 
-        puts indent_text('Test Output:', 3)
-        puts indent_text(Console.color(:dim, '--- BEGIN OUTPUT ---'), 3)
+        puts indent_text('Test Output:', 2)
+        puts indent_text(Console.color(:dim, '--- BEGIN OUTPUT ---'), 2)
 
         output_text.lines.each do |line|
-          puts indent_text(line.chomp, 4)
+          puts indent_text(line.chomp, 3)
         end
 
-        puts indent_text(Console.color(:dim, '--- END OUTPUT ---'), 3)
+        puts indent_text(Console.color(:dim, '--- END OUTPUT ---'), 2)
         puts
       end
 
       # Setup/teardown operations
       def setup_start(line_range:)
         message = "Executing global setup (lines #{line_range.first}..#{line_range.last})"
-        puts indent_text(Console.color(:cyan, message), 2)
+        puts indent_text(Console.color(:cyan, message), 1)
+        puts
       end
 
       def setup_output(output_text)
@@ -187,8 +194,7 @@ class Tryouts
 
       def teardown_start(line_range:)
         message = "Executing teardown (lines #{line_range.first}..#{line_range.last})"
-        puts indent_text(Console.color(:cyan, message), 2)
-        puts
+        puts indent_text(Console.color(:cyan, message), 1)
       end
 
       def teardown_output(output_text)
@@ -201,8 +207,7 @@ class Tryouts
 
       def grand_total(total_tests:, failed_count:, error_count:, successful_files:, total_files:, elapsed_time:)
         puts
-        puts '=' * @line_width
-        puts 'Grand Total:'
+        puts '=== TOTAL ==='
 
         issues_count = failed_count + error_count
         time_str = if elapsed_time < 2.0
@@ -216,13 +221,12 @@ class Tryouts
           details = []
           details << "#{failed_count} failed" if failed_count > 0
           details << "#{error_count} errors" if error_count > 0
-          puts "#{details.join(', ')}, #{passed} passed#{time_str}"
+          printf("%-10s %s\n", "Testcases:", "#{details.join(', ')}, #{passed} passed#{time_str}")
         else
-          puts "#{total_tests} tests passed#{time_str}"
+          printf("%-10s %s\n", "Testcases:", "#{total_tests} tests passed#{time_str}")
         end
 
-        puts "Files: #{successful_files} of #{total_files} successful"
-        puts '=' * @line_width
+        printf("%-10s %s\n", "Files:", "#{successful_files} of #{total_files} passed")
       end
 
       # Debug and diagnostic output
@@ -243,16 +247,16 @@ class Tryouts
 
       def error_message(message, backtrace: nil)
         error_msg = Console.color(:red, "ERROR: #{message}")
-        puts indent_text(error_msg, 1)
+        puts indent_text(error_msg, 0)
 
         return unless backtrace && @show_stack_traces
 
-        puts indent_text('Details:', 2)
+        puts indent_text('Details:', 1)
         # Show first 10 lines of backtrace to avoid overwhelming output
         Console.pretty_backtrace(backtrace, limit: 10).each do |line|
-          puts indent_text(line, 3)
+          puts indent_text(line, 2)
         end
-        puts indent_text("... (#{backtrace.length - 10} more lines)", 3) if backtrace.length > 10
+        puts indent_text("... (#{backtrace.length - 10} more lines)", 2) if backtrace.length > 10
       end
 
       def live_status_capabilities
@@ -272,16 +276,16 @@ class Tryouts
       def show_exception_details(test_case, actual_results, expected_results = [])
         return if actual_results.empty?
 
-        puts indent_text('Exception Details:', 4)
+        puts indent_text('Exception Details:', 2)
 
         actual_results.each_with_index do |actual, idx|
           expected = expected_results[idx] if expected_results && idx < expected_results.length
           expectation = test_case.expectations[idx] if test_case.expectations
 
           if expectation&.type == :exception
-            puts indent_text("Caught: #{Console.color(:blue, actual.inspect)}", 5)
-            puts indent_text("Expectation: #{Console.color(:green, expectation.content)}", 5)
-            puts indent_text("Result: #{Console.color(:green, expected.inspect)}", 5) if expected
+            puts indent_text("Caught: #{Console.color(:blue, actual.inspect)}", 3)
+            puts indent_text("Expectation: #{Console.color(:green, expectation.content)}", 3)
+            puts indent_text("Result: #{Console.color(:green, expected.inspect)}", 3) if expected
           end
         end
         puts
@@ -300,7 +304,7 @@ class Tryouts
             line_display = Console.color(:yellow, line_display)
           end
 
-          puts indent_text(line_display, 4)
+          puts indent_text(line_display, 2)
         end
         puts
       end
@@ -314,15 +318,15 @@ class Tryouts
 
           if !expected.nil?
             # Use the evaluated expected value from the evaluator
-            puts indent_text("Expected: #{Console.color(:green, expected.inspect)}", 4)
-            puts indent_text("Actual:   #{Console.color(:red, actual.inspect)}", 4)
+            puts indent_text("Expected: #{Console.color(:green, expected.inspect)}", 2)
+            puts indent_text("Actual:   #{Console.color(:red, actual.inspect)}", 2)
           elsif expected_line && !expected_results.empty?
             # Only show raw expectation content if we have expected_results (non-error case)
-            puts indent_text("Expected: #{Console.color(:green, expected_line.content)}", 4)
-            puts indent_text("Actual:   #{Console.color(:red, actual.inspect)}", 4)
+            puts indent_text("Expected: #{Console.color(:green, expected_line.content)}", 2)
+            puts indent_text("Actual:   #{Console.color(:red, actual.inspect)}", 2)
           else
             # For error cases (empty expected_results), just show the error
-            puts indent_text("Error:   #{Console.color(:red, actual.inspect)}", 4)
+            puts indent_text("Error:   #{Console.color(:red, actual.inspect)}", 2)
           end
 
           # Show difference if both are strings
@@ -337,21 +341,16 @@ class Tryouts
       def show_string_diff(expected, actual)
         return if expected == actual
 
-        puts indent_text('Difference:', 4)
-        puts indent_text("- #{Console.color(:red, actual)}", 5)
-        puts indent_text("+ #{Console.color(:green, expected)}", 5)
+        puts indent_text('Difference:', 2)
+        puts indent_text("- #{Console.color(:red, actual)}", 3)
+        puts indent_text("+ #{Console.color(:green, expected)}", 3)
       end
 
       def file_header_visual(file_path)
         pretty_path = Console.pretty_path(file_path)
-        header_content = ">>>>>  #{pretty_path}  "
-        padding_length = [@line_width - header_content.length, 0].max
-        padding = '<' * padding_length
 
         [
-          indent_text('-' * @line_width, 1),
-          indent_text(header_content + padding, 1),
-          indent_text('-' * @line_width, 1),
+          indent_text("--- #{pretty_path} ---", 0)
         ].join("\n")
       end
     end
@@ -376,6 +375,20 @@ class Tryouts
         super
       end
 
+      # Suppress setup/teardown output in fails-only mode
+      def setup_start(line_range:)
+        # No output in fails mode
+      end
+
+      def teardown_start(line_range:)
+        # No output in fails mode
+      end
+
+      # Suppress file result summaries in fails-only mode
+      def file_result(_file_path, total_tests:, failed_count:, error_count:, elapsed_time: nil)
+        # No output in fails mode - let the batch_summary handle failures
+      end
+
       def live_status_capabilities
         {
           supports_coordination: true,     # Verbose can work with coordinated output

data/lib/tryouts/cli/line_spec_parser.rb

@@ -0,0 +1,109 @@
+# lib/tryouts/cli/line_spec_parser.rb
+
+class Tryouts
+  class CLI
+    class LineSpecParser
+      # Parse a file path with optional line specification
+      # Supports formats:
+      #   - file.rb:19        (single line)
+      #   - file.rb:19-45     (range)
+      #   - file.rb:L19       (GitHub-style single line)
+      #   - file.rb:L19-45    (GitHub-style range)
+      #   - file.rb:L19-L45   (GitHub-style range with L on both)
+      #
+      # Returns [filepath, line_spec] where line_spec is nil or a Range/Integer
+      def self.parse(path_with_spec)
+        return [path_with_spec, nil] unless path_with_spec.include?(':')
+
+        # Split on the last colon to handle paths with colons
+        parts = path_with_spec.rpartition(':')
+        filepath = parts[0]
+        line_spec_str = parts[2]
+
+        # If the filepath is empty, it means there was no colon or the input started with colon
+        return [path_with_spec, nil] if filepath.empty?
+
+        # If the "line spec" part looks like a Windows drive letter, this isn't a line spec
+        return [path_with_spec, nil] if line_spec_str =~ /\A[a-zA-Z]\z/
+
+        # Parse the line specification
+        line_spec = parse_line_spec(line_spec_str)
+
+        # If we couldn't parse it, treat the whole thing as a filepath
+        return [path_with_spec, nil] if line_spec.nil?
+
+        [filepath, line_spec]
+      end
+
+      private
+
+      def self.parse_line_spec(spec)
+        return nil if spec.nil? || spec.empty?
+
+        # Remove 'L' prefix if present (GitHub style)
+        spec = spec.gsub(/L/i, '')
+
+        # Handle range (e.g., "19-80")
+        if spec.include?('-')
+          parts = spec.split('-', 2)
+
+          # Validate that both parts are numeric
+          return nil unless parts[0] =~ /\A\d+\z/ && parts[1] =~ /\A\d+\z/
+
+          start_line = parts[0].to_i
+          end_line = parts[1].to_i
+
+          # Validate the numbers
+          return nil if start_line <= 0 || end_line <= 0
+          return nil if start_line > end_line
+
+          start_line..end_line
+        else
+          # Single line number - validate it's numeric
+          return nil unless spec =~ /\A\d+\z/
+
+          line = spec.to_i
+          return nil if line <= 0
+
+          line
+        end
+      end
+
+      # Check if a test case at the given line range matches the line specification
+      # Test case line ranges are 0-based, user line specs are 1-based
+      def self.matches?(test_case, line_spec)
+        return true if line_spec.nil?
+
+        # Convert user's 1-based line spec to 0-based for comparison
+        zero_based_spec = case line_spec
+        when Integer
+          line_spec - 1
+        when Range
+          (line_spec.begin - 1)..(line_spec.end - 1)
+        else
+          line_spec
+        end
+
+        # Test case line_range is already 0-based
+        test_range = test_case.line_range
+
+        case zero_based_spec
+        when Integer
+          # Single line - check if it falls within the test's range
+          test_range.cover?(zero_based_spec)
+        when Range
+          # Range - check if there's any overlap
+          spec_start = zero_based_spec.begin
+          spec_end = zero_based_spec.end
+          test_start = test_range.begin
+          test_end = test_range.end
+
+          # Check for overlap: ranges overlap if start of one is before end of other
+          !(test_end < spec_start || spec_end < test_start)
+        else
+          true
+        end
+      end
+    end
+  end
+end

data/lib/tryouts/cli/opts.rb

@@ -123,6 +123,12 @@ 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

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,7 +38,10 @@ class Tryouts
 
       result = process_files
       show_failure_summary
-      show_grand_total if @global_tally[:aggregator].get_file_counts[:total] > 1
+      # 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')
@@ -148,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,
@@ -160,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.4.0'
+  VERSION = '3.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tryouts
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -148,6 +148,7 @@ files:
 - 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
@@ -169,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