Skip to content

Commit 3f2160d

Browse files
RJAK11RJAK11
authored
Update docs for nimbus devtools (#647)
* revised docs to recommend Nimbus DevTools for local testing * added a Nimbus DevTools guide describing its features and uses Fixes #646
1 parent df0d696 commit 3f2160d

File tree

2 files changed

+136
-5
lines changed

2 files changed

+136
-5
lines changed

‎docs/additional-links/nimbus-devtools-guide.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
id: nimbus-devtools-guide
3+
title: Nimbus Developer Tools Guide
4+
slug: /nimbus-devtools-guide
5+
---
6+
7+
# Nimbus Developer Tools Guide
8+
9+
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.
10+
11+
### Installation
12+
13+
To install the Nimbus Developer Tools, download the latest release from the [Nimbus DevTools GitHub repository](https://github.com/mozilla-extensions/nimbus-devtools/releases).
14+
15+
## Core Features
16+
17+
### 1. Experiment Enrollment via JSON Recipe
18+
19+
The **Experiment Enrollment** feature allows you to manually enroll in an experiment by pasting its JSON recipe.
20+
21+
- **How to Use**:
22+
1. Load `about:studies` and ensure that your profile is not enrolled in any conflicting experiments.
23+
2. On the **Experimenter** page for your experiment, copy the contents of the `Recipe JSON` field from the `Summary` tab.
24+
3. Navigate to the Nimbus Developer Tools **JSON Enrollment** page.
25+
4. Paste the copied JSON into the provided textarea.
26+
5. Click **Enroll**.
27+
6. Reload `about:studies` to see the experiment.
28+
29+
### 2. Experiment Enrollment via Feature Configuration
30+
31+
The **Feature Configuration Enrollment** feature allows you to enroll in specific feature configurations for experiments.
32+
33+
- **How to Use**:
34+
1. Load `about:studies` and ensure that your profile is not enrolled in any conflicting experiments.
35+
2. Navigate to the Nimbus Developer Tools **Feature Configuration** page.
36+
3. Select a **Feature ID** from the dropdown.
37+
4. Set the `isRollout` option to `true` or `false` as required.
38+
5. Paste the feature configuration JSON into the textarea.
39+
6. Click **Enroll**.
40+
7. Reload `about:studies` to see the experiment.
41+
42+
### 3. JEXL Debugger
43+
44+
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.
45+
46+
- **How to Use**:
47+
1. Navigate to the **JEXL Debugger** page in Nimbus Developer Tools.
48+
2. Enter your JEXL expression in the provided text area.
49+
3. Click **Evaluate** to test the expression and view the results in the **Output** section.
50+
51+
- **Editing Client Context**:
52+
1. Modify the client context values to simulate different user conditions.
53+
2. Click **Evaluate** again to see how the expression responds to the modified context.
54+
3. Use the **Refresh** button to reset the client context to its original state.
55+
56+
### 4. Experiment Store
57+
58+
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.
59+
60+
- **How to Use**:
61+
1. Navigate to the **Experiment Store** page in Nimbus Developer Tools.
62+
2. Browse through available experiments.
63+
3. To manage enrollments:
64+
- Click **Unenroll** to remove yourself from an active experiment.
65+
- Click **Delete** to remove inactive experiments from the store.
66+
67+
### 5. Experiment Browser
68+
69+
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.
70+
71+
Key features include:
72+
- **Environment Switching**: Choose between **Production** and **Stage** environments to view experiments specific to each environment.
73+
- **Status Filtering**: Filter experiments by **Live** or **Preview** status to focus on active or upcoming experiments.
74+
- **Experiment Details**: For each experiment, view key information such as the **name**, **description**, **channel**, **version**, and **enrollment status**.
75+
- **Branch Selection**: Select a specific branch from a dropdown menu to either **force enroll** in an experiment or **generate a test ID**.
76+
- **Refresh**: Use the **Refresh** button to update the experiment list in real-time, ensuring you're working with the most current data.
77+
78+
79+
### 6. Choosing Experiment Collection
80+
81+
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.
82+
83+
You can choose from three options:
84+
1. **Live (nimbus-desktop-experiments)**: Syncs with the collection used for live experiments.
85+
2. **Preview (nimbus-preview)**: Syncs with the preview collection for testing experiments.
86+
3. **Custom**: Allows you to specify a custom collection for specialized testing needs.
87+
88+
- **How to Use**:
89+
1. Navigate to the **Settings** page in Nimbus Developer Tools.
90+
2. Under **Choose Experiment Collection**, select **Live**, **Preview**, or **Custom** depending on your testing needs.
91+
3. If you choose **Custom**, enter the collection name to load your specified records.
92+
93+
### 7. Manual Experiment Reloading
94+
95+
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.
96+
97+
You can choose from two scenarios:
98+
1. **Update Local Remote Settings Collection**: This will sync your local copy with the latest data from Remote Settings.
99+
2. **Re-evaluate Experiments Without Syncing**: This will refresh the experiment targeting and conditions without syncing the Remote Settings collection.
100+
101+
- **How to Use**:
102+
1. Navigate to the **Settings** page in Nimbus Developer Tools.
103+
2. Choose **Update with Remote Settings Sync** to fetch the latest data from Remote Settings.
104+
3. Alternatively, select **Update without Remote Settings Sync** to refresh only the experiment targeting and conditions.
105+
106+
This gives you the flexibility to either update the Remote Settings data or just re-evaluate experiments without syncing.

‎docs/deep-dives/desktop/desktop-enroll-locally.md

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,22 +8,47 @@ slug: /desktop-enroll-locally
88

99
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.
1010

11-
## Enable Nimbus debugging
11+
## Option A: Enrollment via Nimbus Developer Tools
12+
13+
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:
14+
15+
### Recipe JSON Enrollment
16+
1. Load `about:studies` and unenroll this profile from anything that might interfere
17+
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
18+
3. Navigate to the Nimbus Developer Tools `JSON Enrollment` page
19+
4. Paste the JSON from the `Recipe JSON` field in the provided textarea
20+
5. Click `Enroll`
21+
6. Reload `about:studies`, and you should see the experiment
22+
23+
### Feature Configuration Enrollment
24+
1. Load `about:studies` and unenroll this profile from anything that might interfere
25+
2. Navigate to the Nimbus Developer Tools `Feature Configuration` page.
26+
3. Select the feature ID from the dropdown
27+
4. Set the `isRollout` option to either `true` or `false` as needed
28+
5. Paste the feature configuration JSON into the textarea.
29+
6. Click `Enroll`.
30+
7. Reload `about:studies`, and you should see the experiment
31+
32+
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).
33+
34+
## Option B: Manual Enrollment via Browser Console
35+
36+
### Enable Nimbus debugging
1237

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

16-
## Enable the Browser Toolbox
41+
### Enable the Browser Toolbox
1742

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

22-
## Prepare a few things:
47+
### Prepare a few things:
2348
* Load `about:studies` and unenroll this profile from anything that might interfere
2449
* 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
2550

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

36-
## Reload `about:studies`, and you should see the experiment
61+
### Reload `about:studies`, and you should see the experiment

0 commit comments

Comments
 (0)