Configure data collection

The data collector works out of the box without any further configuration. But you might want to tweak a few of its default settings.

#Configure element selectors

How are built selectors?

When the collector records an end-user interaction with an element (button, text fields...), it automatically computes a CSS selector that helps to:

• Locate the element on the page when browsing sessions
• Compute the coverage of a usage
• Generate the test script

Depending on the HTML attributes of the element, the collector will build a selector based on them in this order of priority:

1. When a custom selector is specified at the collector initialization (see next section), the defined attribute will be used ( e.g., [my-custom-data=register-button])
2. The ID attribute of the element if it's unique on the page (e.g., #register-button)
3. The class attribute of the element if it's unique on the page `(e.g., .cls-btn-register)
4. Full path CSS selector (e.g., :nth-child(3) > div > button)

For example, when clicking on this button:

  <button id="register-button" class="cls-btn-register">
    Register
  </button>

The collector will build the following selector:

  "target": {
    ...
    "selector": "#register-button"
    ...
  }

Use a custom selector

In some cases, the default way to build the selector just won't work for various reasons, such as:

• IDs are not unique or automatically generated by your JS framework
• The attributes do not hold any business information making it hard to find out what element has been actioned

You can override this behavior by specifying a specific custom attribute to build the selector from the init method of the collector: For example, you might want to reuse your data-testid attributes:

  GravityCollector.init({ customSelector: 'data-testid' })

So when this button receives a click:

  <button data-testid="register-button" id="register-button" class="cls-btn-register">
    Register
  </button>

The collector will build the following selector:

  "target": {
    ...
    "selector": "[data-testid=register-button]"
    ...
  }

Deal with auto-generated IDs (React, Vue.js,...)

Auto-generated IDs and CSS classes in the HTML code can interfere with the way the collector builds element selectors.

For example, clicking on this button:

  <button id="ID-123-APP" class="cls-btn-register">
    Register
  </button>

Will produce the following selector:

  "target": {
    ...
    "selector": "#ID-123-APP"
    ...
  }

Which has the following drawbacks:

• Hard to identify which button has been clicked at a glance
• These kind of generated values can change from a build of your app to another, making the usages you defined and your end-to-end tests fragile and inaccurate

You can force the collector to ignore these attributes by using the excludeRegex option of the collector initialization method:

  GravityCollector.init({ excludeRegex: /^#ID-.*-APP$/ })

If we apply this setting to the previous example, the selector will now be:

  "target": {
    ...
    "selector": ".cls-btn-register"
    ...
  }

#Add custom data (traits)

When you'll start collecting sessions, you might quickly need to segment them by some business criteria (personae, access rights, customers/free users...) in order to better target your tests (see the "Segmenting sessions" section of this page).

Session traits allow 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)

#Track test execution

By default, every collected test sessions are stored together. For example, if your tests are run by a CI tool, all the sessions created by the execution of a test by a build won't be grouped in Gravity. It can be a problem if you want to evaluate your application usage coverage by a specific version of your tests.

In order to easily identify your tests sessions in Gravity, the gravity-data-collector can send test run information along interaction data. This is what we call a build in the Gravity UI.

Concretely, you need to set one of the two following environment variables with an identifier for the current test execution (a build number for instance):

• GRAVITY_BUILD_ID
• REACT_APP_GRAVITY_BUILD_ID (in the case of a create-react-app application)

If one of these variables is set, the collector will automatically send the build number with your test sessions. You don't need further configuration at the gravity-data-collector level. Builds are displayed in the sessions list: