Testing and CI

Testing and CI

This page explains local verification, the three continuous-integration hosts and the evidence expected for a completed change.

ChemDraft's tests protect chemical meaning, permission boundaries and the agreement between drawing and export. Passing a typecheck or unit test alone does not prove a native interaction works on both operating systems. Use automated checks for repeatable invariants and hands-on checks for real windows, keyboard focus and operating-system behavior.

The local gauntlet

AGENTS.md specifies these repository-root commands:

pnpm lint
pnpm vitest run
pnpm build
git diff --check
cargo fmt --manifest-path apps/desktop/src-tauri/Cargo.toml --check
cargo clippy --all-targets --manifest-path apps/desktop/src-tauri/Cargo.toml -- -D warnings
cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml

pnpm lint runs root TypeScript checking with no emitted output. It checks test code too; Vitest running a test does not establish that the test typechecks. Root pnpm build runs that check and the desktop package build, so it includes native packaging work. The frontend-only CI build is the separate command pnpm --filter @chemdraft/desktop build:web.

Native compilation needs the frontend distribution directory. Build the web frontend first, and on macOS prepare Sparkle with pnpm --filter @chemdraft/desktop prepare:sparkle. Follow Building from Source for dependencies and launch prerequisites.

What CI runs

The checked-in .github/workflows/ci.yml runs on pull requests and pushes to main:

Host and job	Checks
Linux: Types, tests, web build	Frozen dependency install, root types, Vitest, frontend build
macOS: Rust fmt, clippy, tests	Frontend build, Sparkle preparation, pinned Rust, format, clippy with warnings denied, locked Rust tests
Windows: Windows types, tests, Rust	Root types, Vitest, frontend build, pinned Rust, format, clippy with warnings denied, locked Rust tests
Linux, pull requests only: Build stamp bumped	Compare runtime source changes and the build-stamp constant against the PR base

The toolchain comes from rust-toolchain.toml, currently Rust 1.97.1 with clippy and rustfmt. Do not replace it with an unpinned “stable” toolchain: new compiler lints can otherwise make CI and local results disagree.

All three hosts, including Windows, must pass before merging. A green Linux job cannot exercise AppKit or Windows native branches.

Build-stamp gate

Runtime changes under apps/desktop/src, apps/desktop/src-tauri/src or packages require a changed CURRENT_BUILD_STAMP in apps/desktop/src/MainWindow.tsx. Its suffix identifies the authoring agent, such as -codex, rather than the branch.

The enforcement script is scripts/ci/require-build-stamp-bump.sh. It excludes files matching the test-file pattern and does not require a bump for a wiki-only change. Its comparison is path-based, so check the script when deciding whether a less typical file under packages triggers it. Do not change the stamp solely to conceal a failed or skipped runtime check.

Choose meaningful regression checks

A chemistry-affecting change should compare canonical SMILES, formula, charge, stereochemistry, atom/bond counts and reaction components as relevant. Geometry checks compare coordinates within tolerance. Import/export cases need fixtures with explicit warnings or refusals for unsupported content.

Permission tests should cover undeclared access, command ownership and rollback, not only a successful plugin call. Pointer, hit-testing or bridge changes also require the DOM, agent-bridge and drawing-tool suites. Synthetic bridge events skip browser default behavior; focus-sensitive work needs real-event coverage.

Changes to Spin 3D need the spin3dModel, spinFlatten, spinFlattenStereo, flattenRoundTrip, spinOverlay and rotation3d families. Shared TypeScript platform branches should accept an injected platform so tests can exercise macOS and Windows behavior on one host.

Scoped tools and hands-on checks

Use these scripts when their area changes:

pnpm build:sdk
pnpm plugin:extract
pnpm plugin:package
pnpm audit:engine3d-sidecar
pnpm smoke:engine3d-real-structure
pnpm smoke:engine3d-hold-steady
pnpm smoke:engine3d-anneal-energy
pnpm smoke:windows-menu-churn

Extraction and packaging scripts require the inputs appropriate to the package being checked; follow their implementation and authoring documentation. Window/menu work needs the Windows churn check. Interactive changes also use the standing docs/manual-stress-checklist.md on both platforms; add a new surface there rather than substituting a smaller private checklist.

Launch from the current worktree with the supported command. Report the exact launch, visible worktree label and success signal. An old running app or direct cargo run is not accepted launch evidence.

If one platform is unavailable, state macOS unverified or Windows unverified, name the missing native checks and keep that gap visible for review. Do not present tests parameterized for Windows as a hands-on Windows pass.

See also

• Building from Source
• Chemistry Guarantees
• Contributing
• Project Rules