From 6822493c2771809eec8089517cf271c48251c85a Mon Sep 17 00:00:00 2001 From: Northword Date: Wed, 18 Dec 2024 22:33:06 +0800 Subject: [PATCH] docs: improve docs --- README.md | 12 +++++ docs/.vitepress/config.ts | 2 + docs/index.md | 10 ++-- docs/quick-start.md | 20 +------- docs/release.md | 8 ++++ docs/test.md | 97 +++++++++++++++++++++++++++++++-------- 6 files changed, 107 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index ba2eefa..a5ea64d 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,18 @@ pnpm install # and the modified code does not need to be built again. pnpm run dev +# link local scaffold to your plugin +cd your-plugin-work-dir/ +pnpm link ../zotero-plugin-scaffold +cd zotero-plugin-scaffold/ + +``` + +Now you can make changes to Scaffold and test them in your plugin. + +When you're done modifying, make sure that you can pass the build and that the code style meets the requirements of this repository. + +```bash # Build pnpm run build diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index c898918..d838b6a 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -23,5 +23,7 @@ export default defineConfig({ socialLinks: [ { icon: "github", link: "https://github.com/northword/zotero-plugin-scaffold" }, ], + + outline: "deep", }, }); diff --git a/docs/index.md b/docs/index.md index bf6703d..7ed23f4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,10 +14,14 @@ hero: features: - title: Dev Serve details: Auto reload your plugin when source code changed + link: /serve - title: Build Plugin - details: TypeScript supported, many utils builders - - title: Pack plugin - details: Pack code to xpi file + details: TypeScript supported, many utils builders, and pack code to xpi + link: /build + - title: Test plugin + details: Out-of-the-box test kits + link: /test - title: Release details: Auto bump version, and publish your plugin to GitHub + link: /release --- diff --git a/docs/quick-start.md b/docs/quick-start.md index 5e76cb3..8829883 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -17,8 +17,6 @@ pnpm dlx zotero-plugin create ### 01. Install -#### From NPM - ```bash npm install -D zotero-plugin-scaffold @@ -27,22 +25,6 @@ yarn add -D zotero-plugin-scaffold pnpm add -D zotero-plugin-scaffold ``` -#### From source code - -```bash -# clone this repo -git clone https://github.com/northword/zotero-plugin-scaffold.git zotero-plugin-scaffold/ -cd zotero-plugin-scaffold/ - -# build -pnpm install -pnpm build # or pnpm dev - -# npm link -cd your-plugin-work-dir/ -pnpm link ../zotero-plugin-scaffold -``` - ### 02. Create a config file The configuration file needs to be stored in the following location. @@ -72,7 +54,7 @@ export default defineConfig({ }); ``` -Full config please refrence in [src/types](./src/types/index.ts). +Full config please refrence in [src/types](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts). ### 03. Create a env file diff --git a/docs/release.md b/docs/release.md index aa054b5..eb41282 100644 --- a/docs/release.md +++ b/docs/release.md @@ -1 +1,9 @@ # Release + +我们都知道，对于一个插件的发布，我们需要手动修改 `manifest.json` 中的 `version` 值，然后将其打包，上传到某个地方，随后，我们还需要更新 `update.json` 中的版本号和链接。 + +为了保持 Git 记录，我们在修改 version 值后，还需要提交代码并为这个提交添加 tag。 + +—— 这太麻烦了！ + +在 Scaffold 中，你只需要运行 `zotero-plugin release`，然后选择一个你需要的版本号，一切都将自动运行。 diff --git a/docs/test.md b/docs/test.md index 4a43873..85efd20 100644 --- a/docs/test.md +++ b/docs/test.md @@ -1,25 +1,31 @@ # Testing -`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. -A temporary profile and data directory will be created when launching Zotero, -so tests can be run locally on the system Zotero installation. +`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. -## Configuration +A temporary profile and data directory will be created when launching Zotero, so tests can be run locally on the system Zotero installation. -> [!TIP] -> See the `TestConfig` interface in [`src/types/config.ts`](./src/types/config.ts) for full documentation +## Why -After configuring your project to be built with `zotero-plugin-scaffold`, -add a `test` object to your configuration: +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. -```js +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. + +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`. + +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. + +## Usage + +### Configuring Test Options + +After configuring your project to be built with `zotero-plugin-scaffold`, add a `test` object to your configuration: + +```ts twoslash export default defineConfig({ // ... test: { // Directories containing *.spec.js tests - entries: ["test/"], - // Abort the test when the first test fails - abortOnFail: false, + entries: ["test"], // Exit Zotero when the test is finished. exitOnFinish: true, // Function string that returns the initialization status of the plugin. @@ -28,34 +34,85 @@ export default defineConfig({ // if your plugin created a `MyPlugin` object beneath `Zotero` and it set an // `initialized` field to `true` at the end of its `startup` bootstrap method... waitForPlugin: `() => Zotero.MyPlugin.initialized`, - // Run tests using xvfb without launching a Zotero window - // (Linux only. defaults `true` in CI. Both xvfb and Zotero are installed automatically) - headless: false, } }); ``` +::: tip + +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. + +::: + Add a script to `package.json`: ```json { "scripts": { - "...": "...", - "test": "zotero-plugin test --abort-on-fail --exit-on-finish" + "test": "zotero-plugin test" } } ``` -## CI +### Install Mocha and Chai + +We recommend that you install `mocha.js` locally as a development dependency, as this will avoid some potential dependency conflicts: + +```bash +npm install -D mocha @types/mocha @types/chai +``` + +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. + +Since the ESM import issue for Chai has not been resolved, chai will always use the remote version. + +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. + +### Write Your Test Cases + +You can then write your test file, see [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/) for syntax. + +### Run Test + +一旦你完成测试代码的编写，你可以通过 `npm run test` 来启动测试。 + +`zotero-plugin test` 也提供了一些命令行参数，以便你可以覆盖配置文件中的设置，你可以通过 `zotero-plugin test --help` 来查看： + +```bash +$ pnpm zotero-plugin test --help +Usage: cli test [options] + +Run tests + +Options: + --abort-on-fail Abort the test suite on first failure + --exit-on-finish Exit the test suite after all tests have run + -h, --help display help for command +``` + +## Watch Mode + +In watch mode, Scaffold will: + +- When the source code changes, it will automatically recompile the source code, reload the plugins and re-run the tests; +- When the test code changes, it will automatically re-run the tests; -Tests can be run headlessly, e.g. on Github Actions: +This feature is not yet complete. + +## Run Test on CI + +Most of the time, we want tests to run automatically on CI services such as GitHub Actions, for which we provide `headless` mode. + +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. ::: warning -Currently ubuntu must be pinned lower than `24.04`, see [`#74`](https://github.com/northword/zotero-plugin-scaffold/issues/74) +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. ::: +For tests running on GitHub Actions, this is a typical workflow template: + ```yaml name: test