PageRenderTime 74ms CodeModel.GetById 61ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 0ms

/extra/images/testing/testing-docs.factor

http://github.com/abeaumont/factor
Unknown | 98 lines | 87 code | 11 blank | 0 comment | 0 complexity | f4c22676e24dc030db9a73d8eb43de2e MD5 | raw file
 1! Copyright (C) 2009 Keith Lazuka.
 2! See http://factorcode.org/license.txt for BSD license.
 3USING: help.markup help.syntax images images.viewer kernel
 4quotations strings ;
 5IN: images.testing
 6
 7HELP: decode-test
 8{ $values
 9    { "path" "a pathname string" }
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
13HELP: 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
20HELP: 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
27HELP: 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
34HELP: 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
40HELP: 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
47HELP: 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
54HELP: 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
60ARTICLE: { "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
74ARTICLE: "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
98ABOUT: "images.testing"