Better instruction in test READMEs (#3929)

2 files changed, 23 insertions, 17 deletions

diff --git a/tools/test-helper/README.md b/tools/test-helper/README.md
index f95b8d73..6eab6abd 100644
--- a/tools/test-helper/README.md
+++ b/tools/test-helper/README.md
@@ -1,29 +1,34 @@
 # Test helper
 
 This is a small VS Code extension that helps with managing Typst's test suite.
-When installed, a new Code Lens appears in all `.typ` files in the `tests`
-folder. It provides the following actions:
+When installed, for all `.typ` files in the `tests` directory, the following
+Code Lens buttons will appear above every test's name:
 
 - View: Opens the output and reference image of a test to the side.
 - Run: Runs the test and shows the results to the side.
+- Save: Runs the test with `--update` to save the reference image.
 - Terminal: Runs the test in the integrated terminal.
 
-In the side panel, there are a few menu actions at the top right:
+In the side panel opened by the Code Lens buttons, there are a few menu buttons
+at the top right:
 
-- Refresh: Reloads the panel to reflect changes to the images
-- Run: Runs the test and shows the results
-- Save: Runs the test with `--update` to save the reference image
+- Refresh: Reloads the panel to reflect changes to the images.
+- Run: Runs the test and shows the results.
+- Save: Runs the test with `--update` to save the reference image.
 
 ## Installation
-First, you need to build the extension:
+In order for VS Code to run the extension with its built-in
+[Node](https://nodejs.org) engine, you need to first build it from source.
+Navigate to `test-helper` directory and build the extension:
 ```bash
-npm i
-npm run build
+npm install    # Install the dependencies.
+npm run build  # Build the extension from source.
 ```
 
-Then, you can easily install and (and keep it up-to-date) via VS Code's UI:
+Then, you can easily install it (and keep it up-to-date) via VS Code's UI:
 - Go to View > Command Palette or press Cmd/Ctrl+P,
-- In the drop down list, pick command "Developer: Install extension from
-  location",
+- In the drop down list, pick command "Developer: Install Extension from
+  Location",
 - Select this `test-helper` directory in the file explorer dialogue box. VS Code
-  will add the extension's path to `~/.vscode/extensions/extensions.json`.
+  will add the extension's path to `~/.vscode/extensions/extensions.json` (or
+  `%USERPROFILE%\.vscode\extensions\extensions.json` on Windows).
diff --git a/tools/test-helper/package.json b/tools/test-helper/package.json
index 5da2fe5a..de919ef3 100644
--- a/tools/test-helper/package.json
+++ b/tools/test-helper/package.json
@@ -4,9 +4,6 @@
   "displayName": "Typst Test Helper",
   "description": "Helps to run, compare and update Typst tests.",
   "version": "0.0.1",
-  "engines": {
-    "vscode": "^1.71.0"
-  },
   "categories": [
     "Other"
   ],
@@ -97,8 +94,12 @@
     "watch": "tsc -watch -p ./"
   },
   "devDependencies": {
-    "@types/vscode": "^1.88.0",
     "@types/node": "18.x",
+    "@types/vscode": "^1.88.0",
     "typescript": "^5.3.3"
+  },
+  "engines": {
+    "vscode": "^1.88.0"
   }
 }
+