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 Codebutton.
• 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.

1. Create a new variable template. Click Templatesin the left navigation and click Newunder the Variable Templatessection.

2. Click Fields.

3. Click Add Fieldand select Text input. Name the field text1 and set the display name to "Text 1" .

4. In the Codetab, replace the default code with this sandboxed JavaScript:

    let input = data.text1;
   return input.toUpperCase(); 
   

5. Click Teststo open the testing tab.

6. Click Add Testand change the test's name from "Untitled test 1" to "Handles strings" .

7. Click on the expand icon ( expand_more ) 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 Codetab. 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.

8. Click ▶ Run Teststo run the test. The output of the test will appear in the Console.

   The ▶ Run Testsbutton 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.

9. Click Add Testagain to add a second test. Change the test's name from "Untitled test 2" to "Handles undefined" .

10. 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 
     ); 
     
    

11. Click ▶ Run Teststo 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!

12. Click Codeto 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.

13. Click Teststo go back to the list of test cases.

14. Click ▶ Run Teststo run all of the test cases again. This time the Handles undefined test should pass.

15. Click Save, and close the Template Editor.