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->test_xattr(1);
        $test->test_chown(1);
        $test->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 void.

    $self->test_all()
        Turns on all the tests. Default false.

    $self->test_xattr()
        Default false.

    $self->test_time()
        Default true. If set false, it also sets `atime', `ctime' and
        `utime' false.

    $self->test_atime()
        Default false.

    $self->test_utime()
        Default true.

    $self->test_ctime()
        Default true.

    $self->test_permissions()
        Default false.

    $self->test_special()
        Default true. If set false, it also sets `fifo' false.

    $self->test_fifo()
        Default false. AKA named pipes.

    $self->test_symlink()
        Default true, except `$^O eq 'MSWin32'' where it defaults to false.

    $self->test_hardlink()
        Default true.

    $self->test_nlink()
        Default true.

    $self->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 `new()' to see the supported features
        and subfeatures. The `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_unlink_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
    symlink_create(), introduced in v0.02
    xattr_list(), introduced in v0.02
    xattr_set(), introduced in v0.02
SEE ALSO
    Test::Class

    Fuse::PDF

AUTHOR
    Chris Dolan, *cdolan@cpan.org*