|
1 | 1 | # Native Messaging Test Runner |
2 | 2 |
|
3 | 3 | The Native Messaging Test Runner is a Node application for testing the Native Messaging |
4 | | -functionality in Desktop, specifically the commands received from the DuckDuckGo browser. It |
| 4 | +functionality in Desktop, specifically the commands received from the DuckDuckGo (DDG) browser. It |
5 | 5 | communicates with the desktop app using Inter-process communication (IPC). It was created to enable |
6 | 6 | development on the native messages themselves, and to give QA the ability to test these commands. It |
7 | 7 | is located |
8 | 8 | [here](https://github.com/bitwarden/clients/tree/main/apps/desktop/native-messaging-test-runner) at |
9 | 9 | the root of the `desktop` app in `bitwarden/clients` repo. |
10 | 10 |
|
| 11 | +:::note |
| 12 | + |
| 13 | +This tool does not provide complete testing coverage for the DDG integration. It is a useful tool |
| 14 | +during development, to troubleshoot, and as a general regression check. To do a full comprehensive |
| 15 | +test of the DDG integration, download the DDG browser and test directly with it. |
| 16 | + |
| 17 | +::: |
| 18 | + |
11 | 19 | ## Getting started |
12 | 20 |
|
| 21 | +0. (optional) [Install](https://duckduckgo.com/app) the Duck Duck Go browser. While this is not |
| 22 | + strictly required to utilize the test runner, without it, [errors](#troubleshooting) are apt to |
| 23 | + occur. |
| 24 | + |
13 | 25 | 1. Clone the [bitwarden/clients](https://github.com/bitwarden/clients) repo |
14 | 26 | 2. Run the desktop app locally following [these](../desktop/index.mdx) instructions |
15 | 27 | 3. In the running desktop app, go to `Preferences` and turn on the |
@@ -114,14 +126,30 @@ Utility used by the `IPCService` when creating a promise that allows the usage o |
114 | 126 | waiting for messages. We can't guarantee that we will get a response from the desktop app, so this |
115 | 127 | allows us to gracefully cancel if a response isn't received in a timely manner. |
116 | 128 |
|
| 129 | +## PR reviews |
| 130 | + |
| 131 | +If you're reading this documentation because of an automated message from GitHub Actions to validate |
| 132 | +the DDG integration as part of your PR, please follow the steps above and use the following |
| 133 | +guidelines for what to validate: |
| 134 | + |
| 135 | +- If the DDG integration's feature code is modified, use commands that map to areas of the feature |
| 136 | + that are impacted. |
| 137 | + - For example: If there are cipher changes, the `status` and `bw-credential-create` should be |
| 138 | + tested. |
| 139 | +- If the PR is a non-breaking change dependency update, `status` is sufficient. |
| 140 | + |
117 | 141 | ## Troubleshooting |
118 | 142 |
|
119 | | -- If you are seeing unexpected behavior with services used by the test runner or when editing |
120 | | - commands, delete the `dist` folder at the top level of the `native-messaging-test-runner` and |
121 | | - re-run the command. |
| 143 | +- If you are seeing unexpected behavior or timeouts with services used by the test runner or when |
| 144 | + editing commands: 1. Close the desktop app. 2. Delete the `dist` folder at the top level of the |
| 145 | + `native-messaging-test-runner`. 3. Run the desktop app. 3. Run `npm ci` in the |
| 146 | + `native-messaging-test-runner` folder. 4. Re-try the command. |
122 | 147 |
|
123 | 148 | - If you are adding/editing command files and getting a `MODULE_NOT_FOUND` error when running the |
124 | 149 | command, make sure you have `import "module-alias/register";` in your command file. This maps the |
125 | 150 | compiled JavaScript classes to the ones used in the Typescript files. |
126 | 151 |
|
127 | 152 |  |
| 153 | + |
| 154 | +- If you are seeing messages in the runner output stating `Received unexpected: { <...>`, those are |
| 155 | + benign, but should resolve upon completing [step 0 of Getting Started](#getting-started). |
0 commit comments