Cleanup comments

to explain the "why" rather than the "what".
stbt: Consistent error handling: Raise RuntimeError instead of exiting

In some of these cases the stack trace from the exception won't be that
useful, because it comes from a bus message handler; but at least all
of stbt.py handles errors in the same way.

Maybe in future we will wrap everything in a try block so that we can
print pretty error messages, with the stack trace only shown when
verbose output is enabled; for now, our users will have to put up with
python's default printing of exceptions.
stbt run: Fail if wait_for_motion mask image isn't found on filesystem

In the same manner that we fail if the wait_for_match template image
isn't found.

Note that I simplified the "if" test; I think it is unlikely that any
other element will issue exactly this error message, and this way
simplifies the code a bit.

See also the notes in commit message 71071b6.
stbt run: Search for images in all the caller's directories

detect_match, wait_for_match, press_until_match, detect_motion and
wait_for_motion no longer take the optional "directory" argument;
instead, they search for the given template or mask image in their
caller's directory, then in their caller's caller's directory, etc.

Commit e5133f0 added the optional "directory" argument to
press_until_match, just like wait_for_match and detect_match already
took. This was so that press_until_match could be called from a helper
function that resides in a different directory than the image to match.
For example:

   def find_player(image):
       # some complicated logic to get to the players menu
       press_until_match("RIGHT", image,
                         directory=_caller_dir())

without the `directory` argument, press_until_match would look for
`image` in the directory containing the python script that defines
`find_player`, instead of the directory of find_player's *caller*.

The current commit avoids this whole rigmarole of passing the directory
from one function to the next, by having detect_match iterate over its
callers' directories, searching for the template image (and the same for
detect_motion when searching for the mask image).

WARNING: libraries of functions like the "find_player" example above
must take care not to contain images with commonly-used names in the
same directory as the library python file. Give the image filenames a
prefix based on the library name.

Note that this commit also adds additional checks for the existence of
the file, and raises a UITestError immediately if the file doesn't
exist. This is in addition to the checks done by the GStreamer elements,
which will emit a bus message, handled by stbt.py's
`Display.on_warning`. The new exception fails immediately and provides a
more useful stack trace (`on_warning` is called later, from the
application main loop). I've kept the checks in `on_warning` in case the
GStreamer element detects further errors with the image (maybe it exists
but isn't readable, or it isn't a valid image or mask, etc).

Note that this commit introduces the UITestError exception, for bugs in
the stbt test scripts. There is an existing UITestFailure exception for
legitimate test failures, i.e. when the tests script behaves as expected
but the system under test doesn't. (MatchTimeout and MotionTimeout are
UITestFailures.)
run-tests.sh: `-l` option to leave the scratch dir created in /tmp

Sometimes I want to see the logs left behind by a *successful* test run,
to check that the selftest framework isn't reporting failures as
successes.
run-tests.sh: Print to stdout the log for failed tests

I run "make check" from a Jenkins job, and this way I can see the log
for failed tests directly in the Jenkins log (via the Jenkins web
interface) instead of having to ssh to the Jenkins server and find
the logfile in /tmp/stb-tester.XXX/log.

Right now this will help me debug a failure in
test_wait_for_match_nonexistent_template that is only happening on
Jenkins, not when I run "make check" locally.
run-tests.sh: "-v" (verbose) flag

`run-tests.sh -v` will print the output from the test cases, even when
the test cases pass. This is useful for debugging test cases that are
reporting a pass when they are really failing. Having run-tests.sh print
the output directly saves me from hunting for /tmp/stb-tester.XXX/log.
run-tests.sh: "timeout" function reports error when command not found

This will help me to debug simple mistakes like forgetting to set the
PATH to find stbt-run. (The PATH is set correctly by "make check", but
sometimes I run run-tests.sh directly.)
selftests: Increase timeouts for tests expecting stbt-run to fail

Sometimes it takes several seconds for the GStreamer pipeline to launch,
so the "stbt-run" command was being timed out before it had a chance to
fail.

I haven't upped the timeouts for the tests in
test-{motiondetect,templatematch}.sh, which use a plain "gst-launch"
(instead of "stbt-run"), because those are 2 seconds we have to wait for
every single test run (as opposed to the "stbt-run" tests, where we are
expecting stbt-run to fail, and the full timeout time will only be spent
if stbt-run doesn't behave as expected). Maybe gst-launch can take more
that 2 seconds to initialise the plugin registry, get the ximagesink up
and running, etc. but I imagine that if it gets that far it's probably
going to work; those tests will still catch problems where the stbt
plugin isn't on the GStreamer search path, etc.
stbt run: Don't require an X display

Unless you set "--sink-pipeline=ximagesink", of course.

Before this commit, running "stbt run --sink-pipeline=fakesink", or even
"stbt run --help", tried to connect to an X display.

In our test farm we run stbt headless with "sink-pipeline=fakesink"; now
we can run "stbt run" from an ssh session without having to worry about
setting the DISPLAY environment variable or configuring the X server
access control with xhost.

Before this commit, "stbt run" *would* work if it couldn't connect to
the X display, but it printed an ugly "GtkWarning" message.

We only used gtk for its main() and main_quit() functions, which are
merely wrappers around glib's main loop. So now we use the glib
functions directly, and avoid any X display initialisation that happened
at "import gtk" time.
selftests: test_record is correctly reported as failing

This test has been failing since eda17239, which added "-v" to the call
to "stbt record". In fact only "stbt run" takes "-v".

I will fix the failure in a future commit; now at least the test is
correctly reported as failing.
stbt record: also takes "-v" argument

Commit eda17239 added the "-v" flag for verbose debug output; the
intention was to add the flag to both "stbt run" and "stbt record", but
it only added it to "stbt run".

This commit makes "stbt record" also accept the "-v" argument. Now the
selftest "test_record" (in tests/test-stbt-record.sh) passes.

Also updated the README/manpage to clarify that "-v -v" only applies to
"stbt run".
stbt.ConfigurationError inherits from stbt.UITestError

ConfigurationError still inherits (indirectly) from Exception.

Now all the exceptions explicitly raised by stbt are UITestFailure
(MatchTimeout, MotionTimeout) or UITestError.
Add {Match,Motion}Result and exception classes to "stbt run" public API

These names are now exposed directly in the script's namespace, so the
script can say "except MatchTimeout" instead of "import stbt; except
stbt.MatchTimeout".

You could argue that "stbt run" shouldn't expose *any* names to the test
script, and you should always have to write "import stbt" in the script.
But at least now there is consistency between MatchResult, MatchTimeout,
etc., and wait_for_match etc.
README: Add (autogenerated) documentation for all user-visible python functions

Each time you modify one of the docstrings in stbt.py, the next time you
run "make doc" it will update README.rst; before committing you will
notice the change, and commit it together with your changes to stbt.py.
That's the theory, anyway. :-)

pydoc is part of the standard python distribution.

Note that "press" used to take an unspecified number of arguments and
just passed them on to the particular "control" implementation; but all
implementations only take a single argument, "key". The argument to
"press" needs to be stated explicitly now, so that it appears in the
README.

Note that I had to wrap the namedtuples (MatchResult etc) in a class so
that I could attach a docstring. See
http://stackoverflow.com/questions/1606436/
"make check" should build libgst-stb-tester.so

Otherwise if you did "make clean; make check" you ended up testing an
old version of the plugin previously installed on the GStreamer search
path.
.gitignore OS X ".DS_Store" files
rpm spec file: Bump stb-tester version to 0.7
Makefile: Always generate version number from the *stb-tester* repo

I have a Jenkins server set up that builds the stb-tester RPM for me.
The configuration for that Jenkins job lives in its own git repo.
The job was untarring the stb-tester tarball (with its VERSION file)
inside a checkout of the jenkins-job-configuration repo, so when
the stb-tester Makefile tried to determine the version from the git
tags, it was looking at the history for the jenkins-job-configuration
repo instead of the history for the stb-tester repo.

This change causes the "git describe" to fail in the scenario just
mentioned, so the stb-tester Makefile picks up the version number
from the VERSION file (shipped with the tarball) as intended.