Testing & Quality

Orbitron uses unit tests, integration tests, corpus-backed smoke tests, and a small set of benchmarks. Keep tests fast and deterministic by default, and make large-corpus coverage opt-in.

11.1 What Testing Does

  • Catches regressions in parsing, rendering preparation, selection, editing, and analysis.
  • Ensures file loaders handle malformed inputs without panics.
  • Keeps refactors safe by locking down expected behavior at API boundaries.

11.2 Test Types & Locations

  • Unit tests: alongside code (#[cfg(test)]) or crate tests.
  • Integration tests:
    • IO workflows: io/pipelines/tests/
    • CLI workflows: automation/cli/tests/
  • Smoke tests: load many fixtures and validate “does not crash” behavior (typically under io/pipelines/tests/).
  • Malformed input tests: validate error surfaces (typically under io/pipelines/tests/).
  • Regression tests: tests/regression/.

11.3 Running Tests

# Workspace unit + integration tests
cargo test --workspace

# Single crate
cargo test -p orbitron-io-pipelines

# One test by name
cargo test test_parse_xyz_atom_count

# Show println!/logs
cargo test -- --nocapture

# Parallel execution (recommended for local runs)
cargo nextest run --workspace

With logging:

RUST_LOG=debug cargo test -- --nocapture
RUST_LOG=orbitron=debug cargo test

Quality gates:

cargo fmt --all
cargo clippy --workspace --all-targets --all-features --deny warnings

Optional smoke tests:

  • Wasm viewer smoke test
    • Build + serve the wasm dist/ output (scene and wasm on same origin):
      • cd viewer/wasm && conda run -n orbitron-dev trunk build
      • cp /tmp/scene.bin dist/scene.bin
      • cd dist && python3 -m http.server 8081 --bind 127.0.0.1
    • Then run: WASM_VIEWER_URL="http://127.0.0.1:8081/?scene=/scene.bin" npm run test:smoke
    • One-command alternative (from viewer/wasm): npm run test:smoke:dist
    • First-time Playwright setup may require npx playwright install.
  • Widget frontend scaffold
    • Build the scaffold bundle: cd extensions/python-bridge/widget_frontend && npm install && npm run build
    • Verify output via ./scripts/verify_widget_frontend.sh (from extensions/python-bridge).
  • Widget packaging checklist (draft)
    • Confirm widget_frontend/dist/orbitron-viewer.js builds cleanly.
    • Ensure the frontend bundle is packaged alongside the wheel (see PACKAGING.md in the extensions/python-bridge/ directory).

11.4 Performance Benchmarks

Orbitron uses Criterion for targeted performance regression checks.

cargo bench -p orbitron-viewer-core --bench cartoon_build

Bench sources live in viewer/core/benches/ and should prefer small fixtures from io/pipelines/tests/fixtures/ to keep runs fast and reproducible.

11.5 Test Fixtures

Orbitron uses two fixture roots under io/pipelines/tests/:

  • io/pipelines/tests/fixtures/ (in git): small canonical fixtures and malformed samples.
  • io/pipelines/tests/corpus/ (git-ignored): large real-world corpora. Tests should skip gracefully when corpus files are missing.

Helpers:

  • io/pipelines/tests/common.rs::fixture_path(...)
  • io/pipelines/tests/common.rs::corpus_path(...)

11.6 Regression Checklist

Use this quick pass before requesting review—especially when touching canonical pipelines, helpers, or loader behaviour.

  • Environment prep: source ~/.bash_profile && conda activate orbitron-dev. Run cargo fmt --all and cargo clippy --workspace --all-targets --all-features --deny warnings until clean.
  • Core parsers & canonical helpers: conda run -n orbitron-dev cargo test -p orbitron-io-pipelines --lib plus any targeted binary tests (e.g., cargo run --bin test_gaussian_summary). When adding or modifying helpers, ensure at least one affected format-specific test exercises them.
  • CLI & bundle workflows: cargo test -p orbitron-cli --lib --tests (covers canonical export/import, cache hydration, QE/VASP/Molcas/Molpro regressions). If fixtures changed, re-run the manual smoke: cargo run -p orbitron-cli -- canonical export <fixture> and inspect the manifest + attachments.
  • Regression crate: cargo test -p orbitron-regression for loader digests whenever you change parsing logic, canonical metadata, or attachments.
  • Docs: update documentation in the docs/ directory whenever expectations shift (e.g., new helper contracts, format extras, canonical bundle layout).
  • Fixtures & hashing: for new attachments/fixtures, record SHA256 in the relevant test assertions and verify register_attachment_refs + outcome_with_attachments are wired so caches stay deterministic.
  • UI/TUI spots (if touched): run cargo test -p orbitron-ui-shell --lib and cargo test -p orbitron-tui --lib, then perform a quick manual load of a representative canonical bundle via the CLI or viewer.