diff options
Diffstat (limited to 'stdlib/source/library/lux/test.lux')
| -rw-r--r-- | stdlib/source/library/lux/test.lux | 34 |
1 files changed, 31 insertions, 3 deletions
diff --git a/stdlib/source/library/lux/test.lux b/stdlib/source/library/lux/test.lux index 9fae1bd7e..867304aa7 100644 --- a/stdlib/source/library/lux/test.lux +++ b/stdlib/source/library/lux/test.lux @@ -42,6 +42,7 @@ ["." program]]]]) (type: .public Tally + {#.doc (example "A record of successes and failures while executing tests.")} {#successes Nat #failures Nat #expected_coverage (Set Name) @@ -73,16 +74,18 @@ ) (type: .public Assertion + {#.doc (example "An asynchronous operation that yields test results.")} (Async [Tally Text])) (type: .public Test + {#.doc (example "A test that relies on random data generation to thoroughly cover different scenarios.")} (Random Assertion)) (def: separator text.new_line) (def: .public (and' left right) - {#.doc "Sequencing combinator."} + {#.doc "Sequencing combinator (for assertions)."} (-> Assertion Assertion Assertion) (let [[read! write!] (: [(Async [Tally Text]) (async.Resolver [Tally Text])] @@ -107,10 +110,11 @@ text.tab) (def: .public (context description) + {#.doc (example "Adds a contextual description to a test's documentation.")} (-> Text Test Test) (random\map (async\map (function (_ [tally documentation]) [tally (|> documentation - (text.split_all_with ..separator) + (text.all_split_by ..separator) (list\map (|>> (format context_prefix))) (text.join_with ..separator) (format description ..separator))])))) @@ -119,6 +123,7 @@ (def: success_prefix "[Success] ") (def: .public failure + {#.doc (example "A failing test, with a given error message.")} (-> Text Test) (|>> (format ..failure_prefix) [..failure_tally] @@ -151,6 +156,8 @@ Nat) (def: .public (seed value test) + {#.doc (example "Execute the given test with a specific seed value." + "This allows you to reproduce a failing test case as many times as you want while debugging.")} (-> Seed Test Test) (function (_ prng) (let [[_ result] (random.result (random.pcg_32 [..pcg_32_magic_inc value]) @@ -169,6 +176,9 @@ (exception: .public must_try_test_at_least_once) (def: .public (times amount test) + {#.doc (example "Allows executing a test several times." + "By doing this, it's possible to thoroughly test code with many different scenarios." + "This assumes that random data generation is being used in tests instead of fixed/constant inputs.")} (-> Nat Test Test) (case amount 0 (..failure (exception.error ..must_try_test_at_least_once [])) @@ -241,6 +251,8 @@ (def: success_exit_code +0) (def: .public (run! test) + {#.doc (example "Executes a test, and exits the program with either a successful or a failing exit code." + "WARNING: This procedure is only meant to be used in (program: ...) forms.")} (-> Test (Async Nothing)) (do async.monad [pre (async.future instant.now) @@ -310,7 +322,7 @@ (-> Text Text (Set Name)) (loop [remaining encoding output (set.of_list name.hash (list))] - (case (text.split_with ..coverage_separator remaining) + (case (text.split_by ..coverage_separator remaining) (#.Some [head tail]) (recur tail (set.has [module head] output)) @@ -320,6 +332,11 @@ (template [<macro> <function>] [(syntax: .public (<macro> [coverage (<code>.tuple (<>.many <code>.any)) condition <code>.any]) + {#.doc (example "Specifies a test as covering one or more definitions." + "Adds to the test tally information to track which definitions have been tested." + (<macro> [definition/0 definition/1 ,,, definition/N] + (: Bit + (some "computation"))))} (let [coverage (list\map (function (_ definition) (` ((~! ..reference) (~ definition)))) coverage)] @@ -334,6 +351,11 @@ (syntax: .public (for [coverage (<code>.tuple (<>.many <code>.any)) test <code>.any]) + {#.doc (example "Specifies a context for tests as covering one or more definitions." + "Adds to the test tally information to track which definitions have been tested." + (for [definition/0 definition/1 ,,, definition/N] + (: Test + some_test)))} (let [coverage (list\map (function (_ definition) (` ((~! ..reference) (~ definition)))) coverage)] @@ -352,6 +374,11 @@ (syntax: .public (covering [module <code>.identifier test <code>.any]) + {#.doc (example "Specifies the module being covered by a test." + "Adds tracking information to the tally to know which exported definitions in the module need to be covered." + (covering .._ + (: Test + some_test)))} (do meta.monad [.let [module (name.module module)] definitions (meta.definitions module) @@ -372,6 +399,7 @@ ["Error" (%.text error)])) (def: .public (in_parallel tests) + {#.doc (example "Executes multiple tests in parallel (if the host platform supports it) to take advantage of multiple cores.")} (-> (List Test) Test) (case (list.size tests) 0 |