extra/images/testing/testing-docs.factor

   1 ! Copyright (C) 2009 Keith Lazuka.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax images images.viewer kernel
   4 quotations strings ;
   5 IN: images.testing
   6
   7 HELP: decode-test
   8 { $values
   9     { "path" "a pathname string" } { "image-class" object }
  10 }
  11 { $description "Runs a unit-test on the image at " { $snippet "path" } " to test the image decoder. The image is decoded and compared against its corresponding " { $link { "images" "testing" "reference" } } "." } ;
  12
  13 HELP: encode-test
  14 { $values
  15     { "path" "a pathname string" } { "image-class" object }
  16 }
  17 { $description "Runs a unit-test on the image at " { $snippet "path" } " to test the image encoder. The image is decoded, encoded, and then decoded again to verify that the final decoded output matches the original decoded output. Before comparison for equality, the images are normalized in order to accomodate differences in representation between the two potential encoders." }
  18 { $warning "This test assumes that the image decoder is working correctly. If the image fails both the " { $link decode-test } " and the " { $link encode-test } ", then you should first debug the decoder. Once the decoder is working correctly, proceed with testing the encoder." } ;
  19
  20 HELP: images.
  21 { $values
  22     { "dirpath" "a pathname string" } { "extension" string }
  23 }
  24 { $description "Renders each image at " { $snippet "dirpath" } " directly to the listener tool." } ;
  25 { images. image. } related-words
  26
  27 HELP: load-reference-image
  28 { $values
  29     { "path" "a pathname string" }
  30     { "image" image }
  31 }
  32 { $description "Loads the " { $link { "images" "testing" "reference" } } " that corresponds to the original image at " { $snippet "path" } " into memory." } ;
  33
  34 HELP: ls
  35 { $values
  36     { "dirpath" "a pathname string" } { "extension" object }
  37 }
  38 { $description "Prints out the name of each file surrounded in double quotes so that you can easily copy and paste into your unit test." } ;
  39
  40 HELP: save-all-as-reference-images
  41 { $values
  42     { "dirpath" "a pathname string" } { "extension" object }
  43 }
  44 { $description "Saves a " { $link { "images" "testing" "reference" } } " for each image in " { $snippet "dirpath" } " with file extension " { $snippet "extension" } "." }
  45 { $warning "You should only call this word after you have manually verified that every image in " { $snippet "dirpath" } " decodes and renders correctly!" } ;
  46
  47 HELP: save-as-reference-image
  48 { $values
  49     { "path" "a pathname string" }
  50 }
  51 { $description "Saves a " { $link { "images" "testing" "reference" } } " for the image at " { $snippet "path" } "." }
  52 { $warning "You should only call this word after you have manually verified that the image at " { $snippet "path" } " decodes and renders correctly!" } ;
  53
  54 HELP: with-matching-files
  55 { $values
  56     { "dirpath" "a pathname string" } { "extension" string } { "quot" quotation }
  57 }
  58 { $description "Perform an operation on each file in " { $snippet "dirpath" } " with file extension " { $snippet "extension" } "." } ;
  59
  60 ARTICLE: { "images" "testing" "reference" } "Reference image"
  61 "For the purposes of the " { $vocab-link "images.testing" } " vocab, a reference image is an " { $link image } " which has been serialized to disk by the " { $vocab-link "serialize" } " vocab. The file on disk has a " { $snippet ".fig" } " extension."
  62 $nl
  63 "Reference images are used by " { $link decode-test } " to compare the decoder's output against a saved image that is known to be correct."
  64 $nl
  65 "You can create your own reference image after you verify that the image has been correctly decoded:"
  66 { $subsections
  67     save-as-reference-image
  68     save-all-as-reference-images
  69 }
  70 "A reference image can be loaded by the path of the original image:"
  71 { $subsections load-reference-image }
  72 ;
  73
  74 ARTICLE: "images.testing" "Testing image encoders and decoders"
  75 "The " { $vocab-link "images.testing" } " vocab facilitates writing unit tests for image encoders and decoders by providing common functionality"
  76 $nl
  77 "Creating a unit test:"
  78 { $subsections
  79     decode-test
  80     encode-test
  81 }
  82 "Establishing a " { $link { "images" "testing" "reference" } } ":"
  83 { $subsections save-as-reference-image }
  84 "You should only create a reference image after you manually verify that your decoder is generating a valid " { $link image } " object and that it renders correctly to the screen. The following words are useful for manual verification:"
  85 { $subsections
  86     image.
  87     images.
  88 }
  89 "Helpful words for writing potentially tedious unit tests for each image file under test:"
  90 { $subsections
  91     save-all-as-reference-images
  92     ls
  93     with-matching-files
  94 }
  95 { $notes "This vocabulary is only intended for implementors of image encoders and image decoders. If you are an end-user, you are in the wrong place :-)" }
  96 ;
  97
  98 ABOUT: "images.testing"