kUnit

kUnit is a simple framework to write repeatable tests for applications written in K or KSQL in the spirit of the Java JUnit framework.

related links

• K and Kdb (for KSQL and SQL92) can be downloaded from the Kx site
• Test Infected: Programmers Love Writing Tests - article by Kent Beck and Erich Gamma
• Beck Testing Framework - paper describing the original Smalltalk framework
• for more background on Junit see junit.org, or the latest version of the code on sourceforge at junit.sourceforge.net
• a JUnit Primer - how to write tests for JUnit, but much of the commentary is equally valid for K/KSQL
• Java JUnit performance testing at JUnitPerf, timings are included in kUnit
• Refactoring relies on being able to run tests to check you haven't broken anything with your 'enhancements'
• and frequent testing is an essential part of extreme programmming (XP), for more details see Extreme Programming A Gentle Introduction, and the home site xprogramming.com where you'll also find implementations of *Unit for other languages
• the c2 wiki has a lot of related links, start at TestingFramework, or JavaUnit

install

download the file kUnit.zip (3K) and unzip it into your application directory. All you need is the file kUnit.k, but there'll be a sample test directory created at the same time with a couple of trivial examples you can run to try it out.

running the sample tests

to run the examples you just need to start K or Kdb, load kUnit, then run the tests by calling runTests, then you can either display the results with showTestResults:

showTestResults runTests[]

just check that they were all ok with allOk:

allOk runTests[]

or if you're using Kdb you can use the Kdb viewer instead of showTestResults, the results are saved as .k.TESTRESULTS so you can just do something like:

show select from TESTRESULTS where fail

the shortcut function sR is provided for the most common usage which is to run the tests, and show the results

sR[]

the failing tests output an error report to the console - the standard K/Kdb error text on a load

k
K 2.9t 2001-04-02 Copyright (C) 1993-2001 Kx Systems
\l kUnit
sR[] / sR:{showTestResults runTests x}
sR[]
load: test/testWithAssert.k ... + 1
load: test/testAddFail.k ... + 1

Kdb (notice the extra .t and .s tests are found and executed):

k db
K 2.9t 2001-04-02 Copyright (C) 1993-2001 Kx Systems
KDB 2.3t 2001-05-12 Copyright (C) 1993-2001 Kx Systems
ksql>\\l kUnit
sR[] / sR:{showTestResults runTests x}
ksql>\sR[]
load: test/testWithAssert.k ... + 1
load: test/testAddFail.k ... + 1
ERROR: test/testCountFail.t LINE: 1

rolling your own

for each 'test suite' you need to create a directory containing the test cases stored as K/Kdb scripts, its easiest to do that as a subdirectory of your application directory, but you don't have to put it there

each test case filename must begin with test, and can be either a .k, .t or .s file. The filename is displayed when an error is seen, so its a good idea to use meaningful names rather than test1, test2 etc

before running any tests the file setUp.k is run, after all tests have completed (K and Kdb) the file tearDown.k is run. Before running the Kdb tests setUp.t is run, and afterwards tearDown.t. The use of these files is optional, if they're found in the test directory they're run.

first .k files are run, then .t and .s files, the order for both groups is newest first

when you've created your test suite you run it by loading kUnit.k, and then set the value of TESTDIR to be the name of your directory if the location is something other than the default test (see the source)

the (bright yellow) highlighting of the top execution times is governed by the value of HIGHLIGHTPERCENT - the default is the top 10%, if this doesn't make sense for your tests then set it to 0

change history

• 2001-06-18 - added setUp.t and tearDown.t after all - called directly before and directly after running the Kdb tests
• 2001-06-14 - added the failms column, if you define a global MAXMS in your testfile the failms flag will be set (and displayed in red in the browser) if the test takes more than MAXMS milliseconds to run. Set a global default MAXMS with MAXMSDEFAULT

feedback

bugs or suggestions for changes/enhancements to simon_garland@gmx.net