Some Simple Debugging for Google Apps Script

Even though I’ve been programming for more years than I care to admit, I rarely write code correctly at the first attempt. Debugging, therefore, is an important part of of my development workflow.

In this post I’ll cover some basic techniques that can help you track down and stomp on errors in your Apps Scripts.

When using the Script Editor, you’ll occasionally see an error message appear in a red bar at the top of the screen. The line of code containing the error is usually highlighted too. Two common types of errors, namely syntax errors and runtime errors, tend to be displayed via this method.

Click image to enlarge

Click image to enlarge

In this instance, the message is helpfully telling me that I have an Unterminated string literal on line 2. That’s JavaScript-speak for a missing closing comma – and it’s right, I have. That’s a syntax error.

Runtime errors can be harder to track down, because they don’t contravene the grammar rules; they only show up when trying to run the code. Take a look at this code snippet:

function displayDistance() {
   var output = "The current distance is: " + distance + "miles";
   Browser.msgBox(output);
}
displayDistance(100);

In this version of the code, I’ve corrected the missing comma, but forgotten to pass the parameter distance as an argument in my function definition. Nothing’s wrong until I try to run the code:

Click image to enlarge

Click image to enlarge

Now the message correctly points out that distance is not defined.

You can generate these messages yourself, if you want to, using the throw() command in your code. Of course, using throw() can generate such a message at any time during code execution, not just under error conditions. Here’s an example:

function displayDistance(distance) {
  var output = "The current distance is: " + distance + "miles";
  throw("The value of parameter distance was displayed as " + distance);
  Browser.msgBox(output);
}

Here’s how it looks:

Click image to enlarge

Click image to enlarge

I don’t use this very often, as I find it intrusive, but you might find it to your taste.

Unfortunately, some mistakes cause no error messages. This often happens when the code is grammatically correct and can be run OK, but doesn’t actually do quite what you intended. Now what we need is a method of further investigating the script to examine, for instance, the values of various variables and properties at the time the error occurs.

Here are a few options:

Firstly, you can view the execution transcript after the script has finished running. To do so, select View > Execution transcript in the menu bar.

Click image to enlarge

Click image to enlarge

The transcript is a record of each call to a Google Apps Script service made while the script was running, and it can help you to to work out which actions your script tried to perform and, hopefully, where it all went wrong.

Where you need more detail (about specific variable values, say) Google Apps Script also enables you to write your own custom messages to a log file.

To write such messages you need to pass the message you want logged to the log method of the Logger class:

Logger.log("The value of parameter distance was displayed as " + distance);

This file can be viewed, after the script has finished running, by clicking View > Logs in the menu bar:

Click image to enlarge

Click image to enlarge

So here you have two methods by which error messages are automatically generated by the system, and two further methods by which you can define and generate similar styles of messages providing information of your choice.

In this post I look at more complex debugging using the built-in debugger and setting breakpoints in the script, and, in this post, I’ll discuss how to write code that more elegantly deals with errors by using the language statements try and catch.