Commit 182c6e7a authored by Camil Staps's avatar Camil Staps

Update readme

parent 0505387f
This document explains how to write test programs that the clean test-runner can run and interpret.
We are still working on the tool.
For now, see gitlab issue for the design in progress.
This repository contains a generic test runner for running Clean test programs that adhere to a specific output convention.
You can find more about this specification in Documentation/
# clean-test [![pipeline status](](
This projects hosts tools that can be used to test Clean programs.
The available tools are:
- `cleantest` which can run test programs
- `makecleantest` which can generate test programs from dcl modules
## cleantest
This tool can run other test programs and combine the results.
The tool was conceived in
It is assumed that the other programs adhere to the interface described in
`Testing.TestEvents`. For [Gast][] tests, this can be done easily with the
`exposeProperties` function. For example:
Start w = exposeProperties [OutputTestEvents] [Tests 500000]
[ EP prop_one
, EP prop_two
, EP prop_three
Here, `prop_one`, `prop_two` and `prop_three` are Gast properties (not
necessarily of the same type). `exposeProperties` generates a command-line
interface. `cleantest` can run this kind of test programs (and others) by
adding their executables with the `-r` flag, e.g.:
cleantest -r testModuleA -r testModuleB
The tool has several command-line options; check `cleantest --help` for
up-to-date details.
## makecleantest
This tool can generate test programs using [Gast][]'s `exposeProperties` (see
above) from dcl modules. The properties to test are described in [CleanDoc][]
blocks: comments above function types. This works as follows:
- On the module documentation block, add a `@property-bootstrap` field. This
field should contain the 'header' of the generated test program: required
imports and helper definitions. The programmer must not add a module header
(`definition module ...`) and does not need to import Gast modules or the
module under test itself.
- On each function to test, add one or more `@property` fields to the docblock.
This property for now always starts with `A.`, followed by a number of
parameters and their types. The first line ends with a colon `:`. The
implementation of the property follows on the next line(s). For example:
* @property member_correct: A.x :: a; xs :: [a]:
* member x (fromList xs) <==> isMember x xs
member :: !a !(Set a) -> Bool | < a
Note that one can use Gast's `<==>` here without import, nor does one need to
import the module itself for `member` (and `fromList`). However, `isMember`
requires `import StdList` in the `@property-bootstrap` of the module.
It is possible to use multiple lines for the implementation of the property.
`makecleantest` will guess the right indentation level.
- When parameters in `@property` fields contain type variables, the programmer
is required to suggest types to instantiate these variables with when
testing &mdash; otherwise, how would Gast be able to generate test cases?
This can be done with `@property-test-with`, either locally on the function
docblock or globally on the module docblock. For example:
* @property-test-with a = Int
* @property-test-with a = Real
For all relevant tests using the type variable `a`, two versions will be
generated: one with `Int` and one with `Real`. When multiple type variables
are used, all combinations are tested.
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment