Test Kitchen/SDK/JavaScript SDK

This page provides a guide to using the JavaScript Test Kitchen SDK for instrument and experiment creators.

Setup

To set up a local development environment for writing instrument code, follow the setup guide for MediaWiki and Test Kitchen. For more context and tooling recommendations, see the introduction to Test Kitchen development.

Create an instrument

Assuming that you have registered already your instrument in Test Kitchen UI, you can instantiate an instrument in your instrumentation code as follows:

const instrument = mw.testKitchen.getInstrument( 'my-machine-readable-instrument-name' );

Once you've created an instrument, you can submit an event using send

Send a click event

send provides a simplified method to send any kind of event that use the Test Kitchen base schemas.

Here's an example of an instrument in JavaScript that uses Instrument#send to submit an event when a user clicks on an interwiki link.

function getLinkInteractionData( jqEvent ) {
    const link = jqEvent.target;

    return {
        action_source: link.href,
        action_context: link.title
    };
}

const instrument = mw.testKitchen.getInstrument( 'my-machine-readable-instrument-name' );

// 'a.extiw' will match anchors that have a extiw class. extiw is used for interwiki links.
$( '#content' ).on(
    'click',
    'a.extiw',
    ( jqEvent ) => instrument.send( 'click', getLinkInteractionData( jqEvent ) )
);

The resulting event:

• includes action: click
• includes optional interaction data (action_source and action_context)
• is validated against the latest Test Kitchen base schema for web, as set in newInstrument
• is published to the specified event stream (in this case, mediawiki.product_metrics.example), as it will have been defined when registering the instrument in Test Kitchen UI

Submit an interaction event

An interaction event is meant to represent a basic interaction with some target or some event occurring. For example, a user hovers over a UI element or an app notifies the server of its current state.

Here's an example of an instrument in JavaScript that uses Instrument#send to send an event when a user hovers over an interwiki link.

$( '#content' ).on(
    'mouseover',
    'a.extiw',
    ( jqEvent ) => instrument.send( 'hover', getLinkInteractionData( jqEvent ) )
);

The resulting event:

• includes the specified value of action
• includes optional interaction data you have provided in getLinkInteractionData (action_source and action_context)
• is validated against the specified schema (in this case, the Test Kitchen base schema for web), as it will have been defined when registering the instrument in Test Kitchen UI
• is published to the specified event stream (in this case, mediawiki.product_metrics.example), as it will have been defined when registering the instrument in Test Kitchen UI

Implementation

The JavaScript SDK is provided by the TestKitchen extension.

The EventLogging extension maintains a list of streams to be included in the module, $wgEventLoggingStreamNames, which can be used to minimize the size of the module. When $wgEventLoggingStreamNames is falsy the JavaScript SDK will not validate whether the destination stream is configured before submitting the event to the destination event service.

Reference

For parameter descriptions and validation rules, see the web schema definition.

Instruments

mw.testKitchen.getInstrument

Create a new Instrument according to the configuration defined in Test Kitchen UI

Parameters:

• instrumentName (string): Name of the instrument that has been registered in Test Kitchen UI

Instrument#isInSample

Check if the instrument's stream is in sample

Instrument#send

Submit an interaction event to an event stream for an instrument. An interaction event represents a basic interaction with some target or an event occurring, such as the performer clicking a UI element or an app notifying the server of its current state.

Parameters:

• action (string): Name of the interaction. For example, scroll
• (optional) interactionData (key/value pairs): Additional event data. This data must validate against the specified schema. For example, see the interaction data fields supported by the base schema for web.

Instrument#setSchema

Sets the ID of the schema used to validate analytics events sent with

Parameters:

• schemaID (string): schemaID

Experiments

mw.testKitchen.getExperiment

Get an instance of an existing Experiment according to the configuration defined in Test Kitchen UI.

Note that, by default, analytics/product_metrics/web/base/2.0.0 will be the schemaID. You can set a different one by calling Experiment#setSchema(schemaID)

Parameters:

• experimentName (string): Name of the experiment

Experiment#getAssignedGroup

Gets the group assigned to the current user

Experiment#isAssignedGroup

Gets whether the group assigned to the user is one of the given groups

Parameters:

• groups (...string): groups

Experiment#send

Sends an event to the stream that is configured within the current experiment

Parameters:

• action (string): The action that the user enrolled in this experiment took
• (optional) interactionData (key/value pairs): Additional data about the action that the user enrolled in the experiment took
• (optional) contextualAttributes (array): Additional per-event contextual attributes. These contextual attributes will be added to the ones that are defined in the stream associated with this instrument

Experiment#sendExposure

Sends an exposure event to the stream that is configured within the current experiment

Experiment#setSchema

Sets the ID of the schema used to validate analytics events sent with

Parameters:

• schemaID (string): schemaID