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)