ScriptUnit Testing Application   v0.8
-------------------------------------
Write Unit Tests in a Script language.
http://www.xt1.org/ScriptUnit/

Write your unit tests in functions named TestXxxxx.
You do not need to write a main-line that calls the functions - ScriptUnit 
will do that for you, and will let you call individual functions if you want.

for example:  
MyFirstTest.vbs:

      sub TestSomething
	     Assert.IsEqual 1/2, 0.5
	  end sub

      sub MyProc
	     Assert.IsEqual "a", "b"
	  end sub

      sub TEST_SOMETHING_ELSE
	     Assert.IsEqual "a", "b"
	  end sub

The MyFirstTest.vbs file contains two test function: TestSomething and 
TEST_SOMETHING_ELSE. MyProc is not a test function, since the name does not start with "Test".

Test functions must not return values, and take no parameters. 
The name must start with the word "Test".
See Tests\Testing-subs.vbs for an example.

If you define function called "Setup", it will be called before every test 
function in the file.

If you define a function called "TearDown", it will be called after every 
test function in the file. It will be called even if the test function fails.

If an unexpected error occurs during Setup or Teardown, then the test as a 
whole will be marked as failed.


If you do not write any test functions in your script, then the mainline will 
be run, and if no unexpected errors occur, then the script will be marked as 
a successful test.  
See Tests\Testing.vbs for an example of this approach.




License
-------
ScriptUnit is Free Software, covered by the Lesser General Public license
See COPYING.txt for details.




How to debug with Script Unit
-----------------------------
ScriptUnit was created to test COM objects written in C++.
To illustrate how to do this you can use the TestObject project that is included
along with ScriptUnit.
(it's a VC++ 6.0 project, but the code should work on VS.net as well)

You can see there are two classes in the project: Good and Bad
Good implements the test interface correctly, while Bad does not.

There are two test scripts: TestObjectGood.vbs and TestObjectBad.vbs
The scripts are identical except for the object they create.

To use ScriptUnit to fix the Bad implementation you set ScriptUnit.exe to be
the process started when debugging the TestObject project.
(Project > Settings > Debug > Executable for debug session)

You can then set breakpoints in the Bad.cpp file and invoke the test functions.
As you fix the errors in Bad.cpp you will need to re-compile and re-link the 
object dll in order for the changes to be picked up in ScriptUnit.

If you exit ScriptUnit instead of killing the debug process in Visual Studio,
then the current set of files is saved in the registry, so that next time you
start ScriptUnit it will re-load the tests for you.

You can modify the test code without exiting the debugger by clicking EDIT in
the ScriptUnit GUI. Since the tests are just scripts they are easily modified
and tweaked to cover more testcases. As you debug, you will often discover new
test-cases that need to be considered. You can add new test cases to the file.

Hitting RUN will re-load the file and re-populate the tree with your newly added
test cases.




Script Unit Command Line
------------------------
/? /h			Help
/q				Quiet - do not show the GUI - runs the tests once automatically
/regserver		Register the COM components inside ScriptUnit.exe
/unregserver	Remove the COM components from the registry.
/log filename	Save a copy of the test results to an XML file. The XML format corresponds to NUnit.
filepath		Load the named script file.
dirpath			Load all the script files in the directory.

If no filepath or dirpath are specified, then the set of tests specified in the registry are loaded.
The list of tests in the registry is updated when the GUI exits.



Scripting Commands
------------------

The scripting language is primed with an Assert object that supports 
the following methods for checking the validity of your object.
If a check fails, then the message is logged and the script is stopped
and marked with an error (red ball).

When there are multiple variations grouped together (e.g. Equal/Equals/IsEqual) 
then they are synonyms with no difference except for syntax. Use the one 
which reads best for you.



Assert.IsTrue( expr, [msg] )
  expr is a boolean expression that should evaluate to TRUE.
  msg  optional message to note in the log if expr is false.

e.g.
    set db = CreateObject("Database")
    Assert.IsTrue db.Login("foo","bar"), "Login failed"
    


Assert.IsFalse( expr, [msg] )
  expr is a boolean expression that should evaluate to FALSE.
  msg  optional message to note in the log if expr is true.



Assert.Equal( a, b, [msg] )
Assert.Equals( a, b, [msg] )
Assert.IsEqual( a, b, [msg] )

e.g.
    v = LCase("Foo")
    Assert.IsEqual( "foo", v )



Assert.NotEqual( a, b, [msg] )
Assert.NotEquals( a, b, [msg] )
Assert.IsNotEqual( a, b, [msg] )

e.g.
    v = UCase("Foo")
    Assert.IsNotEqual( "foo", v, "upper and lowercase are the same" )



Assert.IsNothing( obj, [msg] )
Assert.IsNull( obj, [msg] )
   obj is an object expression that should be null/nothing.
   msg is an optional message for the log if the obj is not nothing.

e.g.
    set v = CreateObject("scripting.dictionary")
	set v = nothing
    Assert.IsNothing( v, "variable was not cleared" )



Assert.IsNotNull( obj, [msg] )
Assert.IsSomething( obj, [msg] )
   obj is an object expression that should not be null/nothing.
   msg is an optional message for the log if the obj is null.

e.g.
    set v = CreateObject("scripting.dictionary")
    Assert.IsSomething( v, "object was not created" )
	set v = nothing
    Assert.IsNothing( v, "variable was not cleared" )



Assert.ExpectError [errormsg]
   errormsg is an optional partial error message you expect to be raised.
   This means that if the next error that occurs contains the errormsg in 
   its description, then the error will be ignored.

e.g.
    Assert.ExpectError "division by 0"
    x = 1 / 0
    Assert.Trace "should not reach this point - should have got error by now"



Assert.Failure( [msg] )
Assert.Error( [msg] )
   Reports an error to the framework. Useful for "Not-implemented" tests and 
   "Should not get here" type tests.
   Note that this type of error can never be expected. 
   i.e. ExpectError won't catch the error signaled by this.

e.g.
	dim x
    x = 1 / 0
    Assert.Error "should not reach this point - should have got error by now"