Jump to content

Test Kitchen/Local development setup

From Wikitech
Note that, when working with experiments regardless of they are logged-in or logged-out, there is also a way of testing your code locally via HTTP_header for which no local instance of Test Kitchen UI is needed.

This guide describes the steps you need to run a local MediaWiki configured to work with Test Kitchen and create/modify/test instruments.

Currently, the JS and PHP Test Kitchen SDKs are included in TestKitchen 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.
  • Install TestKitchen extension: Follow the instructions in the Install TestKitchen extension section to install this extension and enable experimentation capabilities for Test Kitchen.
  • 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 TestKitchen extension

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

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

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

Configure TestKitchen extension

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

// Load the extension
wfLoadExtensions( [
    // other extensions might be here
    'TestKitchen',
] );
// Set the Test Kitchen service URL (this example considers it's running on your localhost)
// Linux users might need to use '127.17.0.1' instead of 'host.docker.internal'. The latter doesn't work for some distributions
$wgTestKitchenInstrumentConfiguratorBaseUrl = 'http://host.docker.internal:8086';
// Ensures, when testing/debugging with Test Kitchen UI and MediaWiki locally, Test Kitchen API is used
$wgTestKitchenEnableConfigsFetching = true;
// Enable experimentation capabilities (disabled by default)
$wgTestKitchenEnableExperiments = true;

Configuring MediaWiki to use the Test Kitchen local development environment

A local development environment is ready to be used as part of the `TestKitchen` extension. That way a local instance of Test Kitchen UI will be be launched automatically when running the mediawiki environment via docker compose up -d

Assuming that you have already followed the instructions to configure an Event Platform environment alongside your MediaWiki development environment (recommended/required for local testing) and also the ones to work with local schemas (recommended in the case you are working with a custom schema and you want to also test it along with your instrumentation code), the following would be your docker-compose.override.yml file that resides in the root folder of a MediaWiki instance after adding two additional services: test-kitchen + test-kitchen-db, which allow to run the Test Kitchen service that includes Test Kitchen UI, the web application where instruments/experiments are registered and also Test Kitchen API, that serves that configuration to the components that need it. 

services:
  eventlogging:
    build: "./extensions/EventLogging/devserver"
    volumes:
      - "./cache/events.json:/opt/eventlogging/events.json"
      - "./cache/eventgate.config.yaml:/opt/eventlogging/eventgate.config.yaml"
      - "./cache/primary:/opt/eventlogging/primary"
      - "./cache/secondary:/opt/eventlogging/secondary"
    ports:
      - "8192:8192"

  test-kitchen:
    extends:
      file: ./extensions/TestKitchen/devserver/docker-compose.yml
      service: test-kitchen

  test-kitchen-db:
    extends:
      file: ./extensions/TestKitchen/devserver/docker-compose.yml
      service: test-kitchen-db
    volumes:
      - ./cache/test-kitchen-db:/var/lib/mysql

This way, when you run docker compose up -d from the mediawiki root folder to start your MediaWiki instance, a local instance of Test Kitchen UI will be also running at http://localhost:8086 where you can register your own local instruments/experiments for when developing/debugging locally.

Configure the web/base stream in your local MediaWiki

product_metrics.web_base is the stream that instruments/experiments use by default when working with Test Kitchen. So your local environment should include, at least, the configuration for this stream, that you will have to add to the LocalSetting.php file of your MediaWiki instance: 

$wgEventStreams = [
    'product_metrics.web_base' => [
		'schema_title' => 'analytics/test_kitchen/web/base',
		'destination_event_service' => 'eventgate-analytics-external',
		'producers' => [
			'metrics_platform_client' => [],
		],
		'eventgate' => [
			'enrich_fields_from_http_headers' => [
				'http.request_headers.user-agent' => false,
			],
			'use_edge_uniques' => true,
		]
	],
];

Same way, you can also add additional custom streams if they are needed by your instruments/experiments and you want to work on/test/debug them using your local environment.

Writing the first instrument

Firstly we will have to register and turn on an instrument using our local instance of Test Kitchen UI. (that will be running at http://localhost:8086). Validation may not let you set a start date before today, so you may need to edit the record: 

$ docker compose exec test-kitchen-db bash
$ mariadb -umaria -pmaria
MariaDB [(none)]> update test_kitchen.instruments set utc_start_dt = '2026-03-11 14:30:00' where id=...;

Now you can start implementing the instrumentation code in WikimediaEvents extension. Let's say you have registered an instrument in your local Test Kitchen UI whose machine-readable name is my-instrument. The following code will instantiate your instrument via JS Test Kitchen SDK and send an event to your local EventGate instance. 

mw.loader.using( 'ext.testKitchen' ).then( () => {
    const myInstrument = mw.testKitchen.getInstrument( 'my-experiment' );
    myInstrument.send( 'some_action' );
} );

Those events will be sent to your local eventgate instance and will be stored in the cache/events.json file. So you can monitor how events are submitted via the following command: 

tail -f events.json

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.

Useful commands

  • Start the environment: docker compose up -d
  • Stop the container: docker compose stop
  • Destroy the environment: docker compose down
  • See the events that reach the local EventGate: tail -f cache/events.json

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=2401829"