How to run the script

There are two simple ways and one complicated way to use this script to run tests of Python files in Blender.

Simplest

The simplest way to run the script is:

1. "cd" to a directory containing your Blender Python scripts.  Note that there can be subdirectories inside this directory also containing Python scripts.
2. Run Blender this way:
   
   <blender_executable> -P runtests.py
   
   
3. The runtests.py script will find all files with a .py extension in the current directory, and run each one.
4. For each script it finds, the runtests.py script will create a result file named "<scriptname>.result" (e.g. "test1.py.result"), capture all the text output from the test script into that file, and attempt to compare that file with another file named "<scriptname>.baseline".  If there is no baseline file, or the files don't match, the runtests.py script reports a "FAIL", otherwise it reports a "pass" (into the CMD/console/shell window).
5. When all the py files have been run, the runtests.py script quits Blender and reports a summary of tests passed and failed.
6. If you need to load a .blend file before running Python scripts, run it as:
   
   <blender_executable> <.blend-file> -P runtests.py

Script requirements

Each Python script must:

• be self contained, e.g., it must not depend on any state of any kind
• be independent of all the other tests
• finish (e.g., not wait for input)

A test script does not have to output any text (in which case the result and baseline files are empty), but even just a

print "done!"

at the end of the script would be nice for some kind of a baseline, which would verify that the script at least finished without crashing or major errors.

Less Simple [NOTE: this is no longer supported as of 01.Aug.2004]

You can also have the runtests.py script fire off Blender for each test script.  That is, instead of running runtests.py "inside" of Blender, you can run Blender "inside" runtests.py.

1. In the runtests.py script, comment out all lines containing the text string "Blender-specific:"
2. "cd" to a directory containing your Blender Python scripts.
3. Run the script this way: python runtests.py "<blender_executable> -P".  You must use the quotes!
4. The runtests.py script will fire off Blender once for each py script it "finds".  It will create a temporary copy of each script with the "Blender.Quit()" command at the end so that you don't end up with multiple copies of Blender running.

The downside of this method (as opposed to the first) is this: if you have an error in a python script that causes Blender not to "reach" the "Quit" command in the edited version of the test script, execution stops, and you must manually close Blender for the test suite to continue.  This does not happen with the first method described above. I added this second option because I'm not sure if running multiple Python scripts "inside" another script (e.g., runtests.py) will cause objects to stay around, which might mean that one test would affect the next (or memory might fill up).  This method is also slower, in that Blender must be fired up and shut down for each test script.

Complicated

If you really want to use a command file to pick specific Python scripts instead of just doing a "find", you can read on.

Command file [needs to be updated to reflect latest changes, e.g., trust the code, not the documentation]

The input file required by the test bed Python script has the following format.  Each line begins with a character which is the separator character for that line.  You can use <space> for the separator as long as none of your parameters contain a space (pathnames are the most likely to cause this problem). Blank lines are ignored. Each non-blank line consists of a command followed by zero or more parameters.  There is an example file here.  The following commands are recognized:

comment

Ignore the line.  For example:

#comment#This line contains a comment.

debug

Turns on some debug/dump code by setting the debuglevel (anything > 0).  For example:

#debug#1

echo

Just echos the parameter to stdout.

#echo#This will appear in the console.

programtorun

Runs a program (really a whole command line) after appending the script name to it, instead of running the Python script directly.

runfile

Run the Python script file specified in the command.  If there is a second parameter, compare the output from the Python script file with the file specified in the second parameter.  NOTE: Each file must have a main().  For example:

#runfile#test1/test.py#test1/baseline.txt

setrootdirectory

For all succeeding "runfile" commands (up to another "setrootdirectory"), take the path/filenames specified in the "runfile" command as relative to the root directory specified pointed-to by the environment variable in this command. This isolates directory name changes, such that a user can put their test directory wherever they want, and just change this one line instead of multiple path/filenames.  For example:

#setrootdirectory#blenderroot

setrootsite [NOT YET IMPLEMENTED]

For all succeeding "runlink" commands (up to another "setrootsite"), take the links specified in the "runlink" command as relative to the root site specified in this command.  For example:

#setrootsite#http://home.pacbell.net/c_keith/blender/tests

runlink  [NOT YET IMPLEMENTED]

Run the Python script file at the links specified in the command.  If there is a second parameter, diff the output from the Python script file with the line specified in the second parameter.  For example:

#runfile#test1/test.py#test1/baseline.txt

Notes:

You can use <space> as the separator for a comment line, because all of the "parameters" will be ignored anyway.

Last Modified: Sunday, August 01, 2004