io7m-blueberry 0.4.0 Documentation
Package Information
Orientation
Overview
Well-written software typically has hundreds or thousands of
automated tests. The tests are run as part of the build process
and any failure indicates broken software. Developers typically
assume that a program that passes all of its own tests is working
correctly. Unfortunately, when the program is executed by end-users,
differences in the environment in which the program runs often
uncover new problems .
Ideally, developers would like every end-user to be able to
exhaustively test programs on their own systems. Unfortunately,
this would require the end-users to have access to the program's
source code and would also require them to install development
tools. The latter is out of the question for most end-users (if
development tools are even available on their platform), and the
former is out of the question for many developers.
The blueberry package attempts to
solve this problem by implementing a system that allows
non-technical users to participate in unit testing without having
access to source code and without having to install any development
tools.
Installation
Source compilation
The project can be compiled and installed with
Maven:
Maven
Regular releases are made to the
Central Repository,
so it's possible to use the
blueberry
package in your projects with the following Maven dependencies:
<dependency>
<groupId>com.io7m.blueberry</groupId>
<artifactId>io7m-blueberry-core</artifactId>
<version>0.4.0</version>
</dependency>
<dependency>
<groupId>com.io7m.blueberry</groupId>
<artifactId>io7m-blueberry-gui</artifactId>
<version>0.4.0</version>
</dependency>
Platform Specific Issues
There are currently no known platform-specific issues.
License
All files distributed with the
blueberry
package are placed under the following license:
Copyright © 2013 <code@io7m.com> http://io7m.com
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Usage
Overview
Prerequisites
Most software projects proceed through the following steps (for
a hypothetical project P):
Unfortunately, most projects also move through a subsequent step
consisting of the end-users discovering software bugs that would
have been discovered by the unit tests had they only been executed
on the end-user's computers.
In order to use the blueberry package,
the following steps are required instead:
Note that unit tests are included, in compiled form, with the
package delivered to end-users. The package is also integrated
with
blueberry in some manner. The
precise meaning of "integration" is up to the developer using the
package, as there are numerous optional parts to the
blueberry package).
Most developers will probably want to use the
blueberry
GUI
in order to present end-users with a friendly GUI
interface for running tests.
The first step, therefore, is for the developer to arrange for
unit tests in his/her project to be included with the final
compiled package. The precise details of how to do this
are obviously project-specific and out of the scope of this
documentation. In the case of projects compiled with
Maven,
it's simply a case of producing a
test-jar
and then adding this jar file to the classpath along with the rest
of the dependencies of the project in question.
Structure
Overview
The
blueberry package consists
of four main components: the
test scanner, the
JUnit runner, the
GUI, and the
report format.
Each of the components are essentially optional; a developer using
the
blueberry package can use as
much or as little of the package as desired. The components of the
blueberry package form a rough
pipeline:
Test scanner
The
test scanner uses the
Reflections
package to inspect all classes and jar files on the current
classpath and return the set of all classes that contain runnable
JUnit
tests.
Developers will not usually use the
test scanner directly; it is used
by the
GUI
to determine which tests to run.
The functionality of the test scanner is implemented in the
TestScanning
class.
JUnit runner
The
JUnit runner runs all tests
in the given set of classes. Usually, the set of classes is obtained
from the
test scanner
but the developer can specify classes manually if desired.
Developers will not usually use the
JUnit runner directly; it is used
by the
GUI
to execute tests.
GUI
The
GUI package provides a
friendly and configurable graphical interface to the
JUnit runner.
The GUI interface
can be instantiated for any project by writing a very simple
"main" program using the various GUI classes. The
io7m-blueberry-gui-example
package provides a sample application consisting of the
following code:
With the above code, the following test application is produced:
The resulting application automatically scans all classes on
the classpath that exist within the com.io7m.blueberry
package (and children of that package). It runs the tests and
allows the user to save an XML report of the results. It also
provides an "information" page containing the project's logo,
version, and URI.
Report format
The JUnit runner can serialize
results into a well-defined XML format. The reports contain
very detailed information about the tests: The elapsed time of
each test, the output produced on the standard out and standard
error streams, full traces of any and all exceptions (including
all of the causes of a given exception), and optionally a full
dump of the JVM's system properties and environment variables.
The reports can be validated against a schema to allow for
automated processing of reports. The RELAX-NG schema of the format
is as follows:
API Reference
Javadoc
API documentation for the package is provided via the
included
Javadoc.