Aruba

Aruba-jbb is a fork of github.com/aslakhellesoy/aruba and is found at github.com/byrnejb/aruba.

Aruba-jbb is a set of api methods and cucumber steps for driving out command line application behaviours. The command line application can be anything, a compiled C program, a Java program, a Perl script - anything.

Aruba-jbb may also be used to test complex configuration files for third-party applications where the software itself may not be modified.

Aruba-jbb works with Ruby-1.8.7 and Ruby-1.9.2

Usage

gem install aruba-jbb

Then, just require the library in one of your Ruby files under features/support

require 'aruba'

Note that since aruba-jbb and aruba cannot co-exist in the same project I have left the library name the same as upstream. This permits switching between the two in Bundler without having to alter env.rb as well. However, as of v-0.2.6.3 you have the option of requiring aruba_jbb instead.

You now have several api methods and a selection of step definitions available that you can use in features which test stand-alone processes. Look at aruba/cucumber_steps.rb to see all the step definitions. Look at features/*.feature for examples (which are also testing Aruba itself). A start has been made at documenting the api as well. Any suggestions to improve what is already there, or to provide whatever is missing, are most welcome.

You should be aware that Aruba runs the application it tests and creates all local output in its own working directory (awd). The awd defaults to tmp/aruba and is purged and created by Aruba at the beginning of every Scenario. However, the contents created by the last Scenario are left in the awd for your inspection.

If it is desired to alter the awd then this fork provides for setting the working directory to something else via the ARUBA_WORKING_DIR environmental variable. This must be set relative to the user’s cwd.

This fork also provides support for a @no-aruba-tmpdir tag. Use of this tag will cause Aruba to run the test application in the user’s cwd instead of the awd. When this tag is activated the directory contents are not cleared, for obvious reasons. In fact, regardless of the tag, if the awd is set to anything outside a directory tree containing a /tmp/ portion then an error is raised when trying to clear the contents. For similar reasons, when this is the case the rebase method also raises an error.

This fork contains a rebase api method which creates soft (symbolic) links inside aruba’s working directory to directories rooted at the user’s own current working directory (cwd). This permits the application to find its configuation and support files in their usual directories. A string of directories to rebase also may be passed by setting the ARUBA_REBASE environmental variable. These must be set relative to the user’s cwd as well.

For example:

ARUBA_REBASE="bin,config,lib"

This will cause Aruba to create soft links called ./tmp/aruba/bin, ./tmp/aruba/config and ./tmp/aruba/lib each pointing to the corresponding directory in the user’s cwd.

Upstream addressed the more limited problem of locating ./bin by adding a @bin tag which appends ./bin to Cucumber’s LOADPATH. This technique is supported by Aruba-jbb as well.

The aruba run api method is surrounded by a timeout call. This means that after the default period of 20 seconds any process under test is forceably terminated. However, be advised that the run api methods raises no error by default. Instead the process exit status is set to -1 and stderr will contain Aruba::Api::ProcessTimeout: execution expired.

You are therefore advised to either override the When /run “([^"])”/ do |cmd| step definition or provide an alternative form.

The default timeout value may be overriden either by defining an environmental variable called ARUBA_RUN_TIMEOUT to the approprate value (in seconds) or by passing an optional third parameter to the run api method. Fractional values are acepted but granularity of less than interger seconds is not guarenteed to work. A helper step definition is provided to set environment variables for process testing. This is documented in the api rdoc.

Timeout does not handle the run_interactive api method. This is experimaental code merged from Mike Sassak’s fork.

Ruby/RVM

Aruba once had api methods to run rvm ruby from inside aruba. These were removed in upstream’s 0.2.2 version and are no longer present in this fork either. The last version of this fork having them was 0.2.6.

To test against specific versions of Ruby using RVM you are advised to use following idiom (note the comma between Ruby version numbers):

$ rvm 1.9.2,1.8.7 exec rake cucumber:wip

$ rvm 1.9.2,1.8.7 exec cucumber

Getting more output with tags.

Aruba has several tags you can use to see what command actually gets run (useful if you’re using the RVM steps), STDOUT or STDERR. You can put these tags on individual scenarios, or on a feature. The tags are:

@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

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so that we do not break it in a future version unintentionally.
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.

Note on Aruba-JBB Step Definitions

This fork has extensively refactoried both the API and the Step Definitions. There are some minor syntax differences with the step definitions matchers provided with the parent. Mostly these have to do with making Aruba-jbb steps more specific so as to avoid anticipated collisions with the user’s own steps and to regularlize usage. For example do have instead of simply have. Further, except in a very few cases, these step matchers have removed the start of line and end of line anchors together with most of the subject predicates so as to allow more flexible sentence formulation.

For example, instead of:

When /^I have a file named "([^\"]*)"$/ do |file|

This fork uses:

When /do(?:es)? have a file named "([^\"]*)"$/ do |file|

So in your features you can write this:

When I do have a file named "test" . . . When we do have a file named "test" . . . When they do have a file named "test" . . . When the user does have a file named "test"

Experimental features

A new environment variable NO_ARUBA_STEPS now determines whether or not the step definition library shipped with aruba-jbb are loaded or not. No particular value is required. If the variable is defined then the default step libraries are not loaded. This obviously requires that you define your own steps that make use of the Aruba api.

Note on Aruba-JBB Development Testing

All previously encountered testing exceptions have been resolved. This version now passes all upstream tests and several more besides.

Note on Aruba (mainline)

I have renamed this gem since it has now evolved considerably away from the baseline although, in the main, compatiblity between the the two remains quite high for the end-user. Obviously, if you load both Aruba and Aruba-jbb in the same test process then you are going to encounter step matcher collisions. So, do not do that.

Copyright

Support

You can contact me at [email protected]. I also monitor the [email protected] mailing list.