mirror of
https://github.com/OrcaSlicer/OrcaSlicer.git
synced 2026-09-17 14:02:35 +00:00
Kris Austin
a610d2d899
* ci: build Windows with build_win.bat and drop the old scripts The deps and slicer jobs called build_release_vs.bat; they now call build_win.bat. --deps-dir and --build-dir name the build/build-arm64 directories the cache keys and later steps already use, and the script's own VsDevCmd call replaces the Enter-VsDevShell blocks. With both stages configured each way into the same directory, the deps superbuild is byte-identical and the slicer build files are byte-identical apart from CMakeCache.txt recording how DEP_BUILD_DIR was set. Two changes beyond the script swap: - The compiler is the clang-cl bundled with Visual Studio, the script's default. The old script's bare "clang-cl" resolved to the LLVM on the runner image's PATH, 20.1.8 on x64 and 22.1.8 on arm64; both arches now build with the 22.1.3 VS 18.9 ships. Cached dependencies are only rebuilt when deps/ changes, so they stay on the LLVM they were built with; the arm64 leg already links deps built with Clang 19 into a Clang 22 slicer. - The deps job no longer zips the dependencies afterwards. The zip was never uploaded and was not in the cached path. A failed cmake --build now fails the job. The old script returned 0, so the arm64 failure fixed in #15719 was reported as success and the half-built dependencies were saved to the cache. build_release.bat, build_release_vs.bat and build_release_vs2022.bat are removed; nothing referenced them any more. * ci: run Build all when the Windows build script changes; tests doc builds the deps The push filter of build_all.yml never listed a build script, and CI now depends on build_win.bat, so it and its test suite join the list the pull_request filter already has. tests/AGENTS.md told Windows to run build_win.bat --run-tests, which only implies -s and stops at the dependency check on a clean checkout. The old build_release_vs.bat tests built the dependencies first, so the line now says -ds --run-tests.
59 lines
5.1 KiB
Markdown
59 lines
5.1 KiB
Markdown
# Test suite rules
|
|
|
|
Rules for writing tests under `tests/`. [CATCH2.md](CATCH2.md) is the Catch2 reference. Building and running the suites is covered on the wiki, at <https://www.orcaslicer.com/wiki/developer_reference/how_to_test.html>.
|
|
|
|
## The suites
|
|
|
|
- `libslic3r`: the core library. Geometry, meshes, file formats, config and presets, Clipper, algorithms, data structures.
|
|
- `fff_print`: the FFF slicing pipeline, from a `Model` plus config through `Print` and `PrintObject` to emitted G-code.
|
|
- `sla_print`: SLA support-tree and pad geometry, support-point generation, raycast.
|
|
- `libnest2d`: 2D nesting and packing.
|
|
- `slic3rutils`: the Python plugin system and its slicing-pipeline bindings.
|
|
- `filament_group`: filament-to-extruder grouping, checked against golden files.
|
|
- `cli`: end-to-end runs of the built `orca-slicer` binary, Linux only. These tests carry the `RequiresApp` label, which the CI unit-test job excludes because it receives only `build/tests`; run them with `ctest --test-dir build/tests -C Release -L RequiresApp`.
|
|
|
|
## Building and running
|
|
|
|
Tests are off by default, so the build has to be told to include them.
|
|
|
|
- Windows: `build_win.bat -ds --run-tests`, which builds the dependencies and the tests and runs them (`-l -x` for the clang-cl and Ninja build CI uses)
|
|
- macOS: `./build_release_macos.sh -s -a arm64 -T`, which builds and runs them
|
|
- Linux: `./build_linux.sh -t`, then `ctest --test-dir build/tests -C Release`
|
|
|
|
Rebuild a single suite with `cmake --build build --config Release --target <suite>_tests`. Visual Studio, Xcode and the Ninja Multi-Config generator that `build_linux.sh` uses are all multi-configuration, so `ctest` needs `-C` on every platform; without it, tests registered with plain `add_test()` lose their labels and report "Not Run".
|
|
|
|
## Where a test goes
|
|
|
|
- Pick the suite by the production code the test exercises, not by how the test is written.
|
|
- A property of a class that holds with no `Print` involved belongs in `libslic3r`. Behavior that depends on print settings, or produces or consumes G-code or slicing state, belongs in `fff_print`.
|
|
- One file per subsystem, named `test_<subsystem>.cpp`. It owns every test for that subsystem, whether the test reads in-memory state or generated output.
|
|
- When you add a file, list it in that suite's `CMakeLists.txt` in the same change.
|
|
|
|
## Use the existing helpers
|
|
|
|
Check these before writing your own setup or output-parsing code.
|
|
|
|
- `tests/test_utils.hpp` is shared by every suite. `load_model()` loads a mesh from `tests/data/`, and `ScopedTemporaryFile` gives a temp path that removes itself.
|
|
- `fff_print/test_helpers.hpp` builds and slices a `Print` and parses the emitted G-code. Read it before writing an fff_print test rather than assembling a `Print` by hand.
|
|
- The other suites have their own: `sla_print/sla_test_utils.hpp`, `libnest2d/libnest2d_test_utils.hpp`, `slic3rutils/plugin_test_utils.hpp`, `filament_group/fg_test_utils.hpp`. `libslic3r` has none and uses the shared header.
|
|
- Test data lives in `tests/data/` and is reached through the `TEST_DATA_DIR` define. Wrap it in `std::string(...)` before joining a path onto it.
|
|
|
|
## Writing the test
|
|
|
|
- Name the test case as a plain behavioral sentence in the present tense. No `Subsystem:` prefix.
|
|
- Tag it with the subsystem it covers, matching the file, in PascalCase. That tag is what people filter on, so every test needs one.
|
|
- Add further tags where they help: a narrower one to slice a large file (`[Rotcalip]`, `[Placer]`), a shared one for something spanning files (`[Python]`, `[H2C]`, `[Regression]`), or `[NotWorking]` / `[.]` to disable or hide a test. Say why in a comment if you disable or hide.
|
|
- Prefer a flat `TEST_CASE` per behavior, with `GENERATE` for parameterized cases. Reserve `SCENARIO` / `GIVEN` / `WHEN` / `THEN` for genuine shared setup that branches into a few close variations.
|
|
- Set the config keys your test depends on, and derive the expected values from what you set. A 20mm cube sliced at `layer_height` 2 is 10 layers, and the test should state both parts. If a number in your assertion comes from a key you never set, the test is also testing that default.
|
|
- Assert the defining property, not an incidental value. "Skirt present" or "at least 2 brim loops" survives a refactor; exact coordinates and byte counts do not.
|
|
- Name a regression test for the behavior it protects, never for an issue or PR number.
|
|
- When asserting on G-code, match the meaningful token such as `; skirt` rather than whole lines, whitespace or comment wording. Depend on ordering only when ordering is the contract.
|
|
|
|
## Catch2 rules that cause real breakage
|
|
|
|
- Never reuse a `SECTION` name inside a loop. Use `DYNAMIC_SECTION` so each iteration is unique.
|
|
- Never assert from a spawned thread. Catch2 assertions are not thread-safe. Collect results in the thread and assert on the main thread.
|
|
- Never combine conditions with `&&` or `||` inside one assertion. Split them so Catch2 can print both operands on failure.
|
|
- Compare floats with `WithinAbs` or `WithinRel`, never `==`. Prefer these over `Approx` in new tests.
|
|
- Keep tests self-contained: no shared state, green under `--order rand`.
|