Tests

Unit tests for Google Tag Manager custom templates help you validate the functionality of your templates. You can create a set of tests for each template that can be run without needing to deploy your tag, which allows you to continuously test your template's behavior during development. Each test can provide sample input values, mock function calls, and assert code behavior.

Limitations

Unit tests do not check validation rules but you can manually check validation using the Run Code button.
Permission checks do not happen on mocked APIs in unit tests.

This guide will walk you through how to write unit tests for your custom template. This example creates a variable template that takes an input string and returns the uppercase version of that string.

Create a new variable template. Click Templates in the left navigation and click New under the Variable Templates section.
Click Fields.
Click Add Field and select Text input. Name the field text1 and set the display name to "Text 1".
In the Code tab, replace the default code with this sandboxed JavaScript:
```
let input = data.text1;
return input.toUpperCase();
```
Click Tests to open the testing tab.
Click Add Test and change the test's name from "Untitled test 1" to "Handles strings".
Click on the expand icon () to reveal the test's sandboxed JavaScript editor. Replace the code with this sandboxed JavaScript:
```
// Call runCode to run the template's code with a lowercase string
let variableResult = runCode({text1: 'this is a test'});
// Validate that the result of runCode is an uppercase string.
assertThat(variableResult).isEqualTo('THIS IS A TEST');
```
This test passes the string 'this is a test' to the variable and verifies that the variable returns the expected value of 'THIS IS A TEST'. The runCode API is used to run the template code in the Code tab. The argument to runCode is an object that is used as the data global. The assertThat API returns an object that can be used to fluently make assertions about a subject's value.
Click ▶ Run Tests to run the test. The output of the test will appear in the Console.

The ▶ Run Tests button runs all of the enabled tests in the template, in the order shown. To change the order, use the drag icon (⠿). A test can be temporarily enabled or disabled by clicking on the circle to the left of the test name. To run a single test, click the ▶ button that appears when you move the mouse over the test.

The console should print the total number of tests run and the number of tests that failed, if any. In this case, only one test was run and it should pass.
Click Add Test again to add a second test. Change the test's name from "Untitled test 2" to "Handles undefined".
Click on the test to expand it and reveal the sandboxed JavaScript editor. Enter sandboxed JavaScript in the editor:
```
let variableResult = runCode({});
assertThat(variableResult).isEqualTo(undefined);
```
Note: runCode is called with an empty object, which means the value of the text1 field will be undefined in this test case.
Click ▶ Run Tests to run all of the tests at once. The output of the test will appear in the console.

The Handles undefined test should fail. Congratulations, you found a bug!
Click Code to go back and edit the template's sandboxed JavaScript code. Update the sandboxed JavaScript as follows:
```
const getType = require('getType');

let input = data.text1;
if (getType(input) !== 'string') {
  return input;
}
return input.toUpperCase();
```
The updated code follows the best practice of validating the input variable before using it.
Click Tests to go back to the list of test cases.
Click ▶ Run Tests to run all of the test cases again. This time the Handles undefined test should pass.
Click Save, and close the Template Editor.