Overview

Blunderbuss: brute-force automated testing.

Blunderbuss provides two components: an HTTP-RPC server, which exposes
functions such as `mouseMove`, `click` and `dragTo`, and a client library,
which provide a native ActionScript interface to these functions (client
libraries targeting more languages, especially HTML/JavaScript, are planned but
not yet implemented).


== The Goal ==

The goal of Blunderbuss is to provide a framework which will provide developers
a robust interface for scripting realistic interactions with their application.

The key words here are "realistic" and "robust".

Existing high-level testing libraries (for example, Selenium and FlexMonkey)
can simulate some kinds of interaction, but it is just that: a simulation.  For
example, because they do not generate a "real" mouse click, click handlers
which require x/y coordinates of a click cannot be tested.

Additionally, the scripted interactions will be robust: the client libraries
will allow developers to describe "what" they want done, and let the
Blunderbuss calculate where to click.  For example, instead of a calling
"click(52, 45)" to click on the first row of a table, the JavaScript client
library may accept JQuery-style selectors: "click('#someTable > tr:first')".

For example, this is the script that might be used to test dragging and
dropping between Flex DataGrids:

    var runner:BlunderRunner = BlunderRunner.connectTo(someService);
    runner.targeting(dataGrid(firstDataGrid).row(3))
        .mouseDown()
        .dragTo(dataGrid(secondDataGrid).row(4).tweak(5, 0))
        .drop()
        .call(checkDragDrop);

== Running Blunderbuss ==

To run blunderbuss, you will need to install a few dependencies and build a
.java file.


=== Dependencies ===

Blunderbuss depends on Java and Jython 2.5, which is available here:

    http://www.jython.org/

And, after it is installed, make sure that `jython` exists in $PATH. If you
chose to install Jython as a single .jar, run:

    $ cat <<EOF > jython
    #!/bin/sh
    java -jar "/path/to/jython.jar" $*
    EOF
    $ chmod +x jython
    $ sudo mv jython /usr/local/bin

Test your jython installation by running, at the prompt, "jython":

    $ jython
    Jython 2.5.0 (Release_2_5_0:6476, Jun 16 2009, 13:33:26) 
    [Java HotSpot(TM) Client VM (Apple Inc.)] on java1.5.0_19
    Type "help", "copyright", "credits" or "license" for more information.
    >>>


=== Building ImageFinder ===

In the blunderbuss source directory, run `make` to build ImageFinder (or, if
you don't have make installed, simply run `javac ImageFinder.java`).


=== Running the test suite ===

The best way to see Blunderbuss in action is to run the test suite. From the
blunderbuss directory, run:

    $ jython tests.py

After a moment, a window should briefly appear, and your mouse will click a
button and drag a slider. That's Blunderbuss in action!


=== Running the server ===

To run the blunderbuss server, simply:

    $ jython blunderbuss.py
    Starting server on port 8008

Then, in another shell, test it by running the demo client, demo.py:

    $ jython demo.py