afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
Close stale issues and PRs / stale (push) Has been cancelled
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
xdg-desktop-portal test suite
|
|
=============================
|
|
|
|
## Unit tests
|
|
|
|
This directory contains a number of unit tests. The tests are written in C and
|
|
are using the glib testing framework (https://docs.gtk.org/glib/testing.html).
|
|
|
|
The files follow the pattern `test-$NAME.c` and are compiled by meson. The tests
|
|
can be run with `meson test --suite unit`.
|
|
|
|
## Integration tests
|
|
|
|
The integration tests usually test a specific portal in a fully integrated
|
|
environment. The tests are written in python using the pytest framework.
|
|
|
|
The files follow the pattern `test_$NAME.py`. The tests can be run with
|
|
`meson test --suite integration` or with `run-test.sh` in the source directory.
|
|
|
|
The environment is being set up by fixtures in `conftest.py` which can be
|
|
overwritten or parameterized by the tests themselves. There are a bunch of
|
|
convenient functions and classes in `__init__.py`. The portal backends are
|
|
implemented using dbusmock templates in the `templates` directory.
|
|
|
|
### Environment
|
|
|
|
Some environment variables need to be set for the integration tests to function
|
|
properly and the harness will refuse to launch if they are not set. If the
|
|
harness is executed by meson or run-test.sh, they will be set automatically.
|
|
|
|
* `XDG_DESKTOP_PORTAL_PATH`: The path to the xdg-desktop-portal binary
|
|
|
|
* `XDG_PERMISSION_STORE_PATH`: The path to the xdg-permission-store binary
|
|
|
|
* `XDG_DOCUMENT_PORTAL_PATH`: The path to the xdg-document-portal binary
|
|
|
|
* `XDP_VALIDATE_ICON`: The path to the xdg-desktop-portal-validate-icon binary
|
|
|
|
* `XDP_VALIDATE_SOUND`: The path to the xdg-desktop-portal-validate-sound binary
|
|
|
|
* `XDP_VALIDATE_AUTO`: If set, automatically discovers the icon and sound
|
|
validators (only useful for installed tests) instead of using
|
|
`XDP_VALIDATE_ICON` and `XDP_VALIDATE_SOUND`.
|
|
|
|
Some optional environment variables that can be set to influence how the test
|
|
harness behaves.
|
|
|
|
* `XDP_TEST_IN_CI`: If set (to any value), some unreliable tests might get
|
|
skipped and some tests might run less iterations or otherwise test less
|
|
thoroughly.
|
|
Set this for automated QA testing, leave it unset during development.
|
|
|
|
* `XDP_TEST_RUN_LONG`: If set (to any value), some tests will run more
|
|
iterations or otherwise test more thoroughly
|
|
|
|
* `FLATPAK_BWRAP`: Path to the **bwrap**(1) executable
|
|
(default: discovered at build-time)
|
|
|
|
* `XDP_VALIDATE_ICON_INSECURE`: If set (to any value), x-d-p doesn't
|
|
sandbox the icon validator using **bwrap**(1), even if sandboxed
|
|
validation was enabled at compile time.
|
|
This can be used to run build-time tests in a chroot or unprivileged
|
|
container environment, where **bwrap**(1) normally can't work.
|
|
It should never be set on a production system that will be validating
|
|
untrusted icons!
|
|
|
|
* `XDP_VALIDATE_SOUND_INSECURE`: Same as `XDP_VALIDATE_ICON_INSECURE`,
|
|
but for sounds
|
|
|
|
Some optional environment variables that can be set to help with debugging.
|
|
|
|
* `XDP_DBUS_MONITOR`: If set, starts dbus-monitor on the test dbus server
|
|
|
|
* `XDP_DBUS_TIMEOUT`: Maximum timeout for dbus calls in ms (default: 5s)
|
|
|
|
* `XDG_DESKTOP_PORTAL_WAIT_FOR_DEBUGGER`: Makes xdg-desktop-portal wait for
|
|
a debugger to attach by raising SIGSTOP
|
|
|
|
* `XDG_DOCUMENT_PORTAL_WAIT_FOR_DEBUGGER`: Makes xdg-document-portal wait
|
|
for a debugger to attach by raising SIGSTOP
|
|
|
|
* `XDG_PERMISSION_STORE_WAIT_FOR_DEBUGGER`: Makes xdg-permission-store wait
|
|
for a debugger to attach by raising SIGSTOP
|
|
|
|
Internal environment variables the tests use via pytest fixtures to set up the
|
|
environment they need.
|
|
|
|
* `XDG_DESKTOP_PORTAL_TEST_APP_ID`: If set, the portal will use a host
|
|
XdpAppInfo with the app id set to the variable. This is used to get a
|
|
predictable app id for tests.
|
|
|
|
* `XDG_DESKTOP_PORTAL_TEST_USB_QUERIES`: The USB queries for the USB device
|
|
portal testing
|
|
|
|
### Adding new tests
|
|
|
|
Make sure the required portals are listed in
|
|
`xdg_desktop_portal_dir_default_files` in `conftest.py`.
|
|
|
|
Add a `test_${name}.py` file to this directory and add the file to
|
|
`meson.build`.
|
|
|
|
If the portal that is being tested requires a backend implementation, add
|
|
it to the `templates` directory and add the file to `meson.build`. See the
|
|
dbusmock documentation for details on those templates.
|