This is the latest version of our README.md. If you want to see the one of the last released version of "aruba", please have a look at this one.

aruba is an extension for popular TDD and BDD frameworks like "Cucumber", "RSpec" and "Minitest" to make testing of commandline applications meaningful, easy and fun.

Your benefits:

• Test any command line application implemented in any programming language - e.g. Bash, Python, Ruby, Java, ...
• Manipulate the file system and the process environment with helpers working similar like tools you may know from your shell
• No worries about leaking state: The file system and the process environment will be reset between tests
• Support by a helpful and welcoming community – see our Code of Conduct
• The documentation is our contract with you. You can expect aruba to work as documented

Our Vision:

• Help our users to build better command line applications written in any programming language
• Make creating documentation for command line simple and fun
• Support the cucumber community in its effort to create a specification for all official cucumber implementations

Our Focus:

• Test the user-interaction with the commands at runtime – this excludes the process of installation/deployment of commands like installing Rubygems with gem install <your-gem>.

Add this line to your application's Gemfile:

gem 'aruba'

And then execute:

$ bundle

Or install it yourself as:

$ gem install aruba

We try to be compliant to Semantic Versioning 2.0.0.

For an up to date list of all supported ruby versions, please see our .travis.yml. We only test against the latest version of a version branch - most times.

Please also see this feature test for the most up to date documentation.

There's an initializer to make it easier for you to getting started. If you prefer to setup aruba yourself, please move on to the next section.

1. Go to your project's directory

2. Make sure, it's under version control and all changes are committed to your version control repository

3. Run one of the following commands depending on the tools you use to test your project.

   This assumes, that you use either rspec, cucumber-ruby or minitest to write the tests for your project. Besides that, your tool can be implemented in any programming language you like.

   aruba init --test-framework rspec
   aruba init --test-framework cucumber
   aruba init --test-framework minitest

1. Create a file named "features/support/env.rb" with:

   require 'aruba/cucumber'

2. Create a file named "features/use_aruba_with_cucumber.feature" with:

   Feature: Cucumber
     Scenario: First Run
       Given a file named "file.txt" with:
       """
       Hello World
       """
       Then the file "file.txt" should contain:
       """
       Hello World
       """

3. Run cucumber

1. Create a file named "spec/support/aruba.rb" with:

   require 'aruba/rspec'

2. Create a file named "spec/spec_helper.rb" with:

   $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
   
   ::Dir.glob(::File.expand_path('../support/**/*.rb', __FILE__)).each { |f| require_relative f }

3. Create a file named "spec/use_aruba_with_rspec_spec.rb" with:

   require 'spec_helper'
   
   RSpec.describe 'First Run', :type => :aruba do
     let(:file) { 'file.txt' }
     let(:content) { 'Hello World' }
   
     before(:each) { write_file file, content }
   
     it { expect(read(file)).to eq [content] }
   end

4. Run rspec

1. Add a file named "test/support/aruba.rb" with:

   require 'aruba/api'

2. Add a file named "test/test_helper.rb" with:

   $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
   
   ::Dir.glob(::File.expand_path('../support/**/*.rb', __FILE__)).each { |f| require_relative f }

3. Add a file named "test/use_aruba_with_minitest.rb" with:

   $LOAD_PATH.unshift File.expand_path('../test', __FILE__)
   
   require 'test_helper'
   require 'minitest/autorun'
   
   class FirstRun < Minitest::Test
     include Aruba::Api
   
     def setup
       aruba_setup
     end
   
     def getting_started_with_aruba
       file = 'file.txt'
       content = 'Hello World' 
   
       write_file file, content
       read(file).must_equal [content]
     end
   end

4. Run your tests

   ruby -Ilib:test test/use_aruba_with_minitest.rb

If you're interested in our steps and API, please browse our feature files. You can find a lot of examples there. A good starting point are Getting Started and Step Overview. A more or less full list of our steps can be found here. Our API is documentated here and some more information about how to configure aruba, can be found here. The "RSpec" matchers provided by aruba, are documented here you can use them with any testing framework we support.

You can find our documentation on Relish as well. Unfortunately "Relish" does not like the way we structured our feature tests. So this documentation found there may be not complete.

Table of Contents

There are some things which are still undocumented. We would like to encourage you to add documentation for those and send us a PR.

• Getting Started

  • Cleanup Working Directory
  • Install library
  • Supported Testing Frameworks
  • Writing Good Tests.feature
  • Run Commands

• Use aruba command

  • Start aruba console to try API
  • Initialize project with "aruba"

• Use with test frameworks

  • RSpec

    • Setup
    • Hooks
      • After Command
      • Before Command

  • Cucumber

    • Setup
    • Get overview over steps
    • Announce Information
    • Step definitions
      • Command
        • debug
        • exit statuses
        • in process
        • interactive
        • output
        • run
        • send signal
        • shell
        • stderr
        • stdout
        • stop
      • Environment
        • append environment variable
        • home variable
        • prepend environment variable
        • set environment variable
      • filesystem
        • append to file
        • cd to directory
        • check file content
        • check permissions of file
        • compare files
        • copy
        • create directory
        • create file
        • existence of directory
        • existence of file
        • file content
        • fixtures
        • move
        • non existence of directory
        • non existence of file
        • overwrite file
        • remove directory
        • remove file
        • use fixture
    • Hooks
      • After Command
      • Before Command

• Configuration

  • activate announcer on command failure
  • command runtime environment
  • console history file
  • exit timeout
  • fixtures directories
  • fixtures path prefix
  • home directory
  • io timeout
  • keep ansi
  • log level
  • physical block size
  • remove ansi escape sequences
  • root directory
  • startup wait time
  • usage
  • working directory

• Development of Aruba

  • bootstrap aruba
  • build aruba
  • build docker image
  • install gem
  • lint ruby sources
  • lint travisjconfiguration
  • lint used licenses of rubygems
  • release gem
  • run aruba console
  • run docker container
  • run test suite

• Matchers

  • collection
    • include an object
  • command
  • directory
    • have sub directory
  • file
    • be a command found in path
    • be existing executable
    • be existing file
    • have file content
    • have file size
  • path
    • be an absolute path
    • be an existing path
    • have permissions
  • timeouts

• Platforms * jruby

• Our API

  • Commands
    • find command
    • last command started
    • last command stopped
    • run
    • run simple
    • send signal
    • stderr
    • stdout
    • stop all commands
    • stop
    • terminate all commands
    • which
  • Core
    • expand path
  • Environment
    • append environment variable
    • delete environment variable
    • prepend environment variable
    • set environment variable
  • Filesystem
    • cd
    • copy
    • create directory
    • disk usage
    • does exist
    • is absolute
    • is directory
    • is file
    • is relative
    • move
  • Text
    • extract text
    • replace variables
    • sanitize text
    • unescape text

aruba provides a wonderful API to be used in your tests:

• Creating files/directories
• Deleting files/directories
• Checking file size
• Checking file existence/absence
• ...

A full documentation of the API can be found here.

Please see the CONTRIBUTING file.

Copyright (c) 2010-2016 Aslak Hellesøy et al. See MIT License for details.