Backend-generic HIDAPI tests that run against a virtual HID device so they
need no physical hardware. Every test is written purely against the public
HIDAPI API plus the small backend-agnostic test_virtual_device interface
(test_virtual_device.h), so the same test runs against every backend that
provides a virtual-device implementation.
Rather than injecting arbitrary input from the test (which would need
platform-specific plumbing), the virtual device has a few pre-recorded
scenarios baked in. The test triggers one using the ordinary public API — it
sends a Feature report whose first payload byte is a TEST_VDEV_CMD_* command
— and the device replays the matching canned input report. This keeps the test
code 100% platform-neutral; all device behaviour lives in the per-backend
provider. See test_virtual_device.h for the shared contract (report size,
command bytes, expected payloads).
| Test | What it exercises |
|---|---|
test_device_io.c |
open → write an output report → trigger+read input reports (Feature-report write, then input-report read-back) → close |
| Platform / backend | Provider | Mechanism | CI |
|---|---|---|---|
| Linux / hidraw | test_virtual_device_uhid.c |
kernel /dev/uhid |
runs in builds.yml (ubuntu-cmake) |
| Linux / libusb | test_virtual_device_rawgadget.c |
/dev/raw-gadget + dummy_hcd (in a VM) |
builds + self-skips in builds.yml; runs in the manual libusb-vhid-test job (in a VM) |
| Windows / winapi | test_virtual_device_win.c + windows/driver/ |
modified vhidmini2 UMDF2 driver | builds + self-skips in builds.yml; runs in the manual win-vhid-test job |
| macOS / darwin | test_virtual_device_mac.c |
IOHIDUserDevice (IOKit) |
builds + self-skips in builds.yml (macos-cmake); runs on a real Mac |
Whenever a virtual device cannot be created or does not enumerate, the test returns CTest's skip code (77) instead of failing, so ordinary builds on any host stay green.
Some virtual devices need privileged, out-of-band setup that isn't appropriate for the per-push CI matrix:
- Windows — the vhidmini2 driver must be built, self-signed and installed
(via
devcon, no reboot) before the test, and removed afterwards. Thewin-vhid-testworkflow does this end-to-end on hosted runners (built onwindows-2022, whose MSBuild matches the WDK's driver build tasks, then installed and tested onwindows-latest). The driver underwindows/driver/is derived from Microsoft's vhidmini2 sample and is licensed separately under the MS-PL (not HIDAPI's license); seewindows/driver/README.mdandwindows/driver/LICENSE.txt. - Linux / libusb — needs the
raw_gadgetanddummy_hcdkernel modules, which the hostedubuntu-latestkernel is built without (it has no USB gadget subsystem). Thelibusb-vhid-testworkflow therefore runs the test inside a lightweight VM (virtme-ng+ QEMU) booting a generic Ubuntu kernel whoselinux-modules-extraships both modules; the VM shares the host filesystem, so it runs the host-built binaries. The same approach works locally and on WSL2 (whose default kernel also lacks these modules). - macOS — creating an
IOHIDUserDeviceis gated by thecom.apple.developer.hid.virtual.deviceentitlement and an interactive Accessibility (TCC) consent prompt, neither available on a hosted runner, so the provider self-skips there. It is meant to actually run on a developer machine or a self-hosted runner where consent has been granted.
Some platforms have no practical way to create a virtual HID device — not even
in CI — so there is intentionally no provider for them (the backend simply has
no DeviceIO_* test):
- FreeBSD — HIDAPI uses the libusb backend, but FreeBSD has no userspace
USB/HID creation facility:
cuse(3)can't produce a libusb-visible USB device,usb_template(4)("USB device mode") needs a hardware USB Device Controller (there is nodummy_hcdanalogue), and the plannedusrhid(4)(a/dev/uhidequivalent) is not yet in-tree. A real test would need physical device-mode hardware orusrhid. - NetBSD / OpenBSD —
uhid(4)is consumer-only (no create/emulate ioctl), there is nocuse, andrumphas no virtual USB host controller; on OpenBSD the libusb backend additionally needsuhid/uhidevdisabled in a custom kernel. No userspace virtual-device path exists.
CI can build HIDAPI on these systems, but cannot exercise a virtual device, so the device-I/O test is not wired up there.
# Linux (hidraw via uhid)
cmake -B build -S . -DHIDAPI_WITH_TESTS=ON
cmake --build build
sudo modprobe uhid
sudo ctest --test-dir build -R DeviceIO_hidraw --output-on-failureOn Windows/macOS configure with -DHIDAPI_WITH_TESTS=ON and run ctest; the
device-backed tests self-skip unless the corresponding virtual device has been
set up (see the dedicated workflows under .github/workflows/).
DeviceIO_darwin is the one virtual device that cannot run on hosted CI: macOS
gates IOHIDUserDevice creation behind the private
com.apple.developer.hid.virtual.device entitlement and an interactive
Accessibility (TCC) consent prompt. To run it on a physical Mac you currently
need to:
- have a paid Apple Developer account (US$99/year) and use it to generate a
signing certificate plus a provisioning profile that carries the
com.apple.developer.hid.virtual.deviceentitlement; - code-sign the built
DeviceIO_darwinbinary with that entitlement; and - on first run, grant it Accessibility access under System Settings → Privacy & Security → Accessibility (answer the TCC prompt).
sudo does not help here: the entitlement and the consent prompt are
enforced by AMFI/TCC, not by file permissions, so running as root neither
supplies the entitlement nor bypasses the prompt.
These are the known requirements rather than a verified, step-by-step recipe — the maintainers have not exercised this path themselves. Reports refining it are welcome.