Skip to content

Commit

Permalink
Update docs for nimbus devtools (#647)
Browse files Browse the repository at this point in the history 
* revised docs to recommend Nimbus DevTools for local testing
* added a Nimbus DevTools guide describing its features and uses

Fixes #646
  • Loading branch information
@RJAK11
RJAK11 authored Nov 8, 2024
1 parent df0d696 commit 3f2160d
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 5 deletions.
106 changes: 106 additions & 0 deletions docs/additional-links/nimbus-devtools-guide.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
---
id: nimbus-devtools-guide
title: Nimbus Developer Tools Guide
slug: /nimbus-devtools-guide
---

# Nimbus Developer Tools Guide

This guide provides an overview of the Nimbus Developer Tools, designed for Nimbus experiment debugging. With these tools, you can more easily test experiments, debug targeting expressions, and browse through available experiments.

### Installation

To install the Nimbus Developer Tools, download the latest release from the [Nimbus DevTools GitHub repository](https://github.com/mozilla-extensions/nimbus-devtools/releases).

## Core Features

### 1. Experiment Enrollment via JSON Recipe

The **Experiment Enrollment** feature allows you to manually enroll in an experiment by pasting its JSON recipe.

- **How to Use**:
1. Load `about:studies` and ensure that your profile is not enrolled in any conflicting experiments.
2. On the **Experimenter** page for your experiment, copy the contents of the `Recipe JSON` field from the `Summary` tab.
3. Navigate to the Nimbus Developer Tools **JSON Enrollment** page.
4. Paste the copied JSON into the provided textarea.
5. Click **Enroll**.
6. Reload `about:studies` to see the experiment.

### 2. Experiment Enrollment via Feature Configuration

The **Feature Configuration Enrollment** feature allows you to enroll in specific feature configurations for experiments.

- **How to Use**:
1. Load `about:studies` and ensure that your profile is not enrolled in any conflicting experiments.
2. Navigate to the Nimbus Developer Tools **Feature Configuration** page.
3. Select a **Feature ID** from the dropdown.
4. Set the `isRollout` option to `true` or `false` as required.
5. Paste the feature configuration JSON into the textarea.
6. Click **Enroll**.
7. Reload `about:studies` to see the experiment.

### 3. JEXL Debugger

The **JEXL Debugger** allows you to test JavaScript Expression Language (JEXL) expressions, which are used to define targeting conditions for experiments. You can test expressions with different client context values to ensure they behave as expected.

- **How to Use**:
1. Navigate to the **JEXL Debugger** page in Nimbus Developer Tools.
2. Enter your JEXL expression in the provided text area.
3. Click **Evaluate** to test the expression and view the results in the **Output** section.

- **Editing Client Context**:
1. Modify the client context values to simulate different user conditions.
2. Click **Evaluate** again to see how the expression responds to the modified context.
3. Use the **Refresh** button to reset the client context to its original state.

### 4. Experiment Store

The **Experiment Store** lets you browse all experiments stored in `about:studies`, giving you information about each experiment’s description, feature IDs, and status. You can also use the browser to unenroll from experiments or delete inactive ones.

- **How to Use**:
1. Navigate to the **Experiment Store** page in Nimbus Developer Tools.
2. Browse through available experiments.
3. To manage enrollments:
- Click **Unenroll** to remove yourself from an active experiment.
- Click **Delete** to remove inactive experiments from the store.

### 5. Experiment Browser

The **Experiment Browser** serves as a hub for browsing through experiments from different environments and with different statuses. You can view information about experiments and take actions like enrolling or generating test IDs for specific branches.

Key features include:
- **Environment Switching**: Choose between **Production** and **Stage** environments to view experiments specific to each environment.
- **Status Filtering**: Filter experiments by **Live** or **Preview** status to focus on active or upcoming experiments.
- **Experiment Details**: For each experiment, view key information such as the **name**, **description**, **channel**, **version**, and **enrollment status**.
- **Branch Selection**: Select a specific branch from a dropdown menu to either **force enroll** in an experiment or **generate a test ID**.
- **Refresh**: Use the **Refresh** button to update the experiment list in real-time, ensuring you're working with the most current data.


### 6. Choosing Experiment Collection

The **Choose Experiment Collection** option allows you to select which Nimbus Remote Settings collection to use for experiments. This feature enables you to toggle between live and preview collections or specify a custom collection for advanced testing.

You can choose from three options:
1. **Live (nimbus-desktop-experiments)**: Syncs with the collection used for live experiments.
2. **Preview (nimbus-preview)**: Syncs with the preview collection for testing experiments.
3. **Custom**: Allows you to specify a custom collection for specialized testing needs.

- **How to Use**:
1. Navigate to the **Settings** page in Nimbus Developer Tools.
2. Under **Choose Experiment Collection**, select **Live**, **Preview**, or **Custom** depending on your testing needs.
3. If you choose **Custom**, enter the collection name to load your specified records.

### 7. Manual Experiment Reloading

The **Manual Experiment Reload** option allows you to manually trigger updates for experiments, giving you control over whether or not you sync with the Remote Settings collection.

You can choose from two scenarios:
1. **Update Local Remote Settings Collection**: This will sync your local copy with the latest data from Remote Settings.
2. **Re-evaluate Experiments Without Syncing**: This will refresh the experiment targeting and conditions without syncing the Remote Settings collection.

- **How to Use**:
1. Navigate to the **Settings** page in Nimbus Developer Tools.
2. Choose **Update with Remote Settings Sync** to fetch the latest data from Remote Settings.
3. Alternatively, select **Update without Remote Settings Sync** to refresh only the experiment targeting and conditions.

This gives you the flexibility to either update the Remote Settings data or just re-evaluate experiments without syncing.
35 changes: 30 additions & 5 deletions docs/deep-dives/desktop/desktop-enroll-locally.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,47 @@ slug: /desktop-enroll-locally

Trying to iterate on an experiment in Preview on experimenter.services.mozilla.com can be painful, because even after you change something and post to preview, you have a wait a while for the updated recipe to be propagated to the CDN.

## Enable Nimbus debugging
## Option A: Enrollment via Nimbus Developer Tools

Nimbus Developer Tools provides a simple interface to debug experiments. You can download and install the extension from the [Nimbus DevTools GitHub release page](https://github.com/mozilla-extensions/nimbus-devtools/releases). Here are some of the ways you can use it to debug experiments locally:

### Recipe JSON Enrollment
1. Load `about:studies` and unenroll this profile from anything that might interfere
2. On the Experimenter page for your experiment, select the contents of the `Recipe JSON` field from the `Summary` tab, and copy it into your Copy/Paste buffer
3. Navigate to the Nimbus Developer Tools `JSON Enrollment` page
4. Paste the JSON from the `Recipe JSON` field in the provided textarea
5. Click `Enroll`
6. Reload `about:studies`, and you should see the experiment

### Feature Configuration Enrollment
1. Load `about:studies` and unenroll this profile from anything that might interfere
2. Navigate to the Nimbus Developer Tools `Feature Configuration` page.
3. Select the feature ID from the dropdown
4. Set the `isRollout` option to either `true` or `false` as needed
5. Paste the feature configuration JSON into the textarea.
6. Click `Enroll`.
7. Reload `about:studies`, and you should see the experiment

For a more comprehensive overview of the Nimbus Developer Tools, including additional features beyond this, check out the [Nimbus Developer Tools Guide](docs/additional-links/nimbus-devtools-guide.md).

## Option B: Manual Enrollment via Browser Console

### Enable Nimbus debugging

* In `about:config`, set:
* `nimbus.debug` to `true`

## Enable the Browser Toolbox
### Enable the Browser Toolbox

* In `about:config`, set:
* `devtools.chrome.enabled` to `true`
* `devtools.debugger.remote-enabled` to `true`

## Prepare a few things:
### Prepare a few things:
* Load `about:studies` and unenroll this profile from anything that might interfere
* On the Experimenter page for your experiment, select the contents of the `Recipe JSON` field from the `Details` tab, and copy it into your Copy/Paste buffer

## Do the Enrollment
### Do the Enrollment
* Open `Tools > Browser Tools > Browser Toolbox`
* Switch to the browser console
* In the input area, do the following:
Expand All @@ -33,4 +58,4 @@ Trying to iterate on an experiment in Preview on experimenter.services.mozilla.c
* `let branch = recipe.branches.find(b => b.slug == branchSlug);`
* `em.forceEnroll(recipe, branch);`

## Reload `about:studies`, and you should see the experiment
### Reload `about:studies`, and you should see the experiment

0 comments on commit 3f2160d

Please sign in to comment.