NAME
    Test::TempDir::Tiny - Temporary directories that stick around when tests
    fail

VERSION
    version 0.003

SYNOPSIS
        # t/foo.t
        use Test::More;
        use Test::TempDir::Tiny;

        # default tempdirs
        $dir = tempdir();          # ./tmp/t_foo_t/default_1/
        $dir = tempdir();          # ./tmp/t_foo_t/default_2/

        # labeled tempdirs
        $dir = tempdir("label");   # ./tmp/t_foo_t/label_1/
        $dir = tempdir("label");   # ./tmp/t_foo_t/label_2/

        # labels with spaces and non-word characters
        $dir = tempdir("bar baz")  # ./tmp/t_foo_t/bar_baz_1/
        $dir = tempdir("!!!bang")  # ./tmp/t_foo_t/_bang_1/

DESCRIPTION
    This module works with Test::More to create temporary directories that
    stick around if tests fail.

    It is loosely based on Test::TempDir, but with less complexity, greater
    portability and zero non-core dependencies. (Capture::Tiny is
    recommended for testing.)

    The "tempdir" function is exported by default. When called, it
    constructs a directory tree to hold temporary directories.

    If the current directory is writable, the root for directories will be
    ./tmp. Otherwise, a File::Temp directory will be created wherever
    temporary directories are stored for your system.

    Every *.t file gets its own subdirectory under the root based on the
    test filename, but with slashes and periods replaced with underscores.
    For example, t/foo.t would get a test-file-specific subdirectory
    ./tmp/t_foo_t/. Directories created by "tempdir" get put in that
    directory. This makes it very easy to find files later if tests fail.

    The test-file-specific name is consistent from run-to-run. If an old
    directory already exists, it will be removed.

    When the test file exits, if all tests passed, then the
    test-file-specific directory is recursively removed.

    If a test failed and the root directory is ./tmp, the test-file-specific
    directory sticks around for inspection. (But if the root is a File::Temp
    directory, it is always discarded).

    If nothing is left in ./tmp (i.e. no other test file failed), then ./tmp
    is cleaned up as well.

    This module attempts to avoid race conditions due to parallel testing.
    In extreme cases, the test-file-specific subdirectory might be created
    as a regular File::Temp directory rather than in ./tmp. In such a case,
    a warning will be issued.

FUNCTIONS
  tempdir
        $dir = tempdir();          # .../default_1/
        $dir = tempdir("label");   # .../label_1/

    Creates a directory underneath a test-file-specific temporary directory
    and returns the absolute path to it.

    The function takes a single argument as a label for the directory or
    defaults to "default". An incremental counter value will be appended to
    allow a label to be used within a loop with distinct temporary
    directories:

        # t/foo.t

        for ( 1 .. 3 ) {
            tempdir("in loop");
        }

        # creates:
        #   ./tmp/t_foo_t/in_loop_1
        #   ./tmp/t_foo_t/in_loop_2
        #   ./tmp/t_foo_t/in_loop_3

    If the label contains any characters besides alphanumerics, underscore
    and dash, they will be collapsed and replaced with a single underscore.

        $dir = tempdir("a space"); # .../a_space_1/
        $dir = tempdir("a!bang");  # .../a_bang_1/

    The test-file-specific directory and all directories within it will be
    cleaned up with an END block if the current test file passes tests.

SEE ALSO
    *   File::Temp

    *   Path::Tiny

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://github.com/dagolden/Test-TempDir-Tiny/issues>. You will be
    notified automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/dagolden/Test-TempDir-Tiny>

      git clone https://github.com/dagolden/Test-TempDir-Tiny.git

AUTHOR
    David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2014 by David Golden.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004