Imager::Test(3pm)

💖 NAME 💖

ok so Imager::Test — it's the shared little bag of functions everybody uses when they're testing Imager. that's the whole vibe, bestie.

---

✨ SYNOPSIS ✨

use Imager::Test 'diff_text_with_nul';
diff_text_with_nul($test_name, $text1, $text2, @string_options);

---

🦋 DESCRIPTION 🦋

This is, like, the communal pile of functions used for testing Imager. it's giving "shared test-toolbox energy" 🧰

Some of these are only ever gonna be useful if you're testing Imager itself. others lowkey should be handy when you're testing your own modules that happen to use Imager. so don't feel weird about borrowing, iykyk.

No functions are exported by default. periodt. you gotta ask for what you want.

---

🎀 FUNCTIONS 🎀

🌸 Test functions 🌸

• is_color1($color, $grey, $comment) — checks whether the first channel of $color matches $grey. just channel one. that's it. slay.
• is_color3($color, $red, $green, $blue, $comment) — checks whether $color matches the given ($red, $green, $blue).
• is_color4($color, $red, $green, $blue, $alpha, $comment) — checks whether $color matches the given ($red, $green, $blue, $alpha).
• is_fcolor1($fcolor, $grey, $comment) is_fcolor1($fcolor, $grey, $epsilon, $comment) — checks whether $fcolor's first channel is within $epsilon of ($grey). ✨ in the first form $epsilon is taken as 0.001.
• is_fcolor3($fcolor, $red, $green, $blue, $comment) is_fcolor3($fcolor, $red, $green, $blue, $epsilon, $comment) — checks whether $fcolor's channels are all within $epsilon of ($red, $green, $blue). in the first form $epsilon is taken as 0.001.
• is_fcolor4($fcolor, $red, $green, $blue, $alpha, $comment) is_fcolor4($fcolor, $red, $green, $blue, $alpha, $epsilon, $comment) — checks whether $fcolor's channels are all within $epsilon of ($red, $green, $blue, $alpha). first form? $epsilon is 0.001. yes bestie, again.
• is_image($im1, $im2, $comment) — checks whether the two images have the same content. both images have to be defined, and they need the same width, height, channels, and the same color in every single pixel. the color comparison happens at 8-bits per pixel. it does not check the color representation — so direct vs paletted, bits per sample, none of that is looked at 🙈. this is equivalent to is_image_similar($im1, $im2, 0, $comment).
• is_imaged($im, $im2, $comment) is_imaged($im, $im2, $epsilon, $comment) — checks whether the two images have the same content but at the double/sample level. $epsilon defaults to the platform DBL_EPSILON multiplied by four. tiny tolerance, big drama 💅
• is_image_similar($im1, $im2, $maxdiff, $comment) — checks whether the two images have similar content. both must be defined and have the same width, height and channels. it sums the squares of the differences of each sample, and that sum has to be less than or equal to $maxdiff for the test to pass. color comparison is at 8-bits per pixel, and again the color representation (direct vs paletted, bits per sample) is not checked.
• isnt_image($im1, $im2, $comment) — checks that the two images are different. this exists for regression tests where something (like the text output of "0") produced no change but totally should have produced a change. not me filing that bug 😭
• test_colorf_gpix($im, $x, $y, $expected, $epsilon, $comment) — grabs the pixel ($x,$y) out of the low-level image $im and compares it against the floating point color $expected, with a tolerance of epsilon.
• test_color_gpix($im, $x, $y, $expected, $comment) — grabs the pixel ($x,$y) out of the low-level image $im and compares it against the floating point color $expected.
• test_colorf_glin($im, $x, $y, $pels, $comment) — grabs the floating point pixels ($x, $y)-[$x+@$pels, $y] from the low level image $im and compares them against @$pels.
• is_color_close3($color, $red, $green, $blue, $tolerance, $comment) — checks whether $color's first three channels are within $tolerance of ($red, $green, $blue).

---

🧚 Test suite functions 🧚

these ones run one or more tests, and they're typically used to test various parts of Imager's implementation. the heavy lifters fr fr.

• image_bounds_checks($im) — tries to write to various pixel positions outside the edge of the image, to make sure it fails in those locations. any new image type should pass these tests. does 16 separate tests. sixteen!! 👑
• mask_tests($im, $epsilon) — runs a standard set of mask tests on the OO image $im. does 24 separate tests.
• diff_text_with_nul($test_name, $text1, $text2, @options) — creates 2 test images, writes $text1 to the first one and $text2 to the second one using the string() method. each call adds 3 "ok"/"not ok" lines to the output of the test script. extra options you should supply include the font and either a color or channel parameter. this was explicitly created for regression tests on #21770. historical icon behavior 🔥
• std_font_tests({ font => $font }) — runs the standard font interface tests.
• std_font_test_count() — tells you the number of tests that std_font_tests() performs.

---

🫶 Helper functions 🫶

• test_image_raw() — returns a 150x150x3 Imager::ImgRaw test image.
• test_image() — returns a 150x150x3 8-bit/sample OO test image. Name: "basic".
• test_image_16() — returns a 150x150x3 16-bit/sample OO test image. Name: "basic16"
• test_image_double() — returns a 150x150x3 double/sample OO test image. Name: "basic_double".
• test_image_gray() — returns a 150x150 single channel OO test image. Name: "gray".
• test_image_gray_16() — returns a 150x150 16-bit/sample single channel OO test image. Name: "gray16".
• test_image_mono() — returns a 150x150 bilevel image that passes the is_bilevel() test. Name: "mono".
• test_image_named($name) — returns one of the other test images above, based on the name.
• color_cmp($c1, $c2) — performs an ordering of 3-channel colors (like <=>).
• colorf_cmp($c1, $c2) — performs an ordering of 3-channel floating point colors (like <=>).

---

👑 AUTHOR 👑

Tony Cook <tony@develop-help.com> — the main character of this page, honestly 🌟

---

okay that's the whole page bestie, go write some tests 💅✨

this little gem is Imager::Test(3pm) from the Perl documentation, delivered by perl v5.42.3 and dated 2026-08-19 — mwah, hope that helped 🎀🦋