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 --save
To 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:
- constructor
- get
- getContainerIDs
- getDataModel
- getEvents
- getLatestEvent
- getLatestMessage
- history
- push
- waitForEvent
Instantiates the dataLayer class
pagestring The page object as provided by puppeteercontainerIdstring The containerId of the GTM container you want to interact with
Gets the current value of the specified dataLayer variable
variablestring The variable in the regular GTM dot-notation
Returns 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, defaultthis.containerId)Thestring GTM Container ID to fetch the data model from. Defaults to thecontainerIddefined on the instance
Returns Promise A Promise that resolves to the data model of dataLayer as an object
Returns all dataLayer events matching the given event name
eventstring The event name
Returns 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
eventNamestring The event name to match
Returns 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
messageobject The message to push
Waits for the specified dataLayer event
eventstring The event to wait foroptionsobject 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