Jump to content

Test Kitchen/Local development setup

From Wikitech

This guide describes the steps you need to run a local MediaWiki configured to work with Test Kitchen, either to create/modify/test instruments or work on any client library.

Currently, the JS and PHP Test Kitchen SDKs work within EventLogging (which is part of the Event Platform environment for MediaWiki) and MetricsPlatform extensions. Before getting started with Test Kitchen, you need to have an up-to-date MediaWiki development environment. This guide includes instructions for setting up Test Kitchen using MediaWiki Docker, MediaWiki Vagrant, or your local dev environment.

Using MediaWiki Docker

To set up MediaWiki Docker, follow the instructions in DEVELOPERS.md in the root of the mediawiki/core repository.

Once your MediaWiki site is fully installed, you will need to install and configure the components required to work with Test Kitchen:

  • Event Platform: Follow the instructions in the Event Platform section to set up an Event Platform environment alongside your MediaWiki development environment. You will be able to log events to a containerized EventGate instance (herein "EventGate") from both server-side and client-side MediaWiki code. EventGate will validate events against schemas fetched from https://schema.wikimedia.org.
  • Configuring Test Kitchen: Follow the instructions in the Configuring Test Kitchen section to configure streams and launch some sample events using the Test Kitchen SDK to see them in the local Event Platform you have installed before. That way you will test that everything is working.
  • Install MetricsPlatform extension: Follow the instructions in the Install MetricsPlatform extension section to install this extension and enable experimentation capabilities for Test Kitchen.

Configuring Test Kitchen

Here we'll configure some streams in our local MediaWiki site to test the Test Kitchen SDK to produce sample events. That way we will be able to conclude that our environment is working fine. In the end, Test Kitchen instruments are pieces of code that reside somewhere and end up producing events using one of the following functions we are going to test. In this case we are going to test using the JavaScript SDK but we could do something similar for the other SDKs (PHP, Java and Swift).

To do that, we'll configure a stream in LocalSettings.php to test some of the functions that are currently available in the JavaScript Test Kitchen SDK (anyway take a look at the JavaScript SDK to see how to develop an instrument properly using this client library)

Keep in mind that, you can, for example, keep open your events.json file to see how the events are produced while testing all these functions: 

tail -f events.json

Add the following configuration to your LocalSettings.php to enable a new stream called my_stream: 

$wgEventStreams = [
    // Here are the configuration for all existing streams
    'my_stream' => [
	    'schema_title' => '/analytics/product_metrics/web/base',
	    'destination_event_service' => 'eventgate-analytics-external',
	    'producers' => [
		    'metrics_platform_client' => [
			    'provide_values' => [
				    'performer_is_logged_in',
				    'mediawiki_skin',
			    ],
		    ],
	    ],
    ],
];
$wgEventLoggingStreamNames = array_keys( $wgEventStreams );

Once that done, you should be able to see how an event is produced using the developer console in your browser taking a look at the Network tab. You can use submitClick to submit an action that will be identified as a click or submitInteracion if you want to pass the related action as a parameter.

submitClick

We can produce an event for this new stream with the following code, using only its name:

mw.eventLog.submitClick('my_stream');

submitInteraction

We can produce an event for this new stream with the following code, passing its name, the schema and the action we want to register as parameters:

mw.eventLog.submitInteraction('my_stream',   
   '/analytics/product_metrics/web/base/1.4.1', 'init');

Working with schemas locally

If you are working on creating or updating schemas, you can configure MediaWiki and your local Event Gate to use your local schemas repository. Follow the Event Platform with local schema repositories recipe.

Install MetricsPlatform extension

MetricsPlatform extension is the way for Test Kitchen to provide experimentation capabilities. You need to install to enable those features.

You can install MetricsPlatform extension by running the following command from the root folder of your MediaWiki installation: 

git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/MetricsPlatform extensions/MetricsPlatform

Configuration

Load and enable the extension and some features you may need by adding the following to your LocalSettings.php file: 

// Load the extension
wfLoadExtension( [
    // other extensions might be here
    'MetricsPlatform',
] );
// Set the MPIC URL (this example considers it's running on your localhost)
$wgMetricsPlatformInstrumentConfiguratorBaseUrl = 'https://host.docker.internal';
// Ensures, when logged into MediaWiki locally, xLab API / MPIC is used (see [[phab:T398422]])
$wgMetricsPlatformEnableExperimentConfigsFetching = true;
// Enable experimentation capabilities (disabled by default)
$wgMetricsPlatformEnableExperiments = true;
// You *may/probably* want stream config merging, but commented out here.
// $wgMetricsPlatformEnableStreamConfigsMerging = true;

Useful commands

  • Start the environment: docker compose up -d
  • Stop the container: docker compose stop
  • Destroy the environment: docker compose down

Using MediaWiki Vagrant

Enabling the wikimediaevents role will also include the eventlogging role for you, and set up other Event Platform backend components on MediaWiki Vagrant including EventGate. 

$ vagrant roles enable wikimediaevents --provision
$ vagrant git-update

This will clone WikimediaEvents into mediawiki/extensions/WikimediaEvents and the schemas/event/secondary repository at srv/schemas/event/secondary (and also install its npm dependencies for schema materialization and tests).

Events will be written to /vagrant/logs/eventgate-events.json. eventgate logs, including validation errors, are in /vagrant/logs/eventgate-wikimedia.log.

To verify that eventgate is working properly, you can force a test event to be produced by curl-ing http://localhost:8192/v1/_test/events. You should see a test event logged into eventgate-events.json.

Using your local dev environment with eventgate-devserver

If you aren't using MediaWiki Docker or Mediawiki-Vagrant, or you'd rather have more manual control over your development environment, EventLogging comes with an 'eventgate-devserver' that will accept events and write them to a local file. Clone mediawiki/extensions/EventLogging and run 

$ cd extensions/EventLogging/devserver
$ npm install --no-optional
$ npm run eventgate-devserver

This should download EventGate and other dependencies and run the eventgate-devserver accepting events at http://localhost:8192 and writing them to ./events.json. See devserver/README.md for more info.

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Test_Kitchen/Local_development_setup&oldid=2366037"