Bug 1527299 - Add a short explanation of Event Telemetry Testing to the docs. r=janerik
authorChris H-C <chutten@mozilla.com>
Wed, 27 Feb 2019 10:24:58 +0000
changeset 519665 30cf58a30352c23a8d6070f7d1bc17534854d3da
parent 519664 034dce9d9393f0b0a3a9ac7f61bebe4e34ff2915
child 519666 0b75d7939fe20aeddccecb4426bb738d365c5130
push id10862
push userffxbld-merge
push dateMon, 11 Mar 2019 13:01:11 +0000
treeherdermozilla-beta@a2e7f5c935da [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjanerik
bugs1527299
milestone67.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1527299 - Add a short explanation of Event Telemetry Testing to the docs. r=janerik Differential Revision: https://phabricator.services.mozilla.com/D20865
toolkit/components/telemetry/docs/collection/events.rst
--- a/toolkit/components/telemetry/docs/collection/events.rst
+++ b/toolkit/components/telemetry/docs/collection/events.rst
@@ -308,16 +308,33 @@ value ``2`` and the content-process scal
 ``interaction#click#document`` with the value ``4``.
 
 All dynamically-registered events end up in the dynamic-process ``telemetry.dynamic_event_counts``
 (notice the different name) regardless of in which process the events were recorded. From the
 example above, if ``interaction.click.document`` was registered with ``registerEvents`` then
 the dynamic-process scalar ``telemetry.dynamic_event_counts`` would have a key
 ``interaction#click#document`` with the value ``6``.
 
+Testing
+=======
+
+Tests involving Event Telemetry often follow this four-step form:
+
+1. ``Services.telemetry.clearEvents();`` To minimize the effects of prior code and tests.
+2. ``Services.telemetry.setEventRecordingEnabled(myCategory, true);`` To enable the collection of
+   your events. (May or may not be relevant in your case)
+3. ``runTheCode();`` This is part of the test where you call the code that's supposed to collect
+   Event Telemetry.
+4. ``TelemetryTestUtils.assertEvents(expected, filter, options);`` This will check the
+   events recorded by Event Telemetry against your provided list of expected events.
+   If you only need to check the number of events recorded, you can use
+   ``TelemetryTestUtils.assertNumberOfEvents(expectedNum, filter, options);``.
+   Both utilities have `helpful inline documentation <https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/telemetry/tests/utils/TelemetryTestUtils.jsm>`_.
+
+
 Version History
 ===============
 
 - Firefox 52: Initial event support (`bug 1302663 <https://bugzilla.mozilla.org/show_bug.cgi?id=1302663>`_).
 - Firefox 53: Event recording disabled by default (`bug 1329139 <https://bugzilla.mozilla.org/show_bug.cgi?id=1329139>`_).
 - Firefox 54: Added child process events (`bug 1313326 <https://bugzilla.mozilla.org/show_bug.cgi?id=1313326>`_).
 - Firefox 56: Added support for recording new probes from add-ons (`bug 1302681 <bug https://bugzilla.mozilla.org/show_bug.cgi?id=1302681>`_).
 - Firefox 58: