Perl debugger superpowers, part 2
Tags: debugging, json, perl, testing
Published: 2021-07-06 14:14:32

---
title: Perl debugger superpowers, part 2
published: true
date: 2021-07-06 14:00:00 UTC
tags: debugging,JSON,Perl,testing
canonical_url: https://phoenixtrap.com/2021/07/06/perl-debugger-superpowers-part-2/
series: The Perl debugger can be your superpower
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yqcyharjm0bhqt04ask2.jpeg
---

In March I wrote [_The Perl debugger can be your superpower_](https://phoenixtrap.com/2021/03/09/perl-debugger-superpower/), introducing the [step debugger](https://perldoc.pl/perldebug) as a better way to debug your Perl code rather than littering your source with temporary `print` statements or logging. I use the debugger all the time, and I’ve realized that some more techniques are worth covering.

Although I mentioned a [caveat](https://phoenixtrap.com/2021/03/09/perl-debugger-superpower/#caveat) when debugging web applications, our apps at work all adhere to the Perl Web Server Gateway Interface ([PSGI](https://metacpan.org/pod/PSGI)) specification and thus we can use tools like [Test::WWW::Mechanize::PSGI](https://metacpan.org/pod/Test::WWW::Mechanize::PSGI) or [Plack::Test](https://metacpan.org/pod/Plack::Test) to run tests and debugging sessions in the same Perl process. (Mojolicious users can use something like [Test::Mojo](https://metacpan.org/pod/Test::Mojo) for the same effect.)

To demonstrate, let’s get started with something like this which tests that a given route (`/say-hello`) returns a certain [JSON](https://en.wikipedia.org/wiki/JSON) structure (`{"message": "Hello world!"}`):

```perl
#!/usr/bin/env perl

use Test::Most;
use Test::WWW::Mechanize::PSGI;
use JSON::MaybeXS;
use Local::MyApp; # name of app's main module

my $mech = Test::WWW::Mechanize::PSGI->new(
    # a Dancer2 app, so to_app returns a PSGI coderef
    app => Local::MyApp->to_app(),
);
$mech->get_ok('/say-hello');
lives_and {
    my $json = decode_json($mech->content);
    cmp_deeply( $json, {message => 'Hello world!'} );
} 'message is Hello world!';

done_testing;
```

All very fine and well, but what happens if that route starts returning a different message or worse, invalid output that causes `decode_json` to fail? Eventually, you’ll rewrite the test in the script to output the offending content when something goes wrong, but right now you want to suss out the root cause.

Debuggers have the concept of _breakpoints_, which are flags that tell the debugger to stop at a certain line of code and wait for instructions. We can set them while running the debugger with the [`b`](https://perldoc.pl/perldebug#b-%5Bline%5D-%5Bcondition%5D) command or continue to a one-time breakpoint with the [`c`](https://perldoc.pl/perldebug#c-%5Bline%7Csub%5D) command, or we can insert them into the code ourselves before running it through the debugger in the first place.

Add this line right after the `lives_and {` line:

```perl
$DB::single = 1;
```

This simulates having typed the [`s`](https://perldoc.pl/perldebug#s-%5Bexpr%5D) command in the debugger at that line, stopping execution at that point. Run our test with [perl’s `-d` option](https://perldoc.pl/perlrun#-d), and then type [`c`](https://perldoc.pl/perldebug#c-%5Bline%7Csub%5D) to continue to that breakpoint:

```
$ perl -d -Ilib t/test_psgi.t

Loading DB routines from perl5db.pl version 1.60
Editor support available.

Enter h or 'h h' for help, or 'man perldebug' for more help.

[Local::MyApp:7170] core @2021-07-06 07:33:22> Built config from files: /Users/mgardner/Projects/blog/myapp/config.yml /Users/mgardner/Projects/blog/myapp/environments/development.yml in (eval 310)[/Users/mgardner/.plenv/versions/5.34.0/lib/perl5/site_perl/5.34.0/Sub/Quote.pm:3] l. 910
Test2::API::CODE(0x7ffabea39ee8)(/Users/mgardner/.plenv/versions/5.34.0/lib/perl5/site_perl/5.34.0/Test2/API.pm:71):
71: INIT { eval 'END { test2_set_is_end() }; 1' or die $@ }

  DB<1> c

[...]
ok 1 - GET /say-hello
main::CODE(0x7f8069caf2c8)(t/test_psgi.t:14):
15: my $json = decode_json($mech->content);

  DB<1> 
```

From here we can examine variables, set other breakpoints, or even execute arbitrary lines of code. Let’s see what became of that [HTTP GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) request:

```
  DB<1> x $mech->content

0 '{"error":"Undefined subroutine &Local::MyApp::build_frog called at lib/Local/MyApp.pm line 11.\\n"}'

  DB<2> 
```

Aha, something has returned some different JSON indicating an error. Let’s look at the lines around (10–20) the offending line (11):

```
  DB<2> f lib/Local/MyApp.pm

  DB<3> l 10-20

10: my $method = 'build_frog';
11: $method->();
12 }
13: catch ($e) {
14: send_as JSON => {error => $e};
15 }
16: send_as JSON => {message => 'Hello world!'};
17:	};
18
19 sub build_frob {
20: return;

  DB<4>
```

Yep, a typo on line 11, and one that wasn’t caught at compile time since it’s generated at runtime.

Just to be sure (and to demonstrate some other cool debugger features), let’s set another breakpoint while in the debugger and then exercise that route again. Then we’ll check that `$method` variable against the list of available methods in the `Local::MyApp` package.

```
  DB<4> b 11

  DB<5> $mech->get('/say-hello')

[...]
Local::MyApp::CODE(0x7f8066f2db60)(lib/Local/MyApp.pm:11):
11: $method->();

  DB<<6>> x $method

0 'build_frog'

  DB<<7>> m Local::MyApp
any
app
body_parameters
build_frob
captures
config
content
[...]
  DB<<8>>
```

No doubt about it, that variable is being set incorrectly.

Quit out of the debugger with the [`q`](https://perldoc.pl/perldebug#q-or-%5ED) command, make the fix (we probably want errors to give something other than an [HTTP 200 OK](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) while we’re at it), and re-run the test:

```
$ perl -Ilib t/test_psgi.t

[Local::MyApp:8277] core @2021-07-06 07:48:36> Built config from files: /Users/mgardner/Projects/blog/myapp/config.yml /Users/mgardner/Projects/blog/myapp/environments/development.yml in (eval 309) l. 910
Name "DB::single" used only once: possible typo at t/test_psgi.t line 13.
[Local::MyApp:8277] core @2021-07-06 07:48:36> looking for get /say-hello in /Users/mgardner/.plenv/versions/5.34.0/lib/perl5/site_perl/5.34.0/Dancer2/Core/App.pm l. 35
[Local::MyApp:8277] core @2021-07-06 07:48:36> Entering hook core.app.before_request in (eval 274) l. 1
[Local::MyApp:8277] core @2021-07-06 07:48:36> Entering hook core.app.before_file_render in (eval 274) l. 1
[Local::MyApp:8277] core @2021-07-06 07:48:36> Entering hook core.app.after_file_render in (eval 274) l. 1
[Local::MyApp:8277] core @2021-07-06 07:48:36> Entering hook core.app.after_request in (eval 274) l. 1
ok 1 - GET /say-hello
ok 2 - message is Hello world!
1..2
```

Note that [warning](https://perldoc.pl/perldiag#Name-%22%25s::%25s%22-used-only-once:-possible-typo) about leaving `$DB::single` in there. While harmless, it’s a good reminder to remove such lines from your code so that they don’t surprise you or your teammates during future debugging sessions.

And that’s it. Note that because we’re using PSGI, we were able to set breakpoints in our web app code itself and the debugger stopped there and enabled us to have a look around. And as you’ve seen, once you’re at a breakpoint you can [switch to different files](https://perldoc.pl/perldebug#f-filename), [add/remove more breakpoints](https://perldoc.pl/perldebug#b), [run arbitrary code](https://perldoc.pl/perldebug#command6), and more. The [perldebug](https://perldoc.pl/perldebug) documentation page has all the details.

Happy debugging! For your reference, here’s the full app module and test script used in this article:

{% gist https://gist.github.com/mjgardner/1c9f9816a7e6c67687e8701b35891d5b %}