You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Full config please refrence in [src/types](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts).
63
+
For a full list of configuration options, refer to the [type definitions](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts).
58
64
59
-
### 03. Create a env file
65
+
### 03. Create an Environment File
60
66
61
-
This file defines Zotero's runtime configuration such as binary paths, profile paths, and environment variables required for Node scripts to run.
67
+
Define Zotero’s runtime configuration (e.g., binary paths, profile paths, and environment variables) in a `.env` file.
62
68
63
69
::: warning
64
70
65
-
NOTE: Do not check-in this file to the repository!
71
+
Do not commit this file to your repository!
66
72
67
73
:::
68
74
@@ -71,17 +77,19 @@ NOTE: Do not check-in this file to the repository!
71
77
```
72
78
73
79
```ini
74
-
#The path of the Zotero binary file.
75
-
#The path is `*/Zotero.app/Contents/MacOS/zotero` for macOS.
When releasing a plugin, we typically need to manually update the `version` value in `manifest.json`, package the plugin, upload it somewhere, and then update the `version`and link in `update.json`.
4
4
5
-
为了保持 Git 记录，我们在修改 version 值后，还需要提交代码并为这个提交添加 tag。
5
+
To maintain Git history, we also need to commit the changes and add a tag to the commit after updating the version.
`zotero-plugin-scaffold`can run [Mocha](https://mochajs.org/)/[Chai](https://www.chaijs.com/)-based tests against a live Zotero instance via a proxy plugin.
3
+
`zotero-plugin-scaffold`enables testing with [Mocha](https://mochajs.org/)and[Chai](https://www.chaijs.com/) in a live Zotero instance through a proxy plugin.
4
4
5
-
A temporary profile and data directory will be created when launching Zotero, so tests can be run locally on the system Zotero installation.
5
+
When running tests, a temporary profile and data directory are created, allowing the tests to execute locally on the installed Zotero application.
6
6
7
-
## Why
7
+
## Why Use This Approach?
8
8
9
-
Since Zotero is a browser environment and has a lot of private APIs, if we use the mainstream Node-side testing scheme, we will inevitably need to mock a lot of methods, which will distort the test results.
9
+
Zotero operates in a browser-like environment with many private APIs. Using conventional Node.js testing frameworks would require extensive mocking, leading to distorted test results.
10
10
11
-
In Scaffold, we use mocha as the testing framework, which is a simple but flexible enough testing framework for the browser side. We also use chai as an assertion library.
11
+
To address this, Scaffold uses Mocha as a lightweight yet flexible browser-compatible testing framework, complemented by Chai for assertions.
12
12
13
-
When we start a test, we generate a temporary plugin in `.scaffold/test/resource/` that we use to run the test. Iterate through the test files in the `test.entries` directory and compile them in `.scaffold/test/resource/content`.
14
-
15
-
When Zotero starts up, it loads your plugin and the test plugin that was just generated separately, so we have complete access to all the APIs and can use them for testing.
13
+
Tests are executed via a temporary plugin generated in `.scaffold/test/resource/`. The test files in the `test.entries` directory are compiled into `.scaffold/test/resource/content`. When Zotero launches, it loads both the primary plugin and the generated test plugin, providing full access to all APIs needed for testing.
16
14
17
15
## Usage
18
16
19
17
### Configuring Test Options
20
18
21
-
After configuring your project to be built with `zotero-plugin-scaffold`, add a `test` object to your configuration:
19
+
After setting up your project with `zotero-plugin-scaffold`, add a `test` object to your configuration:
22
20
23
-
```ts twoslash
21
+
```ts
24
22
exportdefaultdefineConfig({
25
23
// ...
26
24
test: {
27
-
// Directories containing *.spec.js tests
25
+
// Directories containing *.spec.js test files
28
26
entries: ["test"],
29
-
// Exit Zotero when the test is finished.
27
+
// Exit Zotero after the tests complete
30
28
exitOnFinish: true,
31
-
// Function string that returns the initialization status of the plugin.
32
-
// If set, the test will wait until the function returns true before running the test.
33
-
// e.g.
34
-
// if your plugin created a `MyPlugin` object beneath `Zotero` and it set an
35
-
// `initialized` field to `true` at the end of its `startup` bootstrap method...
29
+
// Function string that returns the plugin's initialization status
30
+
// The test waits until this function returns true
31
+
// Example: if your plugin sets `Zotero.MyPlugin.initialized` to `true` in its `startup` method...
See the `TestConfig` interface in [`src/types/config.ts`](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts) for full documentation.
44
-
38
+
Refer to the `TestConfig` interface in [`src/types/config.ts`](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts) for complete documentation.
45
39
:::
46
40
47
-
Add a script to `package.json`:
41
+
Add a `test`script to your`package.json`:
48
42
49
43
```json
50
44
{
@@ -56,27 +50,29 @@ Add a script to `package.json`:
56
50
57
51
### Install Mocha and Chai
58
52
59
-
We recommend that you install `mocha.js` locally as a development dependency, as this will avoid some potential dependency conflicts:
53
+
Install `mocha`as a local development dependency to avoid potential conflicts:
60
54
61
55
```bash
62
56
npm install -D mocha @types/mocha @types/chai
63
57
```
64
58
65
-
When Scaffold detects your locally installed mocha, it will automatically use your installed mocha, otherwise Scaffold will get the latest version of mocha from NPM.
59
+
If Scaffold detects a local `mocha` installation, it will use it. Otherwise, it fetches the latest version from NPM. Due to unresolved ESM import issues with Chai, Scaffold always uses the remote version.
66
60
67
-
Since the ESM import issue for Chai has not been resolved, chai will always use the remote version.
61
+
Cached versions of `mocha` and `chai` are stored in `.scaffold/cache`. Delete this cache if you need to force an update.
68
62
69
-
The mocha and chai downloaded from the remote will be cached in the `.scaffold/cache` directory, and you can delete the cache if you need to in order to force Scaffold to update their versions.
63
+
### Writing Test Cases
70
64
71
-
### Write Your Test Cases
65
+
Write test cases using [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/) syntax.
72
66
73
-
You can then write your test file, see [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/) for syntax.
67
+
### Running Tests
74
68
75
-
### Run Test
69
+
After writing your test cases, run them using:
76
70
77
-
一旦你完成测试代码的编写，你可以通过 `npm run test` 来启动测试。
71
+
```bash
72
+
npm run test
73
+
```
78
74
79
-
`zotero-plugin test` 也提供了一些命令行参数，以便你可以覆盖配置文件中的设置，你可以通过 `zotero-plugin test --help`来查看：
75
+
You can override configuration settings with CLI parameters. Use `zotero-plugin test --help`to view available options:
80
76
81
77
```bash
82
78
$ pnpm zotero-plugin test --help
@@ -92,26 +88,24 @@ Options:
92
88
93
89
## Watch Mode
94
90
95
-
In watch mode, Scaffold will:
91
+
In watch mode, Scaffold automatically:
96
92
97
-
-When the source code changes, it will automatically recompile the source code, reload the plugins and re-run the tests;
98
-
-When the test code changes, it will automatically re-run the tests;
93
+
-Recompiles source code, reloads plugins, and reruns tests when the source changes.
94
+
-Reruns tests when test files are modified.
99
95
100
-
This feature is not yet complete.
96
+
This feature is still under development.
101
97
102
-
## Run Test on CI
98
+
## Running Tests on CI
103
99
104
-
Most of the time, we want tests to run automatically on CI services such as GitHub Actions, for which we provide`headless` mode.
100
+
To run tests automatically on CI services like GitHub Actions, Scaffold provides a`headless` mode.
105
101
106
-
In general, when we detect that you are running tests on a CI service, we will automatically enable headless mode. If you have a need to use headless locally, you just need to pass `headless`in the cli parameter or set `test.headless: true` in the configuration.
102
+
By default, Scaffold enables headless mode on CI services. To enable it locally, pass `headless`as a CLI parameter or set `test.headless: true` in the configuration.
107
103
108
104
::: warning
109
-
110
-
Scaffold's built-in headless mode is only supported on Ubuntu 22.04, 24.04. If you are using a different Linux distribution, manually configure the headless environment, set Scaffold's `test.headless` to `false`, and start the test using something like `xvfb-run npm run test`, etc.
111
-
105
+
Scaffold's built-in headless mode supports only Ubuntu 22.04 and 24.04. For other Linux distributions, manually configure a headless environment, set `test.headless` to `false`, and use tools like `xvfb-run npm run test`.
112
106
:::
113
107
114
-
For tests running on GitHub Actions, this is a typical workflow template:
108
+
For GitHub Actions, use the following workflow template:
0 commit comments