From 5415095ef3743048c9aa363b02722e89e2d01d81 Mon Sep 17 00:00:00 2001
From: Leedehai <18319900+Leedehai@users.noreply.github.com>
Date: Tue, 16 Apr 2024 05:44:38 -0400
Subject: [PATCH] Better instruction in test READMEs (#3929)

---
 tests/README.md                |  9 ++++++---
 tools/test-helper/README.md    | 31 ++++++++++++++++++-------------
 tools/test-helper/package.json |  9 +++++----
 3 files changed, 29 insertions(+), 20 deletions(-)

diff --git a/tests/README.md b/tests/README.md
index 6cc79217a..f817e8f93 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -24,14 +24,17 @@ You may want to [make yourself an alias](#making-an-alias) like:
 testit
 ```
 
-Running all tests whose paths contain the string `page` or `stack`.
+Running all tests whose names contain the string `page` or `stack`. Note each
+`.typ` file in this directory can contain multiple tests, each of which is a
+section of Typst code following `--- {name} ---`.
 ```bash
+# Add --verbose to list which tests were run.
 testit page stack
 ```
 
-Running a test with the exact filename `page.typ`.
+Running a test with the exact test name `math-attach-mixed`.
 ```bash
-testit --exact page.typ
+testit --exact math-attach-mixed
 ```
 
 To make the integration tests go faster they don't generate PDFs by default.
diff --git a/tools/test-helper/README.md b/tools/test-helper/README.md
index f95b8d737..6eab6abd8 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 5da2fe5a1..de919ef37 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"
   }
 }
+