Google Tag Manager<\/a> introduced the capability to add tests<\/a> to your Custom Templates<\/a>. Tests, in this context, refer specifically to unit tests<\/strong> that you write in order to make sure your template code works in a predictable way. Unit tests are also used to drive development, ensuring that you have added contingencies for all the different scenarios that the template, when coupled with user input, might introduce.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n In this guide, I\u2019ll introduce how the Tests<\/strong> feature works. Some new APIs are introduced, as well as a grammar<\/em> of sorts that you might be used to if you\u2019ve already worked with tests in a software development context.<\/p>\n \n \n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n <\/span><\/p>\n Unit tests<\/strong> comprise code that is executed against the actual functions and variables of your template code. The purpose of the test is to validate<\/strong> the template code, so that it returns an expected output for any given, tested input.<\/p>\n The purpose of unit tests is to make your code more resilient to changes. By writing tests, you have a tool with which to verify that the changes you make in one place do not break something that happens in another place.<\/p>\n With unit tests, you are testing the most atomic components of your code: the functions and variables. When you write tests, you aim for high code coverage<\/strong>. Coverage means the number of lines<\/strong> of code that are evaluated in some test.<\/p>\n For example, say that you have a simple variable template like this:<\/p>\n This template takes the user input and returns it. If the input is of type array<\/strong>, then When writing tests for this variable, there are basically two<\/strong> scenarios you would need to test.<\/p>\n Here you create a mock<\/strong> object that provides the input. This object has key-value pairs where each key corresponds to a property in the This object is passed to the Finally, the result of As you can see, I\u2019m using constants and variables where possible to avoid hard-coding any values. This prevents simple typos from creating false positives or negatives in your tests.<\/p>\n With these two tests, you actually achieve 100% test coverage<\/strong> for the variable template, because the code tests all the possible variations of the variable.<\/p>\n When writing tests, you\u2019re faced with interesting design decisions as well.<\/p>\n Take the example above. We\u2019re not specifically testing a scenario where the user didn\u2019t add any<\/em> input to the field. Why? Because we\u2019ve decided to handle that in the user interface, by adding a validation rule<\/a> that prevents the template code from running if there is no input in the field.<\/p>\n So when writing tests, you need to know how the template works, and you need to be able to comprehensively approach the different scenarios that imaginative users can exploit when working with your template code.<\/p>\n You\u2019ve learned above that unit tests have some specific components. They are, in order:<\/p>\n Mock of the data object<\/strong> To test a function, you use mock data<\/em>. This is because with automated tests there is no prompt for user input. The test needs to run independently of the template itself. With unit tests, you are only<\/strong> testing the code itself, not the user experience.<\/p>\n In Google Tag Manager\u2019s custom templates, mock data comes in two guises: the contents of the The first is simple to do. You build an object, where each key corresponds to a property of the For example, if your template has a text input<\/a> field named This mock data object would correspond with field input like this:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n You pass this mock data object to the When you run tests for your template, you might not want the template to actually perform the API calls it is configured to do.<\/p>\n Calling This is where API mocking plays a vital row. In the Tests interface, you can replace<\/strong> API functionality with a mock function. This way you can run the test as if<\/em> the template had called the API, and process the returned value as if<\/em> the API had returned it.<\/p>\n For example, let\u2019s say we have a tag template that injects a script onto the page, where the domain name is input by the user into a template field. This is what the template code would look like:<\/p>\n To test this, you could write a test that simply checks if However, this test actually tries to send the pixel request to the domain name, meaning it\u2019s difficult to test positive and negative results without polluting the endpoint.<\/p>\n Instead, you can mock<\/strong> the API like this:<\/p>\n With So when using APIs that invoke external endpoints, it might be a good idea to mock them.<\/p>\n Mocks are reset with every test, so you don\u2019t have to worry about your Once you have your mocks ready, you can invoke the This method runs the template code, mocking the APIs you have chosen to replace, and using the data object that you pass to it as an argument.<\/p>\n If you do not pass any object to it as an argument, or if you pass an empty object, the template will be run as if the user had not added any input to any field.<\/p>\n With tag templates<\/strong>, you just need to execute With variable templates<\/strong>, the template should actually return<\/strong> something, and thus your assertions should also be done against the result<\/em> of Once the test has run, you are ready to assert<\/strong> the results.<\/p>\n Custom Templates offer an API you can use to immediately fail a test.<\/p>\n Note that the typical use case for Some like to use a fail mechanism to indicate tests that have not yet been written, others like to use it to expose paths that should never be encountered by tests.<\/p>\n Typically, you wouldn\u2019t use To use You can use It\u2019s not pretty, but it does its job while we wait for new assertion APIs to be added.<\/p>\n With assertions<\/strong>, you are making statements about the results of the test. The best assertion libraries are a pleasure to use, because assertions are written with a grammar and syntax reminiscent of actual language.<\/p>\n For example, to assert that the variable template code returns a specific value, you add something like:<\/p>\n The test is a success<\/strong> if the assertion resolves to With APIs, you are asserting whether the API was called or not.<\/p>\n This test would be a success if the NOTE!<\/strong> To test whether an API was called with specific parameters, you should mock<\/strong> that API instead.<\/p>\n<\/blockquote>\n You can add more than one assertion<\/strong> to a test case. All the assertions must pass for the test to be a success. I do recommend trying to keep the number of assertions per test to a minimum, though, as having granular test cases lets you more easily identify the link between the failed test and the broken code that caused it to fail.<\/p>\n The The The syntax is this:<\/p>\n The Some of the APIs (e.g. Many APIs don\u2019t take any arguments at all – they are used for quick, simple assertions such as whether the asserted value was defined or not.<\/p>\n Here are the assertions supported by the API.<\/p>\n![\"Custom](\"https:\/\/www.simoahava.com\/images\/2019\/11\/custom-template-tests.jpg#ZgotmplZ\")
<\/p>\n
\n X<\/span><\/p>\n
\n The Simmer Newsletter<\/strong>\n <\/p>\nUnit tests in Custom Templates<\/h2>\n
Simple example of coverage<\/h3>\n
const<\/span> getType = require('getType'<\/span>);\nconst<\/span> input = data.input;\nif<\/span> (getType(input) === 'array'<\/span>) {\n return<\/span>;\n}\nreturn<\/span> input;\n<\/code><\/pre>\n<\/div>\nundefined<\/code> is returned instead.<\/p>\n1. Does the variable return
undefined<\/code> for array input<\/h4>\n\/\/ Call runCode to run the template's code.\n<\/span>const<\/span> mockData = {\n input: 'notAnArray'<\/span>\n};\n\nconst<\/span> variableResult = runCode(mockData);\n\n\/\/ Verify that the variable returns a result.\n<\/span>assertThat(variableResult).isUndefined();\n<\/code><\/pre>\n<\/div>\ndata<\/code> object, reflecting the input the user would have added to the template fields.<\/p>\nrunCode<\/code> function, which is a template API that runs the template code against the data object.<\/p>\nrunCode<\/code> is passed to assertThat<\/code>, which is an assertion<\/strong> method where you check whether the result of the code resolves to an expected value.<\/p>\n2. Does the variable return the input<\/h4>\n
const<\/span> mockInput = 'something'<\/span>;\nconst<\/span> mockData = {\n input: mockInput\n};\n\nconst<\/span> expected = mockInput;\n\nconst<\/span> variableResult = runCode(mockData);\n\n\/\/ Verify that the variable returns a result.\n<\/span>assertThat(variableResult).isEqualTo(expected);\n<\/code><\/pre>\n<\/div>\nWhat about missing input?<\/h4>\n
The anatomy of a test<\/h2>\n
Mocks of the template APIs (mock()<\/code>)<\/strong>
The test runner (runCode()<\/code>)<\/strong>
(Optional fail()<\/code>)<\/strong>
Assertions (assertApi()<\/code>, assertThat()<\/code>)<\/strong><\/p>\n1. Mocking<\/h3>\n
data<\/code> object, and the result of running template APIs<\/a>.<\/p>\nMocking the
data<\/code> object<\/h4>\ndata<\/code> object that your code processes.<\/p>\nname<\/code> and then a simple table<\/a> field named optionalParameters<\/code>, you could build a mock object like this:<\/p>\nconst<\/span> mockData = {\n name: 'Simo Ahava'<\/span>,\n optionalParameters: [{\n parameterName: 'country'<\/span>,\n parameterValue: 'Finland'<\/span>\n },{\n parameterName: 'hair_color'<\/span>,\n parameterValue: 'n\/a'<\/span>\n }]\n};\n<\/code><\/pre>\n<\/div>\n![\"Mock](\"https:\/\/www.simoahava.com\/images\/2019\/11\/mockdata.jpg#ZgotmplZ\")
<\/p>\nrunCode<\/code> method (more on this below) so that the template code is run with input from the object.<\/p>\nMocking template APIs<\/h4>\n
sendPixel<\/code><\/a> over and over again with different inputs might not<\/em> make a lot of sense.<\/p>\nconst<\/span> sendPixel = require('sendPixel'<\/span>);\n\nconst<\/span> domainName = data.domainName;\n\nsendPixel(domainName, data.gtmOnSuccess, data.gtmOnFailure);\n<\/code><\/pre>\n<\/div>\ngtmOnSuccess<\/code> was called for a valid hostname and gtmOnFailure<\/code> for an invalid one:<\/p>\nconst<\/span> mockData = {\n domainName: 'https:\/\/invalid.com'<\/span>\n};\nrunCode(mockData);\nassertApi('gtmOnFailure'<\/span>).wasCalled();\n<\/code><\/pre>\n<\/div>\nconst<\/span> mockData = {\n domainName: 'https:\/\/invalid.com'<\/span>\n};\n\nmock('sendPixel'<\/span>, (url, onSuccess, onFailure) => {\n onFailure();\n});\n\nrunCode(mockData);\n\nassertApi('gtmOnFailure'<\/span>).wasCalled();\n<\/code><\/pre>\n<\/div>\nmock<\/code>, you instruct the test to use the function stub you provide, meaning whenever the sendPixel<\/code> API is invoked, it always runs the onFailure()<\/code> method regardless of input (at least, in this current test).<\/p>\nonFailure()<\/code> leaking into other tests, too.<\/p>\n2. Running the code<\/h3>\n
runCode()<\/code> method.<\/p>\nrunCode()<\/code>, because your assertions will be made against the APIs that have been called. Tag templates do not return anything, so there\u2019s nothing to assess from the result of runCode()<\/code>.<\/p>\nrunCode()<\/code>.<\/p>\nconst<\/span> mockData = {input: 'test'<\/span>};\n\n\/\/ With tag templates\n<\/span>runCode(mockData);\nassertApi('someApi'<\/span>).wasCalled();\n\n\/\/ With variable templates\n<\/span>const<\/span> result = runCode(mockData);\nassertThat(result).isEqualTo('test'<\/span>);\n<\/code><\/pre>\n<\/div>\n3. Failing the test<\/h3>\n
fail()<\/code> is to evaluate the test itself<\/em> rather than the code that is being tested.<\/p>\nfail()<\/code> in production-ready code, because there would not be incomplete tests and assertion logic would handle all possible permutations of the template code.<\/p>\nfail()<\/code> is dead simple – just add the command to a branch of the code, and set the failure message as the argument.<\/p>\nconst<\/span> mockData = {input: 'test'<\/span>};\n\nconst<\/span> result = runCode(mockData);\n\nif<\/span> (result === undefined<\/span>) {\n fail('Result should never be undefined.'<\/span>);\n}\nassertThat(result).isEqualTo('test'<\/span>);\n<\/code><\/pre>\n<\/div>\nfail()<\/code> to create custom assertions. For example, to check if the object returned by the code contains some property, you could do this:<\/p>\nconst<\/span> mockData = {input: 'test'<\/span>};\n\nconst<\/span> result = runCode(mockData);\n\nif<\/span> (result.hasOwnProperty('someProperty'<\/span>)) {\n assertThat(true<\/span>);\n} else<\/span> {\n fail('Variable did not have \"someProperty\".'<\/span>);\n}\n<\/code><\/pre>\n<\/div>\n4. Assertions<\/h3>\n
assertThat(runCodeResult).isEqualTo('some value'<\/span>);\n<\/code><\/pre>\n<\/div>\ntrue<\/code>. In other words, if the runCodeResult<\/code> had exactly the value 'some value'<\/code>, the test would pass.<\/p>\nassertApi('sendPixel'<\/span>).wasCalled();\n<\/code><\/pre>\n<\/div>\nsendPIxel<\/code> API was invoked during the execution of the test code.<\/p>\n\n
Using
assertThat<\/code><\/h4>\nassertThat<\/code> API allows you to make assertions about the result of the code execution. The assertions follow the syntax used by e.g. Google\u2019s Truth<\/a> and the AssertJ<\/a> library.<\/p>\nassertThat<\/code> API is most useful when testing variable templates, because the assertions would be run against the result (the returned value) of the variable template itself.<\/p>\nassertThat(someValueToTest).assertion(someExpectedValue);<\/code><\/p>\nassertThat()<\/code> method takes the value to test as an argument, and it returns an object with all the different assertion APIs listed below.<\/p>\nisEqualTo()<\/code>) take an argument, where the asserted value is tested against this argument.<\/p>\n\n\n
\n \nAssertion<\/th>\n Description<\/th>\n<\/tr>\n<\/thead>\n \n isEqualTo(someValue)<\/code><\/td>\nChecks if the asserted value is equal to someValue<\/code>. Equality is not strict – you can check if [1, 2, 3]<\/code> equals [1, 2, 3]<\/code> and the test will pass. Similarly, you can check complex objects and the assertion will succeed if they have the exact same keys and values.<\/td>\n<\/tr>\n\n