Skip to content

Commit 668463c

Browse files
authored
Minor additions to DDG native messaging test runner (#780)
1 parent 0943b20 commit 668463c

1 file changed

Lines changed: 32 additions & 4 deletions

File tree

docs/getting-started/clients/desktop/native-messaging-test-runner.md

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,27 @@
11
# Native Messaging Test Runner
22

33
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
55
communicates with the desktop app using Inter-process communication (IPC). It was created to enable
66
development on the native messages themselves, and to give QA the ability to test these commands. It
77
is located
88
[here](https://github.com/bitwarden/clients/tree/main/apps/desktop/native-messaging-test-runner) at
99
the root of the `desktop` app in `bitwarden/clients` repo.
1010

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+
1119
## Getting started
1220

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+
1325
1. Clone the [bitwarden/clients](https://github.com/bitwarden/clients) repo
1426
2. Run the desktop app locally following [these](../desktop/index.mdx) instructions
1527
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
114126
waiting for messages. We can't guarantee that we will get a response from the desktop app, so this
115127
allows us to gracefully cancel if a response isn't received in a timely manner.
116128

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+
117141
## Troubleshooting
118142

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.
122147

123148
- If you are adding/editing command files and getting a `MODULE_NOT_FOUND` error when running the
124149
command, make sure you have `import "module-alias/register";` in your command file. This maps the
125150
compiled JavaScript classes to the ones used in the Typescript files.
126151

127152
![Screenshot of MODULE_NOT_FOUND error](native-messaging/module-not-found.png)
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

Comments
 (0)