view release on metacpan or  search on metacpan

lib/Devel/PerlySense.pm  view on Meta::CPAN

C<C-o a t> -- If the test count in a .t file is out of sync with
what's correctly reported when running the test in the
B<*compilation*> buffer (see Run File), use this command to update the
.t file.

This updates the

  use Test::More tests => 43;

line in the current buffer, so be sure to only run this when the
B<*compilation*> buffer contains the run result of this buffer.


=head3 Run Single Test::Class Method

If you use L<Test::Class> to write your tests, you may sometimes want
to run L<just a single test method|Test::Clas/RUNNING_INDIVIDUAL_TESTS>.

Hit C<C-o r m> to mark the current sub as the current test method, and
C<C-o r m> again to unmark it. This will set the $TEST_METHOD
environment variable during program runs, so when you run this test
class, only the marked method will be run.

The current test method is indicated with a "Test::Class -->" next to
it.


=head3 Go to Tests - Other Files


=for html <p>[ <a href="http://search.cpan.org/src/JOHANL/Devel-PerlySense-0.0217/doc/goto_tests.html">Screenshot</a> ]<p>


C<C-o g t o> -- In a test file, navigate to the source files that are
covered by that test file.

In a source file, navigate to test files covering the file. If the
point is on a line with a sub declaration, the list of test files is
limited to those that cover that particular sub.

This requires that L<Devel::CoverX::Covered> is installed and a
L<Devel::Cover> cover_db in the project root directory.

You can build the coverage database either as a (very slow) separate
test run, or by running individual files with C<C-o r c>.

See L<Devel::CoverX::Covered> for details.


=head3 Go to Error line

If you run tests in a regular shell (inside Emacs or in a terminal
window), this may be handy.

C<C-o g e> -- If point is located on an error line from a syntax
error, or a stack trace from the debugger or similar, go to that
file+line.

If no file name can be found, prompt for a piece of text that contains
the file+line spec. The kill ring or clipboard text is used as default
if available (so it's easy to just copy the error line from the
terminal, run this command and hit return to accept the default text).



=head2 Debugging Code

=head3 Run File in Debugger

C<C-o r d> -- Run the file of the current buffer using the Emacs
integrated Perl debugger. This the same as the excellent C<M-x
perldb>, except a few annoyances are fixed, like the include
directories, the working directory, the default command line etc.

Note that if you have spaces in your file names, this might not work
(it's a perldb thing).

The debugger is started according to the file source type, which is
determined by the file name (see the config file).

You can also use C<C-u C-o r d> to Debug with an Alternate Command,
just like with Run File.

This can all be configured similar to how files are run (see above).

Most files are run from the Project root directory by default.


=head3 Commands and key bindings

Commonly used commands:

    |-------------+------+-------------------------|
    | Source      | DB   | Command                 |
    |-------------+------+-------------------------|
    | C-x C-a C-n | n    | Next line (step over)   |
    | C-x C-a C-s | s    | Step into               |
    |             | RET  | Repeat last n or s      |
    | C-x C-a C-r | r    | Return from sub         |
    | C-x C-a C-u |      | Run to (Until) point    |
    |             | x $v | Dump variable $v        |
    |             | T    | Stack trace             |
    |             | y    | Dump lexicals (mY vars) |
    |             | R    | Restart                 |
    |             | m $o | List methods of $o      |
    |-------------+------+-------------------------|


=head3 Dumping objects

  x $VAR

to print/dump objects.

See L<http://use.perl.org/~jplindstrom/journal/34427> for how to deal
with large objects (put the C<.perldb> file in $HOME or the project
root dir).


=head3 Breakpoints

lib/Devel/PerlySense.pm  view on Meta::CPAN

    /cover_db/*
    /covered/*



=head3 Using Coverage Visualization

You can toggle Visualization with C<C-o C-v> at any time when editing.

You can also enable Visualization by default in the install script
(see above), or via C<M-x customize-variable
ps/enable-test-coverage-visualization>.

Whenever Visualization is enabled, PerlySense will try to fetch
coverage information just after a file is opened and highlight the
word "sub" for each subroutine in the buffer.

=over 4

=item * A green underline means that the sub was entered at least
once. This does not mean all lines in the sub was covered.

=item * A red underline means the sub wasn't covered at all. Time to write
more tests!

=item * No underline means that the sub isn't in the coverage
database. Maybe the sub was added after the test run, maybe
Devel::Cover didn't manage to capture any coverage information for the
sub.

If you really think the sub should be covered, generate a HTML report
with L<Devel::Cover> and investigate further.

=back

The point of the visualization is to provide an ambient feeling of
what's covered or not. Too much detail and color all over the place
and the source turns into a christmas tree! But if you browse past a
complex method and see that it isn't tested, that should ring a bell.

To increase this effect you may want to only highlight subs with bad
coverage (customize the variable
C<ps/only-highlight-bad-sub-coverage>)

Note that you can hit C<C-o g t o> -- "Go To Tests - Other Files" to
see what test files are covering I<this file>. If you run the command
with the cursor on a "sub" line, you'll get only the tests that cover
I<that particular subroutine>.



=head2 Editing Code

Editing code includes both smaller editing tasks and refactorings to
restucture the code.


=head3 Edit - Copy Package Name

C<C-o e c p> -- Copy the current package statement name to the
clipboard (kill-ring) and display it in the echo area. If there is no
package statement, try to get the package name from the file name.



=head3 Edit - Copy Package Name From File Name

C<C-o e c P> -- Assuming the file is a Perl module in a lib directory,
copy the corrsponding package name to the clipboard (kill-ring) and
display it in the echo area.

Useful when you've just created an empty new Perl module .pm file.



=head3 Edit - Copy Sub Name

C<C-o e c s> -- Copy the current sub name to the clipboard (kill-ring)
and display it in the echo area.



=head3 Edit - Copy Method Name

C<C-o e c m> -- Copy the current method name to the clipboard
(kill-ring) and display it in the echo area. Method name in this case
means "package->sub".



=head3 Edit - Copy File Name

C<C-o e c f> -- Copy the current file name to the clipboard
(kill-ring) and display it in the echo area.



=head3 Edit - Add 'use Module' Statement

C<C-o e a u> -- Set mark and add a 'use My::Module;' statement to the
end of the 'use Module' section at the top of the file.

The default module is the selected text, or the module at point (point
may be on a method call of the module).

This is typically useful when you realize you're using a module
already, but without a use-statement. But you don't want to leave
where you are just to fiddle with adding it.

So hit C<C-o e a u> to add it, see that it got added at a good place
and hit C-u C-SPC to return to where you were, and continue doing what
you where doing.



=head3 Edit - Move 'use Module' Statement

C<C-o e m u> -- If point is on a line with a single 'use Module'
statement, set mark and move that statement to the end of the 'use
Module' section at the top of the file.

This is typically useful for when you encounter a stray 'use Module'
in the middle of the file.

So type the 'use Module' statement, hit C<C-o e m u> to move it, see
that it got moved to a good place and hit C-u C-SPC to return to where
you were, and continue doing what you where doing.


=head3 Edit/Refactor - Extract Variable

C<C-o e e v> -- Do the refactoring Extract Variable of the active region.

For example, in this piece of code:

    my $syntax = $self->perlysense->config->{external}->{editor}->{emacs}->{flymake}->{syntax};
    my $critic = $self->perlysense->config->{external}->{editor}->{emacs}->{flymake}->{critic};

Select a piece of code (on either of the lines) that is duplicated a
lot and hit C<C-o e e v>. In this case this seems to be the common
part:

    $self->perlysense->config->{external}->{editor}->{emacs}->{flymake}

You will be asked for a variable name to put this in. The default is
the last word in the selected code ($flymake).

All occurrences of the selection will now be replaced with $flymake,
and the new variable $flymake will be declared just before the
earliest usage.

    my $flymake = $self->perlysense->config->{external}->{editor}->{emacs}->{flymake};
    my $syntax = $flymake->{syntax};