The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Test-Virtual-Filesystem-0.05
River stage one • 2 direct dependents • 2 total dependents
/ Test::Virtual::Filesystem

NAME

Test::Virtual::Filesystem - Validate a filesystem

SYNOPSIS

    use Test::Virtual::Filesystem;
    Test::Virtual::Filesystem->new('/path/to/test')->runtests;

or with more customization:

    use Test::Virtual::Filesystem;
    my $test = Test::Virtual::Filesystem->new('/path/to/test');
    $test->enable_test_xattr(1);
    $test->enable_test_chown(1);
    $test->enable_test_atime(1);
    $test->runtests;

LICENSE

Copyright 2007 Chris Dolan, cdolan@cpan.org

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

DESCRIPTION

If you are creating a filesystem, say via Fuse or Filesys::Virtual, you need a fairly mundane set of tests to try out lots of typical filesystem operations. This package attempts to accumulate a bunch of those tests to make it easier for you to test your filesystem.

COMPATIBILITY POLICY

Every time we add a new test to this suite, we annotate it with a version number. If client code specifies an expected version number (say, 1.10) and it's running against a newer version or this module (say, 1.20) then any newer test will be marked as a TODO test. That way if the test fails, it won't regress published code that used to work.

This policy will allow us to continue adding new filesystem tests without worrying about breaking existing CPAN modules.

CAVEATS AND LIMITATIONS

This test class needs a more complete suite of test cases. In particular, tests are needed for the following filesystem features:

    extended attributes (xattr)
    multiple symlinks
    recursive symlinks
    hardlinks
    a/u/ctime
    nlink
    chown
    deep directories
    very full directories
    large files
    binary files
    files with awkward characters: EOF, NUL
    non-ASCII filenames (maybe constructor should specify the encoding?)
    permissions
    special file types (fifos, sockets, character and block devices, etc)
    file locking
    threading and re-entrancy
    truncate
    binmode
    eof
    fileno
    seek/rewinddir, tell/telldir
    read, sysread, syswrite
    async I/O?

Any help writing tests (or adapting tests from existing suites) will be appreciated!

METHODS

This is a subclass of Test::Class. All methods from that class are available, particularly runtests().

$pkg->new({mountdir => $mountdir, ...})

Create a new test which will operate on files contained within the specified mount directory. WARNING: any and all files and folders in that mount directory will be deleted!

The supported options are:

mountdir

This required property indicates where tests should run.

compatible

Specify a Test::Virtual::Filesystem version number that is known to work. If the actual Test::Virtual::Filesystem version number is greater, then any test cases added after the specified compatible version are considered TODO tests. See Test::More for details about TODO tests.

$self->init()

Invoked just before then end of new(). This exists solely for subclassing convenience. This implementation does nothing.

PROPERTIES

The following accessor/mutator methods exist to turn on/off various features. They all behave in usual Perl fashion: with no argument, they return the current value. With one argument, they set the current value and return the newly set value.

$self->enable_test_all()

As a getter, checks whether all of the other tests are enabled.

As a setter, turns on/off all the tests.

$self->enable_test_xattr()

Default false.

$self->enable_test_time()

Default true. If set false, it also sets atime, ctime and utime false.

$self->enable_test_atime()

Default false.

$self->enable_test_utime()

Default true.

$self->enable_test_ctime()

Default true.

$self->enable_test_permissions()

Default false.

$self->enable_test_special()

Default true. If set false, it also sets fifo false.

$self->enable_test_fifo()

Default false. AKA named pipes.

$self->enable_test_symlink()

Default true, except for platforms that do not support symlinks (for example MSWin32 and cygwin) as determined by $Config::Config{d_symlink}.

$self->enable_test_hardlink()

Default true.

$self->enable_test_nlink()

Default true.

$self->enable_test_chown()

Default false.

TEST CASES

setup()

Runs before every test to prepare a directory for testing.

teardown()

Runs after every test to clean up the test directory so the next test will have a clean workspace.

Introduced($version)

A subroutine attribute used to flag the Test::Virtual::Filesystem version number when that test was introduced. It's used like this:

  sub open_nonexistent_file : Tests(1) : Introduced('0.02') {
     ok(!open(my $f, '<', '/tmp/no_such_file'));
  }
Features($featurelist)

This is a subroutine attribute to specify one or more features used in the test. The features should be listed as a comma-separated list:

  sub symlink_create : Tests(1) : Features('symlink') {
     ok(symlink($src, $dest));
  }
  sub symlink_permissions : Tests(2) : Features('symlink, permissions') {
     ok(symlink($src, $dest));
     ok(-w $dest);
  }

Subfeatures must be separated from their parent features by a /. For example:

  sub atime_utime_set : Tests(1) : Features('time/atime, time/utime') {
     my $now = time;
     ok(utime($now, $now, $file));
  }

Look at the source code for %feature_defaults to see the supported features and subfeatures. The enable_test_* methods above describe the all the features, but in those methods the subfeature names are flattened.

stat_dir(), introduced in v0.01
read_dir(), introduced in v0.01
read_dir_fail(), introduced in v0.01
read_file_fail(), introduced in v0.01
write_empty_file(), introduced in v0.01
write_file(), introduced in v0.01
write_file_subdir_fail(), introduced in v0.01
write_append_file(), introduced in v0.01
write_read_file(), introduced in v0.01
write_mkdir(), introduced in v0.01
write_mkdir_fail(), introduced in v0.01
write_rmdir(), introduced in v0.01
write_subdir(), introduced in v0.01
xattr_list(), introduced in v0.02
xattr_set(), introduced in v0.02

SEE ALSO

Test::Class

Fuse::PDF

AUTHOR

Chris Dolan, cdolan@cpan.org