Skip to main content

Desktop Testing

Test helpers for writing automated tests for Nimbus feature integrations on Desktop.

In order to make testing easier we created some helpers that can be accessed by including

const { ExperimentFakes } = ChromeUtils.importESModule(
  "resource://testing-common/NimbusTestUtils.sys.mjs",
);

Testing Your Feature Integrating with Nimbus​

You need to provide a feature configuration and await enrollment

let doExperimentCleanup = await ExperimentFakes.enrollWithFeatureConfig({
  featureId: "<YOUR FEATURE>",
  // You can add values for each variable you added to the manifest
  value: {
    enabled: true,
  },
});

// Now you can assume the feature is enabled so you can
// test and that it's doing the right thing

// Assert.ok(It works!)

// Finishing up
await doExperimentCleanup();

Testing with a live Nimbus recipe​

If you already published an experiment through Nimbus then you will want to test enrollment in the browser.

  1. Flip the following pref to true in the browser you want to enroll (in about:config)

nimbus.debug

  1. You need to copy paste the following URL and fill in the required details.

For experiments that are already live:

about:studies?optin_slug=<YOUR_EXPERIMENT_SLUG>&optin_branch=<BRANCH_SLUG_TO_ENROLL>

For experiments that are in "preview" mode:

about:studies?optin_slug=<YOUR_EXPERIMENT_SLUG>&optin_branch=<BRANCH_SLUG_TO_ENROLL>&optin_collection=nimbus-preview

Testing with Desktop Rollouts​

For writing tests you usually want to have the following modules imported:

const { ExperimentAPI, NimbusFeatures } = ChromeUtils.importESModule(
  "resource://nimbus/ExperimentAPI.sys.mjs",
);
const { ExperimentFakes } = ChromeUtils.importESModule(
  "resource://testing-common/NimbusTestUtils.sys.mjs",
);

Next this is how you would set up your feature to test integration with Desktop Rollouts:

// Ensure everything has finished initializing
await ExperimentAPI.ready();
// The actual setup
const doCleanup = await ExperimentFakes.enrollWithFeatureConfig(
  {
    // Reference your feature id already defined in the FeatureManifest.yaml
    featureId: "<YOUR FEATURE ID>",
    value: {
      enabled: true,
    },
  },
  { isRollout: true }
);

// Now your feature integration is ready for testing

// NimbusFeatures.<YOUR FEATURE>.getVariable("enabled")
// NimbusFeatures.<YOUR FEATURE>.getAllVariables()

await doCleanup(); // to remove the rollout

Testing with gTest​

Otherwise for a gTest or other requirements you can set a pref nimbus.syncdatastore.<feature name>.<variable name> with the appropriate type you defined in the FeatureManifest.

⚠️ This variable naming convention is an implementation detail and might change in the future.

#include "mozilla/browser/NimbusFeatures.h"

# Set a preference as described above based on what you want the test to do

// GetInt will return the appropriate value you set
NimbusFeatures::GetInt("aboutwelcome"_ns, "skipFocus"_ns, false);

// On update will call your callback function when the pref value changes
NimbusFeatures::OnUpdate("aboutwelcome"_ns, "skipFocus"_ns,
  [](const char*, void*){}, void*);

Examples​

Examples of platform consumers: