TypeScript icon, indicating that this package has built-in type declarations

5.0.0 • Public • Published

Node workflow

Gravity Data Collector - README

This repo contains the browser implementation of the Gravity Data Collector. Learn more about Gravity on our website



npm i @smartesting/gravity-data-collector

Via Yarn

yarn add @smartesting/gravity-data-collector

By updating package.json

In your package.json, add the following:

  "dependencies": {
    "@smartesting/gravity-data-collector": "^5.0.0"

In your package.json, add the following:

From a script tag

Put this tag in each page that must use Gravity Data Collector.


Please, look to index.html to see how to use the script in HTML.

Note: The minified version of Gravity Data Collector is available only since release 2.1.5


// initialize
import GravityCollector from '@smartesting/gravity-data-collector/dist'



The GravityCollector.init() can take a CollectorOptions object with the following optional properties:

key type use default value
authKey String The authentication key provided by Gravity to select the correct collection
requestInterval Integer Time (in ms) between two sends to Gravity server (buffering) 1000
gravityServerUrl String Gravity server URL https://api.gravity.smartesting.com
debug Boolean Logs user action in the console instead of sending them to Gravity false
maxDelay Integer In debug mode, adds a random delay (in ms) between 0 and this value before printing an user action. 500
selectorsOptions Object (optional) See Work with selectors. undefined
sessionsPercentageKept [0..100] Rate of sessions to be collected 100
rejectSession function () => boolean Boolean function to ignore session tracking. For instance, to ignore sessions from some bots:
rejectSession: () => /bot|googlebot|robot/i.test(navigator.userAgent)
() => false
onPublish function (optional) Adds a function called after each publish to the gravity server. undefined
recordRequestsFor String[] (optional) The Gravity Data Collector does not record requests by default. You must specify here the URL origin(s) of the requests to record. For example: "https://myserver.com/" undefined
buildId String (optional) The build reference when running tests undefined
useHashInUrlAsPathname Boolean (optional) Set to true to have a correct representation of pages in Gravity if your page URLs look like this: "http://mysite.com/#/something/else" false
cookieStrategy CookieStrategy ('default', 'subDomains' or 'iframeEmbedding') Change the way the cookie is set: default works in most cases, subDomains should be used to track a single session accross multiple sub domains, iframeEmbedding should be used if your app is embedded as an iframe (eg: Jira or Azure DevOps plugin) 'default'
cookieWriter (key, value, options) => string (optional) A function used to create the cookie alue (if you need to specify custom options) null


Work with selectors

In the Gravity Data Collector, when a user action targets an HTML element, selectors are computed in order to replay the session as an automated test.

By default, the following selectors are computed:

  • xpath: a XPath selector to reach the element (eg: /html/body/div)
  • queries: on object describing various ways to reach the objet
    • id: if available, the element's id (eg: #my-object)
    • class: if available, selection of the object following CSS classes (eg: .my-container .some-class)
    • tag: selection based on the tags (eg: html body div ul li)
    • nthChild: selection based on nth-child (eg: :nth-child(2) > :nth-child(4))
    • attributes: if available, selection based on the nodes attributes (eg: [name=])
    • combined: a combination of the previous selectors (eg: #menu nav :nth-child(2))
  • attributes: a hash of attributes provided by the user (default: ['data-testid'])

Tweaking selectors

xpath is always collected.

When initializing the collector, you can specify which selectors (in the queries field) and attributes you want to collect.

GravityCollector.init({ selectorsOptions: { attributes: ['data-testid', 'role'] } })

This configuration will collect all the selectors (default if queries is not specified), the data-testid and the role attributes of the HTML element with which the user interacts.

GravityCollector.init({ selectorsOptions: { queries: ['class', 'tag'] } })

This configuration will collect the CSS class(es), the tag and the data-testid (default if attributes is not specified) of the HTML element with which the user interacts.

Alternatively, you can also exclude some selectors of the queries field. For example, if you do not want id-based selectors, you can specify it this way:

  selectorsOptions: {
    excludedQueries: ['id'],

You can specify both queries and attributes fields:

  selectorsOptions: {
    queries: ['class', 'tag'],
    attributes: ['data-testid', 'role'],

Identify sessions with traits

A sessions trait allows you to add context to the collected sessions, so you can easily segment them in Gravity. It is done by calling the identifySession method.

For instance, you can identify the sessions of users connected to your app:

window.GravityCollector.identifySession('connected', true)

Note: Please, keep in mind that each trait can only have a single value. It means if you set the trait connected to true and then to false, the first value will be overwritten.

Send build information to Gravity

In order to easily identify your tests sessions in Gravity, the data-collector can send build information to Gravity.

The build ID can be specified in multiple way. You can set the following properties on process.env (for example when using React)

environment variable name Gravity data

You can also declare window.GRAVITY_BUILD_ID (or simply declare a global variable GRAVITY_BUILD_ID which should be assigned to the window object).

Another solution is to pass the buildIdparameter when initializing gravity data collector:

  authKey: '...',
  buildId: '1234',


In order to test modifications on the library, a sandbox is accessible in index.html file

First, build the lib

  npm run build

Then build the sandbox and watch for files changes:

npm run build-sandbox
npm run watch-sandbox

Finally, open index.html with a browser, display the console (F12 with most browsers) and interact with the page to see collected user actions.

Note: user actions may not show up in the console and be hidden by default. Ensure Verbose output are allowed by your developer tool.

Any Question ?

Maybe you need help to install and/or understand Gravity Data Collector

  • please visit our documentation pages
  • we start a FAQ hoping it can help you to face eventual problems with th Gravity Data Collector
  • here is a flowchart summarizing how the collector works, depending on the options and configuration of your Gravity project.




Package Sidebar


npm i @smartesting/gravity-data-collector

Weekly Downloads






Unpacked Size

762 kB

Total Files


Last publish


  • jracenet
  • admin-smartesting
  • smart-rfe
  • c.grandpierre
  • vincentpsmartesting
  • yakaldir
  • aymerictn