2.7 KiB
2.7 KiB
Validation Guide
Run the smallest relevant checks while iterating. Escalate to the broad checks when touching shared behavior, release automation, auth, persistence, or chat.
Always Run For PRs
npm run harness:check
npm run check:orphans
For broad or shared changes, also run:
npm run test:coverage
npm run test:e2e
npm run build
Change-Type Matrix
| Change | Minimum local validation |
|---|---|
| Docs only | npm run harness:check |
| Client component/store/API | focused npm run test -- <pattern>, then npm run build |
| User-visible browser flow | focused Vitest plus npm run test:e2e |
| Server controller/service/db | focused npm run test -- tests/server/<file> |
| Auth, profile, or credential behavior | focused server tests plus relevant e2e auth tests |
| Chat, Socket.IO, group chat | focused server tests plus relevant e2e chat tests |
| Chat session chain, Agent Bridge, compression, or Group Chat | Add one docs/chat-chain-changes/*.md fragment with date, PR/commit, touched feature, and behavior impact; then run npm run harness:check plus focused chat/bridge/group-chat tests |
| Electron lifecycle, preload, native packaging | npm run build, npm run electron:setup, npm run test:electron, npm run pack |
| Docker image | npm run harness:check and npm run build |
| GitHub workflow | npm run harness:check and actionlint when available |
| Package manifests | npm ci --ignore-scripts and lockfile workflow expectations |
CI Mapping
- Build workflow: installs dependencies, runs coverage, and builds production assets on pushes and pull requests.
- Playwright workflow: runs browser e2e tests.
- NPM lockfile workflow: verifies
package-lock.jsonis synchronized. - Electron packages workflow: manually builds native installers on macOS, Windows and Linux, then uploads platform-specific artifacts without publishing.
- Electron smoke tests: run after the browser suite on Linux, and in the manual macOS verification workflow.
Release Workflow Guardrail
Published GitHub Releases should still trigger Web UI artifact packaging and Docker image publishing, but those workflows must keep the GitHub Release out of latest.
Web UI release jobs must upload only the artifacts their build can produce. Keep
artifact globs in matrix data and keep fail_on_unmatched_files: true so a
missing expected file still fails.
Failure Handling
When a command fails:
- Read the first actionable error, not just the final stack trace.
- Check whether the failure indicates missing context, missing test coverage, or a missing mechanical rule.
- Fix the product bug when there is one.
- Update docs or
scripts/harness-check.mjswhen the same class of mistake should be prevented next time.