basis/tools/test/test-docs.factor

   1 USING: help.markup help.syntax kernel quotations io ;
   2 IN: tools.test
   3
   4 ARTICLE: "tools.test.write" "Writing unit tests"
   5 "Assert that a quotation outputs a specific set of values:"
   6 { $subsection unit-test }
   7 "Assert that a quotation throws an error:"
   8 { $subsection must-fail }
   9 { $subsection must-fail-with }
  10 "Assert that a quotation or word has a specific static stack effect (see " { $link "inference" } "):"
  11 { $subsection must-infer }
  12 { $subsection must-infer-as } ;
  13
  14 ARTICLE: "tools.test.run" "Running unit tests"
  15 "The following words run test harness files; any test failures are collected and printed at the end:"
  16 { $subsection test }
  17 { $subsection test-all } ;
  18
  19 ARTICLE: "tools.test.failure" "Handling test failures"
  20 "Most of the time the words documented in " { $link "tools.test.run" } " are used because they print all test failures in human-readable form. Sometimes, you want to develop a tool which inspects the test failures and takes some kind of action instead; one example is " { $vocab-link "builder" } "."
  21 $nl
  22 "The following words output an association list mapping vocabulary names to sequences of failures; a failure is an array having the shape " { $snippet "{ error test continuation }" } ", and the elements are as follows:"
  23 { $list
  24     { { $snippet "error" } " - the error thrown by the unit test" }
  25     { { $snippet "test" } " - a pair " { $snippet "{ output input }" } " containing expected output and a unit test quotation which didn't produce this output" }
  26     { { $snippet "continuation" } " - the traceback at the point of the error" }
  27 }
  28 "The following words run test harness files and output failures:"
  29 { $subsection run-tests }
  30 { $subsection run-all-tests }
  31 "The following word prints failures:"
  32 { $subsection test-failures. } ;
  33
  34 ARTICLE: "tools.test" "Unit testing"
  35 "A unit test is a piece of code which starts with known input values, then compares the output of a word with an expected output, where the expected output is defined by the word's contract."
  36 $nl
  37 "For example, if you were developing a word for computing symbolic derivatives, your unit tests would apply the word to certain input functions, comparing the results against the correct values. While the passing of these tests would not guarantee the algorithm is correct, it would at least ensure that what used to work keeps working, in that as soon as something breaks due to a change in another part of your program, failing tests will let you know."
  38 $nl
  39 "Unit tests for a vocabulary are placed in test files in the same directory as the vocabulary source file (see " { $link "vocabs.loader" } "). Two possibilities are supported:"
  40 { $list
  41     { "Tests can be placed in a file named " { $snippet { $emphasis "vocab" } "-tests.factor" } "." }
  42     { "Tests can be placed in files in the " { $snippet "tests" } " subdirectory." }
  43 }
  44 "The latter is used for vocabularies with more extensive test suites."
  45 $nl
  46 "If the test harness needs to define words, they should be placed in a vocabulary named " { $snippet { $emphasis "vocab" } ".tests" } " where " { $emphasis "vocab" } " is the vocab being tested."
  47 { $subsection "tools.test.write" }
  48 { $subsection "tools.test.run" }
  49 { $subsection "tools.test.failure" } ;
  50
  51 ABOUT: "tools.test"
  52
  53 HELP: unit-test
  54 { $values { "output" "a sequence of expected stack elements" } { "input" "a quotation run with an empty stack" } }
  55 { $description "Runs a quotation with an empty stack, comparing the resulting stack with " { $snippet "output" } ". Elements are compared using " { $link = } ". Throws an error if the expected stack does not match the resulting stack." } ;
  56
  57 HELP: must-fail
  58 { $values { "quot" "a quotation run with an empty stack" } }
  59 { $description "Runs a quotation with an empty stack, expecting it to throw an error. If the quotation throws an error, this word returns normally. If the quotation does not throw an error, this word " { $emphasis "does" } " raise an error." }
  60 { $notes "This word is used to test boundary conditions and fail-fast behavior." } ;
  61
  62 HELP: must-fail-with
  63 { $values { "quot" "a quotation run with an empty stack" } { "pred" "a quotation with stack effect " { $snippet "( error -- ? )" } } }
  64 { $description "Runs a quotation with an empty stack, expecting it to throw an error which must satisfy " { $snippet "pred" } ". If the quotation does not throw an error, or if the error does not match the predicate, the unit test fails." }
  65 { $notes "This word is used to test error handling code, ensuring that errors thrown by code contain the relevant debugging information." } ;
  66
  67 HELP: must-infer
  68 { $values { "word/quot" "a quotation or a word" } }
  69 { $description "Ensures that the quotation or word has a static stack effect without running it." }
  70 { $notes "This word is used to test that code will compile with the optimizing compiler for optimum performance. See " { $link "compiler" } "." } ;
  71
  72 HELP: must-infer-as
  73 { $values { "effect" "a pair with shape " { $snippet "{ inputs outputs }" } } { "quot" quotation } }
  74 { $description "Ensures that the quotation has the indicated stack effect without running it." }
  75 { $notes "This word is used to test that code will compile with the optimizing compiler for optimum performance. See " { $link "compiler" } "." } ;
  76
  77 HELP: test
  78 { $values { "prefix" "a vocabulary name" } }
  79 { $description "Runs unit tests for the vocabulary named " { $snippet "prefix" } " and all of its child vocabularies." } ;
  80
  81 HELP: run-tests
  82 { $values { "prefix" "a vocabulary name" } { "failures" "an association list of unit test failures" } }
  83 { $description "Runs unit tests for the vocabulary named " { $snippet "prefix" } " and all of its child vocabularies. Outputs unit test failures as documented in " { $link "tools.test.failure" } "." } ;
  84
  85 HELP: test-all
  86 { $description "Runs unit tests for all loaded vocabularies." } ;
  87
  88 HELP: run-all-tests
  89 { $values { "prefix" "a vocabulary name" } { "failures" "an association list of unit test failures" } }
  90 { $description "Runs unit tests for all loaded vocabularies and outputs unit test failures as documented in " { $link "tools.test.failure" } "." } ;
  91
  92 HELP: test-failures.
  93 { $values { "assoc" "an association list of unit test failures" } }
  94 { $description "Prints unit test failures output by " { $link run-tests } " or " { $link run-all-tests } " to " { $link output-stream } "." } ;