BlitzUnit - 0.1 (11th June, 2008)
=================================

Quick Links
-----------

Project Homepage: http://www.sodaware.net/dev/tools/blitzunit/
Bug Tracker:      http://bugs.sodaware.net/
Documentation:    http://docs.sodaware.net/blitzunit/


Contents
--------

   1)  What is BlitzUnit and why use it?
   2)  Installing
   3)  Creating tests
   4)  Unit test example
   5)  Running BlitzUnit in windowed mode
   6)  Running BlitzUnit in console mode
   7)  Command line switches
   8)  Quick function reference
   9)  Licence


1) What is BlitzUnit and why use it?
------------------------------------

BlitzUnit is a simple tool for creating and running unit tests for the Blitz
series of languages (Blitz3D and BlitzPlus). 

Unit tests are a way for software developers to verify that the software
they write behaves in an expected way. This is particularly useful when
refactoring software, as changes that break the expected behaviour can be
found quickly.

If you've ever written the contents of a variable to the screen to check a 
function did what it was supposed to, then you've written a very simple 
test. Wouldn't it be nice to be able to keep these tests outside of the main 
application source code and run them automatically? 

That's where BlitzUnit comes in.


2) Installing
-------------

Each release of BlitzUnit comes in two forms: an installer and a zip file.

You will need at least one version of Blitz installed your machine to use
BlitzUnit, as it requires the compiler to run tests.

To install from a zip file, extract the contents to a new folder. You will
need to copy "BlitzUnit.decls" to the "userlibs" folder of your Blitz 
installs. To enable documentation help in the Blitz IDE, copy the contents
of the "Blitz Docs" folder (but not the folder) to Blitz your documentation 
folder. For example: "BlitzPlus\help\commands\2d_commands".

The setup screen will be shown the first time BlitzUnit is run, which will
allow you to setup paths to your compilers.


3) Creating tests
-----------------

Before using BlitzUnit, you'll want to create some test files. These are
small pieces of Blitz code that are set out in a certain way and will be
loaded by BlitzUnit.

All test files must contain the following elements:

    * Test Fixture
        This is a Type that contains information used by 
    * Test Functions
    * Assertions
	
Optional elements:
    * Setup function
        A function called "Setup" that takes a test fixture object named
        "this" as a parameter and initialises any data within it. For 
        example, it could create banks used within the tests.
    * TearDown function
        A function called "TearDown" that takes a test fixture object named 
        "this" as a parameter and cleans up anything created in the Setup 
        function. For example, it would free the bank created by "setup".

IMPORTANT: There should only be one type defined in a test file (the test 
fixture), and only functions that are used as tests (with the exception 
Setup and TearDown). 

See the following example for how a test file is laid out, and what it can
do.


4) A detailed example
---------------------

The simplest way to see how it all works is to write a test fixture and see
what happens. 

In this (rather contrived) example, we want to check that our function 
"concat" will join two  strings together with a space between them. HOWEVER, 
if either argument is empty the function should return the non-empty 
argument. White space should be preserved in all cases.

~*~

concat.bb - Deliberate bug

Function concat$(part1$, part2$)
    return part1 + " " + part2
End Function

~*~

You'll notice the function above as a bug in it. It doesn't check for empty
arguments, so it won't behave as it should. Let's see if our testing catches 
that.

~*~

concat_tests.bb

include "concat.bb"

Type Example_ConcatTests
    Field arg1$, arg2$, expected$
End Type

Function Setup(this.Example_ConcatTests)
    this\arg1     = "Hello"
    this\arg2     = "World"
    this\expected = "Hello World"
End Function

; Test to see 
Function NormalStringsTest(this.Example_ConcatTests)
    Assert_StringsAreEqual(this\expected, concat(this\arg1, this\arg2))
End Function

; Test empty strings
; Note nothing is passed to the function, as BlitzUnit will automatically
; update the function definition.
Function EmptyStringTest()
	Assert_StringsAreEqual(this\arg1, concat(this, this\arg1, "")) 
End Function

Function WhiteSpaceIsPreservedTest()
	Assert_AreStringsEqual(this\expected + " ", concat(this\arg1, this\arg2 + " "), "")
End Function 

~*~

The first test passes with the expected behaviour, but the second test fails
because "Hello " is returned instead of "Hello". 

One solution might be to use "Trim" on the return value, so let's add another
test to see what happens.

~*~

concat.bb - Another deliberate bug

Function concat$(part1$, part2$)
    return Trim(part1 + " " + part2)
End Function

~*~

Now the "Empty String" test passes, but the whitespace test fails. Let's try
again...

~*~

concat.bb

Function concat$(part1$, part2$)
	If part1 = "" then return part2
	if part2 = "" then return part1
	
	return part1 + " " + part2
End Function

~*~

Phew, everything passes!

Hopefully such a long-winded example hasn't put you off from unit testing!
With just a few short tests, you can quickly check that your function is
behaving the way it should.

More samples can be found in the "examples" folder.


5) Running BlitzUnit in windowed mode
-------------------------------------

The windowed mode of BlitzUnit is the quickest and easiest way to begin
running unit tests. Start BlitzUnit to be presented with the main window. 
From here you can create new projects (a collection of unit test files) and
run them interactively.

The main form is divided into 4 tabs:

    i) Test Hierarchy -- A view of the project divided into fixtures and 
        unit tests.
    ii) Project View -- A file view of the project, divided into files and
        their tests.
    iii) Raw Output -- Simple output of unit test execution results.
    iv) Log Output -- Pretty view of the unit test output.

Each test has an icon to show its status:

    * Grey circle - Test has not been run
    * Red Exclamation - Test fails
    * Yellow Triangle - Test file contains errors
    * Green Tick - Test passes

To find compilation errors, use the Raw Output tab to view the complete log.


6) Running BlitzUnit in console mode
------------------------------------

BlitzUnit can also be run as a console application by passing "--console"
when running it. You will also need to specify a test file or test project
to load and execute.

Example: "BlitzUnit --console /project my-project.bunit"

This will run BlitzUnit in console mode and execute all tests in the project
"my-project.bunit".

Each test will return one of the following characters:

    . -- The test has passed
    F -- The test failed
    e -- The test file contains errors

Any errors will be displayed once all tests have completed.


7) Command Line Switches
------------------------

Quick overview of command line switches/parameters:

  Command Line Parameters:

    * /p or /project    - The name of the project file to load and run.
    * /i or /input      - The name of the individual test file to load and
	                      run. Not required if /p is specified.
    * /l or /log-file   - [optional] The filename of the log to write to.
    * /f or /log-format - The format of the output log (use "txt" or "xml").
    * /x or /xsl-name   - Optional XSL stylesheet for XML logs
	
  Command Line Switches:
	
    * -c or --console   - Use BlitzUnit in console mode instead of GUI mode.
    * -s or --silent    - Suppresses output to the console.
    * -a or --auto      - Automatically quit the app when tests finish.
    * --stdout          - Use stdout for messages (for capturing app output)


8) Quick Function Reference
---------------------------

Assertions are used to check if something worked as expected. Each assertion
takes three arguments - the expected result, the actual result and an error
message to write in the log if the test fails. Use "" to display no message.

The following assertions are available:

    i) String Assertions (case sensitive)
        
        Assert_AreStringsEqual(expected$, actual$, message$)
        Assert_AreStringsNotEqual(expected$, actual$, message$)

    ii) Integer Assertions
	    
        Assert_AreIntsEqual(expected%, actual%, message$)
        Assert_AreIntsNotEqual(expected%, actual%, message$)

    iii) Floating Point Assertions
	    
        Assert_AreFloatsEqual(expected#, actual#, message$)
        Assert_AreFloatsNotEqual(expected#, actual#, message$)

    iv) Bank Assertions (checks the contents of the bank too)
        
        Assert_AreBanksEqual(expected%, actual%, message$)
        Assert_AreBanksNotEqual(expected%, actual%, message$)

    v) Object Functions (call using Handle(myObject.Object))
	    
        Assert_IsNull(objHandle%, message$)
        Assert_IsNotNull(objHandle%, message$)

Full documentation is available online in HTML format at the following URI:
    http://docs.sodaware.net/blitzunit/


9) Licence
----------

This program is free to use without restriction, and may be freely
distributed provided all documentation is included in an unmodified
state.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
