puppeteer-datalayer is a node.js module to facilitate interaction with Google Tag Manager's dataLayer in combination with Puppeteer.
puppeteer-datalayer was built with the following two main use cases in mind.
Especially when used with other testing tools like Jest and joi it can be a huge timesaver, because you won't have to spend all your time manually clicking through your site to check if your tracking implementation is doing what it's supposed to.
Puppeteer is very useful when doing frontend testing, i. e. checking whether your dataLayer events are trigger properly upon certain user actions on the website, e. g. adding a product to the shopping cart. Checking if the expected event is pushed to dataLayer after mocking the user action is a lot easier with puppeteer-datalayer.
Make sure your tags in GTM work as expected by pushing predefined events to dataLayer. Afterwards you can listen to network requests in Puppeteer to see if the expected requests (Google Analytics, 3rd party conversion tags, …) were triggered and contain the necessary parameters.
You can install this package from npm by executing the following command while in your project directory:
npm install puppeteer-datalayer --saveTo clarify the terminology used in this package:
A message describes any object inside dataLayer regardless of its attributes. These are examples of messages pushed to dataLayer:
dataLayer.push({ event: "addToBasket", product: { id: 12345 } })
dataLayer.push({ order: null })
dataLayer.push({})An event describes any object inside dataLayer that has an event attribute. An event is always a message but not every message is an event.
The name applies no matter whether an event was pushed by a developer-implemented dataLayer.push() or the automatically collected events starting with gtm..
// This is an event
dataLayer.push({ event: "gtm.click" })
// This one, too
dataLayer.push({ event: "addToBasket", product: { id: 12345 } })
// This is not an event, just a message
dataLayer.push({ order: null })Special thanks go out to the following people whose content represents the basis this package was built on. Check out their awesome resources:
Instantiates the dataLayer class
page string The page object as provided by puppeteercontainerId string The containerId of the GTM container you want to interact withGets the current value of the specified dataLayer variable
variable string The variable in the regular GTM
dot-notationReturns Promise Promise that resolves to the current value of the variable
Returns all active container IDs for the page
Returns array An array of strings containing all container IDs
Returns the the full data model, i. e. the current names and values of all variables in dataLayer
containerId (optional, default this.containerId)The string GTM Container ID to fetch the data model from.
Defaults to the containerId defined on the instanceReturns Promise A Promise that resolves to the data model of dataLayer as an object
Returns all dataLayer events matching the given event name
event string The event nameReturns array An array of event objects
Returns the most recent event matching the specified event name from dataLayer. Simply returns the most recent event if no eventName is specified
eventName string The event name to matchReturns Promise A Promise that resolves to the latest da event
Returns the most recent message from dataLayer
Returns Promise A Promise that resolves to the latest dataLayer message
Retrieves all messages that are present in dataLayer
Returns Promise A Promise that resolves to the full dataLayer array
Pushes a message (which can be an event) to the dataLayer
message object The message to pushWaits for the specified dataLayer event
event string The event to wait foroptions object Options to supply to the underlying
waitForFunction, see the puppeteer documentation for valid
options (optional, default {})Returns promise A promise that resolves as soon as the event happens