.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::Test 3pm"
.TH Imager::Test 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Imager::Test \- common functions used in testing Imager
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use Imager::Test \*(Aqdiff_text_with_nul\*(Aq;
\&  diff_text_with_nul($test_name, $text1, $text2, @string_options);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is a repository of functions used in testing Imager.
.PP
Some functions will only be useful in testing Imager itself, while
others should be useful in testing modules that use Imager.
.PP
No functions are exported by default.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS "Test functions"
.IX Subsection "Test functions"
.ie n .IP "is_color1($color, $grey, $comment)" 4
.el .IP "is_color1($color, \f(CW$grey\fR, \f(CW$comment\fR)" 4
.IX Item "is_color1($color, $grey, $comment)"
Tests if the first channel of \f(CW$color\fR matches \f(CW$grey\fR.
.ie n .IP "is_color3($color, $red, $green, $blue, $comment)" 4
.el .IP "is_color3($color, \f(CW$red\fR, \f(CW$green\fR, \f(CW$blue\fR, \f(CW$comment\fR)" 4
.IX Item "is_color3($color, $red, $green, $blue, $comment)"
Tests if \f(CW$color\fR matches the given ($red, \f(CW$green\fR, \f(CW$blue\fR)
.ie n .IP "is_color4($color, $red, $green, $blue, $alpha, $comment)" 4
.el .IP "is_color4($color, \f(CW$red\fR, \f(CW$green\fR, \f(CW$blue\fR, \f(CW$alpha\fR, \f(CW$comment\fR)" 4
.IX Item "is_color4($color, $red, $green, $blue, $alpha, $comment)"
Tests if \f(CW$color\fR matches the given ($red, \f(CW$green\fR, \f(CW$blue\fR, \f(CW$alpha\fR)
.ie n .IP "is_fcolor1($fcolor, $grey, $comment)" 4
.el .IP "is_fcolor1($fcolor, \f(CW$grey\fR, \f(CW$comment\fR)" 4
.IX Item "is_fcolor1($fcolor, $grey, $comment)"
.PD 0
.ie n .IP "is_fcolor1($fcolor, $grey, $epsilon, $comment)" 4
.el .IP "is_fcolor1($fcolor, \f(CW$grey\fR, \f(CW$epsilon\fR, \f(CW$comment\fR)" 4
.IX Item "is_fcolor1($fcolor, $grey, $epsilon, $comment)"
.PD
Tests if \f(CW$fcolor\fR's first channel is within \f(CW$epsilon\fR of ($grey).  For
the first form \f(CW$epsilon\fR is taken as 0.001.
.ie n .IP "is_fcolor3($fcolor, $red, $green, $blue, $comment)" 4
.el .IP "is_fcolor3($fcolor, \f(CW$red\fR, \f(CW$green\fR, \f(CW$blue\fR, \f(CW$comment\fR)" 4
.IX Item "is_fcolor3($fcolor, $red, $green, $blue, $comment)"
.PD 0
.ie n .IP "is_fcolor3($fcolor, $red, $green, $blue, $epsilon, $comment)" 4
.el .IP "is_fcolor3($fcolor, \f(CW$red\fR, \f(CW$green\fR, \f(CW$blue\fR, \f(CW$epsilon\fR, \f(CW$comment\fR)" 4
.IX Item "is_fcolor3($fcolor, $red, $green, $blue, $epsilon, $comment)"
.PD
Tests if \f(CW$fcolor\fR's channels are within \f(CW$epsilon\fR of ($red, \f(CW$green\fR,
\&\f(CW$blue\fR).  For the first form \f(CW$epsilon\fR is taken as 0.001.
.ie n .IP "is_fcolor4($fcolor, $red, $green, $blue, $alpha, $comment)" 4
.el .IP "is_fcolor4($fcolor, \f(CW$red\fR, \f(CW$green\fR, \f(CW$blue\fR, \f(CW$alpha\fR, \f(CW$comment\fR)" 4
.IX Item "is_fcolor4($fcolor, $red, $green, $blue, $alpha, $comment)"
.PD 0
.ie n .IP "is_fcolor4($fcolor, $red, $green, $blue, $alpha, $epsilon, $comment)" 4
.el .IP "is_fcolor4($fcolor, \f(CW$red\fR, \f(CW$green\fR, \f(CW$blue\fR, \f(CW$alpha\fR, \f(CW$epsilon\fR, \f(CW$comment\fR)" 4
.IX Item "is_fcolor4($fcolor, $red, $green, $blue, $alpha, $epsilon, $comment)"
.PD
Tests if \f(CW$fcolor\fR's channels are within \f(CW$epsilon\fR of ($red, \f(CW$green\fR,
\&\f(CW$blue\fR, \f(CW$alpha\fR).  For the first form \f(CW$epsilon\fR is taken as 0.001.
.ie n .IP "is_image($im1, $im2, $comment)" 4
.el .IP "is_image($im1, \f(CW$im2\fR, \f(CW$comment\fR)" 4
.IX Item "is_image($im1, $im2, $comment)"
Tests if the 2 images have the same content.  Both images must be
defined, have the same width, height, channels and the same color in
each pixel.  The color comparison is done at 8\-bits per pixel.  The
color representation such as direct vs paletted, bits per sample are
not checked.  Equivalent to is_image_similar($im1, \f(CW$im2\fR, 0, \f(CW$comment\fR).
.ie n .IP "is_imaged($im, $im2, $comment)" 4
.el .IP "is_imaged($im, \f(CW$im2\fR, \f(CW$comment\fR)" 4
.IX Item "is_imaged($im, $im2, $comment)"
.PD 0
.ie n .IP "is_imaged($im, $im2, $epsilon, $comment)" 4
.el .IP "is_imaged($im, \f(CW$im2\fR, \f(CW$epsilon\fR, \f(CW$comment\fR)" 4
.IX Item "is_imaged($im, $im2, $epsilon, $comment)"
.PD
Tests if the two images have the same content at the double/sample
level.  \f(CW$epsilon\fR defaults to the platform DBL_EPSILON multiplied by
four.
.ie n .IP "is_image_similar($im1, $im2, $maxdiff, $comment)" 4
.el .IP "is_image_similar($im1, \f(CW$im2\fR, \f(CW$maxdiff\fR, \f(CW$comment\fR)" 4
.IX Item "is_image_similar($im1, $im2, $maxdiff, $comment)"
Tests if the 2 images have similar content.  Both images must be
defined, have the same width, height and channels.  The sum of the
squares of the differences of each sample are calculated and must be
less than or equal to \fR\f(CI$maxdiff\fR\fI\fR for the test to pass.  The color
comparison is done at 8\-bits per pixel.  The color representation such
as direct vs paletted, bits per sample are not checked.
.ie n .IP "isnt_image($im1, $im2, $comment)" 4
.el .IP "isnt_image($im1, \f(CW$im2\fR, \f(CW$comment\fR)" 4
.IX Item "isnt_image($im1, $im2, $comment)"
Tests that the two images are different.  For regressions tests where
something (like text output of "0") produced no change, but should
have produced a change.
.ie n .IP "test_colorf_gpix($im, $x, $y, $expected, $epsilon, $comment)" 4
.el .IP "test_colorf_gpix($im, \f(CW$x\fR, \f(CW$y\fR, \f(CW$expected\fR, \f(CW$epsilon\fR, \f(CW$comment\fR)" 4
.IX Item "test_colorf_gpix($im, $x, $y, $expected, $epsilon, $comment)"
Retrieves the pixel ($x,$y) from the low-level image \f(CW$im\fR and compares
it to the floating point color \f(CW$expected\fR, with a tolerance of epsilon.
.ie n .IP "test_color_gpix($im, $x, $y, $expected, $comment)" 4
.el .IP "test_color_gpix($im, \f(CW$x\fR, \f(CW$y\fR, \f(CW$expected\fR, \f(CW$comment\fR)" 4
.IX Item "test_color_gpix($im, $x, $y, $expected, $comment)"
Retrieves the pixel ($x,$y) from the low-level image \f(CW$im\fR and compares
it to the floating point color \f(CW$expected\fR.
.ie n .IP "test_colorf_glin($im, $x, $y, $pels, $comment)" 4
.el .IP "test_colorf_glin($im, \f(CW$x\fR, \f(CW$y\fR, \f(CW$pels\fR, \f(CW$comment\fR)" 4
.IX Item "test_colorf_glin($im, $x, $y, $pels, $comment)"
Retrieves the floating point pixels ($x, \f(CW$y\fR)\-[$x+@$pels, \f(CW$y\fR] from the
low level image \f(CW$im\fR and compares them against @$pels.
.ie n .IP "is_color_close3($color, $red, $green, $blue, $tolerance, $comment)" 4
.el .IP "is_color_close3($color, \f(CW$red\fR, \f(CW$green\fR, \f(CW$blue\fR, \f(CW$tolerance\fR, \f(CW$comment\fR)" 4
.IX Item "is_color_close3($color, $red, $green, $blue, $tolerance, $comment)"
Tests if \f(CW$color\fR's first three channels are within \f(CW$tolerance\fR of ($red,
\&\f(CW$green\fR, \f(CW$blue\fR).
.SS "Test suite functions"
.IX Subsection "Test suite functions"
Functions that perform one or more tests, typically used to test
various parts of Imager's implementation.
.IP image_bounds_checks($im) 4
.IX Item "image_bounds_checks($im)"
Attempts to write to various pixel positions outside the edge of the
image to ensure that it fails in those locations.
.Sp
Any new image type should pass these tests.  Does 16 separate tests.
.ie n .IP "mask_tests($im, $epsilon)" 4
.el .IP "mask_tests($im, \f(CW$epsilon\fR)" 4
.IX Item "mask_tests($im, $epsilon)"
Perform a standard set of mask tests on the OO image \f(CW$im\fR.  Does 24
separate tests.
.ie n .IP "diff_text_with_nul($test_name, $text1, $text2, @options)" 4
.el .IP "diff_text_with_nul($test_name, \f(CW$text1\fR, \f(CW$text2\fR, \f(CW@options\fR)" 4
.IX Item "diff_text_with_nul($test_name, $text1, $text2, @options)"
Creates 2 test images and writes \f(CW$text1\fR to the first image and \f(CW$text2\fR
to the second image with the \fBstring()\fR method.  Each call adds 3
\&\f(CW\*(C`ok\*(C'\fR/\f(CW\*(C`not ok\*(C'\fR to the output of the test script.
.Sp
Extra options that should be supplied include the font and either a
color or channel parameter.
.Sp
This was explicitly created for regression tests on #21770.
.ie n .IP "std_font_tests({ font => $font })" 4
.el .IP "std_font_tests({ font => \f(CW$font\fR })" 4
.IX Item "std_font_tests({ font => $font })"
Perform standard font interface tests.
.IP \fBstd_font_test_count()\fR 4
.IX Item "std_font_test_count()"
The number of tests performed by \fBstd_font_tests()\fR.
.SS "Helper functions"
.IX Subsection "Helper functions"
.IP \fBtest_image_raw()\fR 4
.IX Item "test_image_raw()"
Returns a 150x150x3 Imager::ImgRaw test image.
.IP \fBtest_image()\fR 4
.IX Item "test_image()"
Returns a 150x150x3 8\-bit/sample OO test image. Name: \f(CW\*(C`basic\*(C'\fR.
.IP \fBtest_image_16()\fR 4
.IX Item "test_image_16()"
Returns a 150x150x3 16\-bit/sample OO test image. Name: \f(CW\*(C`basic16\*(C'\fR
.IP \fBtest_image_double()\fR 4
.IX Item "test_image_double()"
Returns a 150x150x3 double/sample OO test image. Name: \f(CW\*(C`basic_double\*(C'\fR.
.IP \fBtest_image_gray()\fR 4
.IX Item "test_image_gray()"
Returns a 150x150 single channel OO test image. Name: \f(CW\*(C`gray\*(C'\fR.
.IP \fBtest_image_gray_16()\fR 4
.IX Item "test_image_gray_16()"
Returns a 150x150 16\-bit/sample single channel OO test image. Name:
\&\f(CW\*(C`gray16\*(C'\fR.
.IP \fBtest_image_mono()\fR 4
.IX Item "test_image_mono()"
Returns a 150x150 bilevel image that passes the \fBis_bilevel()\fR test.
Name: \f(CW\*(C`mono\*(C'\fR.
.IP test_image_named($name) 4
.IX Item "test_image_named($name)"
Return one of the other test images above based on name.
.ie n .IP "color_cmp($c1, $c2)" 4
.el .IP "color_cmp($c1, \f(CW$c2\fR)" 4
.IX Item "color_cmp($c1, $c2)"
Performs an ordering of 3\-channel colors (like <=>).
.ie n .IP "colorf_cmp($c1, $c2)" 4
.el .IP "colorf_cmp($c1, \f(CW$c2\fR)" 4
.IX Item "colorf_cmp($c1, $c2)"
Performs an ordering of 3\-channel floating point colors (like <=>).
.SH AUTHOR
.IX Header "AUTHOR"
Tony Cook <tony@develop\-help.com>