libfreenect2 0.4
Open source driver for the Kinect for Windows v2 (K4W2) sensor
Loading...
Searching...
No Matches
Test plan

Table of Contents

What CI covers automatically, what only a human with a sensor can cover, and what must be attached to a release. This page is the index; it does not restate the procedures that already live in Quality checks and v0.3 upstream issue coverage.

1. Automated coverage

Every push and pull request runs the CI workflow. Full job list and runner placement in Development and contributing.

Dimension Covered by Notes
GCC and Clang, shared and static linux-builds 4-way matrix, C++17
C++17 conformance all build jobs -DCMAKE_CXX_STANDARD=17
Unit tests linux-builds, build-test-metal ctest -L unit
Metal/CPU depth parity build-test-metal self-hosted macOS, real Apple GPU
Depth filter backend combinations linux-filter-backends
VAAPI JPEG decoding linux-vaapi
TegraJPEG fallback state machine linux-vaapi Fake primary; real Tegra hardware is release-only
CUDA compile only No runtime validation in CI
ASan + UBSan, TSan sanitizers
Stream-parser fuzzing fuzzers Bounded smoke run
Coverage coverage LLVM source coverage
Lint and static analysis format, semgrep, static-analysis
Python tooling python-quality Ruff + pytest

What CI does not establish: OpenGL, OpenCL, and CUDA runtime behavior; USB transfer behavior; anything requiring a physical sensor. Hosted CI deliberately does not report GPU or USB runtime success when it only compiled or simulated those paths.

2. Hardware smoke checklist

Run against a connected Kinect v2 after any change to USB handling, the device lifecycle, or a depth backend. Every command is hardware-free of a viewer, so this works over SSH.

# 1. Enumerate, open, stream, close
Protonect -noviewer -frames 30
# 2. Single-stream isolation
Protonect -noviewer -frames 30 -norgb
Protonect -noviewer -frames 30 -nodepth
# 3. Serial selection (multi-device hosts, or to confirm the argument parses)
Protonect -noviewer -frames 30 <serial>
# 4. Every pipeline available on this machine. Substitute the names reported by
# getAvailablePacketPipelines(); the set below is a macOS example.
for p in cpu metal opengl opencl opencl_kde; do
LIBFREENECT2_PIPELINE=$p Protonect -noviewer -frames 30
done
# 5. End-to-end capture with registration
mkdir -p /tmp/cap && KinectCapture snapshot /tmp/cap

Check for each run:

  • The log reports the expected pipeline, and the transfer pool line matches the platform default (Runtime configuration reference).
  • Capture writes rgb.ppm, depth_mm.pgm, infrared.pgm, registered.ppm, and metadata.json, and valid_depth_pixels in the metadata is plausible for the scene.
  • No errors appear before stopped. See Troubleshooting for messages that are known-harmless at teardown.

Lifecycle

  • Repeated open → start → capture → stop → close in one process.
  • Immediate restart: stop and start again without closing.
  • Unplug and reconnect: the old device pointer must reach a terminal state, and capture must resume through a newly opened device object. KinectReconnect drives this.

The Kinect hardware soak workflow automates the repeated-lifecycle and reconnect cases on a runner with the kinect label; see Quality checks and Self-hosted macOS CI runner setup.

3. Release-only evidence

The v0.3.0 gate is specified in v0.3 upstream issue coverage. In short, a release must attach results for:

  • Kinect lifecycle soak, including an attended unplug/replug cycle.
  • 60-second raw recording and replay validation (Recording, replay, and multiple Kinects).
  • Intel or AMD VAAPI runtime fallback.
  • NVIDIA Jetson TegraJPEG runtime fallback.
  • CPU/CUDA recording parity, since CI only compiles CUDA.
  • Three-distance plus unseen-holdout depth calibration (Per-device depth correction).

A soak run with reconnect_cycles: 0 does not satisfy the unplug/replug gate and must be identified as such.

TegraJPEG release check

On a Jetson build with TegraJPEG and TurboJPEG enabled, run at least ten minutes of RGB capture with LIBFREENECT2_RGB_PROCESSOR=tegrajpeg Protonect -noviewer -frames 18000. If TegraJPEG reports an incomplete decoding result, require one fallback warning, a successful frame for that same packet, and uninterrupted TurboJPEG frames afterward. If the hardware failure does not occur, record the run as "not triggered" rather than claiming that runtime recovery was proven.

4. Recording results

When attaching evidence to a release or a bug report, record the environment alongside the outcome — a pass means little without it:

  • OS and version, and CPU architecture
  • Sensor serial and firmware version (both are logged at start, and written to metadata.json by KinectCapture)
  • USB host controller (lspci -nn, or system_profiler SPUSBDataType)
  • GPU and driver version
  • Pipeline exercised
  • Duration or frame count, and any failures

Example, from a validation run of this checklist:

Field Value
Host macOS 15.7.7, Apple M4 Pro (arm64)
Sensor serial 094318334247, firmware 4.0.3917.0
Link 5 Gb/s (Speed: Up to 5 Gb/s)
Pipelines available cpu dump metal opengl opencl opencl_kde
Exercised metal (default), opengl, opencl, cpu
Result Capture and registration OK; benign teardown error only

Next steps