Test::Directory(3)

📦
version 0.052 · 3 versions
, in opensuse-leap 16.0

💖 Test::Directory(3) 💖

okay bestie, so this is the manual page for Test::Directory, a Perl extension for maintaining test directories. yes, that's the whole vibe: it's the Perl extension for maintaining test directories, and we're gonna go through it together. 🫶

✨ SYNOPSIS ✨

 use Test::Directory
 use My::Module

 my $dir = Test::Directory->new($path);
 $dir->touch($src_file);
 My::Module::something( $dir->path($src_file), $dir->path($dst_file) );
 $dir->has_ok($dst_file);   #did my module create dst?
 $dir->hasnt_ok($src_file); #is source still there?

like, that's literally the whole sales pitch in six lines. iconique. 👑

🌸 DESCRIPTION 🌸

So when you're testing code, a lot of the time you're checking that files get created and deleted like they're supposed to. And doing that by hand? lowkey a trap. It's so easy to forget a file, or to completely miss that some random unexpected file showed up and ruined everything. 😭

This module simplifies maintaining test directories by tracking their status as they're modified or tested through this API. Which makes it simple to test individual files, and to verify that there are no missing or unknown files. two for one, we love to see it. 💅

The whole idea: use this API to make a temporary directory and populate an initial set of files. Then, whenever something in the directory changes, use the test methods to verify the change happened like you expected. And at any time you can just verify that the contents of the directory are exactly as expected. vibe check: passed. ✨

Test::Directory implements an object-oriented interface for managing test directories. It tracks which files it knows about (by creating them or testing them via its API), and it can report if any files were missing or unexpectedly added. it's giving attentive bestie energy, honestly. 🎀

There are two flavors of methods for interacting with the directory:

  • Utility methods — they just return a value (i.e. the number of files/errors) with no output at all. quiet queen. 🤫
  • Test functions — these use Test::Builder to produce the appropriate test results and diagnostics for the test harness.

And the directory is automatically cleaned up when the object goes out of scope — see the clean method below for the deets. 🧚

🌈 CONSTRUCTOR 🌈

  • new([$path, $options, ...]) — Create a new instance pointing to the specified $path. $options is an optional hashref of options.

$path will be created (or the constructor will die). If $path is undefined, a unique path gets automatically generated; otherwise it is an error for $path to already exist. no squatters, periodt. 💀

🦋 UTILITY METHODS 🦋

  • touch($file ...) — Create the specified $files and track their state.
  • create($file,%options) — Create the specified $file and track its state. The %options hash supports the following:
    • time => $timestamp — Passed to "utime" in perlfunc to set the file's access and modification times.
    • content => $data — Write $data to the file.
  • mkdir($directory) — Create the specified $directory; dies if mkdir fails.
  • name($file) — Returns the name of the $file, relative to the directory; including any separator normalization. $file need not exist. This method is used internally by most other methods to translate file paths.

For portability, this method implicitly splits the path on UNIX-style / separators, and rejoins it with the local directory separator. 🧵

Absent any separator substitution, the returned value would be equivalent to $file.

  • path($file) — Returns the path for the $file, including the directory name and any substitutions. $file need not exist.
  • check_file($file) — Checks whether the specified $file exists, and updates its state accordingly. Returns true if $file exists, false otherwise.

This method is used internally by the corresponding test methods.

  • check_directory($directory) — Checks whether the specified $directory exists, and updates its state accordingly. Returns true if $directory exists, false otherwise.

This method is used internally by the corresponding test methods.

⚠️ heads up bestie: replacing a file with a directory, or the other way around, would require calling both check_file and check_directory to update the state so it reflects both changes. don't skip one, i'm begging. 🙏
  • remove_files($file...) — Remove the specified $files; return the number of files removed.
  • remove_directories($directory...) — Remove the specified $directoriess; return the number of directories removed.
  • clean — Remove all known files, then call rmdir on the directory; returns the status of the rmdir. The presence of any unknown files will cause the rmdir to fail, leaving the directory with these unknown files. so like… clean up after yourself first, k? 😅

This method is called automatically when the object goes out of scope.

  • count_unknown
  • count_missing — Returns a count of the unknown or missing files and directories.
📌 note: files and directories are interchangeable when counting missing files, but not when counting unknown files. tiny distinction, huge consequences. 💅

💜 TEST METHODS 💜

The test methods validate the state of the test directory, calling Test::Builder's ok and diag methods to generate output. they're the main characters of this whole page fr fr. ✨

  • has ($file, $test_name)
  • hasnt($file, $test_name) — Verify the status of $file, and update its state. The test will pass if the state is expected. If $test_name is undefined, a default will be generated. 🎀
  • has_dir ($directory, $test_name);
  • hasnt_dir($directory, $test_name); — Verify the status of $directory, and update its state. The test will pass if the state is expected. If $test_name is undefined, a default will be generated.
  • is_ok($test_name) — Pass if the test directory has no missing or extra files. the ultimate vibe check tbh. ✅
  • clean_ok([$test_name]) — Equivalent to ok(clean,$test_name)

🔥 EXAMPLES 🔥

Calling an external program to move a file — okay so here's the little glow-up moment:

 $dir->touch('my-file.txt');
 system ('gzip', $dir->path('my-file.txt'));
 $dir->has  ('my-file.txt.gz', '.gz file is added');
 $dir->hasnt('my-file.txt',    '.txt file is removed');
 $dir->is_ok; #verify no other changes to $dir

see how it checks both that the .gz showed up ✨ and that the .txt peaced out 👋, and then verifies nothing else in $dir changed? that's the whole flex. ate and left no crumbs. 🍓

👀 SEE ALSO 👀

Test::Builder — go read that one too, iykyk. 💖

🌟 AUTHOR 🌟

Steve Sanbeg, <sanbeg@cpan.org<gt> — legend behavior, honestly. 👑

Copyright (C) 2013 by Steve Sanbeg

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

okay that's the whole page bestie, no cap, every last flag and file path intact 💅

✨ and for the record, this copy is from perl v5.42.0, dated 2023-02-27 — mwah, stan, bye! ✨

📦 where this page comes from