Development environment

Requirements: Python >= 3.11. Node.js is not needed: the browser viewer and its widget live in the separate machinome-viewer repository, and the tests that need a viewer skip unless that package is installed. OpenSCAD is conditional: put it on the PATH when working on SolidPython2/Solid2 or raw OpenSCAD nodes, or the default OpenSCAD snapshot renderer. All-exact projects — CadQuery, build123d, or the two mixed — build, test, and export without it; use machinome snapshot --renderer web for snapshots on a machine without OpenSCAD.

manifold3d is installed by default and is conditional in the same sense: it decides faceted geometry, so it is needed whenever an assertion compares a part that has no exact geometry, and by assertAssemblySupported, whose statics phase reads contact patches off meshed intersections for every body. An all-exact project’s other geometric assertions are decided by the OCCT kernel and run without it — useful on a platform with no compiled wheel, such as WebAssembly. A path that needs it and cannot import it says so by name.

Clone the repository (the tutorial’s machine under docs/tutorial/ is built and tested by the suite; the real machines the manual points to are on machinome.org, not in this repository):

$ git clone https://github.com/machinome/machinome.git
$ cd machinome

Create a virtualenv and install the package in editable mode with the dev dependencies:

$ python -m venv .venv
$ source .venv/bin/activate
$ pip install -e ".[dev]"

The machinome CLI entrypoint (machinome/cli.py) is now on the PATH of the virtualenv.

Running tests

The test suite is pytest, run from the repository root:

$ make test          # equivalent to: pytest
$ pytest tests/test_builder_lifecycle.py   # a single file
$ make lint          # flake8 + black --check
$ make test-all      # tox across supported Python versions

Notes:

• Rendering tests invoke the real openscad binary. On a headless machine, snapshot-related tests may need xvfb-run -a pytest ....

• Browser-snapshot tests are mandatory for changes to that renderer. Install a matching viewer with its snapshot extra (from source while it is unpublished), then install Chromium and run the real capture explicitly:

  $ playwright install chromium
  $ MACHINOME_WEB_SNAPSHOT_E2E=1 pytest tests/test_browser_renderer.py::BrowserSnapshotEndToEndTest

  The ordinary suite leaves this environment variable unset and skips the capture, even when the viewer is installed. With the opt-in set, a missing viewer or browser is a setup failure. The dedicated CI browser-snapshot job installs both dependencies, sets the opt-in, and runs this same test.

• tests/meta_project/ together with tests/test_meta.py is the end-to-end meta-project harness: it runs small real machinome projects — both deliberately green and deliberately red fixtures — to prove the loading, rendering, and machinome test subprocess paths. Use it when a change touches behavior that direct unit tests cannot establish; see docs/contributor-briefing.md for when and why.

• The browser viewer’s own tests live in the machinome-viewer repository. tools/generate_parity_fixture.py produces, from this framework’s render results, the parity fixture that repository commits beside its expression evaluator.

Where things live

• machinome/node/ — the node tree (base, assembly, fusion, leaf, CAD backend adapters, operations)

• machinome/manager/ and machinome/cli.py — the machinome command: develop loop, test, snapshot, new, export

• machinome/core/ — build pipeline, loader, caching

• machinome/simulation/ — drivers, instructions, the stepped Sim loop, and ScenarioTest

• machinome/test.py — mesh-oriented test cases and assertions

• machinome/viewers/ — the OpenSCAD snapshot renderer, the lookup of the installed machinome-viewer package, and the staging half of the web snapshot renderer (the photograph itself is the viewer’s)

• tests/ — Python test suite

• docs/ — Sphinx documentation, architecture synthesis, ADRs

• openspec/ — OpenSpec change proposals and baseline specs

OpenSpec changes

Behavioral contracts live in openspec/specs/. Changes are proposed, reviewed, implemented, and archived through the OpenSpec workflow (OpenSpec, CLI v1.x; the repo’s openspec/config.yaml carries project context and rules):

1. Propose — create a change under openspec/changes/<name>/ with proposal.md (why, what changes, capabilities, impact), design.md (how), and tasks.md (implementation steps). The change describes deltas against the current specs.

2. Review — the proposal is inspected and refined before any code is written. Specs describe observable behavior only; no aspirational requirements.

3. Apply — implement the ratified proposal, task by task, TDD-style: red evidence first (a failing test that pins the contract), then the smallest change that satisfies it.

4. Archive — when the change lands, its spec deltas are merged into openspec/specs/ and the change moves to openspec/changes/archive/.

The proposal and completed record belong in this repository’s openspec/ directory. See CONTRIBUTING.rst for the contribution workflow.

Architecture Decision Records

Why the system is the way it is lives in docs/adrs/ (see docs/adrs/README.md for the index and the full discipline):

• One decision per ADR, numbered sequentially, filed under the subsystem it affects (NODE, BUILD, IPC, MATH, TEST-FRAMEWORK, VIEWER-WEB, EXPORT).

• Statuses flow Proposed → Accepted; later ADRs may mark earlier ones Superseded. Superseded ADRs stay in the log — they are the history that makes current decisions legible.

• When an OpenSpec change carries an architectural shift, its ADR is written alongside the change and the architecture synthesis (docs/architecture.md) is updated as part of landing it.

Read order for orientation: architecture synthesis first (docs/architecture.md), then the specs for exact observable behavior (openspec/specs/), then an ADR when you need to know why (docs/adrs/). The contributor briefing (docs/contributor-briefing.md) adds verification guidance: how to choose between direct pytest coverage and the meta-project harness, and the red-first evidence principle.