diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea608d9b4657..c64b0178f627 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -108,6 +108,126 @@ To learn about the viewer, run: cargo run -p rerun -- --help ``` +## Tests + +There are various kinds of automated tests throughout the repository. +If not noted otherwise, all tests run automated on CI, however their frequency (per PR, on `main`, nightly, etc.) and platform coverage may vary. + +### Rust tests + +```sh +cargo test --all-targets --all-features +``` +or alternatively (if you've [installed cargo nextest](https://nexte.st/)): +```sh +cargo nextest run --all-targets --all-features +cargo test --all-features --doc +``` + +Runs both unit & integration tests for Rust crates, including the Rerun viewer. + +Tests are written using the standard `#[test]` attribute. + +#### `insta` snapshot tests + +Some of the tests in the `rerun` family of crates are [`insta`](https://docs.rs/insta/latest/insta/) snapshot tests. +These tests work by comparing a textual output of a test against a checked-in reference. + +They run as part of the regular Rust test suite, no extra action is required to include them in a test run. + +If the output of them changes (either intentionally or not), they will fail, and you can review the results by running `cargo insta review` (you first need to install it with `cargo install cargo-insta`). + +#### Image comparison tests + +Some of the tests in the `rerun` family of crates are image comparison tests. +These tests work by rendering an image and then comparing it with a checked-in reference image. + +They run as part of the regular Rust test suite, no extra action is required to include them in a test run. + +Comparison tests are driven by [egui_kittest](https://github.com/emilk/egui/tree/master/crates/egui_kittest)'s `Harness::snapshot` method. +Typically, we use [TestContext](./crates/viewer/re_viewer_context/src/test_context.rs) in order to mock +relevant parts of the Rerun viewer. + +##### Comparing results & updating images + +Each run of the comparison tests will produce new images that are saved to the comparison images. +(typically at `/snapshots`) + +Upon failure, additionally `diff.png` file is added that highlights all differences between the reference and the new image. +In order to update reference with the new image, run with `UPDATE_SNAPSHOTS=1` environment variable set. + +Use `pixi run snapshots` to compare the results of all failed tests in Rerun. + +For best practices & unexpected sources of image differences refer to the [egui_kittest README](https://github.com/emilk/egui/tree/master/crates/egui_kittest#snapshot-testing). + +##### Rendering backend + +Just like for drawing the viewer itself, drawing for comparison tests requires a `wgpu` compatible driver. +As of writing comparison tests are only run via Vulkan & Metal. +For CI / headless environments we a recent version `llvmpipe` for software rendering on Linux & Windows. +On MacOS we currently always use hardware rendering. +For details on how to set this up refer to the [CI setup](./.github/workflows/reusable_checks_rust.yml). + + + +### Python tests + +```sh +pixi run py-test +``` + +The Python SDK is tested using [`pytest`](https://docs.pytest.org/). +Tests are located in the [./rerun_py/tests/](./rerun_py/tests/) folder. + +### C++ tests + +```sh +pixi run cpp-test +``` + +The C++ SDK is tested using [`catch2`](https://github.com/catchorg/Catch2). +Tests are located in the [./rerun_cpp/tests/](./rerun_cpp/tests/) folder. + + +### Snippet comparison tests + +```sh +pixi run -e py docs/snippets/compare_snippet_output.py +``` + +More details in the [README.md](./docs/snippets/README.md). + +Makes sure all of the snippets in the [snippets/](./docs/snippets/) folder are working and yield the same output in all of the supported languages, unless configured otherwise in the [snippets.toml](./docs/snippets/snippets.toml) file. + +### "Roundtrip" tests + +```sh +pixi run ./tests/roundtrips.py +``` + +A set of cross SDK language tests that makes sure that the same logging commands for a select group of archetypes +yields the same output in all of the supported languages. + +Nowadays largely redundant with the snippet comparison tests. + +### Release checklists + +```sh +pixi run -e examples python tests/python/release_checklist/main.py +``` + +More details in the [README.md](./tests/python/release_checklist/README.md). + +A set of **manual** checklist-style tests that should be run prior to each release. +Introduction of new release checklists should be avoided as they add a lot of friction to the release process, +and failures are easy to be missed. + +### Other ad-hoc manual tests + +There's various additional test scenes located at [./tests/cpp/](./tests/cpp/), [./tests/python/](./tests/python/) and [./tests/rust/](./tests/rust/). +We generally build those as a CI step, but they are run only irregularly. +See respective readme files for more details. + ## Tools We use the [`pixi`](https://prefix.dev/) for managing dev-tool versioning, download and task running. To see available tasks, use `pixi task list`. @@ -116,6 +236,10 @@ We use [cargo deny](https://github.com/EmbarkStudios/cargo-deny) to check our de Configure your editor to run `cargo fmt` on save. Also configure it to strip trailing whitespace, and to end each file with a newline. Settings for VSCode can be found in the `.vscode` folder and should be applied automatically. If you are using another editor, consider adding good setting to this repository! Depending on the changes you made run `cargo test --all-targets --all-features`, `pixi run py-test` and `pixi run -e cpp cpp-test` locally. +For details see [the test section above](#tests). + +It is not strictly required, but we recommend [`cargo nextest`](https://nexte.st/) for running Rust tests as it is significantly faster than `cargo test` and yields much more readable output. +Note however, that as of writing `cargo nextest` does not yet support doc tests, those need to be run with `cargo test`. ### Linting Prior to pushing changes to a PR, at a minimum, you should always run `pixi run fast-lint`. This is designed to run diff --git a/crates/viewer/re_renderer/src/renderer/lines.rs b/crates/viewer/re_renderer/src/renderer/lines.rs index e73a3380bcf4..cd38c049ff18 100644 --- a/crates/viewer/re_renderer/src/renderer/lines.rs +++ b/crates/viewer/re_renderer/src/renderer/lines.rs @@ -9,9 +9,7 @@ //! The quads are oriented and spanned in a vertex shader. //! //! It is tempting to use instancing and store per-instance (==quad) data in a instance-stepped vertex buffer. -//! However, GPUs are notoriously bad at processing instances with a small batch size as -//! [various](https://gamedev.net/forums/topic/676540-fastest-way-to-draw-quads/5279146/) -//! [people](https://gamedev.net/forums/topic/702292-performance-fastest-quad-drawing/5406023/) +//! However, at least historically GPUs are notoriously bad at processing instances with a small batch size as //! [point](https://www.reddit.com/r/vulkan/comments/le74sr/why_gpu_instancing_is_slow_for_small_meshes/) //! [out](https://www.reddit.com/r/vulkan/comments/47kfve/instanced_rendering_performance/) //! […](https://www.reddit.com/r/opengl/comments/q7yikr/how_to_draw_several_quads_through_instancing/).