Unit Testing GAS Part 1: QUnit Setup

Published: 2019-11-26 10:38 |

Category: Code | Tags: coding, development, gas, google apps script, qunit, software, testing

I'm not good at writing testable code. I'm more of a 'figure it out when it breaks' kind of hobby programmer. The problem with this is that I am constantly making my own bugs and not really finding them until a bad time.

Unit testing is the process of running automated tests against your code to make sure it's working correctly. Each test is for one unit of code - a single function, usually. It expects a value and will pass or fail based on the value received as part of the test.

To get better, I forced myself to write unit tests in Google Apps Script for two reasons:

I've been writing a lot of Apps Script code lately,
There are not many good methods for unit testing in GAS.

This series

The point of this series is to force myself to learn, and use, a unit testing method when writing code and to update the far outdataed unit testing tutorials for Apps Script published online already. I've tried several testing libraries but will be using QUnit as the testing suite.

Part 1: QUnit Setup
Part 2: Simple Tests
Part 3: Adding and Updating Functions
Part 4: Error Handling
Part 5: Testing Objects and Arrays

I'm following Miguel Grinberg's method of posting tutorial code as tagged versions of a GitHub project. Each post will link to a specific tag with the completed source code for that section.

Here's the source for this post

Now, for large projects, you could argue that using clasp and a traditional unit testing library like Mocha or Jasmine is preferable, and you might be right. But, for the purposes of learning, I wanted to keep everything as 'pure' as I could, so all files and tests are written and tests in the online apps script editor.

What is QUint?

It's a testing framework developed and maintained by the jQuery Foundation. It is used in jQuery development to make sure things don't self destruct as the library expands.

QUnit is written for Javascript. Because GAS is based on Javascript, there is a handy library which can be installed in your apps script project.

When testing on your local computer, tests are run by your machine. With Apps Script, everything is run on Google's servers. The QUnit library exposes the framework through a web app that fetches the framework code and executes it when the web app loads.

Install

You can install QUnit for apps script by going to Resources > Libraries in the editor and searching for MxL38OxqIK-B73jyDTvCe-OBao7QLBR4j in the key field. Select v4 and save. Now the QUnit object is available in your project.

Setup

The QUnit library needs some configuration to work with an apps script project. There are three parts to the setup: 1) Declaring QUnit at the global scope, 2) defining tests, and 3) configuring the web application to run the tests.

1. Instantiate QUnit

Once the library is loaded, it needs to be instantiated at the global level to run. Create a new script file called config.gs to hold all of your QUnit code.

The first line should be:

QUnit.helpers(this);

This exposes all assertion methods in the QUnit library (ok, notEqual, expect, etc.) instead of a pared-down object.

2. Define Tests

Tests are defined within wrapper functions that can be passed into QUnit. This tests function will simply hold a list of tests to run when the web application is loaded. We won't be writing any tests in this post but go ahead and add a wrapper for populate later.

function tests() {
    console = Logger; // Match JS
    // Test definitions will be added here
}

3. Web App Config

TheQUnit.config() object declares settings for the web app, so it gets wrapped in the doGet() function. URL params are used to pass information from the app to the testing library with QUnit.urlParams().

QUnit also has a config object which can set default behaviors. You can see a full config object in the project source. For this simple setup, all I'm going to declare is the web app title. Add this to your config.gs file:

// Updated Feb 2020 to account for V8 runtime
function doGet( e ) {
    var params = JSON.stringify(e);
    return HtmlService.createHtmlOutput(params);
};

Now you're ready to write some code. Running QUnit right now won't do anything; that will come in part 2.

Summary

QUnit is a testing library developed by the jQuery foundation.
Google Apps Script is Javascript-like, so a JS testing library can be modified to test Apps Script projects.
QUnit for Google Apps Script is a library which can be used in the online Apps Script editor.
It runs with a web app and is defined by a doGet method and a config object.