perses-plugin-test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Perses Plugin Testing

Perses插件测试

Test Perses plugins across four layers: CUE schema validation, React component unit tests, integration testing against a live Perses server, and Grafana migration compatibility.

从四个层面测试Perses插件：CUE schema验证、React组件单元测试、针对运行中Perses服务器的集成测试，以及Grafana迁移兼容性测试。

Operator Context

执行上下文

This skill validates Perses plugin correctness from schemas through rendered components. Testing follows a strict order because each layer depends on the previous one passing.

该技能从schema到渲染组件全流程验证Perses插件的正确性。测试需遵循严格顺序，因为每个层面都依赖前一层面测试通过。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Schema tests first: Always run
```
percli plugin test-schemas
```
before any other test layer — component and integration tests are meaningless if schemas are invalid
JSON examples required: Every CUE schema must have a matching JSON example at
```
schemas/<type>/<name>/<name>.json
```
for test coverage
package model
declaration: Every CUE schema file must declare
```
package model
```
—
```
percli plugin test-schemas
```
silently skips files without it
Local server only: Integration tests must target a local Perses instance (
```
localhost
```
), never a shared or production server
Validate all 27 official plugins: When testing a plugin that extends or wraps an official plugin, verify compatibility with the upstream schema

优先执行Schema测试：在执行其他任何测试层面之前，必须先运行
```
percli plugin test-schemas
```
——如果schema无效，组件和集成测试将毫无意义
必须提供JSON示例：每个CUE schema都必须在
```
schemas/<type>/<name>/<name>.json
```
路径下有对应的JSON示例，以确保测试覆盖率
package model
声明：每个CUE schema文件必须声明
```
package model
```
——
```
percli plugin test-schemas
```
会自动跳过未声明该内容的文件
仅使用本地服务器：集成测试必须针对本地Perses实例（
```
localhost
```
），绝不能使用共享或生产环境服务器
验证所有27款官方插件：当测试扩展或封装官方插件的自定义插件时，需验证其与上游schema的兼容性

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Run all four phases: Execute schema, component, integration, and migration tests in order
Stop on phase failure: If a phase fails, fix it before proceeding to the next phase
CUE
close({...})
validation: Verify schemas use
```
close()
```
to reject unknown fields in JSON examples

执行全部四个阶段：按顺序执行schema、组件、集成和迁移测试
阶段失败即终止：如果某个阶段测试失败，需修复后再进入下一阶段
CUE
close({...})
验证：验证schema是否使用
```
close()
```
来拒绝JSON示例中的未知字段

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需开启）

Cross-plugin compatibility: Test that this plugin's output works alongside other plugins in the same dashboard
Performance profiling: Measure React component render time with React Profiler during integration tests
Snapshot testing: Generate and compare React component snapshots across test runs

跨插件兼容性测试：测试该插件的输出能否与同一仪表盘中的其他插件协同工作
性能分析：在集成测试期间使用React Profiler测量React组件的渲染时间
快照测试：生成并对比不同测试运行中的React组件快照

What This Skill CAN Do

该技能可完成的任务

Validate CUE schemas against JSON examples using
```
percli plugin test-schemas
```
Run React component unit tests with mocked
```
@perses-dev/plugin-system
```
hooks
Start a hot-reload dev server with
```
percli plugin start
```
for integration testing
Test Grafana dashboard migration logic against sample JSON fixtures
Diagnose common CUE syntax errors (missing package declaration, unclosed specs, bad imports)

使用
```
percli plugin test-schemas
```
验证CUE schema与JSON示例的一致性
结合模拟的
```
@perses-dev/plugin-system
```
钩子运行React组件单元测试
使用
```
percli plugin start
```
启动热重载开发服务器以进行集成测试
针对示例JSON测试Grafana仪表盘迁移逻辑
诊断常见CUE语法错误（缺失包声明、未闭合的spec、错误的导入路径）

What This Skill CANNOT Do

该技能无法完成的任务

Create new plugins from scratch (use perses-plugin-create)
Validate full dashboards or datasource connectivity (use perses-lint)
Deploy or configure a Perses server (use perses-deploy)
Write CUE schemas — this skill only tests them

从头创建新插件（请使用perses-plugin-create）
验证完整仪表盘或数据源连接性（请使用perses-lint）
部署或配置Perses服务器（请使用perses-deploy）
编写CUE schema——该技能仅能测试已有的schema

Instructions

操作步骤

Phase 1: SCHEMA TESTS

阶段1：SCHEMA测试

Goal: Validate all CUE schemas compile and match their JSON examples.

Verify schema structure: Each schema file must have
```
package model
```
at the top and use
```
close({...})
```
for strict validation
Check JSON examples exist: Every schema at
```
schemas/<type>/<name>/
```
must have a corresponding
```
<name>.json
```
Run schema tests:

bash

percli plugin test-schemas

On failure: Read the CUE error output carefully — common issues are missing imports, unclosed braces, or JSON examples with fields not in the schema

Gate: All schema tests pass. Proceed to Phase 2.

目标：验证所有CUE schema可编译并匹配对应的JSON示例。

验证schema结构：每个schema文件顶部必须包含
```
package model
```
，并使用
```
close({...})
```
进行严格验证
检查JSON示例是否存在：每个位于
```
schemas/<type>/<name>/
```
的schema必须有对应的
```
<name>.json
```
文件
运行schema测试：

bash

percli plugin test-schemas

失败处理：仔细阅读CUE错误输出——常见问题包括缺失导入、未闭合的大括号，或JSON示例包含schema中未定义的字段

准入条件：所有schema测试通过，进入阶段2。

Phase 2: COMPONENT TESTS

阶段2：组件测试

Goal: Run React component unit tests.

Verify test setup: Component tests must mock
```
@perses-dev/plugin-system
```
hooks (e.g.,
```
useDataQueries
```
,
```
useTimeRange
```
)
Run tests:

bash

npm test -- --watchAll=false

Check coverage: Ensure plugin component renders without errors and handles empty/error states

Gate: All component tests pass. Proceed to Phase 3.

目标：运行React组件单元测试。

验证测试环境：组件测试必须模拟
```
@perses-dev/plugin-system
```
钩子（如
```
useDataQueries
```
、
```
useTimeRange
```
）
运行测试：

bash

npm test -- --watchAll=false

检查覆盖范围：确保插件组件可正常渲染，并能处理空值/错误状态

准入条件：所有组件测试通过，进入阶段3。

Phase 3: INTEGRATION TESTS

阶段3：集成测试

Goal: Verify the plugin works inside a running Perses instance.

Start local Perses server (if not already running):

bash

docker run --name perses-test -d -p 127.0.0.1:8080:8080 persesdev/perses

Start plugin dev server:

bash

percli plugin start

Verify plugin loads: Confirm the plugin appears in the Perses UI panel type selector
Test with real data: Create a dashboard using this plugin and verify it renders with a connected datasource

Gate: Plugin loads and renders in local Perses. Proceed to Phase 4.

目标：验证插件在运行中的Perses实例内可正常工作。

启动本地Perses服务器（若未运行）：

bash

docker run --name perses-test -d -p 127.0.0.1:8080:8080 persesdev/perses

启动插件开发服务器：

bash

percli plugin start

验证插件已加载：确认插件出现在Perses UI的面板类型选择器中
使用真实数据测试：创建使用该插件的仪表盘，验证其可结合已连接的数据源正常渲染

准入条件：插件可在本地Perses中加载并渲染，进入阶段4。

Phase 4: MIGRATION TESTS (if applicable)

阶段4：迁移测试（如适用）

Goal: Verify Grafana dashboard JSON converts correctly through migration logic.

Locate migration schema: Check for
```
migrate/migrate.cue
```
Prepare test fixtures: Use sample Grafana dashboard JSON that exercises all panel types this plugin handles
Run migration:

bash

percli migrate --input grafana-dashboard.json --output perses-dashboard.json

Validate output: Verify the migrated dashboard JSON matches expected Perses schema structure

Gate: Migration produces valid Perses dashboard JSON. Task complete.

目标：验证Grafana仪表盘JSON可通过迁移逻辑正确转换。

定位迁移schema：检查是否存在
```
migrate/migrate.cue
```
文件
准备测试用例：使用包含该插件处理的所有面板类型的Grafana仪表盘JSON示例
运行迁移：

bash

percli migrate --input grafana-dashboard.json --output perses-dashboard.json

验证输出结果：确认迁移后的仪表盘JSON符合预期的Perses schema结构

准入条件：迁移生成有效的Perses仪表盘JSON，任务完成。

Error Handling

错误处理

Error	Cause	Solution
`percli plugin test-schemas` fails with "cannot find package"	CUE file missing `package model` declaration at top of file	Add `package model` as the first line of every CUE schema file
`percli plugin test-schemas` fails with parse error	Unclosed `close({...})` spec or mismatched braces in CUE	Count opening/closing braces; ensure every `close(` has matching `)` and every `{` has matching `}`
`percli plugin test-schemas` fails with import error	Wrong CUE import path (e.g., using Go-style paths instead of CUE module paths)	Check `cue.mod/module.cue` for the module name and use it as the import prefix
`percli plugin test-schemas` reports extra fields	JSON example contains fields not defined in the CUE schema	Either add the field to the CUE schema or remove it from the JSON example; `close()` rejects unknown fields
React test: "Cannot find module '@perses-dev/plugin-system'"	Missing mock setup for the plugin system dependency	Add `jest.mock('@perses-dev/plugin-system')` or create `__mocks__/@perses-dev/plugin-system.js` with stub hooks
React test: "Invalid hook call"	Using wrong test renderer or missing React context providers	Wrap component in `<PluginRegistry>` provider during tests; use `@testing-library/react` not `react-test-renderer`
Integration test: connection refused on port 8080	Local Perses server not running or bound to a different port	Start server with `docker run -p 127.0.0.1:8080:8080 persesdev/perses` and verify with `curl http://localhost:8080/api/v1/health`
Integration test: 401 Unauthorized	Perses server has auth enabled but test is not authenticating	Run `percli login http://localhost:8080 --username admin --password <password>` before testing, or disable auth for local test instance
Migration test: unexpected panel type	Grafana dashboard JSON contains panel types not handled by `migrate/migrate.cue`	Add a migration case for the new panel type in `migrate.cue` , or filter unsupported panels before migration
Migration test: schema version mismatch	Grafana JSON structure changed between versions (e.g., v8 vs v10 panel format)	Check the Grafana version in the test fixture and ensure `migrate.cue` handles that version's structure

错误	原因	解决方案
`percli plugin test-schemas` 报错"cannot find package"	CUE文件顶部缺失 `package model` 声明	在每个CUE schema文件的首行添加 `package model`
`percli plugin test-schemas` 报解析错误	CUE中存在未闭合的 `close({...})` 或不匹配的大括号	统计开闭大括号数量；确保每个 `close(` 都有对应的 `)` ，每个 `{` 都有对应的 `}`
`percli plugin test-schemas` 报导入错误	CUE导入路径错误（如使用Go风格路径而非CUE模块路径）	检查 `cue.mod/module.cue` 中的模块名称，并将其作为导入前缀
`percli plugin test-schemas` 报告存在额外字段	JSON示例包含CUE schema中未定义的字段	要么将该字段添加到CUE schema中，要么从JSON示例中删除； `close()` 会拒绝未知字段
React测试："Cannot find module '@perses-dev/plugin-system'"	缺失插件系统依赖的模拟配置	添加 `jest.mock('@perses-dev/plugin-system')` ，或创建 `__mocks__/@perses-dev/plugin-system.js` 并添加钩子存根
React测试："Invalid hook call"	使用了错误的测试渲染器或缺失React上下文提供者	在测试期间将组件包裹在 `<PluginRegistry>` 提供者中；使用 `@testing-library/react` 而非 `react-test-renderer`
集成测试：端口8080连接被拒绝	本地Perses服务器未运行或绑定到其他端口	使用 `docker run -p 127.0.0.1:8080:8080 persesdev/perses` 启动服务器，并通过 `curl http://localhost:8080/api/v1/health` 验证
集成测试：401 Unauthorized	Perses服务器已启用认证，但测试未进行身份验证	测试前运行 `percli login http://localhost:8080 --username admin --password <password>` ，或为本地测试实例禁用认证
迁移测试：出现意外面板类型	Grafana仪表盘JSON包含 `migrate/migrate.cue` 未处理的面板类型	在 `migrate.cue` 中添加新面板类型的迁移逻辑，或在迁移前过滤不支持的面板
迁移测试：schema版本不匹配	Grafana JSON结构在不同版本间发生变化（如v8与v10的面板格式）	检查测试用例中的Grafana版本，并确保 `migrate.cue` 可处理该版本的结构

Anti-Patterns

反模式

Anti-Pattern	Why It Fails	Do Instead
Running component tests before schema tests pass	Components depend on valid schemas; testing components against broken schemas produces misleading failures	Always run `percli plugin test-schemas` first and fix all schema errors before touching component tests
Testing against a shared or production Perses server	Tests may corrupt real data, hit rate limits, or fail due to network latency; results are non-reproducible	Always use a local Perses instance via Docker or binary — disposable and isolated
JSON examples that only test the happy path	Schemas with optional fields, unions, or conditional logic have branches that never get exercised	Create multiple JSON examples per schema: minimal (required fields only), full (all fields), and edge cases (empty arrays, null values)
Skipping migration tests because "the schema didn't change"	Upstream Grafana panel JSON evolves independently; a working migration can break without any local changes	Run migration tests against current Grafana sample fixtures on every test cycle
Mocking the entire plugin-system module with empty stubs	Tests pass but don't verify that hooks are called correctly or return expected shapes	Mock individual hooks with realistic return values (e.g., `useTimeRange` returns `{ start, end }` )

反模式	失败原因	正确做法
在schema测试通过前运行组件测试	组件依赖有效的schema；针对损坏的schema测试组件会产生误导性的失败结果	始终优先运行 `percli plugin test-schemas` ，并在修复所有schema错误后再进行组件测试
针对共享或生产环境的Perses服务器进行测试	测试可能损坏真实数据、触发速率限制，或因网络延迟失败；测试结果不可复现	始终通过Docker或二进制文件使用本地Perses实例——可随时销毁且环境隔离
JSON示例仅测试正常路径	包含可选字段、联合类型或条件逻辑的schema存在从未被测试过的分支	为每个schema创建多个JSON示例：极简版（仅必填字段）、完整版（所有字段）和边缘案例（空数组、空值）
因「schema未变更」而跳过迁移测试	上游Grafana面板JSON会独立演化；即使本地无变更，原本正常的迁移也可能失效	在每次测试周期中，针对当前Grafana示例用例运行迁移测试
使用空存根模拟整个plugin-system模块	测试可通过，但无法验证钩子是否被正确调用或返回预期格式	为单个钩子模拟真实的返回值（如 `useTimeRange` 返回 `{ start, end }` ）

Anti-Rationalization

错误合理化规避

Rationalization	Reality	Required Action
"Schema tests pass so the plugin works"	Schema tests only validate CUE syntax and JSON conformance — they say nothing about whether the React component renders	Run all four phases
"I tested with one JSON example and it passed"	One example may only exercise the default branch of a union type; other branches remain untested	Create JSON examples for every schema variant
"Integration tests are slow, I'll skip them this time"	Integration tests catch issues that unit tests cannot: plugin registration, data binding, render lifecycle	Always run integration tests against local Perses
"The migration worked for my Grafana dashboard"	Your dashboard may only use a subset of panel types; other users' dashboards will have panels you didn't test	Test migration with diverse Grafana fixtures covering all supported panel types

错误合理化	实际情况	必要操作
「Schema测试通过，所以插件可正常工作」	Schema测试仅验证CUE语法和JSON一致性——无法说明React组件可正常渲染	运行全部四个阶段的测试
「我用一个JSON示例测试过了，没问题」	单个示例可能仅测试了联合类型的默认分支；其他分支仍未被测试	为每个schema变体创建JSON示例
「集成测试太慢了，这次我跳过」	集成测试可捕捉单元测试无法发现的问题：插件注册、数据绑定、渲染生命周期	始终针对本地Perses运行集成测试
「我的Grafana仪表盘迁移成功了，没问题」	你的仪表盘可能仅使用了部分面板类型；其他用户的仪表盘可能包含你未测试的面板	使用涵盖所有支持面板类型的多样化Grafana用例测试迁移

FORBIDDEN Patterns

禁止模式

These are hard stops. If you encounter these, fix them before proceeding:

NEVER run integration tests against a non-localhost Perses URL
NEVER commit CUE schemas that lack
```
package model
```
—
```
percli
```
will silently ignore them
NEVER skip schema tests and jump straight to component or integration tests
NEVER use
```
percli plugin test-schemas
```
output as proof that React components work
NEVER test migrations without validating the output against the Perses schema

以下为硬性禁止项，若遇到需先修复再继续：

禁止针对非localhost的Perses URL运行集成测试
禁止提交缺失
```
package model
```
的CUE schema——
```
percli
```
会自动忽略这些文件
禁止跳过schema测试直接进行组件或集成测试
禁止将
```
percli plugin test-schemas
```
的输出作为React组件可正常工作的证明
禁止在未验证输出是否符合Perses schema的情况下测试迁移

Blocker Criteria

阻塞判定条件

Stop and ask the user before proceeding if:

```
percli
```
is not installed or not on PATH
No CUE schemas exist in the plugin (nothing to test with
```
test-schemas
```
)
The plugin has no JSON examples and you'd need to create them from scratch
Integration testing is requested but no local Perses server is available and Docker is not installed
Migration testing is requested but no
```
migrate/migrate.cue
```
file exists in the plugin
Schema tests produce errors you cannot diagnose from the CUE output alone

若遇到以下情况，请先询问用户再继续：

未安装
```
percli
```
或
```
percli
```
不在系统PATH中
插件中无CUE schema（无内容可用于
```
test-schemas
```
测试）
插件无JSON示例，且需要从零开始创建
要求进行集成测试，但无本地Perses服务器可用且未安装Docker
要求进行迁移测试，但插件中无
```
migrate/migrate.cue
```
文件
Schema测试产生的错误无法仅通过CUE输出诊断

perses-plugin-test

Original

Translation

Perses Plugin Testing

Perses插件测试

Operator Context

执行上下文

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需开启）

What This Skill CAN Do

该技能可完成的任务

What This Skill CANNOT Do

该技能无法完成的任务

Instructions

操作步骤

Phase 1: SCHEMA TESTS

阶段1：SCHEMA测试

Phase 2: COMPONENT TESTS

阶段2：组件测试

Phase 3: INTEGRATION TESTS

阶段3：集成测试

Phase 4: MIGRATION TESTS (if applicable)

阶段4：迁移测试（如适用）

Error Handling

错误处理

Anti-Patterns

反模式

Anti-Rationalization

错误合理化规避

FORBIDDEN Patterns

禁止模式

Blocker Criteria

阻塞判定条件

References

参考资料