### Clone and Setup Aruba Getting Started Example

Source: https://github.com/cucumber/aruba/blob/main/features/README.md

Clone the Aruba getting started repository and install its dependencies using Bundler.

```bash
git clone https://github.com/cucumber/aruba-getting-started.git
cd aruba-getting-started
```

```bash
bundle install
```

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

### Example of Starting a Command

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Demonstrates starting a command. Note that `run_command` already starts the process, so calling `start` again has no effect.

```ruby
cmd = run_command('sleep 5')
cmd.start  # Already started by run_command
```

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

### Example of Getting Commandline

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Shows how to obtain and print the command string after running a command.

```ruby
cmd = run_command('echo hello world')
puts cmd.commandline  # => "echo hello world"
```

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

### Example of Getting Combined Output

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Shows how to execute a command and then retrieve its complete output.

```ruby
run_command_and_stop('echo hello && echo world')
puts last_command_started.output
```

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

### Full RSpec Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/integration.md

A comprehensive RSpec example demonstrating setup, configuration, and various test scenarios including command execution, file operations, and error handling.

```ruby
# spec/spec_helper.rb
require 'aruba/rspec'

Aruba.configure do |config|
  config.exit_timeout = 20
  config.remove_ansi_escape_sequences = true
end

# spec/cli_spec.rb
RSpec.describe 'My CLI', type: :aruba do
  describe 'version command' do
    it 'prints version number' do
      run_command_and_stop('my_cli --version')
      expect(last_command_started).to be_successfully_executed
      expect(last_command_started).to have_output(/\d+\.\d+\.\d+/)
    end
  end

  describe 'file operations' do
    it 'creates files' do
      run_command_and_stop('my_cli create myfile.txt')
      expect('myfile.txt').to be_an_existing_file
      expect('myfile.txt').to have_file_content('default content')
    end
  end

  describe 'error handling' do
    it 'fails on missing arguments', announce_stderr: true do
      run_command_and_stop('my_cli', fail_on_error: false)
      expect(last_command_started).not_to be_successfully_executed
      expect(last_command_started).to have_output_on_stderr(/required argument/)
    end
  end
end
```

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

### Example of Getting PID

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Demonstrates how to get and print the PID of a running command.

```ruby
run_command('sleep 10') do |cmd|
  puts "Running with PID: #{cmd.pid}"
  cmd.stop
end
```

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

### Manual Aruba Setup

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Provides an example of manually setting up and using the Aruba API outside of a testing framework.

```ruby
require 'aruba/api'
include Aruba::Api

setup_aruba
run_command_and_stop('echo hello')
```

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

### Setup and Configuration

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/EXPORTED_API.md

Methods for configuring and setting up Aruba for testing scenarios.

```APIDOC
## Setup and Configuration

### Description
Methods for configuring and setting up Aruba for testing scenarios.

### Methods
- `Aruba.configure(&block)`: Configures Aruba using a block.
- `Aruba.config`: Accesses the global Aruba configuration object.
- `Aruba::Api#setup_aruba`: Sets up Aruba for a test scenario.
- `Aruba::Api#aruba`: Provides access to Aruba's core functionalities.

### Source
`lib/aruba/cucumber.rb`, `lib/aruba/rspec.rb`, `lib/aruba/api.rb`
```

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

### started?

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Checks if a command has been started.

```APIDOC
## started?

### Description
Checks if a command has been started.

### Method
Ruby Method

### Parameters
None

### Returns
`Boolean` — true if started, false otherwise.
```

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

### Example: FileSize to Kibibytes Conversion

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Demonstrates converting a FileSize object to kibibytes.

```ruby
size = FileSize.new(2048)
size.to_kibi_byte  # => 2.0
```

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

### Setup Aruba Working Directory

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/core-api.md

Initializes Aruba's working directory for testing. Use `clobber = true` to remove the existing directory before setup, or `false` to preserve it.

```ruby
def setup_aruba(clobber = true)
  Aruba::Setup.new(aruba).call(clobber)
  self
end
```

```ruby
setup_aruba  # Initialize with cleanup
setup_aruba(false)  # Initialize without cleanup
```

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

### Example: FileSize to Gibibytes Conversion

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Demonstrates converting a FileSize object to gibibytes.

```ruby
size = FileSize.new(1024 * 1024 * 1024)
size.to_gibi_byte  # => 1.0
```

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

### Build and Install Local Aruba Copy

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Compile and install your local version of the Aruba gem.

```bash
bundle exec rake install
```

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

### Setup and Configuration

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Methods for initializing Aruba, configuring global settings, and accessing the current configuration.

```APIDOC
## Setup and Configuration

### `setup_aruba(clobber = true)`

Initializes Aruba for testing.

### `Aruba.configure { |c| ... }`

Sets global configuration options for Aruba.

### `aruba.config`

Accesses the current Aruba configuration object.
```

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

### Aruba Setup and Verification Workflow

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/matchers.md

Illustrates a typical Aruba testing workflow: setup, file creation, command execution, and verification of created files and their content.

```ruby
setup_aruba
write_file('input.txt', 'test data')
run_command_and_stop('my_processor input.txt')
expect('input.txt').to be_an_existing_file
expect('output.txt').to be_an_existing_file
expect('output.txt').to have_file_content(/processed/)
```

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

### Install Gem via Bundler

Source: https://github.com/cucumber/aruba/blob/main/fixtures/cli-app/README.md

Execute this command after adding the gem to your Gemfile to install it.

```bash
$ bundle
```

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

### Starting a Command Process

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Starts the command process. This method is often called internally by `run_command`.

```ruby
def start
  __getobj__.start
  event_bus.notify Events::CommandStarted.new(self)
  self
end
```

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

### Install Gem Manually

Source: https://github.com/cucumber/aruba/blob/main/fixtures/cli-app/README.md

Install the cli-app gem directly using the gem install command.

```bash
$ gem install cli-app
```

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

### Start a Command and Optionally Yield to Block

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Initiates a command execution. It can be used to start a command and then interact with it, or to simply start it and get the command object back. Supports configuration options for timeouts and signals.

```ruby
def run_command(cmd, opts = {})
  command = prepare_command(cmd, opts)
  start_command(command)
  block_given? ? yield(command) : command
end
```

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

### Example: FileSize to Mebibytes Conversion

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Demonstrates converting a FileSize object to mebibytes.

```ruby
size = FileSize.new(1024 * 1024)
size.to_mebi_byte  # => 1.0
```

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

### Install Aruba using Bundler

Source: https://github.com/cucumber/aruba/blob/main/README.md

Execute this command after adding Aruba to your Gemfile to install it.

```bash
bundle
```

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

### Example: FileSize Comparison

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Demonstrates comparing two FileSize objects using standard comparison operators.

```ruby
size1 = FileSize.new(1024)
size2 = FileSize.new(2048)

size1 < size2   # => true
size1 == size1  # => true
size1 > size2   # => false
```

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

### Command Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Shows how to run a command and access its properties like command line, output, and exit status using the Command object.

```ruby
run_command('echo hello world')
cmd = last_command_started
puts cmd.commandline  # => "echo hello world"
puts cmd.output       # => "hello world\n"
```

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

### Minitest Integration Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/README.md

Demonstrates how to integrate Aruba with Minitest by including Aruba::Api and calling setup_aruba.

```ruby
require 'aruba/api'

class MyTest < Minitest::Test
  include Aruba::Api

  def setup
    setup_aruba
  end
end
```

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

### ConfigWrapper Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Demonstrates accessing and modifying Aruba configuration settings using the ConfigWrapper.

```ruby
# Access configuration
timeout = aruba.config.exit_timeout
aruba.config.exit_timeout = 30

# List all options
aruba.config.log_level = :debug
```

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

### Install Dependencies with Appraisal

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Install specific versions of Aruba's dependencies using Appraisal.

```bash
bundle exec appraisal cucumber_6 bundle install
```

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

### Test Command Execution and Output

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Examples for running commands, checking their output, and verifying successful execution.

```ruby
# Run command and check output
run_command_and_stop('my_app --version')
expect(last_command_started).to have_output(/
+\d+\.\d+\.\d+/)
```

```ruby
# Check exit status
expect(last_command_started).to be_successfully_executed
```

```ruby
# Check specific output streams
run_command_and_stop('my_app')
expect(last_command_started).to have_output_on_stdout('success')
```

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

### Minitest CLI Test Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/integration.md

An example Minitest test case demonstrating how to run CLI commands and assert their output and file system effects.

```ruby
# test/cli_test.rb
class CLITest < ArubaTestCase
  def test_version_command
    run_command_and_stop('my_cli --version')
    assert last_command_started.exit_status.zero?
    assert last_command_started.output =~ /\d+\.\d+\.\d+/
  end

  def test_creates_files
    run_command_and_stop('my_cli create myfile.txt')
    assert file?('myfile.txt')
    content = read('myfile.txt').join("\n")
    assert content.include?('default')
  end

  def test_error_handling
    run_command_and_stop('my_cli', fail_on_error: false)
    refute last_command_started.exit_status.zero?
  end
end
```

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

### Install Aruba directly

Source: https://github.com/cucumber/aruba/blob/main/README.md

Install the Aruba gem directly using the gem command.

```bash
gem install aruba
```

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

### setup_aruba

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/core-api.md

Initializes Aruba's working directory for testing. It can optionally clean up the existing directory before setup.

```APIDOC
## setup_aruba(clobber = true)

### Description
Initialize Aruba's working directory for testing.

### Parameters
#### Parameters
- **clobber** (Boolean) - Optional - Default: true - Whether to remove existing aruba working directory before setup

### Returns
`self` — The API module for method chaining.

### Example
```ruby
setup_aruba  # Initialize with cleanup
setup_aruba(false)  # Initialize without cleanup
```
```

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

### Install Aruba Dependencies

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Install the project's dependencies using Bundler. This is a prerequisite for development.

```bash
bundle install
```

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

### Get All Registered Commands with all_commands()

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Retrieve a list of all commands that have been registered (started) using the `all_commands` method. This is useful for inspecting or managing multiple running processes.

```ruby
def all_commands
  aruba.command_monitor.registered_commands
end
```

```ruby
run_command('cmd1')
run_command('cmd2')
cmds = all_commands
cmds.length  # => 2
```

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

### Build and Install Local Aruba Copy (No Network)

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Compile and install your local Aruba gem without requiring network access.

```bash
bundle exec rake install:local
```

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

### run_command(cmd, opts = {})

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Starts a command and optionally yields to a block for interaction.

```APIDOC
## run_command(cmd, opts = {})

### Description
Start a command and optionally yield to block.

### Parameters
#### Path Parameters
- **cmd** (String) - The command to run
- **opts** (Hash) - Configuration options

#### Query Parameters
- **exit_timeout** (Numeric) - Timeout for process to exit
- **io_wait_timeout** (Numeric) - Timeout for IO
- **startup_wait_time** (Numeric) - Time to wait for process to start
- **stop_signal** (String) - Signal to send on stop

### Returns
- If block given: The return value of the block
- Otherwise: `Aruba::Command` object

### Raises
- `NotImplementedError` — If process launcher does not support interactive mode

### Example
```ruby
# Start command and interact with it
cmd = run_command('bash')
cmd.write("echo hello\n")
output = cmd.output

# With block
run_command('python interactive.py') do |cmd|
  cmd.write("input\n")
  cmd.stop
end
```
```

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

### Example: FileSize to Bytes Conversion

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Demonstrates converting a FileSize object to bytes using `to_byte` and `to_i`.

```ruby
size = FileSize.new(1024)
size.to_byte     # => 1024
size.to_i        # => 1024
```

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

### Minitest Setup for Aruba

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/integration.md

Sets up a Minitest test case to use Aruba's API for integration testing. Includes setup and teardown methods.

```ruby
# test/test_helper.rb
require 'aruba/api'

class ArubaTestCase < Minitest::Test
  include Aruba::Api

  def setup
    setup_aruba
    # Additional setup
  end

  def teardown
    stop_all_commands
    # Additional teardown
  end
end
```

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

### RSpec Example with Aruba

Source: https://github.com/cucumber/aruba/blob/main/features/README.md

An RSpec example demonstrating file writing, command execution, and output assertion using Aruba's helpers.

```ruby
require 'spec_helper'

RSpec.describe 'First Run', :type => :aruba do
  let(:file) { 'file.txt' }
  let(:content) { 'Hello, Aruba!' }

  before { write_file file, content }
  before { run_command('aruba-test-cli file.txt') }

  # Full string
  it { expect(last_command_started).to have_output content }

  # Substring
  it { expect(last_command_started).to have_output(/Hello/)
end
```

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

### Test Directory Operations

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Examples for creating directories, changing the current directory, and executing commands within a specific directory.

```ruby
# Create directories
create_directory('project/src')
```

```ruby
# Change directories
cd('project')
run_command_and_stop('ls')
```

```ruby
# Or with block
cd('project') do
  run_command_and_stop('make')
end
```

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

### Example of Writing to stdin

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Demonstrates writing multiple lines of text to a command's standard input and then closing it.

```ruby
run_command('cat > output.txt') do |cmd|
  cmd.write("Hello\n")
  cmd.write("World\n")
  cmd.stop
end
```

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

### RSpec Integration Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/README.md

Provides a basic example of how to integrate Aruba with RSpec for testing CLI applications.

```ruby
require 'aruba/rspec'

RSpec.describe 'My CLI', type: :aruba do
  it 'works' do
    run_command_and_stop('echo hello')
  end
end
```

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

### Start Aruba Developer Console

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Launch an interactive IRB console with Aruba's API loaded.

```bash
bin/console
```

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

### Check if Command Has Started

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Use this method to verify if a command has been initiated.

```ruby
def started?
  @started == true
end
```

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

### Example of Stopping a Command

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Shows how to write data to a command's stdin and then stop it gracefully.

```ruby
run_command('bash') do |cmd|
  cmd.write("echo hello\n")
  cmd.stop
end
```

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

### Find a Started Command by Commandline

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Locates a previously started command using its command string or a Command object. Returns the matching Aruba::Command object if found.

```ruby
def find_command(commandline)
  aruba.command_monitor.find(commandline)
end
```

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

### RSpec Example: File Creation and Content Verification

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Shows how to create a file, run a command that processes it, and then assert that the output file exists and contains specific content. Useful for testing file manipulation by CLI tools.

```ruby
describe 'file processing' do
  before do
    write_file('input.txt', 'test data')
  end

  it 'processes input file' do
    run_command_and_stop('my_app process input.txt')
    expect('output.txt').to be_an_existing_file
    expect('output.txt').to have_file_content(/processed/)
  end
end
```

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

### Configure Startup Wait Time

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/configuration.md

Define the time to wait after a process starts before proceeding with further actions. This is useful for commands that have a noticeable startup delay.

```ruby
Aruba.configure do |config|
  config.startup_wait_time = 0.5
end

run_command('slow_startup', startup_wait_time: 2)
```

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

### type(input)

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Sends input to the standard input of the last started command.

```APIDOC
## type(input)

### Description
Send input to last started command's stdin.

### Parameters
#### Path Parameters
- **input** (String) - Text to send to command

### Returns
The return value of write operation, or nil if closing input.

### Special Input
- `" "` (Ctrl-D) — Closes stdin

### Example
```ruby
run_command('bash')
type('echo hello')
type('ls -la')

# Close stdin
type(" ")
```
```

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

### Example of Closing stdin

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Shows how to write data to a command, close its standard input, and then stop the command.

```ruby
run_command('bash') do |cmd|
  cmd.write("data\n")
  cmd.close_io(:stdin)
  cmd.stop
end
```

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

### ArubaPath Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Illustrates accessing and using ArubaPath objects, which provide string-like behavior for path operations.

```ruby
# Accessed through Runtime
cwd = aruba.current_directory  # Returns ArubaPath
cwd.to_s  # => "tmp/aruba"
```

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

### RSpec Test Setup

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Demonstrates how to set up and use Aruba within an RSpec test suite.

```ruby
RSpec.describe 'Example', type: :aruba do
  it 'uses aruba' do
    run_command_and_stop('echo hello')
  end
end
```

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

### Create and Verify Test Files

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/README.md

Demonstrates how to initialize a project, check for directory and file existence, and verify file content using Aruba's matchers.

```ruby
run_command_and_stop('my_app init myproject')
expect('myproject').to be_an_existing_directory
expect('myproject/config.yml').to be_an_existing_file
expect('myproject/config.yml').to have_file_content(/version:/)
```

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

### Cucumber Setup

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/integration.md

Include `aruba/cucumber` in your `features/support/env.rb` to integrate Aruba with Cucumber.

```ruby
# features/support/env.rb
require 'aruba/cucumber'

Aruba.configure do |config|
  config.exit_timeout = 30
end
```

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

### Cucumber Integration Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/README.md

Shows how to integrate Aruba with Cucumber by requiring the Aruba Cucumber plugin and defining a step.

```ruby
require 'aruba/cucumber'

Given('I run a command') do
  run_command_and_stop('my_command')
end
```

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

### Assert Same File Content

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/matchers.md

Use `have_same_file_content` to verify that two files have identical content. The example shows creating files and then comparing them.

```ruby
expect('file1.txt').to have_same_file_content('file2.txt')
expect('file1.txt').not_to have_same_file_content('file3.txt')
```

```ruby
write_file('original.txt', 'content')
copy('original.txt', 'copy.txt')
expect('original.txt').to have_same_file_content('copy.txt')
```

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

### Example of Terminating Commands

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Demonstrates terminating commands, including a scenario where `terminate_all_commands` is used, which internally calls `terminate`.

```ruby
run_command('long_running_process')
terminate_all_commands  # Uses terminate internally
```

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

### Add Local Development Gems

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Use a Gemfile.local to install custom gems for development.

```ruby
gem 'byebug'
```

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

### Get Last Started Command with last_command_started()

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Access the most recently started command using `last_command_started`. This method is useful for immediately interacting with or checking the status of the latest command executed.

```ruby
def last_command_started
  aruba.command_monitor.last_command_started
end
```

```ruby
run_command('echo hello')
cmd = last_command_started
puts cmd.output
```

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

### Minitest Example with Aruba

Source: https://github.com/cucumber/aruba/blob/main/features/README.md

A Minitest test case using Aruba::Api to write a file, run a command, and assert the output.

```ruby
require 'test_helper'
require 'minitest/autorun'

class FirstRun < Minitest::Test
  include Aruba::Api

  def setup
    setup_aruba
  end

  def test_getting_started_with_aruba
    file = 'file.txt'
    content = 'Hello, Aruba!'

    write_file file, content

    run_command_and_stop 'aruba-test-cli file.txt'
    assert_equal last_command_started.output.chomp, content
  end
end
```

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

### all_commands

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Retrieves a list of all commands that have been registered and started. This can be used to inspect or manage multiple running processes.

```APIDOC
## all_commands

### Description
Get all registered commands.

### Returns
`Array<Aruba::Command>` — List of all started commands.

### Example
```ruby
run_command('cmd1')
run_command('cmd2')
cmds = all_commands
cmds.length  # => 2
```
```

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

### RSpec CLI Testing with Subcommands

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/integration.md

Demonstrates testing a CLI with subcommands using RSpec and Aruba. Includes examples for help, init, and build subcommands.

```ruby
RSpec.describe 'My CLI', type: :aruba do
  describe 'help command' do
    it 'shows usage' do
      run_command_and_stop('my_cli help')
      expect(last_command_started).to have_output(/Usage:/)
    end
  end

  describe 'init subcommand' do
    it 'creates directory structure' do
      run_command_and_stop('my_cli init myproject')
      expect('myproject').to be_an_existing_directory
      expect('myproject/config.yml').to be_an_existing_file
    end

    it 'fails if directory exists' do
      create_directory('myproject')
      run_command_and_stop('my_cli init myproject', fail_on_error: false)
      expect(last_command_started).not_to be_successfully_executed
    end
  end

  describe 'build subcommand' do
    before do
      write_file('input.txt', 'test data')
    end

    it 'processes files' do
      run_command_and_stop('my_cli build input.txt')
      expect('output.txt').to be_an_existing_file
    end
  end
end
```

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

### Cucumber Example: Basic Command Execution and Output Check

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Demonstrates how to execute a command and verify its exit status and output using Aruba's Cucumber integration. This is suitable for behavior-driven development of CLI applications.

```gherkin
Feature: My CLI Application
  Scenario: Help command
    When I run "my_app --help"
    Then the exit status is 0
    And the output contains "Usage"
```

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

### Handle Aruba::CommandNotFoundError

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/errors.md

Example of rescuing Aruba::CommandNotFoundError when `find_command` is used to search for a command that was not previously started.

```ruby
run_command_and_stop('echo foo')

begin
  find_command('echo bar')  # Error - not started
rescue Aruba::CommandNotFoundError => e
  puts "Command not found: #{e.message}"
end
```

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

### Cucumber Feature File Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/integration.md

A Gherkin feature file demonstrating scenarios for testing a CLI application with Cucumber and Aruba.

```gherkin
# features/cli.feature
Feature: My CLI
  Background:
    Given a test file

  Scenario: Running the command successfully
    When I run the command
    Then the exit status is 0
    And the output contains "success"

  Scenario: Handling errors
    When I run the command with invalid args
    Then the exit status is 1
    And stderr contains "error"
```

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

### Runtime Attributes Example

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Illustrates accessing key attributes of the Aruba Runtime object, such as configuration, current directory, and root directory.

```ruby
runtime = aruba
config = runtime.config
cwd = runtime.current_directory
```

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

### Run Containerized Development Environment

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Start a bash shell inside a Docker container, mounting the current directory for live code changes.

```bash
docker run -v $PWD:/aruba --rm -it test-aruba:latest bash
```

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

### Aruba Assertions for File System Operations

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/integration.md

Provides examples for asserting the existence, content, and size of files and directories using Aruba's matchers.

```ruby
# File exists
expect('myfile.txt').to be_an_existing_file

# Directory exists
expect('mydir').to be_an_existing_directory

# File content
expect('myfile.txt').to have_file_content('expected text')
expect('myfile.txt').to have_file_content(/regex/)

# File size
expect('myfile.txt').to have_file_size(1024)

# Executable
expect('script.sh').to be_an_existing_executable
```

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

### Define Aruba::CommandNotFoundError Class

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/errors.md

Raised when searching for a command that has not been started or does not match any started command.

```ruby
class CommandNotFoundError < ArgumentError; end
```

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

### Cucumber Feature Example with Aruba

Source: https://github.com/cucumber/aruba/blob/main/features/README.md

A basic Cucumber feature demonstrating file creation, command execution, and output verification using Aruba.

```gherkin
Feature: Cucumber
  Scenario: First Run
    Given a file named "file.txt" with:
    """
    Hello, Aruba!
    """
    When I run `aruba-test-cli file.txt` 
    Then the file "file.txt" should contain:
    """
    Hello, Aruba!
    """
```

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

### Aruba Command Instance Methods

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/EXPORTED_API.md

Methods for interacting with a command process managed by Aruba. This includes starting, stopping, and checking the status of commands.

```ruby
def initialize(command, opts = {})  # Create command
def start                           # Start process
def run!                           # Alias for start
def stop                           # Stop gracefully
def terminate                      # Force terminate
```

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

### Cucumber Example: File Creation and Content Verification

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Shows how to define a file with content, run a command that processes it, and then assert that the output file exists and contains specific text. Use this for BDD scenarios involving file operations.

```gherkin
Scenario: File processing
  Given a file "input.txt" with content:
    """
    test data
    """
  When I run "my_app process input.txt"
  Then the file "output.txt" should exist
  And the file "output.txt" should contain "processed"
```

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

### Install Aruba Gem

Source: https://github.com/cucumber/aruba/blob/main/features/README.md

Add Aruba to your application's Gemfile for dependency management or install it directly using the gem command.

```ruby
gem 'aruba'
```

```bash
bundle
```

```bash
gem install aruba
```

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

### Test File Creation and Content Verification

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Demonstrates how to create files, check for their existence, and verify their content.

```ruby
# Create files
write_file('config.json', '{"setting": "value"}')
```

```ruby
# Test file exists
expect('config.json').to be_an_existing_file
```

```ruby
# Test file content
expect('config.json').to have_file_content(/"setting"/)
```

```ruby
# Read file content
content = read('config.json').join("\n")
config = JSON.parse(content)
```

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

### File Creation and Existence Check

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/matchers.md

Demonstrates creating a file using `write_file` and then asserting its existence with `be_an_existing_file`.

```ruby
# File creation
write_file('config.json', '{"key": "value"}')
expect('config.json').to be_an_existing_file
```

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

### Close Stdin of Last Started Command

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Explicitly closes the standard input stream of the last command that was started. This is equivalent to sending an end-of-file signal.

```ruby
def close_input
  last_command_started.close_io(:stdin)
end
```

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

### Basic Command Execution

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Demonstrates the basic pattern for running a command and asserting its output.

```ruby
run_command_and_stop('echo hello')
expect(last_command_started).to have_output('hello')
```

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

### Get All Files in Current Directory

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/filesystem-api.md

Use `all_files` to get a list of expanded paths for all files in the current directory. This method filters out directories, providing only file paths.

```ruby
def all_files
  list('.').select { |p| file? p }.map { |p| expand_path(p) }
end
```

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

### Aruba::Runtime#initialize

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/runtime.md

Initializes a new instance of the Aruba runtime. It sets up the event bus, announcer, configuration, environment, directories, and logger.

```APIDOC
## Aruba::Runtime#initialize

### Description

Initializes a new instance of the Aruba runtime. It sets up the event bus, announcer, configuration, environment, directories, and logger.

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| announcer | Object | Platform announcer | Custom announcer for output |
| config | ConfigWrapper | Copy of global config | Custom configuration |
| environment | Object | Platform env vars | Custom environment manager |
| command_monitor | Object | Platform monitor | Custom command monitor |
| logger | Object | Platform logger | Custom logger |
```

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

### Send Input to Last Started Command's Stdin

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Writes a string followed by a newline to the standard input of the most recently started command. Use a space character to signal end-of-file (close stdin).

```ruby
def type(input)
  return close_input if input == " "
  last_command_started.write(input, "\n")
end
```

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

### Initialize Project with Minitest

Source: https://github.com/cucumber/aruba/blob/main/features/README.md

Use this command to initialize a new project with Aruba when using Minitest for testing. Ensure your project is under version control and all changes are committed before running.

```bash
aruba init --test-framework minitest
```

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

### restart

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Restarts the command by stopping and then starting it again.

```APIDOC
## restart

### Description
Restarts the command.

### Method
Ruby Method

### Parameters
None

### Returns
`nil`

### Example
```ruby
cmd = run_command('server')
cmd.restart  # Stop and start again
```
```

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

### close_input

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Closes the standard input of the last started command.

```APIDOC
## close_input

### Description
Close stdin of last started command.

### Returns
`nil`

### Example
```ruby
run_command('cat')
type("data\n")
close_input
```
```

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

### Check Project Licenses

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Verify that relevant licenses are present in the project.

```bash
bundle exec rake lint:licenses
```

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

### Create empty files

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/filesystem-api.md

Use `touch` to create one or more empty files. Parent directories are created as needed.

```ruby
def touch(*args)
  # Creates one or more empty files
  # Creates parent directories as needed
end
```

```ruby
touch('file1.txt')
```

```ruby
touch('file1.txt', 'file2.txt')
```

```ruby
touch(['file1.txt', 'file2.txt'])
```

```ruby
touch('dir/file.txt')
```

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

### Create a file with content

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/filesystem-api.md

Use `write_file` to create a new file with specified content. Parent directories are created as needed. This method does not check if the file already exists.

```ruby
def write_file(name, content)
  Aruba.platform.create_file(expand_path(name), content, false)
  self
end
```

```ruby
write_file('dir/subdir/file.txt', 'Hello World')
```

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

### Main Aruba Import Paths

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/EXPORTED_API.md

These are the primary entry points for using Aruba. `require 'aruba'` loads the core functionality, while `require 'aruba/api'` provides direct access to the public API methods.

```ruby
require 'aruba'
require 'aruba/api'
```

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

### File Operations: Copy and Content Comparison

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/matchers.md

Demonstrates copying a file and then comparing its content with the original using `copy` and `have_same_file_content`.

```ruby
# File operations
copy('source.txt', 'dest.txt')
expect('source.txt').to have_same_file_content('dest.txt')
```

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

### find_command(commandline)

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Finds a started command by its command line string or Command object.

```APIDOC
## find_command(commandline)

### Description
Find a started command by commandline.

### Parameters
#### Path Parameters
- **commandline** (String, Aruba::Command) - The command string to find, or a Command object

### Returns
`Aruba::Command` — The matching command.

### Raises
- `Aruba::CommandNotFoundError` — If command not found

### Example
```ruby
run_command('echo hello')
run_command('echo world')
cmd = find_command('echo hello')
puts cmd.output
```
```

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

### Configure Command Launcher

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/configuration.md

Specify how commands should be launched. Options include `:spawn` for external processes, `:in_process` for running Ruby code directly, and `:debug` for detailed logging.

```ruby
Aruba.configure do |config|
  config.command_launcher = :in_process
end
```

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

### Restart a Command

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Restarts a command by first stopping it and then starting it again. Useful for re-initializing a running process.

```ruby
def restart
  stop
  start
end
```

```ruby
cmd = run_command('server')
cmd.restart  # Stop and start again
```

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

### RSpec Example: Basic Command Execution and Output Check

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Demonstrates how to run a command and verify its successful execution and output using Aruba's RSpec integration. Use this for testing CLI applications within an RSpec test suite.

```ruby
require 'aruba/rspec'

RSpec.describe 'My CLI', type: :aruba do
  describe 'help command' do
    it 'shows usage information' do
      run_command_and_stop('my_app --help')
      expect(last_command_started).to be_successfully_executed
      expect(last_command_started).to have_output(/Usage: my_app/)
    end
  end
end
```

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

### Accessing Aruba Configuration

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Demonstrates how to access the global and runtime-specific Aruba configuration objects.

```ruby
Aruba.config  # Global configuration
aruba.config  # Runtime-specific configuration
```

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

### Require Cucumber Integration

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/INDEX.md

Include this line in your Cucumber setup to integrate Aruba's features.

```ruby
require 'aruba/cucumber'
```

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

### Require RSpec Integration

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/INDEX.md

Include this line in your RSpec setup to integrate Aruba's features.

```ruby
require 'aruba/rspec'
```

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

### Define Aruba::NoCommandHasBeenStartedError Class

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/errors.md

Raised when trying to access the last started command before any command has been initiated.

```ruby
class NoCommandHasBeenStartedError < Error; end
```

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

### Initialize Project with RSpec

Source: https://github.com/cucumber/aruba/blob/main/features/README.md

Use this command to initialize a new project with Aruba when using RSpec for testing. Ensure your project is under version control and all changes are committed before running.

```bash
aruba init --test-framework rspec
```

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

### Getting Standard Output (stdout)

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Retrieves the standard output of the command. Supports waiting for IO operations.

```ruby
def stdout(opts = {})
  # Implementation-specific
end
```

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

### Run CLI Application

Source: https://github.com/cucumber/aruba/blob/main/fixtures/cli-app/README.md

Execute the CLI application from the command line.

```bash
cli
```

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

### Execute Command with Custom Environment Variables

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/core-api.md

Demonstrates how to use the `with_environment` method to execute a command with specific environment variables set. The original environment is restored after execution.

```ruby
# Execute command with custom environment
result = with_environment('USER' => 'testuser', 'HOME' => '/tmp/home') do
  ENV['USER']  # => 'testuser'
end

# Environment is restored after block execution
ENV['USER']  # Back to original value
```

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

### Handle Aruba::NoCommandHasBeenStartedError

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/errors.md

Example of rescuing Aruba::NoCommandHasBeenStartedError when attempting to access `last_command_started` before any command has been run.

```ruby
begin
  cmd = last_command_started  # Error if no command started!
rescue Aruba::NoCommandHasBeenStartedError => e
  puts "Start a command first"
end
```

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

### RSpec Setup

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/integration.md

Include aruba/rspec in your spec helper or spec file to enable Aruba integration with RSpec.

```ruby
# spec/spec_helper.rb
require 'aruba/rspec'

RSpec.configure do |config|
  # config goes here
end
```

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

### last_command_started

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/commands-api.md

Returns the most recently started command. This is useful for immediately accessing the details or output of the last executed command.

```APIDOC
## last_command_started

### Description
Get the most recently started command.

### Returns
`Aruba::Command` — The last started command.

### Raises
- `Aruba::NoCommandHasBeenStartedError` - If no command has been started

### Example
```ruby
run_command('echo hello')
cmd = last_command_started
puts cmd.output
```
```

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

### Get File Size

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/filesystem-api.md

Retrieves the size of a specified file in bytes. Ensures the file exists before returning its size.

```ruby
def file_size(name)
  expect(name).to be_an_existing_file
  Aruba.platform.determine_file_size expand_path(name)
end
```

```ruby
write_file('test.txt', 'content')
size = file_size('test.txt')
```

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

### touch

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/filesystem-api.md

Creates one or more empty files. Parent directories are created as needed.

```APIDOC
## touch(*file_names, **options)

### Description
Create empty files.

### Method
```ruby
def touch(*args)
  # Creates one or more empty files
  # Creates parent directories as needed
end
```

### Parameters
#### Path Parameters
- **file_names** (String, Array) - Required - One or more file paths
- **options** (Hash) - Optional - Optional hash of options

### Returns
`self` — For method chaining.

### Example
```ruby
touch('file1.txt')
touch('file1.txt', 'file2.txt')
touch(['file1.txt', 'file2.txt'])
touch('dir/file.txt')
```
```

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

### Getting Standard Error (stderr)

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Retrieves the standard error output of the command. Supports waiting for IO operations.

```ruby
def stderr(opts = {})
  # Implementation-specific
end
```

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

### Get Current Directory

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/runtime.md

Retrieves the current working directory for file operations. This attribute is modified by `cd()` operations.

```ruby
attr_reader :current_directory
```

```ruby
puts aruba.current_directory  # => "tmp/aruba"
```

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

### Initialize Project with Cucumber

Source: https://github.com/cucumber/aruba/blob/main/features/README.md

Use this command to initialize a new project with Aruba when using Cucumber for testing. Ensure your project is under version control and all changes are committed before running.

```bash
aruba init --test-framework cucumber
```

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

### Test Environment Variable Management

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/index.md

Shows how to set, verify, and modify environment variables for command execution.

```ruby
# Set variables
set_environment_variable('API_KEY', 'secret')
run_command_and_stop('my_app')
```

```ruby
# Verify command received it
expect(last_command_started).to have_output('API_KEY=secret')
```

```ruby
# Modify PATH
prepend_environment_variable('PATH', '/custom/bin')
```

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

### Lint Code with RuboCop

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Run the 'rubocop' linter to check code for style guideline compliance.

```bash
bundle exec rake lint:coding_guidelines
```

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

### Example: Unescape Text

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/text-api.md

Demonstrates the conversion of escape sequences to their corresponding characters, including newlines, quotes, and tabs.

```ruby
unescape_text('hello\nworld')
# => "hello\nworld" (with actual newline)

unescape_text('say \"hello\"')
# => 'say "hello"'

unescape_text('line1\tline2')
# => "line1\tline2" (with actual tab)
```

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

### Configure Fixture Directories

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/configuration.md

Specify the directories where Aruba should search for fixture files. The first existing directory in the list will be used.

```ruby
Aruba.configure do |config|
  config.fixtures_directories = ['test/fixtures', 'fixtures']
end
```

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

### Getting Process ID (PID)

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Retrieves the process ID (PID) of the running command. Returns nil if the command is not running.

```ruby
def pid
  # Returns process ID (implementation-dependent)
end
```

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

### Get Root Directory

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/runtime.md

Retrieves the root directory of the test project. This defaults to the current working directory when Aruba is loaded.

```ruby
attr_reader :root_directory
```

```ruby
puts aruba.root_directory  # => "/home/user/project"
```

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

### Aruba Command Initialization

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/command.md

Illustrates the internal initialization of an Aruba Command object, which selects an appropriate launcher based on options and wraps it.

```ruby
def initialize(command, opts = {})
  # Selects appropriate launcher based on opts[:mode]
  # Wraps launcher using SimpleDelegator
end
```

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

### Aruba::Command Instance Methods

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/EXPORTED_API.md

Methods for managing and interacting with a command process.

```APIDOC
## Aruba::Command

### Description
Process wrapper for managing command execution.

### Instance Methods
- **initialize(command, opts = {})** - Create a new command instance.
- **start** - Start the command process.
- **run!** - Alias for `start`.
- **stop** - Stop the command process gracefully.
- **terminate** - Forcefully terminate the command process.
```

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

### Handle Aruba::UnknownOptionError for Invalid Configuration

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/errors.md

Example of rescuing Aruba::UnknownOptionError when attempting to set an invalid configuration option.

```ruby
begin
  Aruba.config.invalid_option = 123
rescue Aruba::UnknownOptionError => e
  puts "Unknown config: #{e.message}"
end
```

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

### Build Docker Container

Source: https://github.com/cucumber/aruba/blob/main/CONTRIBUTING.md

Build the Docker image for the Aruba project.

```bash
docker build -t test-aruba .
```

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

### Example: Extract Text

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/api-reference/text-api.md

Shows how to remove ANSI color codes and control characters from a string, resulting in plain text.

```ruby
colored = "hello \e[31mworld\e[0m"
extract_text(colored)
# => "hello world"

# With control characters
text = "before\007after"
extract_text(text)
# => "beforeafter"
```

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

### Aruba Event Bus Notification

Source: https://github.com/cucumber/aruba/blob/main/_autodocs/types.md

Shows how to manually notify the Aruba event bus about a command starting. This is typically used internally.

```ruby
# Usually accessed internally
aruba.event_bus.notify(Events::CommandStarted.new(command))
```