# Running tests
By default the Rust test runner executes in parallel, trying to run as many tests concurrently as
possible. This is a problem because the underlying librealsense2 API doesn't make any guarantees
surrounding behaviour in parallel environments. In particular, if you try to run pipelines to the
same device (or even different devices) on parallel threads, you may get some contention and random
crashing at the libusb / kernel level. Unit tests can typically avoid this, as full streaming setups
would be more in the realm of integration tests (in the `tests/` directory). The integration tests
aim to setup streaming as a normal program might, so it is necessary to run these tests on a single
thread of execution (otherwise, you'll get random crashes and failures, and the signal : noise on
that isn't worth the time to investigate).
## Running unit tests WITH NO DEVICE connected
`cargo test`
## Running integration tests WITH DEVICE(S) connected
On Linux: `RUST_TEST_THREADS=1 cargo test --all-features` On Windows PowerShell:
`$Env:RUST_TEST_THREADS=1; cargo test --all-features`
Here, `--all-features` is just a quick way to enable the `test-single-device` feature (See
[Cargo.toml](Cargo.toml)).
Some of the integration tests will be hardware specific, and will do nothing if a device of expected
category (e.g. D400, L500) is not connected. These tests are not run on CI checks, and will have to
be run manually.
# Testing
Testing a project that incorporates hardware is going to be difficult by default, because the
end-user expectations hinge on the hardware <-> software interaction, but we cannot always guarantee
full availability of every possible hardware combination.
What's more, we can't even always guarantee that a single device is plugged in. This makes it
difficult to unit-test parts of the API that rely on device-specific behaviour. There are ways to
mock around this, but mocking such behaviour is more often than not going to be uninteresting and
unhelpful in evaluating whether or not the hardware and software are operating as intended.
Lastly, unit-tests specifically become difficult to write because many parts of the underlying
librealsense2 API are interconnected. It is not possible to test a pipeline object without a
context, for example, because the underlying C-API requires that we construct a pipeline from a
context. If we mock this out, we're not testing much at all that the compiler should not already
guarantee in safe Rust. Primarily, remember that the most interesting things to test will be the
`unsafe` blocks and ensuring that no resources are leaked (and that the abstractions encourage good
Rust-like programming!).
## Device support
Unfortunately, we do not own the full suite of sensors that RealSense purports to support. In some
ways this isn't possible because RealSense will also detect and configure webcams, and those will
each have their own set of supported interfaces, resolutions, etc. Fortunately, this isn't actually
a show-stopper for most of the code. The majority of the crate is just a thin-wrapper around the
semantics of the C-API in librealsense2. Additionally, most of the abstractions in that API
(pipelines, contexts, etc.) are more or less the same for all devices. Some device-specific aspects
exist (you can filter devices by product category, and different sensors support different options);
however, the majority of the code is expected to operate in much the same way.
The main feature that we aim to provide with realsense-rust is better memory safety, and providing a
better model of the underlying process in which you acquire data from librealsense2. To that end, we
have spent time to understand the underlying C and C++ ownership model for every pointer type in
librealsense2 as best we can. Where possible, we reflect this in the crate itself. This is all to
say that you should not expect the existing abstractions to leak memory or violate ownership. If you
do find this though, you've found a bug! We encourage you to report it to our
[issue tracker](https://gitlab.com/tangram-vision/oss/realsense-rust/-/issues) to help us fix it for
the community at large!
With all that said, we explicitly have tested for the following devices:
- [RealSense D435i](https://www.intelrealsense.com/lidar-camera-l515/)
- [RealSense L515](https://www.intelrealsense.com/lidar-camera-l515/)
# Other things to be aware of
## Linting
All merge requests and all code must be linted and approved by `cargo clippy` before it is merged
in. This is enforced through the CI pipeline. If you want to run what the pipeline does locally,
run:
```
cargo clippy --all-targets --all-features -- -D warnings
```
## `rustfmt` requirements
We use `rustfmt` to ensure that our code is always consistent in style. If you are contributing any
tests, please do so as well.