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 = await 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 = await 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 up-to-date documentation, see the JavaScript SDK documentation microsite . For parameter descriptions and validation rules, see the web schema definition .