README.md

This is the latest version of our README.md (Branch: "master").

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>.

Install

Add this line to your application's Gemfile:

gem 'aruba'

And then execute:

bundle

Or install it yourself as:

gem install aruba

Usage

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

Getting started

1. Clone the "Getting Started" application and make the cloned repository your current working directory

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

2. Install the required dependencies

   bundle install

Cucumber

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, Aruba!
       """
       When I run `aruba-test-cli file.txt` 
       Then the file "file.txt" should contain:
       """
       Hello, Aruba!
       """

3. Run cucumber

   bundle exec cucumber

RSpec

1. Add the following line to the "spec/spec_helper.rb" file.

   require 'aruba/rspec'

2. 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, Aruba!' }
   
     before(:each) { write_file file, content }
     before(:each) { 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

3. Run rspec

   bundle exec rspec

Minitest

1. Add the following line to the "test/test_helper.rb" file.

   require 'aruba/api'

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

   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

3. Run your tests

   bundle exec ruby -I lib:test test/use_aruba_with_minitest.rb

Development

Api Documentation

A full documentation of the API can be found here.

Code branches

We use two branches for development: "master" and "still". The "master" branch contains the code of the current major version. The "still" branch is used for the old major version. New features are only added to "master". The still branch is still maintained, but only get fixes for major bugs though having the still branch shall be considered as experimental - we need to find out how work it is to maintain two branches of code.

Initialize an existing project

There's an initializer to make it easier for you to get started.

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

Copyright

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