= Autotest Growl

* Author: Sven Schwyn (http://www.bitcetera.com)
* Homepage: http://www.bitcetera.com/products/autotest-growl
* Issues and forum: https://forge.bitcetera.com/projects/show/autotest-growl

== DESCRIPTION:

This gem aims to improve support for Growl notification by ZenTest's autotest.
It comes with a nice colored Ruby icon set and - for now - supports Cucumber 
notifications by means of a workaround.

The priority of a notification is set according to the actual result so you
can  configure Growl to style the notifications differently based on these
priorities:

* 2 for error or failed
* 0 for info
* -1 for pending, undefined or unknown
* -2 for passed

Furthermore the terminal running autotest is cleared on every cycle (unless
configured otherwise). Don't worry though, it's still possible to scroll up
to see the output of previous cycles - at least on the Terminal.app from
Apple.

== REQUIREMENTS:

* Growl >= 1.1.5 (Mac OS X) or >= 2.0b18 (Windows) 
* ZenTest >= 4.1.3

== INSTALL:

First install the gem:

  sudo gem install autotest-growl

Then add the following line to your ~/.autotest file:

  require 'autotest/growl'

Make sure Growl is installed on your computer. You can download it from:

Mac OS X: http://growl.info
Windows:  http://growlforwindows.com

== CONFIGURATION:

=== Custom Icons

Using your own set of icons is pretty simple. Just create a directory
~/.autotest-growl, copy your icons there and name them passed.png,
pending.png, failed.png, error.png and info.png.

=== Don't Clear the Terminal

Add the following to your ~/.autotest if you don't want the terminal to
be cleared before running a test:

  Autotest::Growl::clear_terminal = false

=== Hide the Label

If you prefer the Growl notifications not to show labels such as "LABEL:
All tests have passed", add the following to your ~/.autotest:

  Autotest::Growl::hide_label = true

=== One Notifications per Run

Allow only one test and one feature notification per run by adding the
following to your ~/.autotest:

  Autotest::Growl::one_notification_per_run = true

=== Show Modified Files

Add the following to your ~/.autotest if you would like to receive a Growl
notification listing the files modified before tests are re-run.

  Autotest::Growl::show_modified_files = true

== TROUBLESHOOTING:

=== Loading the Plugin Seems to Fail

Most likely you still have an old version of ZenTest <= 4.0.0 installed,
check it with:

  gem list ZenTest

To uninstall a specific version (e.g. 4.0.0), type:

  sudo gem uninstall ZenTest --version=4.0.0

Or remove all outdated versions of all installed gems:

  sudo gem cleanup

=== Unreliable Growl Notifications on Mac OS X

Under some circumstances, Growl notifications seem to be swallowed randomly
on Mac OS X. If this happens to you, try the following.

Add this to your ~/.autotest:

  Autotest::Growl::remote_notification = true
  
Now open "System Preferences -> Growl -> Network" and set the checkboxes
"Listen for incoming notifications" and "Allow remote application 
registration”. Try whether remote notifications work with the following
test:

  find /Library/Ruby /usr -name growlnotify -exec {} -H localhost -n autotest -m ok \;
  
If you get a NSPortTimeoutException, you should restart Growl and check
whether a firewall is blocking the connection. Once the notification is 
displayed, go back to the System Preferences and disable the checkbox
"Allow remote application registration" again.

== DEVELOPMENT:

You can install the bleeding-edge version as follows:

  sudo gem uninstall autotest-growl
  sudo gem install svoop-autotest-growl --source http://gems.github.com

Bleeding-edge gems contain a fourth version digit group (e.g. the .8 in 
0.1.5.8) to make sure Github builds the gem whenever new code is committed.
If there is no fourth version digit group, the edge version is identical
to the stable version from Rubyforge.

Please submit issues on:

https://forge.bitcetera.com/projects/show/autotest-growl

To contribute code, fork the project on Github, add your code and submit a
pull request:

http://github.com/guides/fork-a-project-and-submit-your-modifications

== CONTRIBUTIONS:

Thanks to the following folks who have contributed to this project:

* Michael Moen
* Graham Savage
* Karl O'Keeffe
* Konstantin Haase

== LICENSE:

(The MIT License)

Copyright (c) 2009 Sven Schwyn

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.