NAME
    Test::CheckGitStatus - Check git status after every test

SYNOPSIS
        CHECK_GIT_STATUS=1 prove -M Test::CheckGitStatus -l t/
        CHECK_GIT_STATUS=1 PERL5OPT="-MTest::CheckGitStatus" prove -l t/

        # or in your test:
        use Test::CheckGitStatus;

        CHECK_GIT_STATUS=1 prove t/

DESCRIPTION
    This module can be used to check if your git directory has any modified
    or untracked files. You can use it in your unit tests, and it will check
    the status after each test file.

    By default it will not run the check, as this would be annoying during
    development.

  USE CASE
    If you have a large test suite and a lot of contributors, it can happen
    that someone implements a test by adding a file in the git worktree.
    They might forget to delete it at the end, or it might not be deleted if
    the test exits before the deletion.

    Sometimes such temp files are even hidden via ".gitignore". Then it can
    happen that one test adds such a file, and one of the next tests relies
    on its existence. And if you only run the next test, you might not have
    the file from the previous test, and it fails, and you don't know why.

    I have seen all of this and wanted to have a check that ensures a clean
    status after every test file, not just at the end.

    You can use this as a normal module in all your tests:

        use Test::CheckGitStatus;

    Then you only have to activate it via "CHECK_GIT_STATUS=1".

    You can also use it with "prove -MTest::CheckGitStatus".

    The module runs the check in an END block and tries to make sure that it
    only runs it in the END block of the actual test script, not of any new
    or forked processes. It will only run if one of the environment
    variables "TEST_ACTIVE", "TEST2_ACTIVE" or "HARNESS_ACTIVE" is set.
    (That is to make sure it does not run as the END block of the "prove"
    app itself.)

    It will modify the exit status and output any modified or untracked
    files.

    Example output:

        1..1
        # Error: modified or untracked files
        #  M lib/Test/CheckGitStatus.pm
        # ?? LICENSE
        # ?? Makefile.PL
        # ?? t/00.compile.t
        # Looks like your test exited with 1 just after 1.
        Dubious, test returned 1 (wstat 256, 0x100)
        All 1 subtests passed

    It's not very pretty and like the normal output from a failed test you
    are used to.

    If you still need to touch some files during tests, you can always add
    them to ".gitignore".

   ALTERNATIVE IMPLEMENTATION
    An alternative could be to implement it like Test::Warnings, for
    example, which sneaks this in as a regular test.

    This can have disadvantages as well.

    For that it would have to run a bit earlier, and at that point some
    tests might still have temp directories open which will be deleted in
    the global destruction phase, which might happen after the status check
    runs.

    But if you actually would want to avoid such temporary files completely,
    the alternative implementation would be a better choice.

    Of course it still cannot prevent any temporary files created and
    removed during a test before the check. For that you might want to try
    "chmod -R a-w ." ;-)

COPYRIGHT AND LICENSE
    MIT License

    Copyright (c) SUSE LLC, Tina Müller

    This library is free software and may be distributed under the same
    terms as perl itself.