Unit Testing GAS Part 2: Simple Tests

Simple Tests

From part one, unit tests are for single units of code. They test a specific function for a specific result. I found a helpful living guide on writing unit tests that included some very clear expectations:

Unit tests are isolated and independent of each other. Any given behaviour should be specified in one and only one test. The execution/order of execution of one test cannot affect the others.

Let's create a simple class with some properties and methods we can test. We'll use QUnit to write some tests for those methods. Once we've covered the basics, a future post will look at more complex application structures and tests.

Source

The completed source for this part can be found here.

Writing Functions and Tests

Let's start by defining a Calculations class using Bruce Mcpherson's recommended namespacing structure to keep everything neat. If you're following along, create a Script file named calculations.gs in your editor and add the following code.

const Calcs = (function() {
    const name = 'Calculation class';

    const about = function() {
        return 'A class for calculating things';
    }

    return {
        name: name,
        about: about,
    }
})();

A Note on Naming Tests

Following the testing guide, naming tests clearly is important as their messages will be your guides to problem solving. Each test is given a specific message parameter that has a specific action...should...result format. An named action (calling a class parameter or method) should do something and end in a defined result.

In QUnit for GAS, the result is defined as the expected result in assertions that accept that paramter (keep reading below).

Writing Simple Tests

Now it's time to define some tests. The biggest change in my thinking came when I switched to writing tests first to define what I want the outcome to be before diving in and figuring out if my function is giving me the right output or not. Create a new script file called tests.gs and add the following:

function calcTests() {
    QUnit.test('Checking the Calcs class parameters', function() {
        ok(Calcs.name, 'The name parameter should be available in the namespace.');
        equal(Calcs.about(), 'A class of calculation methods', 'The about method should return the Calcs class description.');
        ok(Calcs.author(), 'The author method should return the Calcs class author description.');
    });
}

Breaking this block down:

• function calcTests() { ... }: a wrapper which contains several tests. The name is arbitrary, but it should describe what you're testing in general.
• QUnit.test(name, callback): a method requiring two parameters: a name and a callback function. The callback defines specific assertions (or tests) to run.

Inside the test are the specific assertions we're making about the function:

• ok(state, [message]): The simplest test that evaluates the truthy/falsy state of the input. The message parameter is optional.
• equal/notEqual(expected, actual, [message]): Comparisons of expected values with actual returned along with an optional message.

Naming and writing good messaging takes practice and I'm still working on a system that works well for me. The great thing is that if a system isn't working well, just rename it or change the messaging!

The last step before we can run tests is to tell QUnit where to look for those tests in the config file we defined in part one. Open your config.gs file and make sure it looks like this (excluding comments):

QUnit.helpers( this );

// Define the tests to run. Each function is a collection of tests.
function tests() {
  console = Logger; // Match JS
  calcTests();   // Our new tests defined in tests.gs
}

// runs inside a web app, results displayed in HTML.
function doGet( e ) {
  QUnit.urlParams( e.parameter );
  QUnit.config({
    title: "QUnit for GAS" // Sets the title of the test page.
  });

  // Pass the tests() wrapper function with our defined
  // tests into QUnit for testing
  QUnit.load( tests );

  // Return the web app HTML
  return QUnit.getHtml();
};

What's happening:

• calcTests(), our tests function, is included in the tests() wrapper function in the QUnit config (line 8).
• tests() is loaded into QUnit with QUnit.load(tests) (line 20)

Running Tests

QUnit is run as a web application through apps script. Go to Publish and choose Deploy as web app.... In the popup, set the new version and limit access to yourself.

You'll need to verify the application can have access to your account. Once that is done, you can open your web application link. If you've done your setup correctly, you should see your three test results:

You just ran your first unit tests!

Failing a Test

There are plenty of ways to write failing tests. They fail either because your code doesn't produce the expected value or because your test is expecting something that isn't happening. Let's make a small change to our Calcs class which will cause a test to fail.

In the class, change the .about method to:

const about = function() {
    return 'A class of calculation method';
  }

Since our test is asserting that this function will return the string, A class of calculation methods, we can expect this test to fail because it will evaluate to false. Run your tests again either by reloading the web app page. Sure enough, we have a failure:

There are a couple things to note from this result:

1. The expected result is defined in your test function.
2. The actual result and the difference are shown so you can identify the point of failure (and yes, your tests can be the point of failure!)

Since the .about() method fails its test, I know I need to go back and fix the bug. Adding an 's' to 'method' solves the bug. Reloading the page will confirm with a passed test.

Stack traces in QUnit for GAS are marginally helpful. This is because the testing happens on Googles servers, not your computer, so there are several steps in the tooling that add layers of trace data. Some ways to make this more readable are to add code references to your tests file or to have function-based naming so you can find what failed. For this example, we don't have to worry too much, but we'll look into more complex applications at a later point.

Changing Your Code

The whole point of unit testing is that you catch breaking changes before your code is released. Let's make a change to our Calcs class and write a test to make sure that nothing is broken. Start by writing a simple test to define what we want that function to do.

// tests.gs
QUnit.test('About Calcs test', function() {
    ...
    ok(Calcs.author(), 'The author method is publicly available');
    ...
})

...and then add the function to Calcs which will pass the test.

// calculations.gs
const Calcs = (function() {
    // ...
    const author = function() {
        return 'This ' + name + 'is authored by Brian.'
    }
    ...
})

Reload your web app page. What happens?

Your test should have failed (if you followed my code above) with the error, Cannot find function author in object [object Object]. But why?

Something is wrong...the test couldn't find the function author() even though I added it to my class. The explanation is that I never exported that function in the return statement! Since it wasn't exported, the test fails. A potential bug in my application has been caught early and is simple to diagnose and repair before it causes user errors later. Update the return statement in the calculations class to:

// calculations.gs
...
return {
    name: name,
    about: about,
    author: author,
}
...

...and run the tests again by reloading the web app to see that everything now passes.

Summary

This is the first glimpse into using QUnit inside an Apps Script project. Once the setup is complete, you can start writing tests for what you expect your code to do, which gives you clarity and insight into actually writing the function while knowing your test will catch bugs.

• Tests are grouped into wrapper functions, usually by similarity in purpose.
• Specific tests are run with the QUnit.test() method which takes two parameters:
  1. A title for the tests
  2. A callback function defining each type of test
• Tests are passed into a tests() wrapper function in the config file.
• The tests() wrapper is passed into QUnit.load() to run in a web app.
• ok, equal, and notEqual are simple checks for true/false results when the expected and actual results are compared.