volt_unittest.txt

PROPOSAL VOLT_UNITTEST: UNITTEST KEYWORD IMPLEMENTATION & SEMANTICS
VERSION 0.1

ABSTRACT

Volt inherited the 'unittest' keyword from D. Currently, the unittest
keyword is followed by a block of code. Nothing is done with this code,
and the keyword is inert.

The concept of language support for unit testing is not without merit.
This proposal will outline a simple implementation of the unittest
keyword for the Volt language.




LEXICAL

This proposal would add no new tokens to the language, as 'unittest'
is already a keyword.





PARSE

This proposal would add two new IR level concepts to the language:

  - test block
  - test class

The toplevel block would take two forms,
both opened by the sequence 'unittest (':

Standalone form:
    unittest (<identifier:suite>, <identifier:case>) <toplevel_block>

Nested form:
    unittest (<identifier:case>) <toplevel_block>

The test class would be a regular class definition, opened by two
keywords, unittest class:

    unittest class <identifier:name> [: <inheritence_list>] <aggregate_body>





SEMANTIC

A test block would define a function associated with a grouping of test blocks.
If the block runs to completion, that test would be considered passing.
A companion library of assertions would be added to Watt to be used for
this purpose; see the WATT_UNITTEST proposal for details.

A test block can either be standalone (with the suite the first identifier passed
to the unittest block) or nested inside a unittest class, in which case the
suite name would be the name of the class. Suite names would be a global namespace,
with normal package and module names applied to form the final suite name.

For example, module a.b had a CalculatorTest unittest class with three tests, and
a standalone CalculatorTest test, and module c.d had a CalculatorTest standalone
test and they were linked together with unittests enabled, the final executable
(assuming no other tests) would have four a.b.CalculatorTest tests and one
c.d.CalculatorTest tests.

A unittest class may have zero or one constructor. If it has a constructor,
it may not take any arguments. It may define a destructor. Each test inside
the unittest class is treated like a method, with access to the member variables.
A new instance of the class will be created for each test inside the test
class, and the destructor will always be called immediately upon the
test case's completion.

A standalone test with the same name as a unittest class does not have access
to the class's member variables, and no instance of the class is created
for its test run.





DETAILS

Running the volta compiler with the -unittest flag would create a test executable;
a standard runner that would display console output of the test run by default,
and when passed the --xml flag would generate XML output compatible with
XUnit test runners to stdout, or to a file if --xml-file is passed.

If no test cases are included in the set of object/source files given,
but --unittest is given, an error is generated, and the compilation fails.

If a main function is included in the set of object/source files given,
but --unittest is given, an error is generated, and the compilation fails.