init

Telegram/ThirdParty/xdg-desktop-portal/tests/README.md

@@ -0,0 +1,105 @@
+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.