shell_test

= ShellTest

Test modules for shell scripts.

== Description

Provides test modules to simplify testing of shell scripts.

ShellTest is not a testing framework. ShellTest integrates with Test::Unit and MiniTest out of the box, but it should be possible to include the test modules into other test frameworks.

== Usage

ShellTest builds on modules that provide specific functionality. The modules may be used independently, but by including ShellTest you get them all:

require 'shell_test/unit'

class ShellTestExample < Test::Unit::TestCase include ShellTest

def test_a_script
  script = prepare 'script.sh', %{
    echo goodnight $1
  }

  assert_script %{
    $ sh '#{script}' moon
    goodnight moon
  }, :exitstatus => 0
end

def test_a_script_that_takes_input
  script = prepare 'script.sh', %{
    stty -echo
    while true; do
      printf "Do you wish to continue? [y/n]: "
      read answer
      case $answer in
          y ) printf "\nOk!\n"; break;;
          n ) printf "\nToo bad.\n"; break;;
          * ) printf "\nPlease answer y or n.\n";;
      esac
    done
    stty echo
  }

  assert_script %{
    $ sh '#{script}'
    Do you wish to continue? [y/n]: {{hmmm}}
    Please answer y or n.
    Do you wish to continue? [y/n]: {{y}}
    Ok!
  }
end

end

==== {ShellMethods}[link:classes/ShellTest/ShellMethods.html]

Provides the shell testing methods. These methods are designed to input a string that looks like terminal input/output. Indeed with PS1 and PS2 set to their POSIX defaults, assert_script tests can be created by directly copying from the terminal.

require 'shell_test/unit' class ShellMethodsExample < Test::Unit::TestCase include ShellTest::ShellMethods

def test_a_script_with_env_variables
  with_env("THIS" => "moon") do
    assert_script %{
      $ THAT="boat"
      $ echo "goodnight $THIS"
      goodnight moon
      $ echo "goodnight $THAT"
      goodnight boat
    }
  end
end

def test_multiline_commands
  assert_script %{
    $ for n in one two; do
    >   echo $n
    > done
    one
    two
  }
end

def test_script_with_overall_and_per_command_timeouts
  assert_script %{
    $ sleep 0.1  # [0.5]
    $ sleep 0.1  # [0.5]
  }, :max_run_time => 1
end

def test_scripts_where_the_output_is_variable
  assert_script_match %{
    $ cal
    :...:
    Su Mo Tu We Th Fr Sa:. *.:
    :....:
  }
end

def test_scripts_where_alternate_prompts_are_needed
  with_env('PS1' => '% ') do
    assert_script %{
      % echo '$ $ $'
      $ $ $
    }
  end
end

end

==== {FileMethods}[link:classes/ShellTest/FileMethods.html]

Sets up a temporary, test-specific directory for working with files. This approach is better in most cases than using Tempfile because you can flag the directory to be saved on a failure (using ENV['KEEP_OUTPUTS']='true') and immediately know where to look for your files.

By default the directory is guessed based off of the test file and test method. If this example were located in the 'test/file_methods_example.rb' file, then the directory for the test case would be 'test/file_methods_example/test_preparation_of_a_test_specific_file'.

require 'shell_test/unit'

class FileMethodsExample < Test::Unit::TestCase include ShellTest::FileMethods

def test_setup_of_a_test_specific_file
  path = prepare('dir/file.txt') {|io| io << 'content' }
  assert_equal "content", File.read(path)
end

end

== Installation

ShellTest is available as a gem[http://rubygems.org/gems/shell_test].

$ gem install shell_test

== Development

To get started, checkout the code from GitHub[http://github.com/thinkerbot/shell_test] and run:

rake test

Please report any issues {here}[http://github.com/thinkerbot/shell_test/issues].

== Info

Developer:: {Simon Chiang}[http://github.com/thinkerbot] License:: {MIT-Style}[link:files/MIT-LICENSE.html]