basis/tools/coverage/coverage-docs.factor

   1 ! Copyright (C) 2011 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: alien.c-types assocs help.markup help.syntax kernel quotations
   4 sequences strings ;
   5 IN: tools.coverage
   6
   7 HELP: <coverage-state>
   8 { $values
   9     { "executed?" boolean }
  10     { "coverage-state" coverage-state }
  11 }
  12 { $description "Makes a coverage tuple. Users should not call this directly." } ;
  13
  14 HELP: each-word
  15 { $values
  16     { "string" string } { "quot" quotation }
  17 }
  18 { $description "Calls a quotation on every word in the vocabulary and its private vocabulary, if there is one." } ;
  19
  20 HELP: map-words
  21 { $values
  22     { "string" string } { "quot" quotation }
  23     { "sequence" sequence }
  24 }
  25 { $description "Calls a quotation on every word in the vocabulary and its private vocabulary, if there is one, and collects the results." } ;
  26
  27 HELP: coverage
  28 { $values
  29     { "object" object }
  30     { "seq" sequence }
  31 }
  32 { $description "Outputs a sequence of quotations that were not called since coverage tracking was enabled. If the input is a string, the output is an alist of word-name/quotations that were not used. If the input is a word name, the output is a sequence of quotations." } ;
  33
  34 HELP: coverage-off
  35 { $description "Deactivates the coverage tool on a word or vocabulary and its private vocabulary." } ;
  36
  37 HELP: coverage-on
  38 { $description "Activates the coverage tool on a word or vocabulary and its private vocabulary." } ;
  39
  40 HELP: coverage.
  41 { $values
  42     { "object" object }
  43 }
  44 { $description "Calls the coverage word on all the words in a vocabalary or on a single word and prints out a report." } ;
  45
  46 HELP: %coverage
  47 { $values
  48     { "string" string }
  49     { "x" double }
  50 }
  51 { $description "Returns a fraction representing the number of quotations called compared to the number of quotations that exist in a vocabulary or word." } ;
  52
  53 HELP: add-coverage
  54 { $values
  55     { "object" object }
  56 }
  57 { $description "Recompiles a vocabulary with the coverage annotation. Note that the annotation tool is still disabled until you call " { $link coverage-on } "." } ;
  58
  59 HELP: covered
  60 { $values
  61         { "value" object }
  62 }
  63 { $description "The value that determines whether coverage will set the " { $snippet "executed?" } " slot when code runs." } ;
  64
  65 HELP: flag-covered
  66 { $values
  67     { "coverage" object }
  68 }
  69 { $description "A word that sets the " { $snippet "executed?" } " slot of the coverage tuple when the covered value is true." } ;
  70
  71 HELP: remove-coverage
  72 { $values
  73     { "object" object }
  74 }
  75 { $description "Recompiles a vocabulary without the coverage annotation." } ;
  76
  77 HELP: reset-coverage
  78 { $values
  79     { "object" object }
  80 }
  81 { $description "Sets the " { $snippet "execute?" } " slot of each coverage tuple to false." } ;
  82
  83 HELP: test-coverage
  84 { $values
  85     { "vocab" "a vocabulary specifier" }
  86     { "coverage" sequence }
  87 }
  88 { $description "Enables code coverage for a vocabulary and runs its unit tests. The returned value is a sequence of pairs containing names and quotations which did not execute." } ;
  89
  90 HELP: test-coverage-recursively
  91 { $values
  92     { "prefix" "a vocabulary name" }
  93     { "assoc" assoc }
  94 }
  95 { $description "Enables code coverage for the vocabulary named " { $snippet "prefix" } " and all of its child vocabularies." } ;
  96
  97 ARTICLE: "tools.coverage" "Coverage tool"
  98 "The " { $vocab-link "tools.coverage" } " vocabulary is a tool for testing code coverage. The implementation uses " { $vocab-link "tools.annotations" } " to place a coverage object at the beginning of every quotation. When the quotation executes, a slot on the coverage object is set to true. By examining the coverage objects after running the code for some time, one can see which of the quotations did not execute and write more tests or refactor the code." $nl
  99 "An example of using the coverage tool by hand would be to call " { $link add-coverage } " and then call " { $link coverage-on } ". Next, run whatever code you think will call the most quotations in the code you're testing, and then run the " { $link coverage. } " word on your vocabulary to see which quotations didn't get run." $nl
 100 "A fully automated way to test the unit-test coverage of a vocabulary is the " { $link test-coverage } " word." $nl
 101 "Adding coverage annotations to a vocabulary:"
 102 { $subsections add-coverage remove-coverage }
 103 "Resetting coverage annotations:"
 104 { $subsections reset-coverage }
 105 "Enabling/disabling coverage:"
 106 { $subsections coverage-on coverage-off }
 107 "Examining coverage data:"
 108 { $subsections coverage coverage. %coverage }
 109 "Gather unit-test coverage data for a vocabulary:"
 110 { $subsections test-coverage }
 111 "Combinators for iterating over words in a vocabulary:"
 112 { $subsections each-word map-words } ;
 113
 114 ABOUT: "tools.coverage"