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
Copy file name to clipboardExpand all lines: docs/test.md
+77-20Lines changed: 77 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,25 +1,31 @@
1
1
# Testing
2
2
3
-
`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.
4
-
A temporary profile and data directory will be created when launching Zotero,
5
-
so tests can be run locally on the system Zotero installation.
3
+
`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.
6
4
7
-
## Configuration
5
+
A temporary profile and data directory will be created when launching Zotero, so tests can be run locally on the system Zotero installation.
8
6
9
-
> [!TIP]
10
-
> See the `TestConfig` interface in [`src/types/config.ts`](./src/types/config.ts) for full documentation
7
+
## Why
11
8
12
-
After configuring your project to be built with `zotero-plugin-scaffold`,
13
-
add a `test` object to your configuration:
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.
14
10
15
-
```js
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.
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.
16
+
17
+
## Usage
18
+
19
+
### Configuring Test Options
20
+
21
+
After configuring your project to be built with `zotero-plugin-scaffold`, add a `test` object to your configuration:
22
+
23
+
```ts twoslash
16
24
exportdefaultdefineConfig({
17
25
// ...
18
26
test: {
19
27
// Directories containing *.spec.js tests
20
-
entries: ["test/"],
21
-
// Abort the test when the first test fails
22
-
abortOnFail:false,
28
+
entries: ["test"],
23
29
// Exit Zotero when the test is finished.
24
30
exitOnFinish: true,
25
31
// Function string that returns the initialization status of the plugin.
@@ -28,34 +34,85 @@ export default defineConfig({
28
34
// if your plugin created a `MyPlugin` object beneath `Zotero` and it set an
29
35
// `initialized` field to `true` at the end of its `startup` bootstrap method...
// Run tests using xvfb without launching a Zotero window
32
-
// (Linux only. defaults `true` in CI. Both xvfb and Zotero are installed automatically)
33
-
headless:false,
34
37
}
35
38
});
36
39
```
37
40
41
+
::: tip
42
+
43
+
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
+
45
+
:::
46
+
38
47
Add a script to `package.json`:
39
48
40
49
```json
41
50
{
42
51
"scripts": {
43
-
"...": "...",
44
-
"test": "zotero-plugin test --abort-on-fail --exit-on-finish"
52
+
"test": "zotero-plugin test"
45
53
}
46
54
}
47
55
```
48
56
49
-
## CI
57
+
### Install Mocha and Chai
58
+
59
+
We recommend that you install `mocha.js` locally as a development dependency, as this will avoid some potential dependency conflicts:
60
+
61
+
```bash
62
+
npm install -D mocha @types/mocha @types/chai
63
+
```
64
+
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.
66
+
67
+
Since the ESM import issue for Chai has not been resolved, chai will always use the remote version.
68
+
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.
70
+
71
+
### Write Your Test Cases
72
+
73
+
You can then write your test file, see [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/) for syntax.
74
+
75
+
### Run Test
76
+
77
+
一旦你完成测试代码的编写，你可以通过 `npm run test` 来启动测试。
78
+
79
+
`zotero-plugin test` 也提供了一些命令行参数，以便你可以覆盖配置文件中的设置，你可以通过 `zotero-plugin test --help` 来查看：
80
+
81
+
```bash
82
+
$ pnpm zotero-plugin test --help
83
+
Usage: cli test [options]
84
+
85
+
Run tests
86
+
87
+
Options:
88
+
--abort-on-fail Abort the test suite on first failure
89
+
--exit-on-finish Exit the test suite after all tests have run
90
+
-h, --help display helpforcommand
91
+
```
92
+
93
+
## Watch Mode
94
+
95
+
In watch mode, Scaffold will:
96
+
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;
50
99
51
-
Tests can be run headlessly, e.g. on Github Actions:
100
+
This feature is not yet complete.
101
+
102
+
## Run Test on CI
103
+
104
+
Most of the time, we want tests to run automatically on CI services such as GitHub Actions, for which we provide `headless` mode.
105
+
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.
52
107
53
108
::: warning
54
109
55
-
Currently ubuntu must be pinned lower than `24.04`, see [`#74`](https://github.com/northword/zotero-plugin-scaffold/issues/74)
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.
56
111
57
112
:::
58
113
114
+
For tests running on GitHub Actions, this is a typical workflow template:
0 commit comments