From 62b6bd355669bcfc6ca1b88cbc72ae39f0353d4d Mon Sep 17 00:00:00 2001 From: Justineo Date: Tue, 23 Sep 2025 13:50:58 +0800 Subject: [PATCH] docs: improve guideline docs --- AGENTS.md | 7 +------ tests/TESTING.md | 29 ++++++++++++++++++----------- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 16231be..3048218 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,12 +14,7 @@ This project targets Vue 3 + TypeScript with ECMAScript modules. Follow the exis ## Testing Guidelines -There is no standalone unit-test runner yet; rely on TypeScript, linting, and manual QA in the demo. Before opening a PR, run `pnpm lint`, `pnpm typecheck`, and `pnpm build`. Exercise relevant demos in `demo/src/` and add or update examples that showcase new behaviors. For major fixes, include reproduction and verification steps in the PR description so reviewers can follow along. - -- Centralize repeated test setup in shared helpers so suites stay focused on behavior, not plumbing. -- Keep browser-mode output deterministic—assert on warnings or silence them intentionally rather than letting them leak to the console. -- Lean on the framework/tooling type definitions wherever possible; only add custom shims when the build truly requires them. -- For coverage in browser mode, enable Vitest’s built-in coverage (V8 for Chromium, Istanbul for other browsers) and run `pnpm vitest run --coverage`; an HTML report is emitted under `coverage/browser/`. +For complete and up-to-date testing and CI guidance, see `tests/TESTING.md`. ## Commit & Pull Request Guidelines diff --git a/tests/TESTING.md b/tests/TESTING.md index e68f80c..c40e6dd 100644 --- a/tests/TESTING.md +++ b/tests/TESTING.md @@ -1,16 +1,23 @@ -# Test conventions +# Testing -This project uses Vitest browser mode with Playwright (Chromium) and `vitest-browser-vue` for mounting Vue components. +We run Vitest in browser mode using Playwright (Chromium) with `vitest-browser-vue` to mount Vue components. -- Global setup is in `tests/setup.ts`: - - Mocks `echarts/core` via `tests/helpers/mock.ts` - - Centralizes DOM cleanup with `vitest-browser-vue/pure`'s `cleanup()` and resets `document.body` after each test +- Global setup: see `tests/setup.ts` (mocks `echarts/core`, resets DOM after each test). +- Prefer shared helpers under `tests/helpers/` to avoid duplicated setup. +- Test only public behavior; avoid internal implementation details. +- Keep tests deterministic: silence console noise and flush updates/animation frames with provided helpers. -- Prefer helpers to reduce duplication: - - `tests/helpers/renderChart.ts` exposes `renderChart(propsFactory, exposesRef)` to mount `src/ECharts` with reactive props and capture the exposed API. - - `tests/helpers/dom.ts` provides `createSizedContainer`, `flushAnimationFrame`, and `withConsoleWarn`. - - `tests/helpers/testing.ts` re-exports `render` from `vitest-browser-vue/pure` for consistency. +## Run locally -- Avoid testing internal, non-user-observable branches. Focus tests on public behavior of composables and the `ECharts` component, not implementation details. +- Install dependencies: `pnpm install` +- Install Chromium: `pnpm exec playwright install chromium` +- Run tests: `pnpm test` +- Coverage (V8): `pnpm test:coverage` + - HTML report: `coverage/browser/index.html` + - LCOV: `coverage/browser/lcov.info` -- Keep tests deterministic: silence console warnings via `withConsoleWarn`; use `await nextTick()` to flush Vue updates; for ResizeObserver-driven code, use `flushAnimationFrame()`. +## CI + +- CI runs tests with coverage and uploads LCOV to Codecov (non-blocking). +- Chromium is provisioned via the Playwright GitHub Action. +- Optional: restrict Codecov uploads to PRs and `main` via a workflow condition.