test/lua/testlib.lua

   1 ----------------------------------------
   2 -- library name: testlib.lua
   3 --
   4 -- Provides common functions for other lua test scripts to use.
   5 ----------------------------------------
   6 --[[
   7     This library aims to codify the most common practices used in testing
   8     Wireshark's lua features. The intent is to reduce boilerplate code
   9     so test scripts can focus on test cases.
  10
  11     Tests are nominally classified into named groups.
  12     (In practice, most test files just use a single group called "other",
  13     but this should be tidied up at some point.)
  14     A test script must call testlib.init() with a table of
  15     group names and the number of tests expected to be run in each group.
  16     This number can be zero if you want to declare a group but don't
  17     need to check that a specific number of tests is run.
  18
  19     Suggested use (abridged):
  20
  21         local testlib = require("testlib")
  22         testlib.init({ other = 3 })
  23         testlib.testing("other", "example tests")
  24         testlib.test("other", "firsttest", 1+1 == 2)
  25         testlib.test("other", "funccall", pcall(my_function, func_args), "function should succeed")
  26         testlib.test("other", "funccall", not pcall(my_function2, func_args), "function expected to give error")
  27         testlib.getResults()
  28
  29     For information on specific functions, keep reading.
  30 --]]
  31
  32 ----------------------------------------
  33 -- This is the module object, which will be returned at the end of this file.
  34 local M = {
  35     ["groups"] = {},
  36 }
  37
  38 ----------------------------------------
  39 -- Initialize the test suite. Define one or more testing groups,
  40 -- giving the expected number of tests to run for each.
  41 -- (Telling it to "expect" zero tests for a group just skips
  42 -- the check that a specific number of tests ran in that group.)
  43 -- May be called repeatedly if you want to define group names
  44 -- at runtime.
  45 M.init = function(t)
  46     for group, expected in pairs(t) do
  47         M.groups[group] = {
  48             ["expected"] = expected,
  49             ["passed"] = 0,
  50             ["failed"] = 0,
  51             ["total"] = 0,
  52             ["packets"] = 0,
  53         }
  54     end
  55 end
  56
  57 ----------------------------------------
  58 -- Indicate a passed test in the named group.
  59 M.pass = function(group)
  60     M.groups[group].passed = M.groups[group].passed + 1
  61     M.groups[group].total = M.groups[group].total + 1
  62 end
  63
  64 ----------------------------------------
  65 -- Indicate a failed test in the named group.
  66 M.fail = function(group)
  67     M.groups[group].failed = M.groups[group].failed + 1
  68     M.groups[group].total = M.groups[group].total + 1
  69 end
  70
  71 ----------------------------------------
  72 -- There are some tests which track the number of packets they're testing.
  73 -- Use this function to count a single packet as being "seen" by a group.
  74 M.countPacket = function(group)
  75     M.groups[group].packets = M.groups[group].packets + 1
  76 end
  77
  78 ----------------------------------------
  79 -- Get the number of packets that have been counted under the named group.
  80 M.getPktCount = function(group)
  81     return M.groups[group].packets
  82 end
  83
  84 ----------------------------------------
  85 -- Print a banner reporting test progress.
  86 -- Has no material affect on test progression, but is useful for
  87 -- understanding the test results.
  88 M.testing = function(group, msg)
  89     if msg == nil then
  90         msg, group = group, nil
  91     end
  92     if group then
  93         if M.groups[group].packets > 0 then
  94             print(string.format("\n-------- Testing %s -- %s for packet # %d --------\n",
  95                 group, msg, M.groups[group].packets))
  96         else
  97             print(string.format("\n-------- Testing %s -- %s --------\n",
  98                 group, msg))
  99         end
 100     else
 101         print(string.format("\n-------- Testing %s --------\n", msg))
 102     end
 103 end
 104
 105 ----------------------------------------
 106 -- Core function: test a condition, report and track its status.
 107 -- The output format shown here is what was commonly used in test scripts,
 108 -- but can be changed.
 109 M.test = function(group, name, cond, msg)
 110     -- io.stdout:write() doesn't add a newline like print() does
 111     io.stdout:write(string.format("test %s --> %s-%d-%d...",
 112             group, name, M.groups[group].total, M.groups[group].packets))
 113     if cond then
 114         io.stdout:write("passed\n")
 115         M.pass(group)
 116         return true
 117     else
 118         io.stdout:write("failed!\n")
 119         M.fail(group)
 120         if msg then
 121             print(string.format("Got the following error: '%s'", msg))
 122         end
 123         -- Using error() causes the entire test script to abort.
 124         -- This is how the lua test suite typically operates.
 125         -- If a test script wants to continue with subsequent tests
 126         -- after a failed test, this behaviour could be made
 127         -- configurable in this module.
 128         error(name .. " test failed!")
 129         return false
 130     end
 131 end
 132
 133 ----------------------------------------
 134 -- Call this at the finale of a test script to output the results of testing.
 135 -- This is where the number of tests run is compared to what was expected,
 136 -- if applicable.
 137 -- Scripts which run over empty.pcap will usually call this at the end of
 138 -- the file.
 139 -- Scripts which test by creating a protocol object will call this from
 140 -- the object's .init() method *the second time it is called*.
 141 -- Others usually call it in a tap listener's .draw() method,
 142 -- which tshark calls once when it reaches the end of the pcap.
 143 M.getResults = function()
 144     local rv = true
 145     print("\n===== Test Results =====")
 146     for group, num in pairs(M.groups) do
 147         if num.expected > 0 and num.total ~= num.expected then
 148             rv = false
 149             print("Something didn't run or ran too much... tests failed!")
 150             print(string.format("%s: expected %d tests but ran %d tests",
 151                     group, num.expected, num.total))
 152         end
 153         if num.failed > 0 then
 154             rv = false
 155             print(string.format("%s: passed %d/%d, FAILED %d/%d",
 156                     group, num.passed, num.total, num.failed, num.total))
 157         else
 158             print(string.format("%s: passed %d/%d",
 159                     group, num.passed, num.total))
 160         end
 161     end
 162     if rv then
 163         -- The python wrapper which performs our lua testing
 164         -- expects to see this string in the output if there were no failures.
 165         print("All tests passed!")
 166     else
 167         print("Some tests failed!")
 168     end
 169     return rv
 170 end
 171
 172 ----------------------------------------
 173 -- That's the end of this library. Return the module we've created.
 174 return M