Test::...isplay(3pm)

💖 Test::NeedsDisplay 💖

okay bestie, so this is the manual page for Test::NeedsDisplay, which lives in the User Contributed Perl Documentation section of the perl manpages (you'll see it filed as Test::...isplay(3pm) in the index, the middle got eaten by the table of contents, it's giving chopped 💀).

---

✨ NAME ✨

Test::NeedsDisplay — the module that makes sure your tests that need a display actually get one 🖥️✨

---

🌸 SYNOPSIS 🌸

first up, in your Makefile.PL...

use inc::Module::Install;
# ... or whatever else you use

# Check for a display
use Test::NeedsDisplay;

# ... your Makefile.PL content as normal

and then again in every single test script that loads Wx:

#!/usr/bin/perl

use strict;

use Test::NeedsDisplay;

# Test content as normal...

like yes, both places. no skipping. 🫶

---

🦋 DESCRIPTION 🦋

so here's the situation, and it's lowkey infuriating. when you're testing GUI applications, sometimes those apps or modules are absolutely unhinged about needing a display — like, they need one even if they're just being loaded and aren't even showing you a single object. no cap. 💅

and regardless of how silly that is, it makes GUI applications pretty much impossible to build and test on headless or automated systems. and it doesn't just fail gracefully, bestie — it fails so hard that it won't even run the Makefile.PL script, because some dependency needs a display just so it can be loaded and someone can find out what version it is. the audacity. 😭

so in these situations, what you actually need is a fake display.

and that's literally the whole job of Test::NeedsDisplay — it searches around and tries to find a way to load some sort of display that can be used for the testing. main character energy for a module that just wants your CI to stop crying. 👑

🌈 Strategies for Finding a Display 🌈

right now, only a single method is used — and it's a very simple one, no gatekeeping.

Debian Linux has a script called xvfb-run, which is a wrapper for xvfb: a virtual X server that uses the linux frame buffer. iconic honestly.

when the module gets loaded without a viable display, it will re-exec the same script using something like (for example) xvfb-run test.t.

and because of that, you should load it as early as possible, before anything has a chance to change the script parameters — because those params are gonna get sent through to the script again. 🎀

---

💅 METHODS 💅

there are no methods. none. zero. it's giving minimalist.

you literally just use the module as early as possible — probably right after use strict; — and make sure you load it with only default params.

specifically: you must always load it before you set the test plan, otherwise the test script will report two plans, and the harness will complain about it and die. not a vibe. 💀

# Use it like this ...
use Test::NeedsDisplay;

# ... not like this ...
use Test::NeedsDisplay 'anything';

# ... and not like this.
use Test::NeedsDisplay ();

and that's all there is to do. the module will take care of the rest. periodt. ✨

---

⭐ TO DO ⭐

• Find alternative ways to launch a display on different platforms

(future plans, we love a roadmap 🫶)

---

🍓 SUPPORT 🍓

bugs should be reported via the CPAN bug tracker at

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-NeedsDisplay>

for other issues, contact the author. 📬

---

💜 AUTHOR 💜

Adam Kennedy <adamk@cpan.org>

---

👑 COPYRIGHT 👑

Copyright 2005 - 2009 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

okay that's the whole thing, you're fully caught up bestie 🧚✨

this page ships with perl v5.34.0 and was last touched on 2022-06-28 — go forth and xvfb-run your way to a green test suite, mwah 💋