NAME
    Devel::CoverX::Covered - Collect and report caller (test file) and
    covered (source file) statistics from the cover_db

DESCRIPTION
  Dealing with large code bases and large test suites
    When a test suite grows as a team of developers implement new features,
    knowing exactly which test files provide test coverage for which parts
    of the application becomes less and less obvious.

    This is especially true for tests on the acceptance / integration /
    system level (rather than on the unit level where the tests are more
    concentrated and easily deduced).

    This is also extra difficult for developers new to the code base who
    have no clue what types of code may need extra testing, or about common
    idioms for testing certain parts of the application.

  Enter Devel::CoverX::Covered
    Devel::CoverX::Covered extracts and stores the relationship between
    covering test files and covered source files.

    This makes it possible to

    *   Given a source file, list the test files that provide coverage to
        that source file. This can be done on a file, sub routine and row
        level.

    *   Given a test file, list the source files and subs covered by that
        test file.

    *   Given a source file, report efficiently on the coverage details per
        row, or sub and highlight source code accordingly.

  Usage Scenarios
    Using this module it should be possible to implement e.g.

    *   From within the editor, list or open interesting source / test
        files, depending on the editor context (current file, sub, line).

    *   When a source file is saved or changed on disk, look up which tests
        correspond to that source file and run only those, thereby providing
        a quicker feedback loop than running the entire test suite.

  OUTPUT FORMAT
    The general output format is one record per line. When there are may
    columns per record, they are tab separated.

  Development Status
    Early release. Solid, but somewhat prone to change as a result of
    feedback.

SYNOPSIS
  Nightly / automatic run
      #Clean up from previous test run (optional)
      cover -delete

      #Test run with coverage instrumentation
      PERL5OPT=-MDevel::Cover prove -r t

      #Collect covered and caller information
      #  Run this _before_ running "cover"
      #  Don't run with Devel::Cover enabled
      covered runs
        - or e.g. -
      covered runs --rex_skip_test_file='/your-prove-file.pl$/' \
              --rex_skip_source_file='{app_cpan_deps/}'

      #Post process to generate covered database
      cover -report Html_basic

  During development
      #Query the covered database per source file
      covered covering --source_file=lib/MyApp/DoStuff.pm
      t/myapp-do_stuff.t
      t/myapp-do_stuff/edge_case1.t
      t/myapp-do_stuff/edge_case2.t


      #Query the covered database per test file
      covered by --test_file=t/myapp-do_stuff.t
      lib/MyApp/DoStuff.pm
      lib/MyApp/DoStuff/DoOtherStuff.pm


      #Query the covered database for coverate details of a source file
      #sub_name \t coverage count (0 is red, >= 1 is green)
      covered subs --source_file=lib/MyApp/DoStuff.pm
      new       4
      as_string 32
      as_xml    0
      do_stuff  4


      #List version, and all known files
      covered info

    -- not implemented --

      #Query the covered database per source file and row
      covered covering --source_file=lib/MyApp/DoStuff.pm --row=37
      t/myapp-do_stuff/edge_case1.t

      covered covering --source_file=lib/MyApp/DoStuff.pm --row=142
      t/myapp-do_stuff.t
      t/myapp-do_stuff/edge_case2.t

      #Query the covered database per source file and subroutine
      covered covering --source_file=lib/MyApp/DoStuff.pm --sub=as_xml
      t/myapp-do_stuff.t


      #Query the covered database per test file, but also show covered
      #subroutines (\t separated)
      covered subs_by --test_file=t/myapp-do_stuff.t
      lib/MyApp/DoStuff.pm       as_xml
      lib/MyApp/DoStuff.pm       do_stuff
      lib/MyApp/DoStuff.pm       new
      lib/MyApp/DoStuff/DoOtherStuff.pm   new
      lib/MyApp/DoStuff/DoOtherStuff.pm   do_other_stuff


      #Query the covered database for details of a source file
      covered lines --source_file=lib/MyApp/DoStuff.pm --metric=statement
      11   1
      17   0
      26   0
      32   1
      77   3
      80   1
      99   2
      102  2
      104  1

THE COVERED DATABASE
    The Devel::CoverX::Covered database is the "covered" directory located
    next to the "cover_db" directory. It is created by running the "covered
    runs" command (see the SYNOPSIS above).

EDITOR SUPPORT
  Emacs
    Devel::PerlySense has a feature "Go to Tests - Other Files" for
    navigating to related files.

  Vim
    Ovid provides similar key bindings here:
    <http://use.perl.org/~Ovid/journal/36280>.

PLAYING WITH OTHERS
  Test::Aggregate
    Tests run by Test::Aggregate won't be reported properly. That's because
    the single .t file running all the aggregate tests will be reported as
    the covering test file.

    The workaround is to perform the Devel::Cover test run without
    Test::Aggregate, i.e. do something like (assuming "aggtest" contains
    your aggregate tests):

      PERL5OPT=-MDevel::Cover prove -r t aggtest

    The extra time taken to do this is probably not a problem since running
    tests with Devel::Cover enabled is so very slow anyway. The startup time
    is simply less significant here.

SEE ALSO
    Devel::Cover

AUTHOR
    Johan Lindstrm, "<johanl[T]DarSerMan.com>"

BUGS AND CAVEATS
  BUG REPORTS
    Please report any bugs or feature requests to
    "bug-devel-coverx-covered@rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel-CoverX-Covered>. I
    will be notified, and then you'll automatically be notified of progress
    on your bug as I make changes.

  CAVEATS
    The Devel::Cover db version is hard coded since it's not exposed by
    Devel::Cover. So that's a bit fragile.

  KNOWN BUGS
    If you delete a .t file, running the test suite again won't de-register
    it from the covered database. To get rid of it you need to delete the
    "covered" directory and re-run the entire coverage test suite.

COPYRIGHT & LICENSE
    Copyright 2007 Johan Lindstrm, All Rights Reserved.

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

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 54:
        You forgot a '=back' before '=head2'

