Shake
A Simple Lua Test Engine

## Examples

### Running Shake in the command line

Assuming you have a module like LuaFileSystem installed and you go to its `/tests` directory and run Shake from there, the output would be:

    ~/workspace/luafilesystem/tests$ shake
    ->  test.lua OK!
    _________________

    Tests: 27
    Failures: 0
    Errors: 0

On the other hand, if you have a test script like the one below that includes two assertions that are supposed to fail (lines are numbered):

     1	items = 10
     2	-- checks the correct case
     3	assert (items == 10, "this should not fail")
     4
     5	items = 20
     6	-- checks an overflow case
     7	assert (items == 10, "wrong number of items")
     8
     9	print("Verifying the total")
    10	items = 10
    11	total = 30
    12	assert (items == total, "wrong total")

Shake would register the failures but would run the whole test script, reporting at the end:

    :~/workspace$ shake
    ----------------    test.lua failed!   ----------------

    -- checks an overflow case
       #7 assert (items == 10, "wrong number of items")
       items -> 20

    Verifying the total
       #12 assert (items == total, "wrong total")
       items -> 10
       total -> 30
    _________________

    Tests: 3
    Failures: 2
    Errors: 0

Note how much more informative this is when compared to the default output of running the test script with Lua:

    :~/workspace$ lua5.1 test.lua
    lua5.1: test.lua:7: wrong number of items
    stack traceback:
            [C]: in function 'assert'
            test.lua:7: in main chunk
            [C]: ?

### Implementing a simple Shake runner

Here we show how to use the Shake API to implement runners. Note that if you just want to execute tests, the built in runners (command line and CGILua app) may be enough. On the other hand, if you need to show more detailed information about the tests results or if you want to use Shake as part of your application runtime, then you will need to use the Shake API.

The minimal Shake runner would be like:

    require "shake"
    local run = shake.runner()
    run:test("somefile.lua")
    print (run:summary())

This would be basically equivalent to the command line Shake runner, and if you want to report more details than the default summary does, you will need to drill down the results using something like:

    function ReportModules(run)
       local results = run.results
       for cs, suite in ipairs(results.suites) do
           -- displays information about the suite.title
           if suite.error then
    	-- displays information about the suite error
           elseif suite.failed > 0 then
    	-- displays information about the suite.failed results
           else
    	-- displays information about the suite.passed and suite.failed results
           end
       end
    end

For even more details, you may want to inspect each test result and decide what to show:

    function ReportModule(run)
      local results = run.results
      for _, suite in ipairs(results.suites) do
        if suite.error == -1 then
          -- displays information about the error
        else
          for _, context in ipairs(suite.contexts) do
            if next(context.tests) then
              if context.output[1] ~= "" or context.comments then
                -- displays information about the context
                for _, output in ipairs(context.output) do
                  if output and output ~= "" then
                    -- using context.output
                  end
                end
                if context.comments and context.comments ~= "" then
                  --  or context.comments
                end
              end
              for _, test in ipairs (context.tests) do
    	  local linenumber = test.linenumber or "???"
    	  local op = test.op
    	   local val2 = tostring(test.val2)
    	  -- when there is no comparision operator, assume that this is an assert(x) case
    	  if not op then
    	    val2 = "True value" -- just to diferentiate from the Lua "true"
    	  end
    	  if not op or op == "==" then
    	    op = ""
    	  end
    	  -- displays information about the test result using
    	  -- linenumber, test.exp1, op, val2, test.val1 and test.msg
    	end
           end
        end
    end

Valid XHTML 1.0!

$Id: examples.html,v 1.5 2007/12/21 22:55:20 carregal Exp $