### Running Tryouts Tests

Source: https://github.com/delano/tryouts/blob/main/docs/agent_guide.md

Provides examples of how to execute Tryouts tests from the command line, including auto-discovery and running specific files or directories, with options for verbose output and debug mode.

```bash
# Auto-discover and run
try -vfD # verbose for failing tests, and enable debug mode (stack traces)

# Specific file
try -vfD path/to/file_try.rb path/to/dir
```

--------------------------------

### Tryouts File Structure Example

Source: https://github.com/delano/tryouts/blob/main/docs/agent_guide.md

Demonstrates the basic 3-section structure of a Tryouts file: setup, test cases with descriptions and expectations, and teardown. Instance variables are shown to persist across sections.

```ruby
# SETUP SECTION (optional)
# Code runs once before all tests
puts 'Setup code'
@shared_variable = 'available to all tests'

## TEST CASE 1: Basic calculation
# Description lines start with ##
a = 1 + 1
#=> 2

## TEST CASE 2: String manipulation
'hello'.upcase
#=> 'HELLO'

# TEARDOWN SECTION (optional)
# Code runs once after all tests
puts 'Cleanup complete'
```

--------------------------------

### Tryouts Common Patterns: Helpers and Instance Variables

Source: https://github.com/delano/tryouts/blob/main/docs/agent_guide.md

Demonstrates common patterns in Tryouts, including defining and using helper methods in the setup section and managing instance variables across test cases.

```ruby
# Setup helpers
def helper_method
  'I help with testing'
end

## TEST: Using helpers
helper_method
#=> 'I help with testing'

## TEST: Instance variables
@counter = (@counter || 0) + 1
@counter
#=> 1

## TEST: Complex objects
user = { name: 'Alice', age: 30 }
user[:name]
#=> 'Alice'
```

--------------------------------

### Tryouts Exception Handling Example

Source: https://github.com/delano/tryouts/blob/main/docs/agent_guide.md

Shows how to test for exceptions in Tryouts using the `#=!>` expectation. It includes a direct division by zero example and a case demonstrating rescue.

```ruby
## TEST: Exception handling
1 / 0
#=!> error.is_a?(ZeroDivisionError)

## TEST: Exception with rescue
begin
  raise "custom error"
rescue => e
  e.message
end
#=> "custom error"
```

--------------------------------

### Install Tryouts Gem

Source: https://github.com/delano/tryouts/blob/main/README.md

Instructions for installing the Tryouts testing framework using RubyGems. This can be done by adding it to your Gemfile or installing it directly via the command line.

```ruby
gem 'tryouts'
```

```bash
$ gem install tryouts
```

--------------------------------

### Install Tryouts Dependencies

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Installs all the necessary dependencies required for the Tryouts project using Bundler. This command should be run before any other development commands to ensure the environment is set up correctly.

```Bash
bundle install
```

--------------------------------

### Tryouts Summary Focus Output

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Example output for Tryouts in summary focus mode, displaying a concise status line indicating the number of passed tests and timing.

```text
PASS: 21 tests passed (0μs)
```

--------------------------------

### Tryouts Token-Limited Output Example

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Example output for Tryouts with a token limit applied. For passing tests, the output remains the same as standard mode, as no truncation is needed.

```text
PASS: 21 tests (1 files, 0μs)

Summary: 21 passed, 0 failed in 1 files
```

--------------------------------

### Tryouts First-Failure Output

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Example output for Tryouts in first-failure focus mode, showing the failure status, test counts, and the first failure encountered in a file, with a notice for additional failures.

```text
FAIL: 10/37 tests (1 files, 0μs)

try/formatters/token_budget_try.rb:
  L32: NoMethodError: undefined method 'estimate_tokens' for nil
  ... (9 more failures not shown)

Summary: 27 passed, 0 failed, 10 errors in 1 files
```

--------------------------------

### Tryouts CLI Verbose Output Sample

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Provides a sample of the verbose output from the Tryouts CLI when processing a Ruby file, including processing status and test results.

```text
======================================================================
                          PROCESSING 1 FILES
======================================================================

  ----------------------------------------------------------------------
  >>>>>  try/formatters/agent_formatter_try.rb  <<<<<<<<<<<<<<<<<<<<<<<<
  ----------------------------------------------------------------------
    Executing global setup (lines 3..5)
    Test 1/21: Test TokenBudget initialization and basic functionality

    PASSED @ try/formatters/agent_formatter_try.rb:10
          7: ## Test TokenBudget initialization and basic functionality
          8: @budget = Tryouts::CLI::TokenBudget.new(100)
          9: @budget.limit
         10: #=> 100

    Test 2/21: Unnamed test

    PASSED @ try/formatters/agent_formatter_try.rb:13
         12: @budget.used
         13: #=> 0
```

--------------------------------

### Tryouts CLI Verbose Mode Execution

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Demonstrates executing a Ruby file in verbose mode using the Tryouts CLI, showing the initial processing lines and a sample test output.

```shell
try -v try/formatters/agent_formatter_try.rb
```

--------------------------------

### Tryouts Passing Tests Output

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Example output for passing tests in Tryouts agent mode, showing the PASS status, test and file counts, and timing information.

```text
PASS: 21 tests (1 files, 0μs)

Summary: 21 passed, 0 failed in 1 files
```

--------------------------------

### Tryouts Mixed Results Output

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Example output for Tryouts in standard agent mode with mixed results, detailing failures with error messages and line numbers within specific files, followed by a summary.

```text
FAIL: 10/104 tests (6 files, 0μs)

try/formatters/token_budget_try.rb:
  L32: NoMethodError: undefined method 'estimate_tokens' for nil
  L36: NoMethodError: undefined method 'estimate_tokens' for nil
  L40: NoMethodError: undefined method 'estimate_tokens' for nil
  L45: NoMethodError: undefined method 'consume' for nil
  L48: NoMethodError: undefined method 'used' for nil
  L51: NoMethodError: undefined method 'remaining' for nil
  L56: NoMethodError: undefined method 'would_exceed?' for nil
  L60: NoMethodError: undefined method 'would_exceed?' for nil
  L66: NoMethodError: undefined method 'force_consume' for nil
  L70: NoMethodError: undefined method 'used' for nil

Summary: 94 passed, 0 failed, 10 errors in 6 files
```

--------------------------------

### Start Interactive Debugging with Pry

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Launches an interactive Pry session within the Tryouts project environment. This allows developers to inspect variables, step through code, and debug issues interactively.

```Bash
bundle exec pry
```

--------------------------------

### Tryouts Test Case with Multiple Expectations

Source: https://github.com/delano/tryouts/blob/main/docs/agent_guide.md

Illustrates a single Tryouts test case that includes multiple expectation lines. The framework evaluates each expectation sequentially.

```ruby
## TEST: Multiple expectations allowed
result = [1, 2, 3]
#=> [1, 2, 3]
#=> [1] + [2, 3]
```

--------------------------------

### Tryouts Critical Focus Output

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Example output for Tryouts in critical focus mode, displaying a 'CRITICAL:' status and listing all errors within a file, without including assertion failures or a summary line.

```text
CRITICAL: 1 file with errors

try/formatters/token_budget_try.rb:
  L32: NoMethodError: undefined method 'estimate_tokens' for nil
  L36: NoMethodError: undefined method 'estimate_tokens' for nil
  L40: NoMethodError: undefined method 'estimate_tokens' for nil
  L45: NoMethodError: undefined method 'consume' for nil
  L48: NoMethodError: undefined method 'used' for nil
  L51: NoMethodError: undefined method 'remaining' for nil
  L56: NoMethodError: undefined method 'would_exceed?' for nil
  L60: NoMethodError: undefined method 'would_exceed?' for nil
  L66: NoMethodError: undefined method 'force_consume' for nil
  L70: NoMethodError: undefined method 'used' for nil
```

--------------------------------

### Tryouts First-Failure Focus Mode

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Demonstrates the first-failure focus mode in Tryouts, which displays only the initial failure for each file. This mode offers a token reduction while retaining key debugging information for rapid triage.

```bash
try --agent --agent-focus first-failure try/formatters/token_budget_try.rb
```

--------------------------------

### Tryouts Passing Tests (Agent Mode)

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Demonstrates the minimal output format for passing tests in Tryouts agent mode. The output includes a status line with test counts and timing, and a summary line confirming the test results.

```bash
try --agent try/formatters/agent_formatter_try.rb
```

--------------------------------

### Tryouts Summary Focus Mode

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Shows the most compact output format in Tryouts, focusing solely on essential status information. This mode achieves significant token reduction, making it ideal for quick status checks.

```bash
try --agent --agent-focus summary try/formatters/agent_formatter_try.rb
```

--------------------------------

### Tryouts Token-Limited Output

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Shows an example of token-limited output in Tryouts agent mode. For passing tests, the output is the same as standard mode, but the token limit would affect failure details if present, preserving essential information first.

```bash
try --agent --agent-limit 1000 try/formatters/agent_formatter_try.rb
```

--------------------------------

### Tryouts CLI Summary Line Format

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Specifies the format for the summary line in the Tryouts CLI output, providing counts of passed, failed, and errored tests across files.

```text
Summary: {passed} passed, {failed} failed[, {errors} errors] in {files} files
```

--------------------------------

### TOPA Format Overview

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Provides a high-level overview of the Test Output Protocol for AI (TOPA) format, detailing its hierarchical structure consisting of a status line, optional file sections, and a summary line.

```text
STATUS_LINE
[FILE_SECTIONS]
SUMMARY_LINE
```

--------------------------------

### Tryouts CLI File Section Format

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Illustrates the hierarchical format used for reporting file-specific details, including line numbers, error types, and expected vs. actual values.

```text
file_path:
  L{line}: {error_type}: {error_message}
  L{line}: expected {expected}, got {actual}
```

--------------------------------

### Tryouts CLI Status Line Format

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Defines the standard format for status lines in the Tryouts CLI output, indicating test counts, file counts, and timing.

```text
STATUS: count/total tests (file_count files, timing)
```

--------------------------------

### Tryouts Critical Focus Mode

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Highlights the critical focus mode in Tryouts, which exclusively displays errors and exceptions, ignoring assertion failures. This mode is indicated by a 'CRITICAL:' header and is useful for focusing on severe issues.

```bash
try --agent --agent-focus critical try/formatters/token_budget_try.rb
```

--------------------------------

### Tryouts Mixed Results (Standard Agent Mode)

Source: https://github.com/delano/tryouts/blob/main/docs/topa-output-examples.md

Illustrates the standard agent mode output for tests with mixed results, including failures and errors. The output is hierarchical, showing status, file sections with specific errors, and a final summary.

```bash
try --agent try/formatters/
```

--------------------------------

### Tryouts Test Writing Syntax

Source: https://github.com/delano/tryouts/blob/main/README.md

Examples of writing Tryouts tests using comment-based expectations. This includes simple value equality, multi-line tests, object method testing, error handling, and various 'Great Expectations' syntaxes for different assertion types.

```ruby
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

puts 'Cleanup complete'
```

--------------------------------

### Hierarchical Output Structure

Source: https://github.com/delano/tryouts/blob/main/docs/topa-algorithms.md

Illustrates the hierarchical organization of test results, starting from a status line, followed by file sections containing failure entries, and ending with a summary line. Includes details on what information is presented at each level.

```text
STATUS_LINE (always force_consume)
├── FILE_SECTION (per file with failures)
│   ├── FILE_PATH: (once per file)
│   ├── FAILURE_ENTRY (per failure, budget permitting)
│   │   ├── Line Number: L{num}
│   │   ├── Error/Expected vs Got
│   │   ├── Test Description (if not 'unnamed test')
│   │   └── Diff (if budget remaining > 50 tokens)
│   └── TRUNCATION_NOTICE (if applicable)
└── SUMMARY_LINE (always included)
```

--------------------------------

### Tryouts Key Dependencies

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Lists the key dependencies required for the Tryouts Ruby testing framework, including Ruby version, parser, and testing libraries.

```text
Key Dependencies
- **Ruby** (>= 3.4.4)
- **prism** (~> 1.0): Native Ruby parser
- **rspec**, **minitest**: Framework integration
- **rubocop**: Code quality with performance and thread safety extensions
```

--------------------------------

### Tryouts Core Functionality

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

This snippet demonstrates how to run core functionality tests for the Tryouts framework. It uses a simple command-line interface to specify which test directories to execute.

```bash
# Test specific areas
try try/core/          # Core functionality
try try/expectations/  # All expectation types
try try/formatters/    # Output formatting

# Run with code coverage
COVERAGE=1 try try/
```

--------------------------------

### Run Tryouts with Verbose Output

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Executes Tryouts tests with verbose output enabled, which includes the source code and return values of each test case. This provides detailed insight into test execution.

```Bash
try -v
```

--------------------------------

### Run Tryouts with Minitest Integration

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Executes a specific Tryouts test file while generating Minitest-compatible output. This facilitates integration with Minitest or analysis using Minitest's output structure.

```Bash
~/.rbenv/shims/ruby ./exe/try -v --minitest try/expectations/type_expectations_try.rb
```

--------------------------------

### Tryouts Output Options

Source: https://github.com/delano/tryouts/blob/main/README.md

Various command-line options for controlling Tryouts output. These include verbose mode, quiet mode, showing only failures, debug mode, and agent-optimized output for LLMs with different focus and limit options.

```bash
try -v
try -q
try -f
try -D
try --agent
try --agent --agent-focus summary
try --agent --agent-focus first-failure
try --agent --agent-focus critical
try --agent --agent-limit 1000
```

--------------------------------

### Format and Lint Tryouts Code with RuboCop

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Applies code formatting and linting rules using RuboCop to maintain code quality and consistency within the Tryouts project. The `-A` flag automatically corrects most style violations.

```Bash
bundle exec rubocop
```

```Bash
bundle exec rubocop -A
```

--------------------------------

### Test Framework Using Itself

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Runs the Tryouts framework's own test suite using the `try` command. This is a meta-testing approach to ensure the framework's integrity.

```Bash
try try/
```

--------------------------------

### Run Tryouts Tests

Source: https://github.com/delano/tryouts/blob/main/README.md

Commands to execute Tryouts tests. You can run all auto-discovered tests or specify a particular test file. The framework supports integration with RSpec and Minitest for running tests.

```bash
try
try try/core/basic_syntax_try.rb
try --rspec try/core/basic_syntax_try.rb
try --minitest try/core/basic_syntax_try.rb
```

--------------------------------

### Run Tryouts Tests

Source: https://github.com/delano/tryouts/blob/main/try/README.md

Execute the Tryouts test suite. Supports running all tests, specific directories or files, and various output modes like verbose or quiet.

```bash
try
try try/core/
try try/core/advanced_syntax_try.rb
try -v
try -vf
try -q
try -q  2> /dev/null
```

--------------------------------

### Test TokenBudget Initialization and Basic Functionality

Source: https://github.com/delano/tryouts/blob/main/docs/topa_reference_outputs/test_output_verbose.txt

Tests the initialization of TokenBudget with a given limit and verifies its basic properties like limit, used, and remaining tokens. It also checks the initial state of the budget.

```Ruby
@budget = Tryouts::CLI::TokenBudget.new(100)
@budget.limit
#=> 100
@budget.used
#=> 0
@budget.remaining > 90  # Account for 5% buffer
#=> true
```

--------------------------------

### Run Tryouts in Debug Mode

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Executes Tryouts tests with debug mode enabled, providing additional logging information, including stack traces, to aid in diagnosing issues.

```Bash
try -D
```

--------------------------------

### Test AgentFormatter Initialization with Options

Source: https://github.com/delano/tryouts/blob/main/docs/topa_reference_outputs/test_output_verbose.txt

Tests the AgentFormatter's initialization with specific options, such as `agent_limit` and `agent_focus`, ensuring it initializes without errors and retains the provided configuration.

```Ruby
opts_formatter = Tryouts::CLI::AgentFormatter.new({
  agent_limit: 2000,
  agent_focus: :summary
})
# Should initialize without errors
opts_formatter.class
#=> Tryouts::CLI::AgentFormatter
```

--------------------------------

### Generate Test Files

Source: https://github.com/delano/tryouts/blob/main/README.md

Commands to generate RSpec and Minitest test files from Tryouts test files. This allows for integration with other testing frameworks by converting Tryouts syntax into their respective formats.

```bash
try --generate-rspec try/core/basic_syntax_try.rb > spec/basic_syntax_spec.rb
try --generate-minitest try/core/basic_syntax_try.rb > test/basic_syntax_test.rb
```

--------------------------------

### Tryouts Expectation Syntax

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

This Ruby code illustrates the various expectation types supported by Tryouts, including basic equality, boolean checks, type checking, regex matching, performance timing, and exception handling. Each expectation is defined using a comment-based syntax.

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

# Basic equality expectation
a = 1 + 1
#=> 2

# Boolean expectations (strict true/false)
[1, 2, 3]
#==> result.length == 3  # Must be exactly true
#=/=> result.empty?      # Must be exactly false
#=|> result.include?(2)  # Must be true OR false (boolean)

# Type checking
"hello"
#=:> String

# Regex matching
"user@example.com"
#=~> /\A[^@]+@[^@]+\.[^@]+\z/

# Performance timing (10% tolerance)
sleep(0.01)
#=%> 15  # Allow up to 15ms

# Exception handling
lambda { raise "error" }
#=!> RuntimeError

## Multi-line test with description
## TEST: Addition works correctly
a = 1
b = 2
a + b
#=> 3
#=> result  # Variable access

# Teardown runs after all tests
puts 'Cleanup complete'
```

--------------------------------

### Test AgentFormatter Initialization

Source: https://github.com/delano/tryouts/blob/main/docs/topa_reference_outputs/test_output_verbose.txt

Verifies the successful initialization of the AgentFormatter class and checks its class name to confirm it's correctly instantiated.

```Ruby
@formatter = Tryouts::CLI::AgentFormatter.new
@formatter.class.name
#=> "Tryouts::CLI::AgentFormatter"
```

--------------------------------

### Generate Minitest Output for Tryouts Test

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Generates Minitest-compatible output for a Tryouts test file without execution. This aids in creating Minitest-formatted test definitions or analyzing the structure.

```Bash
~/.rbenv/shims/ruby ./exe/try -v --generate-minitest try/expectations/performance_timing_try.rb
```

--------------------------------

### Run Specific Tryouts Test Categories

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Runs Tryouts tests categorized under specific directories like 'core' or 'expectations'. This allows for focused testing of particular functionalities or components of the framework.

```Bash
~/.rbenv/shims/ruby ./exe/try -v try/core/
```

```Bash
~/.rbenv/shims/ruby ./exe/try -v try/expectations/
```

```Bash
~/.rbenv/shims/ruby ./exe/try -v try/formatters/
```

--------------------------------

### Run Tryouts with RSpec Integration

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Executes a specific Tryouts test file while generating RSpec-compatible output. This allows for integration with RSpec test runners or for analyzing results in an RSpec format.

```Bash
~/.rbenv/shims/ruby ./exe/try -v --rspec try/core/basic_syntax_try.rb
```

--------------------------------

### Tryouts Test File Organization

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

This outlines the directory structure for organizing Tryouts test files. It specifies the purpose of each directory and the pattern used for auto-discovering test files.

```text
Test files are organized into logical directories:

- **`try/core/`** - Core framework functionality (9 files)
- **`try/expectations/`** - All expectation types (7 files)
- **`try/formatters/`** - Output formatting (2 files)
- **`try/translators/`** - Framework translation (future)

Auto-discovers test files matching: `./{try,tryouts,.}/*_try.rb`
Files are processed in lexical order.
```

--------------------------------

### Run Tryouts Showing Failures Only

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Executes Tryouts tests and displays only the failing test cases. This is a focused approach to quickly identify and address test failures.

```Bash
try -f
```

--------------------------------

### Run Specific Tryouts Test File

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Executes a single, specific Tryouts test file. This is helpful for isolating and testing a particular test case or a small set of related tests.

```Bash
~/.rbenv/shims/ruby ./exe/try -v try/core/basic_syntax_try.rb
```

```Bash
~/.rbenv/shims/ruby ./exe/try -v try/expectations/boolean_expectations_try.rb
```

--------------------------------

### AgentFormatter Initialization

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Initializes the AgentFormatter, setting up the TokenBudget, focus mode, and tracking variables. It also disables colors for cleaner output parsing.

```Ruby
def initialize(options = {})
  @budget = TokenBudget.new(options[:agent_limit] || TokenBudget::DEFAULT_LIMIT)
  @focus_mode = options[:agent_focus] || :failures
  @collected_files = []
  @current_file_data = nil
  @total_stats = { files: 0, tests: 0, failures: 0, errors: 0, elapsed: 0 }
  @output_rendered = false

  # No colors in agent mode for cleaner parsing
  @use_colors = false
end
```

--------------------------------

### Test Budget Allocation Strategy

Source: https://github.com/delano/tryouts/blob/main/docs/topa_reference_outputs/test_output_verbose.txt

Examines the `allocate_budget` method to ensure it correctly distributes the budget, summing up the allocated portions to match the total budget limit.

```Ruby
allocation = @budget_large.allocate_budget
allocation[:summary] + allocation[:failures] + allocation[:context] + allocation[:buffer]
#=> 1000
```

--------------------------------

### Integrate Tryouts with RSpec/Minitest

Source: https://github.com/delano/tryouts/blob/main/try/README.md

Run Tryouts tests using RSpec or Minitest frameworks, or generate test files for these frameworks. This allows integration with existing CI workflows or for using familiar testing tools.

```bash
try --rspec
try --minitest
try --generate-rspec try/core/basic_syntax_try.rb > spec/basic_syntax_spec.rb
try --generate-minitest try/core/basic_syntax_try.rb > test/basic_syntax_test.rb
```

--------------------------------

### Track Token Usage Against Budget

Source: https://github.com/delano/tryouts/blob/main/docs/topa-algorithms.md

Provides functions to track token usage against a defined budget. `would_exceed?` checks if adding new text would exceed the limit considering a buffer, while `consume` adds tokens if within limits. `force_consume` bypasses limits for critical information.

```ruby
def would_exceed?(text)
  token_count = estimate_tokens(text)
  (@used + token_count) > (@limit - @buffer_size)
end

def consume(text)
  return false if would_exceed?(text)
  @used += estimate_tokens(text)
  true
end

def force_consume(text)
  @used += estimate_tokens(text)
  true
end
```

--------------------------------

### Tryouts Framework Translation Modes

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

This section describes the framework translation capabilities of Tryouts, allowing tests to be executed in RSpec Mode, Minitest Mode, or Direct Mode. This enables better IDE support, debugging, and CI/CD integration.

```text
The core philosophy is using Tryouts as a preprocessor/transpiler:

- **RSpec Mode**: Generates `describe/it` blocks, leverages RSpec's full ecosystem
- **Minitest Mode**: Creates test classes with `test_*` methods
- **Direct Mode**: Original tryouts execution with shared context

This approach provides IDE support, debugging capabilities, and CI/CD integration through mature test frameworks.
```

--------------------------------

### Data Structures in Go

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Notes for Go implementation regarding data structures, recommending the creation of structs for data organization.

```Go
// Create structs for data structures
```

--------------------------------

### Run Tryouts Tests (Verbose, Failures Only)

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Executes all Tryouts tests with verbose output, specifically showing only the failing tests. This command is useful for quickly identifying and debugging issues within the test suite.

```Bash
~/.rbenv/shims/ruby ./exe/try -vf
```

--------------------------------

### Allocate Token Budget

Source: https://github.com/delano/tryouts/blob/main/docs/topa-algorithms.md

Defines a strategy for allocating a token budget across different categories: summary, failures, context, and a buffer. Failures receive the largest allocation (60%) due to their critical nature, followed by summary (20%), context (15%), and a buffer (5%) to prevent overflow.

```ruby
DEFAULT_LIMIT = 5000        # Default token budget
BUFFER_PERCENT = 0.05       # 5% buffer to prevent overflow
```

```ruby
def allocate_budget
  {
    summary: (@limit * 0.20).to_i,      # 20% for file summaries
    failures: (@limit * 0.60).to_i,     # 60% for failure details
    context: (@limit * 0.15).to_i,      # 15% for additional context
    buffer: (@limit * 0.05).to_i        # 5% buffer
  }
end
```

--------------------------------

### Run Tryouts with Quiet Output

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Executes Tryouts tests with quiet output, suppressing most informational messages and only showing essential results or errors.

```Bash
try -q
```

--------------------------------

### TokenBudget Budget Allocation Strategy

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Defines a distribution strategy for budget allocation, specifying percentages for summaries, failure details, context, and a buffer.

```Ruby
# Distribution strategy for budget allocation
def allocate_budget
  {
    summary: (@limit * 0.20).to_i,      # 20% for file summaries
    failures: (@limit * 0.60).to_i,     # 60% for failure details
    context: (@limit * 0.15).to_i,      # 15% for additional context
    buffer: (@limit * 0.05).to_i        # 5% buffer
  }
end
```

--------------------------------

### Token Estimation in Go

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Notes for Go implementation regarding token estimation, suggesting `len(text) / 4` with proper rounding.

```Go
// Use `len(text) / 4` with proper rounding
```

--------------------------------

### Determine Output Content Based on Focus Mode

Source: https://github.com/delano/tryouts/blob/main/docs/topa-algorithms.md

A case statement that determines the output content based on the provided focus mode. It maps different focus modes (e.g., :summary, :critical, :first_failure) to specific rendering functions or disclosure levels.

```ruby
def determine_output_content(focus_mode)
  case focus_mode
  when :summary
    render_summary_only()
  when :critical
    render_critical_only()  # Errors only, skip assertions
  when :first_failure, :'first-failure'
    render_with_disclosure_level(:targeted)
  when :failures
    render_with_disclosure_level(:comprehensive)
  else
    render_with_disclosure_level(:comprehensive)
  end
end
```

--------------------------------

### Execute Ruby Interpreter

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Specifies the path to the Ruby interpreter, likely managed by rbenv, for executing Ruby scripts or commands within the project context.

```Bash
/Users/d/.rbenv/shims/ruby
```

--------------------------------

### Failure Data Structure in Ruby

Source: https://github.com/delano/tryouts/blob/main/docs/topa-algorithms.md

Defines the data structure for capturing failure details, including line number, test description, expected output, actual output, and an optional diff. It emphasizes smart truncation for managing output length.

```ruby
failure_data = {
  line: (test_case.first_expectation_line || test_case.line_range&.first || 0) + 1,
  test: test_case.description.to_s.empty? ? 'unnamed test' : test_case.description.to_s,
  expected: budget.smart_truncate(result_packet.first_expected, max_tokens: 25),
  got: budget.smart_truncate(result_packet.first_actual, max_tokens: 25),
  diff: optional_diff_if_budget_allows
}
```

--------------------------------

### Format Time with Seconds

Source: https://github.com/delano/tryouts/blob/main/docs/topa_reference_outputs/test_output_verbose.txt

This snippet shows how to format a time value of 1.5 seconds into a string representation '1.5s' using the agent formatter.

```Ruby
@formatter.send(:format_time, 1.5)     # 1.5 seconds
#=> "1.5s"
```

--------------------------------

### Set Ruby Version Locally

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Sets the local Ruby version for the project to 3.4.4 using rbenv. This ensures that the project is developed and tested against the intended Ruby version.

```Bash
rbenv local 3.4.4
```

--------------------------------

### Define Progressive Disclosure Levels

Source: https://github.com/delano/tryouts/blob/main/docs/topa-algorithms.md

Defines different levels of detail for progressive disclosure, specifying which elements to include (e.g., status line, summary, failures) and the maximum number of failures per file.

```ruby
DISCLOSURE_LEVELS = {
  minimal: {
    include: [:status_line, :summary_line],
    max_failures_per_file: 0
  },
  targeted: {
    include: [:status_line, :first_failure_per_file, :summary_line],
    max_failures_per_file: 1
  },
  comprehensive: {
    include: [:status_line, :all_failures, :summary_line],
    max_failures_per_file: Float::INFINITY
  },
  debug: {
    include: [:status_line, :all_failures, :source_context, :summary_line],
    max_failures_per_file: Float::INFINITY
  }
}
```

--------------------------------

### Ruby NoMethodError in Token Budget Formatter

Source: https://github.com/delano/tryouts/blob/main/docs/topa_reference_outputs/test_output_critical.txt

This snippet highlights a series of NoMethodError exceptions occurring in the `try/formatters/token_budget_try.rb` file. These errors indicate that methods like `estimate_tokens`, `consume`, `used`, `remaining`, and `would_exceed?` are being called on nil objects, suggesting issues with object initialization or state management within the token budget formatting logic.

```Ruby
L32: NoMethodError: undefined method 'estimate_tokens' for nil
  L36: NoMethodError: undefined method 'estimate_tokens' for nil
  L40: NoMethodError: undefined method 'estimate_tokens' for nil
  L45: NoMethodError: undefined method 'consume' for nil
  L48: NoMethodError: undefined method 'used' for nil
  L51: NoMethodError: undefined method 'remaining' for nil
  L56: NoMethodError: undefined method 'would_exceed?' for nil
  L60: NoMethodError: undefined method 'would_exceed?' for nil
  L66: NoMethodError: undefined method 'force_consume' for nil
  L70: NoMethodError: undefined method 'used' for nil
```

--------------------------------

### Data Structures in Python

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Notes for Python implementation regarding data structures, recommending the use of `dataclasses` for structured data.

```Python
# Use `dataclasses` for structured data
```

--------------------------------

### Format Time with Milliseconds

Source: https://github.com/delano/tryouts/blob/main/docs/topa_reference_outputs/test_output_verbose.txt

This snippet demonstrates formatting a time value of 0.05 seconds (50 milliseconds) into a string representation '50ms' using the agent formatter.

```Ruby
@formatter.send(:format_time, 0.05)    # 50 milliseconds
#=> "50ms"
```

--------------------------------

### Estimate Tokens from Text Length

Source: https://github.com/delano/tryouts/blob/main/docs/topa-algorithms.md

Estimates the number of tokens in a given text based on the formula 1 token ≈ 4 characters. Handles nil or empty strings by returning 0. This estimation is validated to have ~90% accuracy for typical test output text.

```ruby
def estimate_tokens(text)
  return 0 if text.nil? || text.empty?
  (text.length / 4.0).ceil
end
```

--------------------------------

### TokenBudget Class Structure

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Defines the core structure of the TokenBudget class, including default limits, buffer percentages, and initialization of budget tracking attributes.

```Ruby
class TokenBudget
  DEFAULT_LIMIT = 5000
  BUFFER_PERCENT = 0.05  # 5% buffer to avoid going over

  attr_reader :limit, :used, :remaining

  def initialize(limit = DEFAULT_LIMIT)
    @limit = limit
    @used = 0
    @buffer_size = (@limit * BUFFER_PERCENT).to_i
  end
end
```

--------------------------------

### Render Full Structured Output in Ruby

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Renders the complete structured output, including a status line, file sections (respecting budget constraints), and a summary line. It manages budget consumption for output elements.

```Ruby
def render_full_structured
  output = []

  # Status line (always force_consume)
  status_line = "#{status}: #{issues_count}/#{@total_stats[:tests]} tests (#{@total_stats[:files]} files, #{format_time(@total_stats[:elapsed])})"
  output << status_line
  @budget.force_consume(status_line)

  # File sections (budget permitting)
  files_to_show.each do |file_data|
    break unless @budget.has_budget?

    file_section = render_file_section(file_data)
    if @budget.would_exceed?(file_section)
      truncated = @budget.fit_text(file_section, preserve_suffix: "\n  ... (truncated)")
      output << truncated if truncated.length > 20
      break
    else
      output << file_section
      @budget.consume(file_section)
    end
  end

  # Summary line
  summary = "Summary: #{passed_count} passed, #{@total_stats[:failures]} failed"
  summary += ", #{@total_stats[:errors]} errors" if @total_stats[:errors] > 0
  summary += " in #{@total_stats[:files]} files"

  output << ""
  output << summary

  puts output.join("\n")
end
```

--------------------------------

### Generate RSpec Output for Tryouts Test

Source: https://github.com/delano/tryouts/blob/main/CLAUDE.md

Generates RSpec-compatible output for a given Tryouts test file without actually executing the tests. This is useful for pre-generating test structures or analyzing test definitions.

```Bash
~/.rbenv/shims/ruby ./exe/try -v --generate-rspec try/core/basic_syntax_try.rb
```

--------------------------------

### Token Estimation in Java

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Notes for Java implementation regarding token estimation, suggesting `text.length() / 4` with `Math.ceil()` for calculation.

```Java
// Use `text.length() / 4` with `Math.ceil()`
```

--------------------------------

### Test Budget Consumption and Remaining Tokens

Source: https://github.com/delano/tryouts/blob/main/docs/topa_reference_outputs/test_output_verbose.txt

Checks the functionality of consuming tokens from the budget and verifies that the used and remaining token counts are updated correctly. It ensures the budget does not exceed its limit.

```Ruby
@budget.consume("test")
#=> true
@budget.used
#=> 1
@budget.remaining < 95
#=> true
```

--------------------------------

### Token Estimation in Python

Source: https://github.com/delano/tryouts/blob/main/docs/topa-reference-code.md

Notes for Python implementation regarding token estimation, suggesting `len(text) // 4` for calculation.

```Python
# Use `len(text) // 4` for token estimation
```