summaryrefslogtreecommitdiffstats
path: root/toolkit/components/telemetry/tests/utils
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/components/telemetry/tests/utils')
-rw-r--r--toolkit/components/telemetry/tests/utils/TelemetryTestUtils.sys.mjs428
1 files changed, 428 insertions, 0 deletions
diff --git a/toolkit/components/telemetry/tests/utils/TelemetryTestUtils.sys.mjs b/toolkit/components/telemetry/tests/utils/TelemetryTestUtils.sys.mjs
new file mode 100644
index 0000000000..075c0afbe7
--- /dev/null
+++ b/toolkit/components/telemetry/tests/utils/TelemetryTestUtils.sys.mjs
@@ -0,0 +1,428 @@
+/* Any copyright is dedicated to the Public Domain.
+ http://creativecommons.org/publicdomain/zero/1.0/ */
+
+import { Assert } from "resource://testing-common/Assert.sys.mjs";
+
+export var TelemetryTestUtils = {
+ /* Scalars */
+
+ /**
+ * A helper that asserts the value of a scalar.
+ *
+ * @param {Object} scalars The snapshot of the scalars.
+ * @param {String} scalarName The name of the scalar to check.
+ * @param {Boolean|Number|String} value The expected value for the scalar.
+ * @param {String} msg The message to print when checking the value.
+ */
+ assertScalar(scalars, scalarName, value, msg) {
+ Assert.equal(scalars[scalarName], value, msg);
+ },
+
+ /**
+ * A helper that asserts a scalar is not set.
+ *
+ * @param {Object} scalars The snapshot of the scalars.
+ * @param {String} scalarName The name of the scalar to check.
+ */
+ assertScalarUnset(scalars, scalarName) {
+ Assert.ok(!(scalarName in scalars), scalarName + " must not be reported.");
+ },
+
+ /**
+ * Asserts if the snapshotted keyed scalars contain the expected
+ * data.
+ *
+ * @param {Object} scalars The snapshot of the keyed scalars.
+ * @param {String} scalarName The name of the keyed scalar to check.
+ * @param {String} key The key that must be within the keyed scalar.
+ * @param {String|Boolean|Number} expectedValue The expected value for the
+ * provided key in the scalar.
+ */
+ assertKeyedScalar(scalars, scalarName, key, expectedValue) {
+ Assert.ok(scalarName in scalars, scalarName + " must be recorded.");
+ Assert.ok(
+ key in scalars[scalarName],
+ scalarName + " must contain the '" + key + "' key."
+ );
+ Assert.equal(
+ scalars[scalarName][key],
+ expectedValue,
+ scalarName + "['" + key + "'] must contain the expected value"
+ );
+ },
+
+ /**
+ * Returns a snapshot of scalars from the specified process.
+ *
+ * @param {String} aProcessName Name of the process. Could be parent or
+ * something else.
+ * @param {boolean} [aKeyed] Set to true if keyed scalars rather than normal
+ * scalars should be snapshotted.
+ * @param {boolean} [aClear] Set to true to clear the scalars once the snapshot
+ * has been obtained.
+ * @param {Number} aChannel The channel dataset type from nsITelemetry.
+ * @returns {Object} The snapshotted scalars from the parent process.
+ */
+ getProcessScalars(
+ aProcessName,
+ aKeyed = false,
+ aClear = false,
+ aChannel = Ci.nsITelemetry.DATASET_PRERELEASE_CHANNELS
+ ) {
+ const extended = aChannel == Ci.nsITelemetry.DATASET_PRERELEASE_CHANNELS;
+ const currentExtended = Services.telemetry.canRecordExtended;
+ Services.telemetry.canRecordExtended = extended;
+ const scalars = aKeyed
+ ? Services.telemetry.getSnapshotForKeyedScalars("main", aClear)[
+ aProcessName
+ ]
+ : Services.telemetry.getSnapshotForScalars("main", aClear)[aProcessName];
+ Services.telemetry.canRecordExtended = currentExtended;
+ return scalars || {};
+ },
+
+ /* Events */
+
+ /**
+ * Asserts that the number of events, after filtering, is equal to numEvents.
+ *
+ * @param {Number} numEvents The number of events to assert.
+ * @param {Object} filter As per assertEvents.
+ * @param {Object} options As per assertEvents.
+ */
+ assertNumberOfEvents(numEvents, filter, options) {
+ // Create an array of empty objects of length numEvents
+ TelemetryTestUtils.assertEvents(
+ Array.from({ length: numEvents }, () => ({})),
+ filter,
+ options
+ );
+ },
+
+ /**
+ * Returns the events in a snapshot, after optional filtering.
+ *
+ * @param {Object} filter An object of strings or RegExps for first filtering
+ * the event snapshot. Of the form {category, method, object}.
+ * Absent filters filter nothing.
+ * @param {Object} options An object containing any of
+ * - process {string} the process to examine. Default parent.
+ */
+ getEvents(filter = {}, { process = "parent" } = {}) {
+ // Step 0: Snapshot and clear.
+ let snapshots = Services.telemetry.snapshotEvents(
+ Ci.nsITelemetry.DATASET_PRERELEASE_CHANNELS,
+ false
+ );
+
+ if (!(process in snapshots)) {
+ return [];
+ }
+
+ let snapshot = snapshots[process];
+
+ // Step 1: Filter.
+ // Shared code with the below function
+ let {
+ category: filterCategory,
+ method: filterMethod,
+ object: filterObject,
+ } = filter;
+ let matches = (expected, actual) => {
+ if (expected === undefined) {
+ return true;
+ } else if (expected && expected.test) {
+ // Possibly a RegExp.
+ return expected.test(actual);
+ } else if (typeof expected === "function") {
+ return expected(actual);
+ }
+ return expected === actual;
+ };
+
+ return snapshot
+ .map(([, /* timestamp */ category, method, object, value, extra]) => {
+ // We don't care about the `timestamp` value.
+ // Tests that examine that value should use `snapshotEvents` directly.
+ return [category, method, object, value, extra];
+ })
+ .filter(([category, method, object]) => {
+ return (
+ matches(filterCategory, category) &&
+ matches(filterMethod, method) &&
+ matches(filterObject, object)
+ );
+ })
+ .map(([category, method, object, value, extra]) => {
+ return { category, method, object, value, extra };
+ });
+ },
+
+ /**
+ * Asserts that, after optional filtering, the current events snapshot
+ * matches expectedEvents.
+ *
+ * @param {Array} expectedEvents An array of event structures of the form
+ * [category, method, object, value, extra]
+ * or the same as an object with fields named as above.
+ * The array can be empty to assert that there are no events
+ * that match the filter.
+ * Each field can be absent/undefined (to match
+ * everything), a string or null (to match that value), a
+ * RegExp to match what it can match, or a function which
+ * matches by returning true when called with the field.
+ * `extra` is slightly different. If present it must be an
+ * object whose fields are treated the same way as the others.
+ * @param {Object} filter An object of strings or RegExps for first filtering
+ * the event snapshot. Of the form {category, method, object}.
+ * Absent filters filter nothing.
+ * @param {Object} options An object containing any of
+ * - clear {bool} clear events. Default true.
+ * - process {string} the process to examine. Default parent.
+ */
+ assertEvents(
+ expectedEvents,
+ filter = {},
+ { clear = true, process = "parent" } = {}
+ ) {
+ // Step 0: Snapshot and clear.
+ let snapshots = Services.telemetry.snapshotEvents(
+ Ci.nsITelemetry.DATASET_PRERELEASE_CHANNELS,
+ clear
+ );
+ if (expectedEvents.length === 0 && !(process in snapshots)) {
+ // Job's done!
+ return;
+ }
+ Assert.ok(
+ process in snapshots,
+ `${process} must be in snapshot. Has [${Object.keys(snapshots)}].`
+ );
+ let snapshot = snapshots[process];
+
+ // Step 1: Filter.
+ // Shared code with the above function
+ let {
+ category: filterCategory,
+ method: filterMethod,
+ object: filterObject,
+ } = filter;
+ let matches = (expected, actual) => {
+ if (expected === undefined) {
+ return true;
+ } else if (expected && expected.test) {
+ // Possibly a RegExp.
+ return expected.test(actual);
+ } else if (typeof expected === "function") {
+ return expected(actual);
+ }
+ return expected === actual;
+ };
+
+ let filtered = snapshot
+ .map(([, /* timestamp */ category, method, object, value, extra]) => {
+ // We don't care about the `timestamp` value.
+ // Tests that examine that value should use `snapshotEvents` directly.
+ return [category, method, object, value, extra];
+ })
+ .filter(([category, method, object]) => {
+ return (
+ matches(filterCategory, category) &&
+ matches(filterMethod, method) &&
+ matches(filterObject, object)
+ );
+ });
+
+ // Step 2: Match.
+ Assert.equal(
+ filtered.length,
+ expectedEvents.length,
+ "After filtering we must have the expected number of events."
+ );
+ if (expectedEvents.length === 0) {
+ // Job's done!
+ return;
+ }
+
+ // Transform object-type expected events to array-type to match snapshot.
+ if (!Array.isArray(expectedEvents[0])) {
+ expectedEvents = expectedEvents.map(
+ ({ category, method, object, value, extra }) => [
+ category,
+ method,
+ object,
+ value,
+ extra,
+ ]
+ );
+ }
+
+ const FIELD_NAMES = ["category", "method", "object", "value", "extra"];
+ const EXTRA_INDEX = 4;
+ for (let i = 0; i < expectedEvents.length; ++i) {
+ let expected = expectedEvents[i];
+ let actual = filtered[i];
+
+ // Match everything up to `extra`
+ for (let j = 0; j < EXTRA_INDEX; ++j) {
+ if (expected[j] === undefined) {
+ // Don't spam the assert log with unspecified fields.
+ continue;
+ }
+ Assert.report(
+ !matches(expected[j], actual[j]),
+ actual[j],
+ expected[j],
+ `${FIELD_NAMES[j]} in event ${actual[0]}#${actual[1]}#${actual[2]} must match.`,
+ "matches"
+ );
+ }
+
+ // Match extra
+ if (
+ expected.length > EXTRA_INDEX &&
+ expected[EXTRA_INDEX] !== undefined
+ ) {
+ Assert.ok(
+ actual.length > EXTRA_INDEX,
+ `Actual event ${actual[0]}#${actual[1]}#${actual[2]} expected to have extra.`
+ );
+ let expectedExtra = expected[EXTRA_INDEX];
+ let actualExtra = actual[EXTRA_INDEX];
+ for (let [key, value] of Object.entries(expectedExtra)) {
+ Assert.ok(
+ key in actualExtra,
+ `Expected key ${key} must be in actual extra. Actual keys: [${Object.keys(
+ actualExtra
+ )}].`
+ );
+ Assert.report(
+ !matches(value, actualExtra[key]),
+ actualExtra[key],
+ value,
+ `extra[${key}] must match in event ${actual[0]}#${actual[1]}#${actual[2]}.`,
+ "matches"
+ );
+ }
+ }
+ }
+ },
+
+ /* Histograms */
+
+ /**
+ * Clear and get the named histogram.
+ *
+ * @param {String} name The name of the histogram
+ * @returns {Object} The obtained histogram.
+ */
+ getAndClearHistogram(name) {
+ let histogram = Services.telemetry.getHistogramById(name);
+ histogram.clear();
+ return histogram;
+ },
+
+ /**
+ * Clear and get the named keyed histogram.
+ *
+ * @param {String} name The name of the keyed histogram
+ * @returns {Object} The obtained keyed histogram.
+ */
+ getAndClearKeyedHistogram(name) {
+ let histogram = Services.telemetry.getKeyedHistogramById(name);
+ histogram.clear();
+ return histogram;
+ },
+
+ /**
+ * Assert that the histogram index is the right value. It expects that
+ * other indexes are all zero.
+ *
+ * @param {Object} histogram The histogram to check.
+ * @param {Number} index The index to check against the expected value.
+ * @param {Number} expected The expected value of the index.
+ */
+ assertHistogram(histogram, index, expected) {
+ const snapshot = histogram.snapshot();
+ let found = false;
+ for (let [i, val] of Object.entries(snapshot.values)) {
+ if (i == index) {
+ found = true;
+ Assert.equal(
+ val,
+ expected,
+ `expected counts should match for ${histogram.name()} at index ${i}`
+ );
+ } else {
+ Assert.equal(
+ val,
+ 0,
+ `unexpected counts should be zero for ${histogram.name()} at index ${i}`
+ );
+ }
+ }
+ Assert.ok(
+ found,
+ `Should have found an entry for ${histogram.name()} at index ${index}`
+ );
+ },
+
+ /**
+ * Assert that a key within a keyed histogram contains the required sum.
+ *
+ * @param {Object} histogram The keyed histogram to check.
+ * @param {String} key The key to check.
+ * @param {Number} [expected] The expected sum for the key.
+ */
+ assertKeyedHistogramSum(histogram, key, expected) {
+ const snapshot = histogram.snapshot();
+ if (expected === undefined) {
+ Assert.ok(
+ !(key in snapshot),
+ `The histogram ${histogram.name()} must not contain ${key}.`
+ );
+ return;
+ }
+ Assert.ok(
+ key in snapshot,
+ `The histogram ${histogram.name()} must contain ${key}.`
+ );
+ Assert.equal(
+ snapshot[key].sum,
+ expected,
+ `The key ${key} must contain the expected sum in ${histogram.name()}.`
+ );
+ },
+
+ /**
+ * Assert that the value of a key within a keyed histogram is the right value.
+ * It expects that other values are all zero.
+ *
+ * @param {Object} histogram The keyed histogram to check.
+ * @param {String} key The key to check.
+ * @param {Number} index The index to check against the expected value.
+ * @param {Number} [expected] The expected values for the key.
+ */
+ assertKeyedHistogramValue(histogram, key, index, expected) {
+ const snapshot = histogram.snapshot();
+ if (!(key in snapshot)) {
+ Assert.ok(false, `The histogram ${histogram.name()} must contain ${key}`);
+ return;
+ }
+ for (let [i, val] of Object.entries(snapshot[key].values)) {
+ if (i == index) {
+ Assert.equal(
+ val,
+ expected,
+ `expected counts should match for ${histogram.name()} at index ${i}`
+ );
+ } else {
+ Assert.equal(
+ val,
+ 0,
+ `unexpected counts should be zero for ${histogram.name()} at index ${i}`
+ );
+ }
+ }
+ },
+};