Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
CLI Steps for Cucumber
Ruby Cucumber CSS HTML

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Aruba is Cucumber extension for Command line applications written in any programming language. Features at a glance:

  • Test any command line application

  • Manipulate the file system

  • Create great HTML documentation based on your own Cucumber scenarios


gem install aruba

Then, just require the library in one of your ruby files under features/support (e.g. env.rb)

require 'aruba/cucumber'

You now have a bunch of step definitions that you can use in your features. Look at aruba/cucumber.rb to see all the step definitions. Look at features/*.feature for examples (which are also testing Aruba itself).


Aruba has tags you can put on on individual scenarios, or on a feature.

To get more information use these tags:

  • @announce-cmd - See what command is is run

  • @announce-stdout - See the stdout

  • @announce-stderr - See the stderr

  • @announce-dir - See the current directory

  • @announce-env - See environment variables set by Aruba

  • @announce - Does all of the above

To prevent Aruba from removing its working directory before each scenario:

  • @no-clobber - Don't cleanup before scenarios

Aruba strips away ANSI escapes from the stdout and stderr of spawned children by default. If you want to override this behaviour and leave the ANSI escape characters intact, just tag your scenario with @ansi. Alternatively you can add your own Before hook that sets @aruba_keep_ansi=true

Runtime Configuration

Per default Aruba will create a directory tmp/aruba where it performs it's file operations. If you want to change this behaviour put this into your features/support/env.rb:

Before do
  @dirs = ["somewhere/else"]

If testing an executable in your project's `bin` directory, it might not be in the path Aruba uses. An easy way to set it is to put the following in features/support/env.rb:

ENV['PATH'] = "#{File.expand_path(File.dirname(__FILE__) + '/../../bin')}#{File::PATH_SEPARATOR}#{ENV['PATH']}"

Set @aruba_timeout_seconds to control the amount of time Aruba will wait for a process to finish running before terminating it:

Before do
  @aruba_timeout_seconds = 5

Running processes interactively can result in race conditions when Aruba executes an IO-related step but the interactive process has not yet flushed or read some content. To help prevent this Aruba waits before reading or writing to the process if it is still running. You can control the wait by setting @aruba_io_wait_seconds to an appropriate value. This is particularly useful with tags:

Before('@slow_process') do
  @aruba_io_wait_seconds = 5


Aruba can generate a HTML page for each scenario that contains:

  • The title of the scenario

  • The description from the scenario (You can use Markdown here)

  • The command(s) that were run

  • The output from those commands (in colour if the output uses ANSI escapes)

  • The files that were created (in colour - syntax highlighted by [Pygments](

Reporting is off by default, but you can enable it by defining the`ARUBA_REPORT_DIR` environment variable, giving it the value where reports should be written:

ARUBA_REPORT_DIR=doc cucumber features

This will use Aruba's built-in template by default (See the `templates` folder). If you want to use your own template you can override its location:

ARUBA_REPORT_TEMPLATES=templates ARUBA_REPORT_DIR=doc cucumber features

The templates directory must contain a `main.erb` and `files.erb` template. It can also contain other assets such as css, javascript and images. All of these files will be copied over to the report dir well.

Escaping Markdown

There are some edge cases where Gherkin and Markdown don't agree. Bullet lists using `*` is one example. The `*` is also an alias for step keywords in Gherkin. Markdown headers (the kind starting with a #) is another example. They are parsed as comments by Gherkin. To use either of these, just escape them with a backslash. So instead of writing:

Scenario: Make tea
  ## Making tea
  * Get a pot
  * And some hot water


You'd write:

Scenario: Make tea
  \## Making tea
  \* Get a pot
  \* And some hot water


This way Gherkin won't recognize these lines as special tokens, and the reporter will render them as Markdown. (The reporter strips away any leading the backslashes before handing it off to the Markdown parser).

Another option is to use alternative Markdown syntax and omit conflicts and escaping altogether:

Scenario: Make tea
  Making tea
  ======           - Get a pot
  - And some hot water



Aruba doesn't bundle all of the tools needed for report generation. You have to add these yourself to your project:

  • bcat (gem)

  • rdiscount (gem)

  • pygments

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally. Note: the existing tests may fail with pre-1.9 versions of ruby; upgrade to get clean runs.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2010 Aslak Hellesøy and David Chelimsky. See LICENSE for details.

Something went wrong with that request. Please try again.