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
       subsequent 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 recompilation.

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 setup


       When all is ready, TestMe will run all unit tests with a '*.tst'
       extension. 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'
       command 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
       commands 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);
              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
              operation 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 display
              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


       --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 © Embedthis Software. TestMe and Ejscript are a trademarks of
       Embedthis Software.

SEE ALSO

       me pak



testme                            January 2014                         TESTME(1)