Testing🔗

Unit Tests🔗

Unit tests are written in C using the GLib testing framework. Files follow the pattern tests/test-$NAME.c.

meson test -C build --suite unit

Integration Tests🔗

Integration tests test a specific portal in a fully integrated environment. They are written in Python using pytest and dbusmock. Files follow the pattern tests/test_$NAME.py.

meson test -C build --suite integration

# or from the source directory
./tests/run-test.sh

The environment is set up by fixtures in conftest.py which can be overwritten or parameterized by individual tests. Convenient functions and classes live in xdp_utils.py. Portal backends are implemented using dbusmock templates in the tests/templates/ directory.

Adding New Tests🔗

  1. Add a test_$NAME.py file to tests/

  2. Add the file to tests/meson.build

  3. If the portal requires a backend, add a template to tests/templates/ and add it to tests/meson.build

  4. Make sure the required portals are listed in xdg_desktop_portal_dir_default_files in conftest.py

Look at existing tests for examples of fixtures, request patterns, session handling, and template parameters.

Running Tests🔗

# All tests
meson test -C build

# By suite
meson test -C build --suite unit
meson test -C build --suite integration

# Single test
meson test -C build integration/clipboard

# Verbose output
meson test -C build --verbose

# Specific pytest test
./tests/run-test.sh ./tests/test_clipboard.py::TestClipboard::test_version -v

Environment Variables🔗

Required variables are set automatically by meson and run-test.sh:

  • XDG_DESKTOP_PORTAL_PATH – path to the xdg-desktop-portal binary

  • XDG_PERMISSION_STORE_PATH – path to the xdg-permission-store binary

  • XDG_DOCUMENT_PORTAL_PATH – path to the xdg-document-portal binary

  • XDP_VALIDATE_ICON – path to the icon validator binary

  • XDP_VALIDATE_SOUND – path to the sound validator binary

  • XDP_VALIDATE_AUTO – automatically discover validators (for installed tests)

Test control:

  • XDP_TEST_IN_CI – run fewer iterations and test less thoroughly

  • XDP_TEST_RUN_LONG – run more iterations and enable additional test variants (e.g. Snap and Linyaps app info)

  • XDP_TEST_VALGRIND – signal that Valgrind is running externally so the framework increases timeouts

  • XDP_VALIDATE_ICON_INSECURE – skip bwrap sandboxing for the icon validator (for chroot/container environments; never set in production)

  • XDP_VALIDATE_SOUND_INSECURE – same for the sound validator

Debugging:

  • G_MESSAGES_DEBUG=all – enable debug output

  • XDP_DBUS_MONITOR – start dbus-monitor on the test bus

  • XDP_DBUS_TIMEOUT – D-Bus call timeout in ms (default: 5000)

  • XDG_DESKTOP_PORTAL_WAIT_FOR_DEBUGGER – pause for debugger attach (raises SIGSTOP)

  • XDG_DOCUMENT_PORTAL_WAIT_FOR_DEBUGGER – same for xdg-document-portal

  • XDG_PERMISSION_STORE_WAIT_FOR_DEBUGGER – same for xdg-permission-store