TESTME(1) User Commands TESTME(1)
NAME
testme - TestMe -- Utility to run unit tests
SYNOPSIS
testme
--chdir dir
--clean
--clobber
--compile
--continue
--debug
--depth level
--ide
--log logSpec
--noserver
--projects
--quiet
--rebuild
--show
--trace traceSpec
--version
--verbose
--why
[filters ...]
DESCRIPTION
TestMe is a dynamic unit test runner. It will traverse a directory tree
and automatically build required unit tests and run them with output to
the console.
Unit tests are stand-alone programs that have a '.tst' extension after
the normal file extension. For example, a C unit test file would be
named 'file.c.tst', while an Ejscript unit test file would be named
'file.es.tst' and a shell script test would be named 'file.sh.tst'.
Test parameters are passed to unit tests as environment strings with a
'TM_' prefix. Unit tests emit results to their standard output and are
captured by TestMe. Unit tests emit results via a 'pass' or 'fail'
command depending on the test results. Unit tests can control the sub-
sequent execution of tests via a 'skip' command and can write output to
the TestMe console via a 'write' command. Unit tests can define values
in the environment for subsequent tests by emitting a 'set' command
(see below).
TestMe will automatically compile and recompile C unit tests as
required. Ejscript unit tests can be run directly without recompila-
tion.
OPERATION
When TestMe is invoked, testme traverses the current directory tree
looking for unit test files. At each directory level, it first runs
any setup test files that have a '*.set' extension. The purpose of set-
up files is to define the environment and configuration for all tests
at or below that directory level.
Next, TestMe will compile any Ejscript common files with a '*.es.com'
extension. The purpose of common files it to define shared code that
will be used by Ejscript unit tests. Common files should wrap all
script in a 'module' directive of the same name as the file without
extensions. For example: 'support.es.com' would use 'module support {
/* code */ }'. The compiled common file will be placed in a generated
'testme' directory.
For all C unit tests with a '*.c.tst' extension, TestMe will first cre-
ate a 'testme' directory with a MakeMe file for the unit test. It will
then use MakeMe to build the unit test into a stand-alone executable.
When all is ready, TestMe will run all unit tests with a '*.tst' exten-
sion. For subdirectories, TestMe will recurse and run unit tests in
those subdirectories. The aggregated environment is passed down to unit
tests in subdirectories. Note that if a unit tests uses the 'set' com-
mand to define a key value in the environment, it will only be passed
to unit tests at that directory level or below.
TEST ENVIRONMENT
TestMe communicates test parameters to unit tests via the environment.
TM_INB -- Set to the local binary directory.
TM_DEBUG -- Set if testme invoked with --debug. Run in debug
mode.
TM_DEPTH -- Set to the test depth instructed via --depth.
TM_DIR -- Set to the directory containing the test.
TM_NOSERVER -- Set if testme invoked with --noserver. Do not run
server-side programs.
TM_OUT -- Set to the build output configuration directory.
TM_PHASE -- Set to 'Setup', 'Finalize' or 'Test'.
TM_TOP -- Set to the top directory for the project.
TM_* -- All defines in the me.h are converted to TM_
defines.
TEST OUTPUT
A unit test should emit results to the standard out. The following com-
mands are supported.
fail reason ...
info message ...
pass
set key value
skip reason ...
write message ...
A 'fail' command will typically terminate a test run unless testme is
invoked with --continue. A 'pass' command will be counted and if no
'fail' commands are emitted by the unit test, the unit test will be
PASSED. An 'info' command will echo information message to the testme
output. A 'write' message will write raw messages to the testme output.
A 'set' command will define a key in the environment that is passed to
subsequent unit tests. The 'skip' command will cause all subsequent
unit tests in or below the current directory to be skipped.
TESTME UNIT TEST C API
The follow C API is supported for C unit tests.
bool ttrue(expression);
bool tfalse(expression);
bool ttest(cchar *loc, cchar *expression, bool success);
cchar *tget(cchar *key, cchar *def);
int tgetInt(cchar *key, int def);
void tinfo(cchar *fmt, ...);
void tset(cchar *key, cchar *value);
void tskip(bool skip);
void twrite(cchar *fmt, ...);
OPTIONS
--chdir dir
Change to the given directory before running tests.
--clean
Clean the contents of all generated 'testme' directories.
--clobber
Remove all generated 'testme' directories.
--compile
Compile required C unit tests but do not run. Use --rebuild to
force a recompile regardless of whether the unit test file has
been updated or not.
--continue
Continue to run tests despite any previous errors. Normal opera-
tion is to stop testing if any tests fail.
--debug
Run in debug mode. Sets TM_DEBUG in the environment.
--depth level
Set the unit test depth level.
--ide Run the specified test in an IDE debugger. Supported on Mac OSX
only.
--log logName[:logLevel]
Specify a file to log test messages. TestMe will normally dis-
play test output to the console. The --log option will redirect
this output to the specified log file. The log level specifies
the desired verbosity of output. Level 0 is the least verbose
and level 5 is the most.
--noserver
Do not run server side support code. This emits TM_NOSERVER into
the environment for unit tests.
--projects Generate IDE projects for the specified unit tests.
At least one test must be specified by name on the command line.
The IDE projects are generated in the 'testme' directory.
--quiet
Run in quiet mode without trace.
--rebuild
Force a recompilation of all C unit tests.
--show Show the actual commands executed by TestMe.
--trace logName[:logLevel]
Specify a file to trace HTTP requests. The level specifies the
desired verbosity of output. Level 0 is the least verbose and
level 5 is the most.
--version
Print the ejs command version and exit.
--verbose
Run in verbose mode with more trace about TestMe activities.
--why Display why various tests were run or not and why actions were
taken.
REPORTING BUGS
Report bugs to dev@embedthis.com.
COPYRIGHT
Copyright (C) Embedthis Software. TestMe and Ejscript are a trademarks
of Embedthis Software.
SEE ALSO
me pak
testme January 2014 TESTME(1)